agentplane 0.3.2 → 0.3.4

package/dist/cli/run-cli.js

@@ -1,12 +1,8 @@
-import os from "node:os";
-import path from "node:path";
 import { loadConfig, resolveProject, } from "@agentplaneorg/core";
 import { mapCoreError } from "./error-map.js";
 import { exitCodeForError } from "./exit-codes.js";
-import { warnMessage } from "./output.js";
-import { fetchLatestNpmVersion, readUpdateCheckCache, resolveUpdateCheckCachePath, shouldCheckNow, UPDATE_CHECK_SCHEMA_VERSION, UPDATE_CHECK_TIMEOUT_MS, UPDATE_CHECK_TTL_MS, writeUpdateCheckCache, } from "./update-check.js";
 import { loadDotEnv } from "../shared/env.js";
-import { CliError, formatJsonError } from "../shared/errors.js";
+import { CliError } from "../shared/errors.js";
 import { resolveContext } from "../usecases/context/resolve-context.js";
 import { getVersion } from "../meta/version.js";
 import { getApprovalRequirements } from "../commands/shared/approval-requirements.js";
@@ -14,478 +10,11 @@ import { parseCommandArgv } from "./spec/parse.js";
 import { helpSpec } from "./spec/help.js";
 import { usageError } from "./spec/errors.js";
 import { suggestOne } from "./spec/suggest.js";
-import { COMMANDS } from "./run-cli/command-catalog.js";
-import { getReasonCodeMeta } from "./reason-codes.js";
-const GLOBAL_FLAGS = [
-    { key: "help", forms: ["--help", "-h"], takesValue: false, scoped: false },
-    { key: "version", forms: ["--version", "-v"], takesValue: false, scoped: false },
-    { key: "noUpdateCheck", forms: ["--no-update-check"], takesValue: false, scoped: false },
-    { key: "allowNetwork", forms: ["--allow-network"], takesValue: false, scoped: true },
-    { key: "jsonErrors", forms: ["--json-errors"], takesValue: false, scoped: true },
-    { key: "outputMode", forms: ["--output"], takesValue: true, scoped: false },
-    { key: "root", forms: ["--root"], takesValue: true, scoped: false },
-];
-const GLOBAL_FLAG_FORMS = new Map(GLOBAL_FLAGS.flatMap((def) => def.forms.map((form) => [form, def])));
+import { matchCommandCatalog } from "./run-cli/catalog.js";
+import { prescanJsonErrors, parseGlobalArgs, resolveOutputMode, runWithOutputMode, } from "./run-cli/globals.js";
+import { writeError } from "./run-cli/error-guidance.js";
+import { maybeWarnOnUpdate } from "./run-cli/update-warning.js";
 const HELP_TAIL_OPTIONS = new Set(["--compact", "--json"]);
