Skip to content

AGENTS.md

Latest commit

 

History

History
64 lines (52 loc) · 2.47 KB

AGENTS.md

File metadata and controls

64 lines (52 loc) · 2.47 KB
Raw

@async/cli Repository Guide

This repo owns the @async/cli package: a filesystem command router with Node 24+ as the default binary host and Deno 2.7+ as an explicit alternate host.

Working Rules

  • Use Node 24+, pnpm, ESM, TypeScript source under src/, and explicit .js import extensions. Keep the published build compatible with Deno 2.7+ through its Node and npm compatibility layer.
  • Keep runtime dependencies at zero unless a future ADR explicitly approves one.
  • Preserve command directories as the move unit.
  • Keep script valid as a command segment; only script.{ts,mts,js,mjs} files make a command directory runnable.
  • v0.3 ships filesystem-root discovery, completions, the overlay trust model, --edit/--rm, templates, the cli-cwd pragma, --doctor, machine-readable listing, and command packs; keep their contracts aligned with SPEC.md.
  • Deno is supported as an alternate host for the published CLI while keeping the installed cli and async-cli binaries on Node; keep the runtime contract and security wording aligned with SPEC.md and SECURITY.md.
  • Command discovery never consults .git; only the --agents context-file subsystem, including its doctor audit, uses the Git repository boundary.
  • Do not add a persistent or time-based command-path cache. Resolution must observe the live filesystem on every invocation.
  • Do not add non-JavaScript entrypoints (.sh, .py) or a hosted pack registry.
  • Do not move or delete ../cli (1)/SPEC.md; it is source material outside this package.

Generated Artifacts And Pipeline

  • @async/pipeline (pinned in devDependencies) generates this repo's CI, Pages, preview, and release automation from pipeline.ts.
  • Do not hand-edit .github/workflows/async-pipeline.yml, the locks under .locks/pipeline/, or the generated pipeline:* scripts in package.json. Change pipeline.ts, then run:
pnpm run pipeline:sync:generate
pnpm run pipeline:sync:check
pnpm run pipeline:github:check
  • Releases of @async/pipeline dispatch async-dep-bump to this repo; the generated dependency-bump job applies the bump, regenerates synced surfaces, runs release:check, and pushes to main or opens a pull request on failure. Manual pipeline version bumps should follow the same steps: bump, regenerate, verify.

Verification

Run the package gate before handoff:

pnpm run release:check

For a narrower loop:

pnpm run build
pnpm test
pnpm run test:deno