@delegance/claude-autopilot 5.0.8 → 5.2.1

package/dist/src/core/migrate/doctor-checks.js

@@ -0,0 +1,304 @@
+// src/core/migrate/doctor-checks.ts
+//
+// Pure check functions for `claude-autopilot doctor` (migrate-specific).
+// Each check is read-only and returns { ok, message?, fixHint? }.
+// Mutations live behind `--fix` (see src/cli/migrate-doctor.ts).
+//
+// Spec: docs/superpowers/specs/2026-04-29-migrate-skill-generalization-design.md
+// (§ "claude-autopilot doctor", checks 1–8)
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import * as yaml from 'js-yaml';
+import { validateStackMd } from "./schema-validator.js";
+import { resolveSkill } from "./alias-resolver.js";
+import { DETECTION_RULES } from "./detector-rules.js";
+function stackPath(repoRoot) {
+    return path.join(repoRoot, '.autopilot', 'stack.md');
+}
+function readStackMdRaw(repoRoot) {
+    const p = stackPath(repoRoot);
+    if (!fs.existsSync(p))
+        return null;
+    const raw = fs.readFileSync(p, 'utf8');
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    return { raw, parsed: parsed };
+}
+// 1. stack.md exists
+export function stackMdExists(repoRoot) {
+    const p = stackPath(repoRoot);
+    if (fs.existsSync(p))
+        return { ok: true };
+    return {
+        ok: false,
+        message: `.autopilot/stack.md not found in ${repoRoot}`,
+        fixHint: 'run `claude-autopilot init` to scaffold one',
+    };
+}
+// 2. JSON Schema validates
+export function schemaValidates(repoRoot) {
+    const data = readStackMdRaw(repoRoot);
+    if (!data) {
+        return {
+            ok: false,
+            message: 'cannot validate schema: stack.md missing or unparseable',
+            fixHint: 'run `claude-autopilot init`',
+        };
+    }
+    const result = validateStackMd(data.raw);
+    if (result.valid)
+        return { ok: true };
+    const summary = result.errors
+        .map(e => (e.path ? `${e.path}: ${e.message}` : e.message))
+        .join('; ');
+    return {
+        ok: false,
+        message: `schema validation failed — ${summary}`,
+        fixHint: 'run `claude-autopilot doctor --fix` to auto-fix simple cases (missing schema_version, default policy keys)',
+    };
+}
+// 3. migrate.skill resolves to an installed skill
+export function skillResolves(repoRoot) {
+    const data = readStackMdRaw(repoRoot);
+    if (!data) {
+        return { ok: false, message: 'cannot resolve skill: stack.md missing' };
+    }
+    const skill = data.parsed.migrate?.skill;
+    if (!skill || typeof skill !== 'string') {
+        return {
+            ok: false,
+            message: 'migrate.skill is missing or not a string',
+            fixHint: 'set `migrate.skill` to a stable ID (e.g. "migrate@1", "migrate.supabase@1", "none@1")',
+        };
+    }
+    const res = resolveSkill(skill, { repoRoot });
+    if (res.ok) {
+        if (res.normalizedFromRaw) {
+            return {
+                ok: false,
+                message: `migrate.skill "${skill}" is a raw alias; resolves to stable ID "${res.stableId}"`,
+                fixHint: `change \`migrate.skill\` to "${res.stableId}" (auto-fixable via --fix)`,
+            };
+        }
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        message: `migrate.skill "${skill}" failed to resolve: ${res.message}`,
+        fixHint: 'use a stable ID listed in presets/aliases.lock.json',
+    };
+}
+// 4. Per-env commands explicit (no env reuses envs.dev.command)
+export function perEnvCommandsExplicit(repoRoot) {
+    const data = readStackMdRaw(repoRoot);
+    if (!data) {
+        return { ok: false, message: 'cannot check envs: stack.md missing' };
+    }
+    const envs = data.parsed.migrate?.envs;
+    if (!envs)
+        return { ok: true };
+    const dev = envs.dev?.command;
+    if (!dev)
+        return { ok: true };
+    const devKey = JSON.stringify(dev);
+    const offenders = [];
+    for (const [name, spec] of Object.entries(envs)) {
+        if (name === 'dev')
+            continue;
+        if (spec?.command && JSON.stringify(spec.command) === devKey) {
+            offenders.push(name);
+        }
+    }
+    if (offenders.length === 0)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `envs.${offenders.join(', envs.')} reuse envs.dev.command — running a dev migration against a non-dev env is destructive`,
+        fixHint: `set an explicit \`command\` for each non-dev env (e.g. \`prisma migrate deploy\` for prod)`,
+    };
+}
+// 5. policy.* fields are booleans
+export function policyFieldsValid(repoRoot) {
+    const data = readStackMdRaw(repoRoot);
+    if (!data) {
+        return { ok: false, message: 'cannot check policy: stack.md missing' };
+    }
+    const policy = data.parsed.migrate?.policy;
+    if (!policy || typeof policy !== 'object')
+        return { ok: true };
+    const offenders = [];
+    for (const [k, v] of Object.entries(policy)) {
+        if (typeof v !== 'boolean') {
+            offenders.push(`${k}=${JSON.stringify(v)}`);
+        }
+    }
+    if (offenders.length === 0)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `policy fields must be booleans; offenders: ${offenders.join(', ')}`,
+        fixHint: 'edit `.autopilot/stack.md` so each policy.* field is `true` or `false`',
+    };
+}
+function findRuleForSkill(skill) {
+    // Match by defaultSkill. For migrate@1 there are many rules; we
+    // can't disambiguate without re-detecting, so we only verify
+    // narrow skill IDs (migrate.supabase@1) and return undefined for
+    // generic migrate@1 (which can have any toolchain).
+    return DETECTION_RULES.find(r => r.defaultSkill === skill);
+}
+// 6. project_root has expected toolchain files for the resolved skill.
+export function projectRootHasToolchain(repoRoot) {
+    const data = readStackMdRaw(repoRoot);
+    if (!data) {
+        return { ok: false, message: 'cannot verify toolchain: stack.md missing' };
+    }
+    const skill = data.parsed.migrate?.skill;
+    if (!skill)
+        return { ok: false, message: 'migrate.skill is missing' };
+    // Skip the no-op skill — nothing to verify.
+    if (skill === 'none@1')
+        return { ok: true };
+    const projectRoot = data.parsed.migrate?.project_root ?? '.';
+    const projectAbs = path.resolve(repoRoot, projectRoot);
+    if (!fs.existsSync(projectAbs)) {
+        return {
+            ok: false,
+            message: `project_root "${projectRoot}" does not exist (resolved: ${projectAbs})`,
+            fixHint: 'set `migrate.project_root` to a path that exists, or run `init`',
+        };
+    }
+    // Rule-based toolchain check. For migrate.supabase@1 there's exactly
+    // one matching rule (nextjs-supabase). For migrate@1, multiple rules
+    // share the skill; we only enforce the toolchain when stack.md
+    // explicitly declares a supabase or shape-narrowed skill.
+    if (skill === 'migrate.supabase@1') {
+        const rule = DETECTION_RULES.find(r => r.defaultSkill === 'migrate.supabase@1');
+        if (!rule)
+            return { ok: true };
+        const missing = rule.requireAll.filter(p => !fs.existsSync(path.join(projectAbs, p)));
+        if (missing.length === 0)
+            return { ok: true };
+        return {
+            ok: false,
+            message: `project_root missing expected toolchain files for ${skill}: ${missing.join(', ')}`,
+            fixHint: 'verify `migrate.project_root` points to the correct workspace',
+        };
+    }
+    // For migrate@1, attempt best-effort detection via existing rules to
+    // catch obvious misalignments. We require AT LEAST one migrate@1 rule
+    // to satisfy its requireAll/requireAny set; if none do, the stack.md
+    // claims a tool that isn't present.
+    if (skill === 'migrate@1') {
+        const candidates = DETECTION_RULES.filter(r => r.defaultSkill === 'migrate@1');
+        const anySatisfied = candidates.some(r => {
+            const allOk = r.requireAll.every(p => fs.existsSync(path.join(projectAbs, p)));
+            const anyOk = !r.requireAny || r.requireAny.some(p => fs.existsSync(path.join(projectAbs, p)));
+            return allOk && anyOk && r.requireAll.length + (r.requireAny?.length ?? 0) > 0;
+        });
+        if (anySatisfied)
+            return { ok: true };
+        return {
+            ok: false,
+            message: `project_root "${projectRoot}" does not contain any recognized migration toolchain files for ${skill}`,
+            fixHint: 'verify `migrate.project_root` or change `migrate.skill` to match your stack',
+        };
+    }
+    // Unknown skill — let skillResolves report the issue.
+    const rule = findRuleForSkill(skill);
+    if (!rule)
+        return { ok: true };
+    return { ok: true };
+}
+// 7. Deprecated keys reported (read-only).
+export function deprecatedKeysAbsent(repoRoot) {
+    const data = readStackMdRaw(repoRoot);
+    if (!data) {
+        return { ok: false, message: 'cannot check deprecated keys: stack.md missing' };
+    }
+    const offenders = [];
+    if ('dev_command' in data.parsed) {
+        offenders.push('dev_command (top-level)');
+    }
+    if (offenders.length === 0)
+        return { ok: true };
+    return {
+        ok: false,
+        message: `deprecated keys present: ${offenders.join(', ')}`,
+        fixHint: 'run `claude-autopilot doctor --fix` to migrate `dev_command` → `migrate.envs.dev.command`',
+    };
+}
+// 8. env_file safety: relative to project_root, no `..`, NOT git-tracked.
+export function envFileSafety(repoRoot) {
+    const data = readStackMdRaw(repoRoot);
+    if (!data) {
+        return { ok: false, message: 'cannot check env_file: stack.md missing' };
+    }
+    const envs = data.parsed.migrate?.envs;
+    if (!envs)
+        return { ok: true };
+    const projectRoot = data.parsed.migrate?.project_root ?? '.';
+    const projectAbs = path.resolve(repoRoot, projectRoot);
+    const issues = [];
+    for (const [name, spec] of Object.entries(envs)) {
+        const ef = spec?.env_file;
+        if (!ef)
+            continue;
+        if (path.isAbsolute(ef)) {
+            issues.push(`envs.${name}.env_file is absolute (${ef}); must be relative to project_root`);
+            continue;
+        }
+        const segments = ef.split(/[/\\]/);
+        if (segments.some(s => s === '..')) {
+            issues.push(`envs.${name}.env_file contains ".." traversal (${ef}); reject for safety`);
+            continue;
+        }
+        const efAbs = path.resolve(projectAbs, ef);
+        const rel = path.relative(projectAbs, efAbs);
+        if (rel.startsWith('..') || path.isAbsolute(rel)) {
+            issues.push(`envs.${name}.env_file resolves outside project_root (${ef})`);
+            continue;
+        }
+        // Existence is not required (the env file may live only on the
+        // operator's machine), but if the repo is a git repo and the file
+        // IS tracked, that's a leak we must warn about.
+        try {
+            const out = execFileSync('git', ['ls-files', '--error-unmatch', '--', ef], { cwd: projectAbs, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+            if (out) {
+                issues.push(`envs.${name}.env_file is git-tracked (${ef}); secrets in env files must be gitignored`);
+            }
+        }
+        catch {
+            // Not tracked, or not a git repo — both are fine for the safety
+            // check. Doctor surfaces tracked files only.
+        }
+    }
+    if (issues.length === 0)
+        return { ok: true };
+    return {
+        ok: false,
+        message: issues.join('; '),
+        fixHint: 'remove the offending env_file from git (`git rm --cached <file>`) and add it to .gitignore',
+    };
+}
+export function runAllChecks(repoRoot) {
+    return [
+        { name: 'stackMdExists', result: stackMdExists(repoRoot) },
+        { name: 'schemaValidates', result: schemaValidates(repoRoot) },
+        { name: 'skillResolves', result: skillResolves(repoRoot) },
+        { name: 'perEnvCommandsExplicit', result: perEnvCommandsExplicit(repoRoot) },
+        { name: 'policyFieldsValid', result: policyFieldsValid(repoRoot) },
+        { name: 'projectRootHasToolchain', result: projectRootHasToolchain(repoRoot) },
+        { name: 'deprecatedKeysAbsent', result: deprecatedKeysAbsent(repoRoot) },
+        { name: 'envFileSafety', result: envFileSafety(repoRoot) },
+    ];
+}
+//# sourceMappingURL=doctor-checks.js.map

package/dist/src/core/migrate/envelope.d.ts

@@ -0,0 +1,25 @@
+import type { InvocationEnvelope } from './types.ts';
+export interface BuildEnvelopeOptions {
+    changedFiles: string[];
+    env: string;
+    repoRoot: string;
+    cwd?: string;
+    dryRun?: boolean;
+    ci?: boolean;
+    projectId?: string;
+    attempt?: number;
+    trigger?: 'cli' | 'ci';
+}
+export interface CIDetectionResult {
+    ci: boolean;
+    provider: string | null;
+    overridden: boolean;
+}
+/**
+ * Detect whether we're running in CI and which provider, based on
+ * standard env-var markers. AUTOPILOT_CI_PROVIDER overrides the
+ * detected value (with audit-log evidence).
+ */
+export declare function detectCI(): CIDetectionResult;
+export declare function buildEnvelope(opts: BuildEnvelopeOptions): InvocationEnvelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/src/core/migrate/envelope.js

@@ -0,0 +1,84 @@
+// src/core/migrate/envelope.ts
+//
+// Builds an InvocationEnvelope for a migrate dispatch. Generates a
+// per-call invocationId (UUID v4) and nonce (32-byte hex), reads
+// gitBase/gitHead via git rev-parse, auto-detects CI from env vars.
+import { execFileSync } from 'node:child_process';
+import { randomUUID, randomBytes } from 'node:crypto';
+import { ENVELOPE_CONTRACT_VERSION } from "./contract.js";
+/**
+ * Detect whether we're running in CI and which provider, based on
+ * standard env-var markers. AUTOPILOT_CI_PROVIDER overrides the
+ * detected value (with audit-log evidence).
+ */
+export function detectCI() {
+    const override = process.env.AUTOPILOT_CI_PROVIDER;
+    if (override) {
+        return { ci: true, provider: override, overridden: true };
+    }
+    if (process.env.GITHUB_ACTIONS === 'true') {
+        return { ci: true, provider: 'github-actions', overridden: false };
+    }
+    if (process.env.GITLAB_CI === 'true') {
+        return { ci: true, provider: 'gitlab', overridden: false };
+    }
+    if (process.env.CIRCLECI === 'true') {
+        return { ci: true, provider: 'circleci', overridden: false };
+    }
+    if (process.env.BUILDKITE === 'true') {
+        return { ci: true, provider: 'buildkite', overridden: false };
+    }
+    if (process.env.JENKINS_URL) {
+        return { ci: true, provider: 'jenkins', overridden: false };
+    }
+    // CI=true alone (no recognized provider) — ci:true, provider:null.
+    // Policy enforcer treats this as "missing provider" and blocks prod.
+    if (process.env.CI === 'true') {
+        return { ci: true, provider: null, overridden: false };
+    }
+    return { ci: false, provider: null, overridden: false };
+}
+function readGitRef(ref, cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', ref], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch (err) {
+        throw new Error(`buildEnvelope: not in a git repo or rev-parse failed for ${ref}: ${err.message}`);
+    }
+}
+export function buildEnvelope(opts) {
+    const ciInfo = detectCI();
+    const ci = opts.ci ?? ciInfo.ci;
+    const trigger = opts.trigger ?? (ci ? 'ci' : 'cli');
+    const cwd = opts.cwd ?? opts.repoRoot;
+    const gitHead = readGitRef('HEAD', opts.repoRoot);
+    // Use HEAD~1 as base; if no parent (initial commit), reuse HEAD.
+    let gitBase;
+    try {
+        gitBase = readGitRef('HEAD~1', opts.repoRoot);
+    }
+    catch {
+        gitBase = gitHead;
+    }
+    return {
+        contractVersion: ENVELOPE_CONTRACT_VERSION,
+        invocationId: randomUUID(),
+        nonce: randomBytes(32).toString('hex'),
+        trigger,
+        attempt: opts.attempt ?? 1,
+        repoRoot: opts.repoRoot,
+        cwd,
+        changedFiles: opts.changedFiles,
+        env: opts.env,
+        dryRun: opts.dryRun ?? false,
+        ci,
+        gitBase,
+        gitHead,
+        ...(opts.projectId !== undefined ? { projectId: opts.projectId } : {}),
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/core/migrate/executor.d.ts

@@ -0,0 +1,33 @@
+import type { CommandSpec } from './types.ts';
+export interface ExecuteOptions {
+    cwd: string;
+    env?: Record<string, string>;
+}
+export interface ExecuteResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface ExecutableResolution {
+    found: boolean;
+    absolutePath?: string;
+    reason?: string;
+}
+/**
+ * Resolve an executable name against PATH (or as a workspace-relative
+ * script if the name starts with ./ or ../). Returns absolute path if
+ * found.
+ */
+export declare function resolveExecutable(exec: string, cwd: string): ExecutableResolution;
+export declare function executeCommand(spec: CommandSpec, opts: ExecuteOptions): Promise<ExecuteResult>;
+export interface LegacyParseResult {
+    spec: CommandSpec;
+    warning: string;
+}
+/**
+ * Parse a legacy string-form command via shell-quote. Rejects strings
+ * containing any shell metachar — those are valid in shell but dangerous
+ * in a structured-argv contract. Emits a deprecation warning.
+ */
+export declare function parseLegacyCommand(raw: string): LegacyParseResult;
+//# sourceMappingURL=executor.d.ts.map

package/dist/src/core/migrate/executor.js

@@ -0,0 +1,102 @@
+// src/core/migrate/executor.ts
+//
+// Runs CommandSpec via spawn(shell:false). Structured argv is the only
+// non-deprecated path; legacy string form goes through shell-quote with
+// metachar rejection. PATH resolution is explicit; relative paths are
+// resolved against the workspace cwd.
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse as shellParse } from 'shell-quote';
+import { SHELL_METACHARS } from "./contract.js";
+/**
+ * Resolve an executable name against PATH (or as a workspace-relative
+ * script if the name starts with ./ or ../). Returns absolute path if
+ * found.
+ */
+export function resolveExecutable(exec, cwd) {
+    // Workspace-relative form
+    if (exec.startsWith('./') || exec.startsWith('../') || path.isAbsolute(exec)) {
+        const abs = path.isAbsolute(exec) ? exec : path.resolve(cwd, exec);
+        if (fs.existsSync(abs)) {
+            return { found: true, absolutePath: abs };
+        }
+        return { found: false, reason: `script not found at ${abs}` };
+    }
+    // PATH lookup
+    const PATH = process.env.PATH ?? '';
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const exts = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').map(e => e.toLowerCase())
+        : [''];
+    for (const dir of PATH.split(sep)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, exec + ext);
+            try {
+                const stat = fs.statSync(candidate);
+                if (stat.isFile()) {
+                    return { found: true, absolutePath: candidate };
+                }
+            }
+            catch {
+                // try next
+            }
+        }
+    }
+    return { found: false, reason: `'${exec}' not found in PATH` };
+}
+export async function executeCommand(spec, opts) {
+    return new Promise(resolve => {
+        const env = { ...process.env, ...(opts.env ?? {}) };
+        let stdout = '';
+        let stderr = '';
+        let child;
+        try {
+            child = spawn(spec.exec, spec.args, {
+                cwd: opts.cwd,
+                env,
+                shell: false,
+                windowsHide: true,
+            });
+        }
+        catch (err) {
+            resolve({ exitCode: -1, stdout: '', stderr: `spawn failed: ${err.message}` });
+            return;
+        }
+        child.stdout?.on('data', (b) => { stdout += b.toString(); });
+        child.stderr?.on('data', (b) => { stderr += b.toString(); });
+        child.on('error', (err) => {
+            resolve({ exitCode: -1, stdout, stderr: stderr + `\nspawn error: ${err.message}` });
+        });
+        child.on('exit', (code) => {
+            resolve({ exitCode: code ?? -1, stdout, stderr });
+        });
+    });
+}
+/**
+ * Parse a legacy string-form command via shell-quote. Rejects strings
+ * containing any shell metachar — those are valid in shell but dangerous
+ * in a structured-argv contract. Emits a deprecation warning.
+ */
+export function parseLegacyCommand(raw) {
+    if (SHELL_METACHARS.test(raw)) {
+        throw new Error(`shell metachar in legacy command: '${raw}'. Forbidden — convert to structured argv form { exec, args[] }.`);
+    }
+    const tokens = shellParse(raw);
+    if (tokens.length === 0) {
+        throw new Error('empty command string');
+    }
+    // shell-quote returns string | { op: '...' } | { comment: '...' };
+    // we already filtered metachars so all tokens should be strings.
+    if (tokens.some(t => typeof t !== 'string')) {
+        throw new Error(`unparseable legacy command: '${raw}'`);
+    }
+    const [exec, ...args] = tokens;
+    return {
+        spec: { exec: exec, args },
+        warning: `legacy string command form is deprecated; convert to { exec, args } structured argv. Auto-fix available via \`claude-autopilot doctor --fix\`.`,
+    };
+}
+//# sourceMappingURL=executor.js.map

package/dist/src/core/migrate/handshake.d.ts

@@ -0,0 +1,17 @@
+import type { SkillManifest } from './types.ts';
+export interface HandshakeOptions {
+    skillPath: string;
+    runtimeVersion: string;
+    envelopeContractVersion: string;
+}
+export type HandshakeResult = {
+    ok: true;
+    manifest: SkillManifest;
+} | {
+    ok: false;
+    reasonCode: HandshakeReason;
+    message: string;
+};
+export type HandshakeReason = 'manifest-missing' | 'manifest-invalid' | 'runtime-below-min' | 'runtime-above-max' | 'api-version-mismatch';
+export declare function performHandshake(opts: HandshakeOptions): HandshakeResult;
+//# sourceMappingURL=handshake.d.ts.map