-function prescanJsonErrors(argv) {
-    // If parseGlobalArgs throws (e.g. missing --root value), we still want to honor
-    // `--json-errors` in the "scoped global" zone (before the command id).
-    let hasRest = false;
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (!arg)
-            continue;
-        const def = GLOBAL_FLAG_FORMS.get(arg);
-        if (!def) {
-            // First non-global token is treated as the start of the command id.
-            hasRest = true;
-            break;
-        }
-        if (def.key === "jsonErrors" && !hasRest)
-            return true;
-        if (def.takesValue) {
-            // Skip the value if present; do not throw on missing value here.
-            i++;
-        }
-    }
-    return false;
-}
-function parseGlobalArgs(argv) {
-    let help = false;
-    let version = false;
-    let noUpdateCheck = false;
-    let jsonErrors = false;
-    let root;
-    let allowNetwork = false;
-    let outputMode;
-    const rest = [];
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (!arg)
-            continue;
-        const def = GLOBAL_FLAG_FORMS.get(arg);
-        if (!def) {
-            rest.push(arg);
-            continue;
-        }
-        // Scoped globals are only recognized before the command id token.
-        if (def.scoped && rest.length > 0) {
-            rest.push(arg);
-            continue;
-        }
-        switch (def.key) {
-            case "help": {
-                help = true;
-                break;
-            }
-            case "version": {
-                version = true;
-                break;
-            }
-            case "noUpdateCheck": {
-                noUpdateCheck = true;
-                break;
-            }
-            case "allowNetwork": {
-                allowNetwork = true;
-                break;
-            }
-            case "jsonErrors": {
-                jsonErrors = true;
-                break;
-            }
-            case "root": {
-                const next = argv[i + 1];
-                if (!next) {
-                    throw new CliError({
-                        exitCode: 2,
-                        code: "E_USAGE",
-                        message: "Missing value after --root (expected repository path)",
-                    });
-                }
-                root = next;
-                i++;
-                break;
-            }
-            case "outputMode": {
-                const next = argv[i + 1];
-                if (!next) {
-                    throw new CliError({
-                        exitCode: 2,
-                        code: "E_USAGE",
-                        message: "Missing value after --output (expected text|json)",
-                    });
-                }
-                const normalized = next.trim().toLowerCase();
-                if (normalized !== "text" && normalized !== "json") {
-                    throw new CliError({
-                        exitCode: 2,
-                        code: "E_USAGE",
-                        message: `Invalid value for --output: ${next} (expected text|json)`,
-                    });
-                }
-                outputMode = normalized;
-                i++;
-                break;
-            }
-            default: {
-                // Exhaustive by construction; keep a defensive fallback.
-                rest.push(arg);
-                break;
-            }
-        }
-    }
-    return {
-        globals: { help, version, noUpdateCheck, root, jsonErrors, allowNetwork, outputMode },
-        rest,
-    };
-}
-const OUTPUT_MODE_ENV = "AGENTPLANE_OUTPUT";
-function resolveOutputMode(modeFromFlag) {
-    if (modeFromFlag)
-        return modeFromFlag;
-    const fromEnv = process.env[OUTPUT_MODE_ENV]?.trim().toLowerCase();
-    if (!fromEnv || fromEnv === "text")
-        return "text";
-    if (fromEnv === "json")
-        return "json";
-    throw new CliError({
-        exitCode: 2,
-        code: "E_USAGE",
-        message: `Invalid ${OUTPUT_MODE_ENV}: ${fromEnv} (expected text|json)`,
-    });
-}
-function chunkToString(chunk, encoding) {
-    if (typeof chunk === "string")
-        return chunk;
-    if (chunk instanceof Uint8Array)
-        return Buffer.from(chunk).toString(encoding);
-    return String(chunk);
-}
-async function runWithOutputMode(opts) {
-    if (opts.mode === "text")
-        return await opts.run();
-    const stdoutWrite = process.stdout.write.bind(process.stdout);
-    const stderrWrite = process.stderr.write.bind(process.stderr);
-    let stdout = "";
-    let stderr = "";
-    process.stdout.write = ((chunk, ...rest) => {
-        const encoding = typeof rest[0] === "string" ? rest[0] : undefined;
-        stdout += chunkToString(chunk, encoding);
-        const callback = rest.find((item) => typeof item === "function");
-        callback?.(null);
-        return true;
-    });
-    process.stderr.write = ((chunk, ...rest) => {
-        const encoding = typeof rest[0] === "string" ? rest[0] : undefined;
-        stderr += chunkToString(chunk, encoding);
-        const callback = rest.find((item) => typeof item === "function");
-        callback?.(null);
-        return true;
-    });
-    try {
-        const exitCode = await opts.run();
-        let parsed;
-        const trimmedStdout = stdout.trim();
-        if (trimmedStdout.length > 0) {
-            try {
-                parsed = JSON.parse(trimmedStdout);
-            }
-            catch {
-                parsed = undefined;
-            }
-        }
-        const payload = {
-            schema_version: 1,
-            mode: "agent_json_v1",
-            command: opts.command,
-            ok: exitCode === 0,
-            exit_code: exitCode,
-            stdout: trimmedStdout,
-            stderr: stderr.trim(),
-        };
-        if (parsed !== undefined) {
-            payload.data = parsed;
-        }
-        stdoutWrite(`${JSON.stringify(payload, null, 2)}\n`);
-        return exitCode;
-    }
-    finally {
-        process.stdout.write = stdoutWrite;
-        process.stderr.write = stderrWrite;
-    }
-}
-function matchCommandCatalog(tokens) {
-    let best = null;
-    for (const entry of COMMANDS) {
-        const id = entry.spec.id;
-        if (tokens.length < id.length)
-            continue;
-        let ok = true;
-        for (const [i, seg] of id.entries()) {
-            if (tokens[i] !== seg) {
-                ok = false;
-                break;
-            }
-        }
-        if (!ok)
-            continue;
-        if (!best || id.length > best.consumed) {
-            best = { entry, consumed: id.length };
-        }
-    }
-    return best;
-}
-function writeError(err, jsonErrors) {
-    const guidance = resolveErrorGuidance(err);
-    const contextReasonCode = typeof err.context?.reason_code === "string" ? String(err.context.reason_code) : undefined;
-    const reasonCode = contextReasonCode ?? guidance.nextAction?.reasonCode;
-    const reasonDecode = getReasonCodeMeta(reasonCode);
-    if (jsonErrors) {
-        process.stdout.write(`${formatJsonError(err, {
-            hint: guidance.hint,
-            nextAction: guidance.nextAction,
-            reasonDecode,
-        })}\n`);
-    }
-    else {
-        const header = `error [${err.code}]`;
-        if (err.message.includes("\n")) {
-            process.stderr.write(`${header}\n${err.message}\n`);
-        }
-        else {
-            process.stderr.write(`${header}: ${err.message}\n`);
-        }
-        if (guidance.hint) {
-            process.stderr.write(`hint: ${guidance.hint}\n`);
-        }
-        if (guidance.nextAction) {
-            process.stderr.write(`next_action: ${guidance.nextAction.command} (${guidance.nextAction.reason})\n`);
-        }
-        if (reasonDecode) {
-            process.stderr.write(`reason_code: ${reasonDecode.code} [${reasonDecode.category}] ${reasonDecode.summary}\n`);
-            process.stderr.write(`reason_action: ${reasonDecode.action}\n`);
-        }
-    }
-}
-const AGENTPLANE_HOME_ENV = "AGENTPLANE_HOME";
-function resolveAgentplaneHome() {
-    const overridden = process.env[AGENTPLANE_HOME_ENV]?.trim();
-    if (overridden)
-        return overridden;
-    return path.join(os.homedir(), ".agentplane");
-}
-function resolveErrorGuidance(err) {
-    const command = typeof err.context?.command === "string" ? err.context.command : undefined;
-    const reasonCode = typeof err.context?.reason_code === "string" ? String(err.context.reason_code) : undefined;
-    const usage = command ? `agentplane help ${command} --compact` : "agentplane help";
-    switch (err.code) {
-        case "E_USAGE": {
-            if (reasonCode === "sync_backend_mismatch") {
-                return {
-                    hint: "Configured backend id mismatch. Check active backend and retry with a matching id.",
-                    nextAction: {
-                        command: "agentplane config show",
-                        reason: "inspect active backend id before running sync",
-                        reasonCode: "sync_backend_mismatch",
-                    },
-                };
-            }
-            return {
-                hint: `See \`${usage}\` for usage.`,
-                nextAction: {
-                    command: usage,
-                    reason: "inspect required arguments and flags",
-                    reasonCode: "usage_help",
-                },
-            };
-        }
-        case "E_GIT": {
-            if (reasonCode === "reconcile_git_state_unreadable") {
-                return {
-                    hint: "Reconcile check could not read git state.",
-                    nextAction: {
-                        command: "git status --short --untracked-files=no",
-                        reason: "confirm repository state is readable before mutating commands",
-                        reasonCode: "reconcile_git_state_unreadable",
-                    },
-                };
-            }
-            if (command?.startsWith("branch")) {
-                return {
-                    hint: "Check git repo/branch; run `git branch` or pass --root <path>.",
-                    nextAction: {
-                        command: "git branch",
-                        reason: "inspect repository branch state",
-                        reasonCode: "git_branch_state",
-                    },
-                };
-            }
-            if (command === "guard commit" || command === "commit") {
-                return {
-                    hint: "Check git status/index; stage changes and retry.",
-                    nextAction: {
-                        command: "git status --short",
-                        reason: "inspect staged/unstaged changes before commit",
-                        reasonCode: "git_index_state",
-                    },
-                };
-            }
-            return {
-                hint: "Check git repo context; pass --root <path> if needed.",
-                nextAction: {
-                    command: "git status --short --untracked-files=no",
-                    reason: "confirm repository context and tracked changes",
-                    reasonCode: "git_context",
-                },
-            };
-        }
-        case "E_NETWORK": {
-            return {
-                hint: "Check network access and credentials.",
-                nextAction: {
-                    command: "agentplane preflight --json",
-                    reason: "recheck approvals and network requirements",
-                    reasonCode: "network_gate",
-                },
-            };
-        }
-        case "E_BACKEND": {
-            if (command?.includes("sync")) {
-                return {
-                    hint: "Check backend config under .agentplane/backends and retry.",
-                    nextAction: {
-                        command: "agentplane config show",
-                        reason: "verify backend config path and active settings",
-                        reasonCode: "backend_sync_config",
-                    },
-                };
-            }
-            return {
-                hint: "Check backend config under .agentplane/backends.",
-                nextAction: {
-                    command: "agentplane config show",
-                    reason: "inspect backend configuration",
-                    reasonCode: "backend_config",
-                },
-            };
-        }
-        case "E_VALIDATION": {
-            if (reasonCode === "reconcile_task_scan_failed" ||
-                reasonCode === "reconcile_task_scan_incomplete") {
-                return {
-                    hint: "Reconcile check failed due to task scan drift or parse/read errors.",
-                    nextAction: {
-                        command: "agentplane task list --strict-read",
-                        reason: "surface task scan/read failures before retrying mutating commands",
-                        reasonCode: reasonCode,
-                    },
-                };
-            }
-            return {
-                hint: "Fix invalid config/input shape and rerun.",
-                nextAction: {
-                    command: "agentplane preflight --json",
-                    reason: "pinpoint validation failure in one report",
-                    reasonCode: "validation_preflight",
-                },
-            };
-        }
-        default: {
-            return {};
-        }
-    }
-}
-const UPDATE_CHECK_PACKAGE = "agentplane";
-const UPDATE_CHECK_URL = `https://registry.npmjs.org/${UPDATE_CHECK_PACKAGE}/latest`;
-function parseVersionParts(version) {
-    const cleaned = version.trim().replace(/^v/i, "").split("+")[0] ?? "";
-    const [mainRaw, prereleaseRaw] = cleaned.split("-", 2);
-    const main = (mainRaw ?? "")
-        .split(".")
-        .filter((part) => part.length > 0)
-        .map((part) => {
-        const parsed = Number.parseInt(part, 10);
-        return Number.isFinite(parsed) ? parsed : 0;
-    });
-    return { main, prerelease: prereleaseRaw ? prereleaseRaw.trim() : null };
-}
-function compareVersions(left, right) {
-    const a = parseVersionParts(left);
-    const b = parseVersionParts(right);
-    const length = Math.max(a.main.length, b.main.length);
-    for (let i = 0; i < length; i++) {
-        const partA = a.main[i] ?? 0;
-        const partB = b.main[i] ?? 0;
-        if (partA !== partB)
-            return partA > partB ? 1 : -1;
-    }
-    if (a.prerelease === b.prerelease)
-        return 0;
-    if (a.prerelease === null)
-        return 1;
-    if (b.prerelease === null)
-        return -1;
-    return a.prerelease.localeCompare(b.prerelease);
-}
-function isTruthyEnv(value) {
-    if (!value)
-        return false;
-    const normalized = value.trim().toLowerCase();
-    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
-}
-async function maybeWarnOnUpdate(opts) {
-    if (opts.skip || opts.jsonErrors)
-        return;
-    if (isTruthyEnv(process.env.AGENTPLANE_NO_UPDATE_CHECK))
-        return;
-    const now = new Date();
-    const cachePath = resolveUpdateCheckCachePath(resolveAgentplaneHome());
-    const cache = await readUpdateCheckCache(cachePath);
-    if (cache && !shouldCheckNow(cache.checked_at, now, UPDATE_CHECK_TTL_MS)) {
-        if (cache.status === "ok" &&
-            cache.latest_version &&
-            compareVersions(cache.latest_version, opts.currentVersion) > 0) {
-            const message = `Update available: ${UPDATE_CHECK_PACKAGE} ${opts.currentVersion} → ${cache.latest_version}. Run: npm i -g ${UPDATE_CHECK_PACKAGE}@latest`;
-            process.stderr.write(`${warnMessage(message)}\n`);
-        }
-        return;
-    }
-    const result = await fetchLatestNpmVersion({
-        url: UPDATE_CHECK_URL,
-        timeoutMs: UPDATE_CHECK_TIMEOUT_MS,
-        etag: cache?.etag ?? null,
-    });
-    const nextCache = {
-        schema_version: UPDATE_CHECK_SCHEMA_VERSION,
-        checked_at: now.toISOString(),
-        latest_version: cache?.latest_version ?? null,
-        etag: cache?.etag ?? null,
-        status: "error",
-    };
-    if (result.status === "ok") {
-        nextCache.status = "ok";
-        nextCache.latest_version = result.latestVersion;
-        nextCache.etag = result.etag;
-    }
-    else if (result.status === "not_modified") {
-        nextCache.status = "not_modified";
-        nextCache.etag = result.etag ?? nextCache.etag;
-    }
-    try {
-        await writeUpdateCheckCache(cachePath, nextCache);
-    }
-    catch {
-        // Best-effort cache: ignore write failures.
-    }
-    const latest = result.status === "ok" ? result.latestVersion : nextCache.latest_version;
-    if (!latest || result.status === "error")
-        return;
-    if (compareVersions(latest, opts.currentVersion) <= 0)
-        return;
-    const message = `Update available: ${UPDATE_CHECK_PACKAGE} ${opts.currentVersion} → ${latest}. Run: npm i -g ${UPDATE_CHECK_PACKAGE}@latest`;
-    process.stderr.write(`${warnMessage(message)}\n`);
-}
 async function maybeResolveProject(opts) {
     try {
         return await resolveProject({

package/dist/cli/spec/docs-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-render.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/docs-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAmCjD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAsGnE"}
+{"version":3,"file":"docs-render.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/docs-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAgDjD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAsGnE"}

package/dist/cli/spec/docs-render.js

@@ -6,6 +6,7 @@ function escText(text) {
         .replaceAll("&", "&")
         .replaceAll("<", "&lt;")
         .replaceAll(">", "&gt;")
+        .replaceAll("*", String.raw `\*`)
         .replaceAll("`", "\\`");
 }
 function toAnchor(text) {
@@ -34,6 +35,18 @@ function formatDefaultValue(value) {
         return "[unserializable]";
     }
 }
+function normalizeGeneratedMdx(text) {
+    let normalized = text;
+    for (;;) {
+        const next = normalized
+            .replaceAll(/\n{3,}/g, "\n\n")
+            .replaceAll("```\n- ", "```\n\n- ")
+            .replaceAll(/\n(- [^\n]+)\n```/g, "\n$1\n\n```");
+        if (next === normalized)
+            return normalized;
+        normalized = next;
+    }
+}
 export function renderCliDocsMdx(specs) {
     const byGroup = new Map();
     for (const s of specs) {
@@ -121,5 +134,5 @@ export function renderCliDocsMdx(specs) {
         ...bodyLines,
         "",
     ];
-    return lines.join("\n");
+    return normalizeGeneratedMdx(lines.join("\n"));
 }

package/dist/commands/doctor/archive.d.ts

@@ -0,0 +1,4 @@
+export declare function checkDoneTaskCommitInvariants(repoRoot: string, opts?: {
+    fullArchive?: boolean;
+}): Promise<string[]>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/commands/doctor/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/archive.ts"],"names":[],"mappings":"AA6IA,wBAAsB,6BAA6B,CACjD,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACnC,OAAO,CAAC,MAAM,EAAE,CAAC,CA2FnB"}