agentplane 0.3.1 → 0.3.3

package/dist/cli/run-cli/error-guidance.js

@@ -0,0 +1,180 @@
+import os from "node:os";
+import path from "node:path";
+import { readDiagnosticContext } from "../../shared/diagnostics.js";
+import { formatJsonError } from "../../shared/errors.js";
+import { getReasonCodeMeta } from "../reason-codes.js";
+export 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, {
+            state: guidance.state,
+            likelyCause: guidance.likelyCause,
+            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.state) {
+            process.stderr.write(`state: ${guidance.state}\n`);
+        }
+        if (guidance.likelyCause) {
+            process.stderr.write(`likely_cause: ${guidance.likelyCause}\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";
+export function resolveAgentplaneHome() {
+    const overridden = process.env[AGENTPLANE_HOME_ENV]?.trim();
+    if (overridden)
+        return overridden;
+    return path.join(os.homedir(), ".agentplane");
+}
+function resolveErrorGuidance(err) {
+    const explicit = readDiagnosticContext(err.context);
+    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";
+    const withExplicit = (fallback) => ({
+        state: explicit.state ?? fallback.state,
+        likelyCause: explicit.likelyCause ?? fallback.likelyCause,
+        hint: explicit.hint ?? fallback.hint,
+        nextAction: explicit.nextAction ?? fallback.nextAction,
+    });
+    switch (err.code) {
+        case "E_USAGE": {
+            if (reasonCode === "sync_backend_mismatch") {
+                return withExplicit({
+                    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 withExplicit({
+                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 withExplicit({
+                    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 withExplicit({
+                    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 withExplicit({
+                    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 withExplicit({
+                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 withExplicit({
+                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 withExplicit({
+                    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 withExplicit({
+                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 withExplicit({
+                    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,
+                    },
+                });
+            }
+            return withExplicit({
+                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 withExplicit({});
+        }
+    }
+}

package/dist/cli/run-cli/globals.d.ts

@@ -0,0 +1,22 @@
+export type ParsedArgs = {
+    help: boolean;
+    version: boolean;
+    noUpdateCheck: boolean;
+    root?: string;
+    jsonErrors: boolean;
+    allowNetwork: boolean;
+    outputMode?: "text" | "json";
+};
+export type CliOutputMode = "text" | "json";
+export declare function prescanJsonErrors(argv: readonly string[]): boolean;
+export declare function parseGlobalArgs(argv: string[]): {
+    globals: ParsedArgs;
+    rest: string[];
+};
+export declare function resolveOutputMode(modeFromFlag: "text" | "json" | undefined): CliOutputMode;
+export declare function runWithOutputMode(opts: {
+    mode: CliOutputMode;
+    command: string;
+    run: () => Promise<number>;
+}): Promise<number>;
+//# sourceMappingURL=globals.d.ts.map

package/dist/cli/run-cli/globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/globals.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B,CAAC;AAgCF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAG5C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAsBlE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CA0FvF;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,CAU1F;AAQD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDlB"}

package/dist/cli/run-cli/globals.js

@@ -0,0 +1,197 @@
+import { CliError } from "../../shared/errors.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])));
+const OUTPUT_MODE_ENV = "AGENTPLANE_OUTPUT";
+export 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;
+}
+export 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;
+        }
+        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: {
+                rest.push(arg);
+                break;
+            }
+        }
+    }
+    return {
+        globals: { help, version, noUpdateCheck, root, jsonErrors, allowNetwork, outputMode },
+        rest,
+    };
+}
+export 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);
+}
+export 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;
+    }
+}

package/dist/cli/run-cli/update-warning.d.ts

@@ -0,0 +1,6 @@
+export declare function maybeWarnOnUpdate(opts: {
+    currentVersion: string;
+    skip: boolean;
+    jsonErrors: boolean;
+}): Promise<void>;
+//# sourceMappingURL=update-warning.d.ts.map

package/dist/cli/run-cli/update-warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-warning.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/update-warning.ts"],"names":[],"mappings":"AAwBA,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoDhB"}

package/dist/cli/run-cli/update-warning.js

@@ -0,0 +1,64 @@
+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 { resolveAgentplaneHome } from "./error-guidance.js";
+import { compareVersions } from "../../shared/version-compare.js";
+const UPDATE_CHECK_PACKAGE = "agentplane";
+const UPDATE_CHECK_URL = `https://registry.npmjs.org/${UPDATE_CHECK_PACKAGE}/latest`;
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+export 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`);
+}

package/dist/cli/run-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AA0lBA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6N5D"}
+{"version":3,"file":"run-cli.d.ts","sourceRoot":"","sources":["../../src/cli/run-cli.ts"],"names":[],"mappings":"AAqDA,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6N5D"}