agentplane 0.3.6 → 0.3.8

package/dist/cli/run-cli.test-helpers.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { gzipSync } from "node:zlib";
-import { afterAll, afterEach, beforeAll, beforeEach, vi } from "vitest";
+import { afterAll, afterEach, beforeAll, beforeEach, expect, vi } from "vitest";
 import { defaultConfig } from "@agentplaneorg/core";
 import { runCli } from "./run-cli.js";
 const execFileAsync = promisify(execFile);
@@ -142,6 +142,27 @@ export function captureStdIO() {
         },
     };
 }
+export function splitOutputLines(text) {
+    return text
+        .trim()
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter(Boolean);
+}
+export function parseAgentJsonEnvelope(stdout) {
+    return JSON.parse(stdout);
+}
+export function expectAgentJsonEnvelope(payload, opts) {
+    expect(payload.schema_version).toBe(1);
+    expect(payload.mode).toBe("agent_json_v1");
+    expect(payload.command).toBe(opts.command);
+    expect(payload.ok).toBe(opts.ok);
+    expect(payload.exit_code).toBe(opts.exitCode);
+    expect(Object.keys(payload)).toEqual(opts.hasData
+        ? ["schema_version", "mode", "command", "ok", "exit_code", "stdout", "stderr", "data"]
+        : ["schema_version", "mode", "command", "ok", "exit_code", "stdout", "stderr"]);
+    expect(Object.hasOwn(payload, "data")).toBe(opts.hasData ?? false);
+}
 export function silenceStdIO() {
     if (stdioSilenceDepth === 0) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -167,8 +188,11 @@ export function stubTaskBackend(overrides = {}) {
         capabilities: {
             canonical_source: "local",
             projection: "canonical",
+            projection_read_mode: "fallback",
             reads_from_projection_by_default: false,
             writes_task_readmes: true,
+            supports_task_revisions: true,
+            supports_revision_guarded_writes: true,
             may_access_network_on_read: false,
             may_access_network_on_write: false,
             supports_projection_refresh: false,
@@ -208,6 +232,51 @@ export async function writeDefaultConfig(root) {
     const configPath = path.join(agentplaneDir, "config.json");
     await writeFile(configPath, JSON.stringify(defaultConfig(), null, 2), "utf8");
 }
+export async function writeAndConfigureRoot() {
+    const root = await mkGitRepoRoot();
+    await writeDefaultConfig(root);
+    return root;
+}
+export async function approveTaskPlan(root, taskId) {
+    await runCliSilent([
+        "task",
+        "plan",
+        "set",
+        taskId,
+        "--text",
+        "1) Do the work\n2) Verify the work",
+        "--updated-by",
+        "ORCHESTRATOR",
+        "--root",
+        root,
+    ]);
+    await runCliSilent([
+        "task",
+        "plan",
+        "approve",
+        taskId,
+        "--by",
+        "USER",
+        "--note",
+        "OK",
+        "--root",
+        root,
+    ]);
+}
+export async function recordVerificationOk(root, taskId) {
+    await runCliSilent([
+        "verify",
+        taskId,
+        "--ok",
+        "--by",
+        "REVIEWER",
+        "--note",
+        "Ok to integrate",
+        "--quiet",
+        "--root",
+        root,
+    ]);
+}
 export async function writeConfig(root, config) {
     const agentplaneDir = path.join(root, ".agentplane");
     await mkdir(agentplaneDir, { recursive: true });
@@ -292,10 +361,7 @@ export async function createRecipeArchive(opts) {
                 run_profile: {
                     mode: "analysis",
                     sandbox: "workspace-write",
-                    network: false,
-                    requires_human_approval: false,
                     writes_artifacts_to: ["logs/", "reports/"],
-                    expected_exit_contract: "report",
                 },
                 file: "scenarios/recipe-scenario.json",
             },
@@ -332,6 +398,21 @@ export async function createRecipeArchive(opts) {
         id: "RECIPE_SCENARIO",
         summary: "Recipe scenario",
         goal: "Preview installed tasks.",
+        task_template: {
+            title: "Recipe scenario task",
+            description: "Materialize a task from the recipe scenario.",
+            owner: "CODER",
+            priority: "med",
+            tags: ["code", "recipes"],
+            verify: ["bunx vitest run packages/agentplane/src/cli/run-cli.scenario.test.ts"],
+            doc: {
+                summary: "Recipe-backed task execution.",
+                scope: "Run the scenario without task materialization heuristics.",
+                plan: "1. Materialize the task. 2. Execute the shared runner.",
+                verify_steps: "1. Run scenario execution tests.",
+                rollback_plan: "Revert the generated task and runner artifacts.",
+            },
+        },
         inputs: [{ name: "task_id", type: "string" }],
         outputs: [{ name: "report", type: "html" }],
         steps: [{ tool: "RECIPE_TOOL" }],
@@ -446,6 +527,11 @@ export async function createUnsafeRecipeArchive(opts) {
         id: "RECIPE_SCENARIO",
         summary: "Recipe scenario",
         goal: "Exercise unsafe archive validation.",
+        task_template: {
+            title: "Unsafe archive task",
+            description: "Validate unsafe archive handling.",
+            owner: "CODER",
+        },
         inputs: [],
         outputs: [],
         steps: [{ tool: "RECIPE_TOOL" }],

package/dist/cli/spec/help.d.ts

@@ -1,10 +1,18 @@
 import type { CommandHandler, CommandSpec } from "./spec.js";
-import type { CommandRegistry } from "./registry.js";
 export type HelpParsed = {
     cmd: string[];
     compact: boolean;
     json: boolean;
 };
+export type HelpRegistryView = {
+    list(): readonly {
+        spec: CommandSpec;
+    }[];
+    match(tokens: readonly string[]): {
+        spec: CommandSpec;
+        consumed: number;
+    } | null;
+};
 export declare const helpSpec: CommandSpec<HelpParsed>;
-export declare function makeHelpHandler(registry: CommandRegistry): CommandHandler<HelpParsed>;
+export declare function makeHelpHandler(registry: HelpRegistryView): CommandHandler<HelpParsed>;
 //# sourceMappingURL=help.d.ts.map

package/dist/cli/spec/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAQ7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAwB5C,CAAC;AAEF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAAC,UAAU,CAAC,CAuCrF"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAY7D,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,IAAI,SAAS;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,EAAE,CAAC;IACzC,KAAK,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAClF,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAwB5C,CAAC;AAEF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,GAAG,cAAc,CAAC,UAAU,CAAC,CAuCtF"}

package/dist/cli/spec/help.js

@@ -1,6 +1,8 @@
+import { createCliEmitter } from "../output.js";
 import { renderCommandHelpJson, renderCommandHelpText, renderRegistryHelpText, } from "./help-render.js";
 import { suggestOne } from "./suggest.js";
 import { usageError } from "./errors.js";
+const output = createCliEmitter();
 export const helpSpec = {
     id: ["help"],
     group: "Core",
@@ -12,7 +14,7 @@ export const helpSpec = {
         { kind: "boolean", name: "json", description: "Emit JSON help (success output)." },
     ],
     examples: [
-        { cmd: "agentplane help", why: "List commands available in cli2 registry." },
+        { cmd: "agentplane help", why: "List commands available in the CLI command catalog." },
         { cmd: "agentplane help task new --compact", why: "Show compact help for a command." },
         { cmd: "agentplane help task new --json", why: "Show JSON help for a command." },
     ],
@@ -31,10 +33,10 @@ export function makeHelpHandler(registry) {
         if (p.cmd.length === 0) {
             if (p.json) {
                 const out = specs.map((s) => renderCommandHelpJson(s));
-                process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+                output.json(out);
             }
             else {
-                process.stdout.write(`${renderRegistryHelpText(specs)}\n`);
+                output.line(renderRegistryHelpText(specs));
             }
             return Promise.resolve(0);
         }
@@ -51,14 +53,14 @@ export function makeHelpHandler(registry) {
             });
         }
         if (p.json) {
-            process.stdout.write(`${JSON.stringify(renderCommandHelpJson(match.spec), null, 2)}\n`);
+            output.json(renderCommandHelpJson(match.spec));
             return Promise.resolve(0);
         }
         const text = renderCommandHelpText(match.spec, {
             compact: p.compact,
             includeHeader: true,
         });
-        process.stdout.write(`${text}\n`);
+        output.line(text);
         return Promise.resolve(0);
     };
 }

package/dist/cli/spec/registry.d.ts

@@ -1,12 +1,38 @@
 import type { CommandHandler, CommandId, CommandSpec, MatchResult } from "./spec.js";
+export type CommandGraphMatch<T> = {
+    value: T;
+    consumed: number;
+};
+export declare class CommandGraph<T> {
+    private readonly getId;
+    private readonly root;
+    private readonly values;
+    constructor(getId: (value: T) => CommandId);
+    add(value: T): void;
+    list(): readonly T[];
+    lookup(id: CommandId): T | null;
+    match(tokens: readonly string[]): CommandGraphMatch<T> | null;
+    directChildren(parentId?: CommandId): readonly T[];
+    directChildSegments(parentId?: CommandId): readonly string[];
+    private resolveNode;
+}
 export declare class CommandRegistry {
-    private readonly entries;
+    private readonly graph;
     register<TParsed>(spec: CommandSpec<TParsed>, handler: CommandHandler<TParsed>): void;
     list(): readonly {
         spec: CommandSpec;
         handler: CommandHandler;
     }[];
     match(tokens: readonly string[]): MatchResult | null;
+    lookup(id: CommandId): {
+        spec: CommandSpec;
+        handler: CommandHandler;
+    } | null;
+    directChildren(parentId?: CommandId): readonly {
+        spec: CommandSpec;
+        handler: CommandHandler;
+    }[];
+    directChildSegments(parentId?: CommandId): readonly string[];
 }
 export declare function formatCommandId(id: CommandId): string;
 //# sourceMappingURL=registry.d.ts.map

package/dist/cli/spec/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIrF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAIf;IAET,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC;IAgB9E,IAAI,IAAI,SAAS;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,EAAE;IAIjE,KAAK,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,GAAG,IAAI;CAoBrD;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAErD"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAUrF,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAWF,qBAAa,YAAY,CAAC,CAAC;IAQb,OAAO,CAAC,QAAQ,CAAC,KAAK;IAPlC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAGnB;IAEF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;gBAEL,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,SAAS;IAE3D,GAAG,CAAC,KAAK,EAAE,CAAC;IAwBZ,IAAI,IAAI,SAAS,CAAC,EAAE;IAIpB,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,CAAC,GAAG,IAAI;IAI/B,KAAK,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI;IAiB7D,cAAc,CAAC,QAAQ,GAAE,SAAc,GAAG,SAAS,CAAC,EAAE;IAQtD,mBAAmB,CAAC,QAAQ,GAAE,SAAc,GAAG,SAAS,MAAM,EAAE;IAMhE,OAAO,CAAC,WAAW;CASpB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuD;IAE7E,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC;IAe9E,IAAI,IAAI,SAAS;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,EAAE;IAIjE,KAAK,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,GAAG,IAAI;IAOpD,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAI5E,cAAc,CACZ,QAAQ,GAAE,SAAc,GACvB,SAAS;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,EAAE;IAI5D,mBAAmB,CAAC,QAAQ,GAAE,SAAc,GAAG,SAAS,MAAM,EAAE;CAGjE;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAErD"}

package/dist/cli/spec/registry.js

@@ -1,45 +1,118 @@
 import { CliError } from "../../shared/errors.js";
+function getRegistryEntryId(entry) {
+    return entry.spec.id;
+}
+export class CommandGraph {
+    getId;
+    root = {
+        id: [],
+        children: new Map(),
+    };
+    values = [];
+    constructor(getId) {
+        this.getId = getId;
+    }
+    add(value) {
+        const id = this.getId(value);
+        let node = this.root;
+        for (const segment of id) {
+            const existing = node.children.get(segment);
+            if (existing) {
+                node = existing;
+                continue;
+            }
+            const child = {
+                id: [...node.id, segment],
+                children: new Map(),
+            };
+            node.children.set(segment, child);
+            node = child;
+        }
+        if (node.value !== undefined) {
+            throw new Error(`Duplicate command id registered: ${formatCommandId(id)}`);
+        }
+        node.value = value;
+        this.values.push(value);
+    }
+    list() {
+        return this.values;
+    }
+    lookup(id) {
+        return this.resolveNode(id)?.value ?? null;
+    }
+    match(tokens) {
+        let node = this.root;
+        let best = null;
+        for (const [index, token] of tokens.entries()) {
+            const next = node.children.get(token);
+            if (!next)
+                break;
+            node = next;
+            if (node.value !== undefined) {
+                best = {
+                    value: node.value,
+                    consumed: index + 1,
+                };
+            }
+        }
+        return best;
+    }
+    directChildren(parentId = []) {
+        const parent = this.resolveNode(parentId);
+        if (!parent)
+            return [];
+        return [...parent.children.values()].flatMap((child) => child.value === undefined ? [] : [child.value]);
+    }
+    directChildSegments(parentId = []) {
+        const parent = this.resolveNode(parentId);
+        if (!parent)
+            return [];
+        return [...parent.children.keys()].toSorted((left, right) => left.localeCompare(right));
+    }
+    resolveNode(id) {
+        let node = this.root;
+        for (const segment of id) {
+            const next = node.children.get(segment);
+            if (!next)
+                return null;
+            node = next;
+        }
+        return node;
+    }
+}
 export class CommandRegistry {
-    entries = [];
+    graph = new CommandGraph(getRegistryEntryId);
     register(spec, handler) {
         const key = formatCommandId(spec.id);
-        if (this.entries.some((e) => formatCommandId(e.id) === key)) {
+        if (this.graph.lookup(spec.id)) {
             throw new CliError({
                 exitCode: 1,
                 code: "E_INTERNAL",
                 message: `Duplicate command id registered: ${key}`,
             });
         }
-        this.entries.push({
-            id: spec.id,
+        this.graph.add({
             spec: spec,
             handler: handler,
         });
     }
     list() {
-        return this.entries;
+        return this.graph.list();
     }
     match(tokens) {
-        // Longest-prefix match by id segments.
-        let best = null;
-        for (const e of this.entries) {
-            const id = e.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 = { spec: e.spec, handler: e.handler, consumed: id.length };
-            }
-        }
-        return best;
+        const match = this.graph.match(tokens);
+        return match
+            ? { spec: match.value.spec, handler: match.value.handler, consumed: match.consumed }
+            : null;
+    }
+    lookup(id) {
+        return this.graph.lookup(id);
+    }
+    directChildren(parentId = []) {
+        return this.graph.directChildren(parentId);
+    }
+    directChildSegments(parentId = []) {
+        return this.graph.directChildSegments(parentId);
     }
 }
 export function formatCommandId(id) {

package/dist/commands/backend/sync.command.d.ts

@@ -1,13 +1,15 @@
 import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+import { type GroupCommandParsed } from "../../cli/group-command.js";
 import type { CommandContext } from "../shared/task-backend.js";
-import { type BackendSyncParsed } from "../backend.js";
-type BackendRootParsed = {
-    cmd: string[];
-};
-export declare const backendSpec: CommandSpec<BackendRootParsed>;
+import { type BackendInspectParsed, type BackendMigrateCanonicalStateParsed, type BackendSyncParsed } from "../backend.js";
+export declare const backendSpec: CommandSpec<GroupCommandParsed>;
 export declare const backendSyncSpec: CommandSpec<BackendSyncParsed>;
-declare function runBackendRootGroup(_ctx: CommandCtx, p: BackendRootParsed): Promise<number>;
+export declare const backendMigrateCanonicalStateSpec: CommandSpec<BackendMigrateCanonicalStateParsed>;
+export declare const backendInspectSpec: CommandSpec<BackendInspectParsed>;
+declare function runBackendRootGroup(_ctx: CommandCtx, p: GroupCommandParsed): Promise<number>;
 export declare function makeRunBackendHandler(_getCtx: (cmd: string) => Promise<CommandContext>): typeof runBackendRootGroup;
 export declare function makeRunBackendSyncHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: BackendSyncParsed) => Promise<number>;
+export declare function makeRunBackendInspectHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: BackendInspectParsed) => Promise<number>;
+export declare function makeRunBackendMigrateCanonicalStateHandler(getCtx: (cmd: string) => Promise<CommandContext>): (ctx: CommandCtx, p: BackendMigrateCanonicalStateParsed) => Promise<number>;
 export {};
 //# sourceMappingURL=sync.command.d.ts.map

package/dist/commands/backend/sync.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.command.d.ts","sourceRoot":"","sources":["../../../src/commands/backend/sync.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAItE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7E,KAAK,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,iBAAiB,CAQtD,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAuC1D,CAAC;AAEF,iBAAS,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUpF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,8BAEtF;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC1E,KAAK,UAAU,EAAE,GAAG,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,CAStE"}
+{"version":3,"file":"sync.command.d.ts","sourceRoot":"","sources":["../../../src/commands/backend/sync.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,kCAAkC,EACvC,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CASvD,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAuC1D,CAAC;AAEF,eAAO,MAAM,gCAAgC,EAAE,WAAW,CAAC,kCAAkC,CAoB5F,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAoBhE,CAAC;AAEF,iBAAe,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ3F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,8BAEtF;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC1E,KAAK,UAAU,EAAE,GAAG,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,CAStE;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC7E,KAAK,UAAU,EAAE,GAAG,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAAC,CASzE;AAED,wBAAgB,0CAA0C,CACxD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAElC,KAAK,UAAU,EAAE,GAAG,kCAAkC,KAAG,OAAO,CAAC,MAAM,CAAC,CASvF"}

package/dist/commands/backend/sync.command.js

@@ -1,15 +1,14 @@
 import { COMMAND_SNIPPETS } from "../../cli/command-snippets.js";
-import { usageError } from "../../cli/spec/errors.js";
-import { suggestOne } from "../../cli/spec/suggest.js";
-import { cmdBackendSyncParsed } from "../backend.js";
+import { loadDirectSubcommandNames, parseGroupCommand, throwGroupCommandUsage, } from "../../cli/group-command.js";
+import { cmdBackendInspectParsed, cmdBackendMigrateCanonicalStateParsed, cmdBackendSyncParsed, } from "../backend.js";
 export const backendSpec = {
     id: ["backend"],
     group: "Backend",
     summary: "Backend-related operations.",
-    description: "This is a command group. Use a subcommand such as `agentplane backend sync ...`.",
+    description: "This is a command group. Use a subcommand such as `agentplane backend sync ...`, `agentplane backend inspect ...`, or `agentplane backend migrate-canonical-state ...`.",
     args: [{ name: "cmd", required: false, variadic: true, valueHint: "<cmd>" }],
     examples: [{ cmd: COMMAND_SNIPPETS.backendSync.pullLocal, why: "Sync the backend." }],
-    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+    parse: (raw) => parseGroupCommand(raw),
 };
 export const backendSyncSpec = {
     id: ["backend", "sync"],
@@ -51,15 +50,55 @@ export const backendSyncSpec = {
         quiet: raw.opts.quiet === true,
     }),
 };
-function runBackendRootGroup(_ctx, p) {
-    const input = p.cmd.join(" ");
-    const suggestion = suggestOne(input, ["sync"]);
-    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
-    const msg = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
-    throw usageError({
-        spec: backendSyncSpec,
-        message: `${msg}${suffix}`,
-        context: { command: "backend sync" },
+export const backendMigrateCanonicalStateSpec = {
+    id: ["backend", "migrate-canonical-state"],
+    group: "Backend",
+    summary: "Backfill canonical_state for issues in the configured backend.",
+    args: [{ name: "id", required: true, valueHint: "<id>", description: "Configured backend id." }],
+    options: [
+        { kind: "boolean", name: "yes", default: false, description: "Auto-approve network access." },
+        { kind: "boolean", name: "quiet", default: false, description: "Reduce output noise." },
+    ],
+    examples: [
+        {
+            cmd: "agentplane backend migrate-canonical-state redmine --yes",
+            why: "Backfill structured canonical_state into legacy Redmine issues.",
+        },
+    ],
+    parse: (raw) => ({
+        backendId: String(raw.args.id),
+        yes: raw.opts.yes === true,
+        quiet: raw.opts.quiet === true,
+    }),
+};
+export const backendInspectSpec = {
+    id: ["backend", "inspect"],
+    group: "Backend",
+    summary: "Inspect visible backend readiness facts without mutating remote state.",
+    args: [{ name: "id", required: true, valueHint: "<id>", description: "Configured backend id." }],
+    options: [
+        { kind: "boolean", name: "yes", default: false, description: "Auto-approve network access." },
+        { kind: "boolean", name: "quiet", default: false, description: "Reduce output noise." },
+    ],
+    examples: [
+        {
+            cmd: "agentplane backend inspect redmine --yes",
+            why: "Inspect visible Redmine custom fields and canonical_state readiness without remote writes.",
+        },
+    ],
+    parse: (raw) => ({
+        backendId: String(raw.args.id),
+        yes: raw.opts.yes === true,
+        quiet: raw.opts.quiet === true,
+    }),
+};
+async function runBackendRootGroup(_ctx, p) {
+    throwGroupCommandUsage({
+        spec: backendSpec,
+        cmd: p.cmd,
+        subcommands: await loadDirectSubcommandNames(["backend"]),
+        command: "backend",
+        contextCommand: "backend",
     });
 }
 export function makeRunBackendHandler(_getCtx) {
@@ -76,3 +115,25 @@ export function makeRunBackendSyncHandler(getCtx) {
         });
     };
 }
+export function makeRunBackendInspectHandler(getCtx) {
+    return async (ctx, p) => {
+        const commandCtx = await getCtx("backend inspect");
+        return await cmdBackendInspectParsed({
+            ctx: commandCtx,
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            flags: p,
+        });
+    };
+}
+export function makeRunBackendMigrateCanonicalStateHandler(getCtx) {
+    return async (ctx, p) => {
+        const commandCtx = await getCtx("backend migrate-canonical-state");
+        return await cmdBackendMigrateCanonicalStateParsed({
+            ctx: commandCtx,
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride,
+            flags: p,
+        });
+    };
+}

package/dist/commands/backend.d.ts

@@ -13,6 +13,16 @@ export type SyncParsed = {
     yes: boolean;
     quiet: boolean;
 };
+export type BackendMigrateCanonicalStateParsed = {
+    backendId: string;
+    yes: boolean;
+    quiet: boolean;
+};
+export type BackendInspectParsed = {
+    backendId: string;
+    yes: boolean;
+    quiet: boolean;
+};
 export declare function cmdBackendSyncParsed(opts: {
     ctx?: CommandContext;
     cwd: string;
@@ -25,4 +35,16 @@ export declare function cmdSyncParsed(opts: {
     rootOverride?: string;
     flags: SyncParsed;
 }): Promise<number>;
+export declare function cmdBackendMigrateCanonicalStateParsed(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    flags: BackendMigrateCanonicalStateParsed;
+}): Promise<number>;
+export declare function cmdBackendInspectParsed(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    flags: BackendInspectParsed;
+}): Promise<number>;
 //# sourceMappingURL=backend.d.ts.map

package/dist/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAGnF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAInF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kCAAkC,GAAG;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB;AAED,wBAAsB,qCAAqC,CAAC,IAAI,EAAE;IAChE,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,kCAAkC,CAAC;CAC3C,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDlB;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,oBAAoB,CAAC;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgElB"}