@407dev/cli

Purpose

• Command-line tool for CLI login (cms login), project linking (cms link), static AST manifest extraction (cms extract), template & schema validation (cms check), code-first manifest synchronization (cms push), and entry migrations.

Surface

• Binary runner: src/index.ts (cms, runCli, printHelp)
• Auth resolution: src/auth.ts (resolveAuthToken)
• Credentials store: src/credentials.ts (saveStoredCredentials, getStoredCredentials, removeStoredCredentials, refreshCredentialsIfNeeded)
• Login command: src/commands/login.ts (executeLogin)
• Logout command: src/commands/logout.ts (executeLogout)
• Whoami command: src/commands/whoami.ts (executeWhoami)
• Link command: src/commands/link.ts (executeLink, mergeEnvContent, mergeEnvFile)
• Push command: src/commands/push.ts (executePush)
• Assets import command: src/commands/assets-import.ts (executeAssetsImport, formatAssetsImportReport)
• Check command: src/commands/check.ts (executeCheck)
• Extract command: src/commands/extract.ts (executeExtract)
• Skills command: src/commands/skills.ts (executeSkillsInstall, installSkills, listBundledSkills)
• Bundled agent skills: skills/ (407dev-cms-setup, 407dev-cms-keying, 407dev-cms-fields)
• AST parser & sourcemap tracer: src/extract/parse.ts (parseFile, globSourceFiles)
• Scope & group resolution: src/extract/resolve.ts (resolveFileContext)
• Field & collection collector: src/extract/collect.ts (collectFromFile)
• Merge & conflict detection: src/extract/merge.ts (mergeExtractionResults)
• Manifest builder: src/extract/manifest.ts (buildSiteManifest)
• Derived routes resolver: src/extract/routes.ts (loadDerivedRoutes)
• Entry migrations runner: src/migrations.ts (runEntryMigrations)
• State store: src/state-store.ts (StateStore)
• Extractor types: src/extract/types.ts

Commands

• cms login: Starts local HTTP server, opens browser to /cli/authorize, and receives isolated session credentials into ~/.config/407dev/credentials.json (supports --api-url).
• cms logout: Removes stored credentials for target API URL (--api-url).
• cms whoami: Displays current authentication identity and target API URL (--api-url).
• cms link: Links local codebase to a remote site (--site <id>, --api-url <url>). Interactively prompts if --site is omitted, updates .env (CMS_SITE_ID, CMS_API_URL, CMS_CONTENT_URL), and checks astro.config.mjs.
• cms check: Statically scans .astro and .ts files, validates field helper calls, detects invalid dynamic keys or cyclic groups, and reports diagnostics.
• cms extract: Extracts AST into canonical SiteManifest JSON containing all fields, groups, collections, and derived routes.
• cms push: Extracts manifest, verifies authentication, checks SHA-256 state hash in .cms/state.json, inserts collection seed entries once into empty collections, and synchronizes new/updated fields, collection schemas, and routes to the CMS Write API (PUT /sites/:id/manifest). Run --dry-run to preview changes and collections that would seed; run --force to bypass hash caching.
• cms assets import <dir>: Uploads a directory of images into the site's media library with extracted dimensions. With --link <collection>.<field>, matches uploaded assets by filename stem and rewrites existing collection entries to reference assets by UUID while pruning stale fields to the collection schema. Supports --alt-from <field> to copy alt text to asset records, --map <file.json> for explicit overrides, --concurrency <n> (default 4), --force to re-upload existing filenames, and --dry-run to preview actions.
• cms skills install [dir]: Copies bundled agent skills into <dir>/.claude/skills/. Files edited locally are kept and reported unless --force is passed. cms skills list prints the bundled names.

Patterns

• Auth Resolution Precedence:
  1. Explicit environment token: CMS_AUTH_TOKEN or SUPABASE_ACCESS_TOKEN (supports deploy tokens cms_dt_*).
  2. Local credentials file (~/.config/407dev/credentials.json), auto-refreshed via Supabase if expiring within 60s.
  3. Ephemeral dev JWT auto-signed if running against loopback (127.0.0.1 or localhost).
  4. Exit with error: Not logged in to <api>. Run: cms login.
• Credentials Security: Local directory created with 0700 permissions; credentials.json written with 0600 permissions.
• Isolated CLI Sessions: POST /cli/sessions issues a separate magic-link session for CLI usage to prevent Supabase refresh token rotation collisions with browser sessions.
• Safe Env Merging: cms link updates target CMS keys in .env without modifying unrelated variables, ordering, comments, or formatting.
• Static AST Extraction: Walks .astro (via @astrojs/compiler TSX conversion) and .ts files to derive SiteManifest automatically from f.<type>(), <f.<type> />, f.scope(), f.group(), and defineCollection().
• Bare Specifier Source Resolution: Resolves bare package imports (e.g. @407dev/cms-astro/collections) via package.json exports mapping containing a "source" condition.
• Sourcemap Position Tracing: Traces original file:line:col in .astro frontmatter and JSX templates for exact error diagnostic reporting.
• Group Multi-Hop Restriction: Enforces 1-hop maximum for imported groups so static extraction remains deterministic without full project type-checking.
• State Hashing & Skip: Computes SHA-256 hash of canonical manifest JSON and caches in .cms/state.json. Skips API push if hash is unchanged (override with --force).

Integrations

• Consumes @407dev/api-client (packages/api-client) for pushManifest, listEntries, updateEntry, getSites, createCliSession.
• Consumes @407dev/blocks (packages/blocks) for hashSchema.
• Consumes @407dev/field-types (packages/field-types) for field types and registry.
• Uses @supabase/supabase-js for refreshing local CLI sessions.

Constraints

• Published to public npm with executable permissions (bin.cms) and ESM build via tsup.
• Any export or command change requires a changeset (pnpm changeset).
• Zero dependencies on application packages (apps/*).

Gotchas

• In CI pipelines, set CMS_AUTH_TOKEN=<site-deploy-token> to authenticate cms push without browser logins.
• Deploy tokens (cms_dt_*) authorize manifest pushes, orphan previews, and migrations for their designated site only; central user operations are rejected.
• Field keys and scope prefixes passed to field helpers MUST be static string literals (dynamic variables or template strings produce extractor errors).
• Group and collection definitions must be in-file or imported across at most 1 hop.
• Bare package imports used in top-level definitions MUST declare a "source" export condition in package.json or extraction fails with an error diagnostic.
• skills/** ships in the npm tarball and is what agents in site repos follow; update it in the same commit as any change to cms-astro helpers, extractor rules, or CLI flags.
• apply_manifest sets group on each field definition (field.group), joining multiple source paths into a sorted comma-separated string.