@407dev/cli 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @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](src/index.ts) (`cms`, `runCli`, `printHelp`)
+- Auth resolution: [src/auth.ts](src/auth.ts) (`resolveAuthToken`)
+- Credentials store: [src/credentials.ts](src/credentials.ts) (`saveStoredCredentials`, `getStoredCredentials`, `removeStoredCredentials`, `refreshCredentialsIfNeeded`)
+- Login command: [src/commands/login.ts](src/commands/login.ts) (`executeLogin`)
+- Logout command: [src/commands/logout.ts](src/commands/logout.ts) (`executeLogout`)
+- Whoami command: [src/commands/whoami.ts](src/commands/whoami.ts) (`executeWhoami`)
+- Link command: [src/commands/link.ts](src/commands/link.ts) (`executeLink`, `mergeEnvContent`, `mergeEnvFile`)
+- Push command: [src/commands/push.ts](src/commands/push.ts) (`executePush`)
+- Check command: [src/commands/check.ts](src/commands/check.ts) (`executeCheck`)
+- Extract command: [src/commands/extract.ts](src/commands/extract.ts) (`executeExtract`)
+- Skills command: [src/commands/skills.ts](src/commands/skills.ts) (`executeSkillsInstall`, `installSkills`, `listBundledSkills`)
+- Bundled agent skills: [skills/](skills) (`407dev-cms-setup`, `407dev-cms-keying`, `407dev-cms-fields`)
+- AST parser & sourcemap tracer: [src/extract/parse.ts](src/extract/parse.ts) (`parseFile`, `globSourceFiles`)
+- Scope & group resolution: [src/extract/resolve.ts](src/extract/resolve.ts) (`resolveFileContext`)
+- Field & collection collector: [src/extract/collect.ts](src/extract/collect.ts) (`collectFromFile`)
+- Merge & conflict detection: [src/extract/merge.ts](src/extract/merge.ts) (`mergeExtractionResults`)
+- Manifest builder: [src/extract/manifest.ts](src/extract/manifest.ts) (`buildSiteManifest`)
+- Derived routes resolver: [src/extract/routes.ts](src/extract/routes.ts) (`loadDerivedRoutes`)
+- Entry migrations runner: [src/migrations.ts](src/migrations.ts) (`runEntryMigrations`)
+- State store: [src/state-store.ts](src/state-store.ts) (`StateStore`)
+- Extractor types: [src/extract/types.ts](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 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](../api-client)) for `pushManifest`, `listEntries`, `updateEntry`, `getSites`, `createCliSession`.
+- Consumes `@407dev/blocks` ([packages/blocks](../blocks)) for `hashSchema`.
+- Consumes `@407dev/field-types` ([packages/field-types](../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.

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+import { createApiClient, SiteManifest, ManifestPushReport, SiteRecord, SiteManifestRoute } from '@407dev/api-client';
+import { TraceMap } from '@jridgewell/trace-mapping';
+import ts from 'typescript';
+
+type ApiClient = ReturnType<typeof createApiClient>;
+interface CmsCliState {
+    sites: Record<string, {
+        manifestHash: string;
+        lastPushedAt: string;
+    }>;
+}
+interface EntryMigration {
+    collection: string;
+    fromVersion: number;
+    toVersion: number;
+    migrate: (content: Record<string, unknown>) => Record<string, unknown>;
+}
+interface PushCommandOptions {
+    siteId: string;
+    siteDir?: string;
+    manifest?: SiteManifest;
+    configPath?: string;
+    renames?: Array<{
+        from: string;
+        to: string;
+    }>;
+    force?: boolean;
+    dryRun?: boolean;
+    check?: boolean;
+    yes?: boolean;
+    noSync?: boolean;
+    statePath?: string;
+    apiClient?: ApiClient;
+    migrations?: EntryMigration[];
+    /** Prompts before an orphaning push; defaults to a stdin y/N prompt. Injectable for tests/non-interactive callers. */
+    confirm?: (message: string) => Promise<boolean>;
+}
+interface PushCommandResult {
+    success: boolean;
+    skipped?: boolean;
+    aborted?: boolean;
+    hash: string;
+    report?: ManifestPushReport;
+    migrationsRun?: number;
+    warnings: string[];
+    errors: string[];
+}
+
+declare function resolveAuthToken(apiUrl?: string, customCredentialsPath?: string): Promise<string>;
+
+interface StoredCredentials {
+    access_token: string;
+    refresh_token: string;
+    expires_at: number;
+    email?: string;
+}
+declare function normalizeApiUrl(url: string): string;
+declare function getDefaultCredentialsPath(): string;
+declare function loadAllCredentials(customPath?: string): Record<string, StoredCredentials>;
+declare function getStoredCredentials(apiUrl: string, customPath?: string): StoredCredentials | null;
+declare function saveStoredCredentials(apiUrl: string, creds: StoredCredentials, customPath?: string): void;
+declare function removeStoredCredentials(apiUrl: string, customPath?: string): boolean;
+declare function refreshCredentialsIfNeeded(apiUrl: string, creds: StoredCredentials, customPath?: string, fetchFn?: typeof fetch): Promise<StoredCredentials>;
+
+interface CheckCommandOptions {
+    siteDir?: string;
+    noSync?: boolean;
+}
+interface CheckCommandResult {
+    success: boolean;
+    errorsCount: number;
+    warningsCount: number;
+    report: string;
+}
+declare function executeCheck(options?: CheckCommandOptions): Promise<CheckCommandResult>;
+
+interface ExtractCommandOptions {
+    siteDir?: string;
+    noSync?: boolean;
+    json?: boolean;
+}
+declare function executeExtract(options?: ExtractCommandOptions): Promise<string>;
+
+interface LinkCommandOptions {
+    siteId?: string;
+    apiUrl?: string;
+    siteDir?: string;
+    apiClient?: ApiClient;
+    selectPrompt?: (sites: SiteRecord[]) => Promise<SiteRecord>;
+}
+declare function mergeEnvContent(content: string, vars: Record<string, string>): string;
+declare function mergeEnvFile(filePath: string, vars: Record<string, string>): void;
+declare function executeLink(options?: LinkCommandOptions): Promise<string>;
+
+interface LoginCommandOptions {
+    apiUrl?: string;
+    openBrowser?: boolean;
+    timeoutMs?: number;
+}
+declare function executeLogin(options?: LoginCommandOptions): Promise<string>;
+
+interface LogoutCommandOptions {
+    apiUrl?: string;
+    customCredentialsPath?: string;
+}
+declare function executeLogout(options?: LogoutCommandOptions): string;
+
+declare function executePush(options: PushCommandOptions): Promise<PushCommandResult>;
+
+interface SkillsInstallOptions {
+    targetDir?: string;
+    force?: boolean;
+    sourceDir?: string;
+}
+interface SkillInstallResult {
+    name: string;
+    status: 'installed' | 'updated' | 'unchanged' | 'conflict';
+    conflicts: string[];
+}
+declare function resolveBundledSkillsDir(): string;
+declare function listBundledSkills(sourceDir?: string): string[];
+declare function installSkills(options?: SkillsInstallOptions): SkillInstallResult[];
+declare function executeSkillsInstall(options?: SkillsInstallOptions): string;
+declare function executeSkillsList(): string;
+
+interface WhoamiCommandOptions {
+    apiUrl?: string;
+    customCredentialsPath?: string;
+}
+declare function executeWhoami(options?: WhoamiCommandOptions): Promise<string>;
+
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+interface ExtractedField {
+    key: string;
+    type: string;
+    constraints?: Record<string, unknown>;
+    defaultValue?: unknown;
+    group?: string;
+    location: SourceLocation;
+}
+interface ExtractedCollection {
+    key: string;
+    jsonSchema: Record<string, unknown>;
+    schemaVersion: number;
+    orderable?: boolean;
+    routePattern?: string;
+    presentation?: 'visual' | 'form';
+    titleField?: string;
+    listColumns?: string[];
+    bodyField?: string;
+    group?: string;
+    seed?: Array<{
+        slug: string;
+        content: Record<string, unknown>;
+    }>;
+    location: SourceLocation;
+}
+interface ExtractedGroup {
+    groupName: string;
+    shape: Record<string, string>;
+    location: SourceLocation;
+}
+interface ExtractedScope {
+    varName: string;
+    prefix: string;
+    location: SourceLocation;
+}
+interface ExtractionDiagnostic {
+    type: 'error' | 'warning';
+    message: string;
+    file: string;
+    line: number;
+    column: number;
+    code?: string;
+}
+interface FileExtractionResult {
+    file: string;
+    fields: ExtractedField[];
+    collections: ExtractedCollection[];
+    groups: ExtractedGroup[];
+    scopes: ExtractedScope[];
+    diagnostics: ExtractionDiagnostic[];
+}
+interface MergedField {
+    type: string;
+    constraints?: Record<string, unknown>;
+    defaultValue?: unknown;
+    group?: string;
+    sources: SourceLocation[];
+}
+interface MergedExtractionResult {
+    fields: Record<string, MergedField>;
+    collections: Record<string, ExtractedCollection>;
+    routes: SiteManifestRoute[];
+    diagnostics: ExtractionDiagnostic[];
+}
+
+interface ExtractOptions {
+    siteDir?: string;
+    noSync?: boolean;
+}
+interface ExtractResult {
+    manifest: SiteManifest;
+    diagnostics: ExtractionDiagnostic[];
+    errors: ExtractionDiagnostic[];
+    warnings: ExtractionDiagnostic[];
+    merged: MergedExtractionResult;
+}
+declare function extractProject(siteDir?: string, options?: ExtractOptions): Promise<ExtractResult>;
+declare function formatDiagnostics(diagnostics: ExtractionDiagnostic[]): string;
+
+interface ParsedFile {
+    filePath: string;
+    relativePath: string;
+    isAstro: boolean;
+    sourceFile: ts.SourceFile;
+    traceMap?: TraceMap;
+    getLocation: (node: ts.Node) => SourceLocation;
+}
+declare function parseFile(filePath: string, rootPath?: string): Promise<ParsedFile>;
+declare function globSourceFiles(dir: string): string[];
+
+interface ResolvedGroup {
+    groupName: string;
+    shape: Record<string, string>;
+    definedLocation: SourceLocation;
+    hopCount: number;
+}
+interface ResolvedContext {
+    scopes: Map<string, {
+        prefix: string;
+        location: SourceLocation;
+    }>;
+    groups: Map<string, ResolvedGroup>;
+    groupInstances: Map<string, {
+        groupName: string;
+        prefix: string;
+        shape: Record<string, string>;
+        location: SourceLocation;
+    }>;
+    collections: Map<string, ExtractedCollection>;
+    diagnostics: ExtractionDiagnostic[];
+}
+declare function parseBareSpecifier(specifier: string): {
+    packageName: string;
+    subpath: string;
+};
+declare function findPackageRoot(fromFile: string, packageName: string): string | null;
+interface ExportResolution {
+    resolvedPath: string | null;
+    hasSource: boolean;
+    exportFound: boolean;
+}
+declare function resolvePackageExport(pkgRoot: string, subpath: string): ExportResolution;
+declare function resolveModulePath(fromFile: string, importSpecifier: string): string | null;
+declare function getStringLiteralValue(node: ts.Node): string | null;
+declare function extractGroupFromCall(callExpr: ts.CallExpression, fallbackName: string, sf: ts.SourceFile, diagnostics?: ExtractionDiagnostic[], getLocation?: (node: ts.Node) => SourceLocation): {
+    groupName: string;
+    shape: Record<string, string>;
+} | null;
+declare function resolveFileContext(parsed: ParsedFile, rootPath?: string, cachedParsedFiles?: Map<string, ParsedFile>): Promise<ResolvedContext>;
+
+declare function collectFromFile(parsed: ParsedFile, context: ResolvedContext): FileExtractionResult;
+
+declare function buildSiteManifest(merged: MergedExtractionResult, extraRoutes?: SiteManifestRoute[]): {
+    manifest: SiteManifest;
+    diagnostics: ExtractionDiagnostic[];
+};
+
+declare function mergeExtractionResults(fileResults: FileExtractionResult[]): MergedExtractionResult;
+
+interface AstroResolvedRoute {
+    route?: string;
+    component?: string;
+    type?: string;
+    params?: string[];
+}
+declare function shouldSyncRoutes(siteDir: string, cmsRoutesFile: string): boolean;
+declare function syncAstroRoutes(siteDir: string): boolean;
+declare function deriveRouteFromComponent(componentPath: string): string;
+declare function scanPagesDirectory(siteDir: string): AstroResolvedRoute[];
+declare function loadDerivedRoutes(siteDir: string, collections?: Record<string, ExtractedCollection>, options?: {
+    noSync?: boolean;
+}): {
+    routes: SiteManifestRoute[];
+    diagnostics: ExtractionDiagnostic[];
+};
+
+declare function loadManifest(pathOrObject?: string | SiteManifest): Promise<SiteManifest>;
+
+declare function runEntryMigrations(apiClient: ApiClient, siteId: string, migrations: EntryMigration[]): Promise<{
+    migratedCount: number;
+    errors: string[];
+}>;
+
+declare class StateStore {
+    private filePath;
+    constructor(customPath?: string);
+    load(): CmsCliState;
+    getSiteManifestHash(siteId: string): string | null;
+    saveSiteManifestHash(siteId: string, hash: string): void;
+}
+
+declare const VERSION = "0.0.1";
+declare function printHelp(): string;
+declare function formatPushReport(result: PushCommandResult): string;
+declare function runCli(args?: string[]): Promise<string>;
+
+export { type ApiClient, type AstroResolvedRoute, type CheckCommandOptions, type CheckCommandResult, type CmsCliState, type EntryMigration, type ExportResolution, type ExtractCommandOptions, type ExtractOptions, type ExtractResult, type ExtractedCollection, type ExtractedField, type ExtractedGroup, type ExtractedScope, type ExtractionDiagnostic, type FileExtractionResult, type LinkCommandOptions, type LoginCommandOptions, type LogoutCommandOptions, type MergedExtractionResult, type MergedField, type ParsedFile, type PushCommandOptions, type PushCommandResult, type ResolvedContext, type ResolvedGroup, type SkillInstallResult, type SkillsInstallOptions, type SourceLocation, StateStore, type StoredCredentials, VERSION, type WhoamiCommandOptions, buildSiteManifest, collectFromFile, deriveRouteFromComponent, executeCheck, executeExtract, executeLink, executeLogin, executeLogout, executePush, executeSkillsInstall, executeSkillsList, executeWhoami, extractGroupFromCall, extractProject, findPackageRoot, formatDiagnostics, formatPushReport, getDefaultCredentialsPath, getStoredCredentials, getStringLiteralValue, globSourceFiles, installSkills, listBundledSkills, loadAllCredentials, loadDerivedRoutes, loadManifest, mergeEnvContent, mergeEnvFile, mergeExtractionResults, normalizeApiUrl, parseBareSpecifier, parseFile, printHelp, refreshCredentialsIfNeeded, removeStoredCredentials, resolveAuthToken, resolveBundledSkillsDir, resolveFileContext, resolveModulePath, resolvePackageExport, runCli, runEntryMigrations, saveStoredCredentials, scanPagesDirectory, shouldSyncRoutes, syncAstroRoutes };