agentplane 0.3.6 → 0.3.8

package/dist/cli/run-cli/commands/core/preflight.js

@@ -0,0 +1,286 @@
+import { loadConfig, resolveProject } from "@agentplaneorg/core";
+import { loadTaskBackend } from "../../../../backends/task-backend.js";
+import { GitContext } from "../../../../commands/shared/git-context.js";
+import { gitCurrentBranch } from "../../../../commands/shared/git-ops.js";
+import { dedupeStrings } from "../../../../shared/strings.js";
+import { isWorkflowEnforcementDisabled, validateWorkflowAtPath, workflowEnforcementEnvHint, } from "../../../../workflow-runtime/index.js";
+import { renderQuickstart } from "../../../command-guide.js";
+import { createCliEmitter } from "../../../output.js";
+import { wrapCommand } from "../wrap-command.js";
+const output = createCliEmitter();
+function compactError(err) {
+    if (err instanceof Error) {
+        const first = (err.message ?? "").split("\n", 1)[0] ?? "";
+        return first.trim() || err.name;
+    }
+    return String(err);
+}
+function probeYesNo(probe) {
+    return probe.ok ? "yes" : "no";
+}
+function probeValueOrUnknown(probe) {
+    return probe.ok && probe.value !== undefined ? String(probe.value) : "unknown";
+}
+function inferWorkflowMode(config) {
+    if (!config)
+        return "unknown";
+    return config.workflow_mode === "direct" || config.workflow_mode === "branch_pr"
+        ? config.workflow_mode
+        : "unknown";
+}
+function inferApprovals(config) {
+    if (!config?.agents?.approvals) {
+        return {
+            require_plan: "unknown",
+            require_verify: "unknown",
+            require_network: "unknown",
+        };
+    }
+    const approvals = config.agents.approvals;
+    return {
+        require_plan: approvals.require_plan,
+        require_verify: approvals.require_verify,
+        require_network: approvals.require_network,
+    };
+}
+async function buildPreflightReport(opts) {
+    const nextActions = [];
+    const harnessHealthReasons = [];
+    const quickstartText = renderQuickstart();
+    const quickstartLoaded = {
+        ok: quickstartText.trim().length > 0,
+        error: quickstartText.trim().length > 0 ? undefined : "quickstart renderer returned empty output",
+    };
+    let resolved = null;
+    try {
+        resolved = await resolveProject({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+    }
+    catch (err) {
+        nextActions.push({
+            command: "agentplane init",
+            reason: `project not resolved (${compactError(err)})`,
+        });
+    }
+    let config = null;
+    let configLoaded = { ok: false, error: "project not resolved" };
+    if (resolved) {
+        try {
+            const loaded = await loadConfig(resolved.agentplaneDir);
+            config = loaded.config;
+            configLoaded = { ok: true };
+        }
+        catch (err) {
+            const message = compactError(err);
+            configLoaded = { ok: false, error: message };
+            nextActions.push({
+                command: "agentplane config show",
+                reason: `config failed validation (${message})`,
+            });
+            harnessHealthReasons.push("config_unavailable");
+        }
+    }
+    let taskListLoaded = {
+        ok: false,
+        error: opts.mode === "quick" ? "skipped in quick mode" : "project not resolved",
+    };
+    if (opts.mode === "full" && resolved) {
+        try {
+            const loaded = await loadTaskBackend({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+            });
+            const tasks = await loaded.backend.listTasks();
+            taskListLoaded = { ok: true, count: tasks.length };
+        }
+        catch (err) {
+            const message = compactError(err);
+            taskListLoaded = { ok: false, error: message };
+            nextActions.push({
+                command: "agentplane task list",
+                reason: `task backend unavailable (${message})`,
+            });
+            harnessHealthReasons.push("task_backend_unavailable");
+        }
+    }
+    let workflowLoaded = { ok: false, error: "project not resolved" };
+    if (resolved) {
+        if (isWorkflowEnforcementDisabled()) {
+            workflowLoaded = {
+                ok: true,
+                error: `workflow checks disabled via ${workflowEnforcementEnvHint()}`,
+            };
+        }
+        else {
+            try {
+                const workflowValidation = await validateWorkflowAtPath(resolved.gitRoot);
+                workflowLoaded = workflowValidation.ok
+                    ? { ok: true }
+                    : {
+                        ok: false,
+                        error: workflowValidation.diagnostics
+                            .filter((diagnostic) => diagnostic.severity === "ERROR")
+                            .map((diagnostic) => `${diagnostic.code}:${diagnostic.path}`)
+                            .join(", "),
+                    };
+                if (!workflowValidation.ok) {
+                    harnessHealthReasons.push("workflow_contract_invalid");
+                    nextActions.push({
+                        command: "agentplane workflow build --validate --dry-run",
+                        reason: "workflow contract is invalid",
+                    });
+                }
+            }
+            catch (err) {
+                const message = compactError(err);
+                workflowLoaded = { ok: false, error: message };
+                harnessHealthReasons.push("workflow_contract_unreadable");
+                nextActions.push({
+                    command: "agentplane workflow build --validate --dry-run",
+                    reason: `cannot validate workflow (${message})`,
+                });
+            }
+        }
+    }
+    let workingTree = {
+        ok: false,
+        error: "project not resolved",
+    };
+    let branch = {
+        ok: false,
+        error: "project not resolved",
+    };
+    if (resolved) {
+        try {
+            const git = new GitContext({ gitRoot: resolved.gitRoot });
+            const [staged, unstagedTracked] = await Promise.all([
+                git.statusStagedPaths(),
+                git.statusUnstagedTrackedPaths(),
+            ]);
+            workingTree = { ok: true, value: staged.length === 0 && unstagedTracked.length === 0 };
+            if (!workingTree.value) {
+                harnessHealthReasons.push("working_tree_dirty");
+                nextActions.push({
+                    command: "git status --short --untracked-files=no",
+                    reason: "tracked changes detected",
+                });
+            }
+        }
+        catch (err) {
+            const message = compactError(err);
+            workingTree = { ok: false, error: message };
+            harnessHealthReasons.push("working_tree_unreadable");
+            nextActions.push({
+                command: "git status --short --untracked-files=no",
+                reason: `cannot inspect git status (${message})`,
+            });
+        }
+        try {
+            branch = { ok: true, value: await gitCurrentBranch(resolved.gitRoot) };
+        }
+        catch (err) {
+            branch = { ok: false, error: compactError(err) };
+        }
+    }
+    return {
+        mode: opts.mode,
+        project_detected: resolved !== null,
+        config_loaded: configLoaded,
+        quickstart_loaded: quickstartLoaded,
+        workflow_loaded: workflowLoaded,
+        task_list_loaded: taskListLoaded,
+        working_tree_clean_tracked: workingTree,
+        current_branch: branch,
+        workflow_mode: inferWorkflowMode(config),
+        approvals: inferApprovals(config),
+        harness_health: {
+            status: harnessHealthReasons.length === 0 ? "ok" : "warn",
+            reasons: dedupeStrings(harnessHealthReasons),
+        },
+        outside_repo_needed: false,
+        next_actions: nextActions,
+    };
+}
+export const preflightSpec = {
+    id: ["preflight"],
+    group: "Core",
+    summary: "Run aggregated preflight checks and print a deterministic readiness report.",
+    options: [
+        {
+            kind: "string",
+            name: "mode",
+            valueHint: "<quick|full>",
+            choices: ["quick", "full"],
+            default: "quick",
+            description: "Preflight depth. quick skips backend task-list probe; full includes backend readiness.",
+        },
+        {
+            kind: "boolean",
+            name: "full",
+            default: false,
+            description: "Shortcut for --mode full.",
+        },
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit machine-readable JSON report.",
+        },
+    ],
+    examples: [
+        { cmd: "agentplane preflight --json", why: "Produce one-shot agent-readable preflight." },
+        {
+            cmd: "agentplane preflight --json --mode full",
+            why: "Run full preflight including backend task-list probe.",
+        },
+    ],
+    parse: (raw) => ({
+        json: raw.opts.json === true,
+        mode: raw.opts.full === true ? "full" : (raw.opts.mode ?? "quick"),
+    }),
+};
+async function cmdPreflight(opts) {
+    return wrapCommand({ command: "preflight", rootOverride: opts.rootOverride }, async () => {
+        const report = await buildPreflightReport({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            mode: opts.mode,
+        });
+        if (opts.json) {
+            output.json(report);
+            return 0;
+        }
+        const lines = [
+            "Preflight Summary",
+            `- mode: ${report.mode}`,
+            `- project detected: ${report.project_detected ? "yes" : "no"}`,
+            `- config loaded: ${probeYesNo(report.config_loaded)}`,
+            `- quickstart loaded: ${probeYesNo(report.quickstart_loaded)}`,
+            `- workflow loaded: ${probeYesNo(report.workflow_loaded)}`,
+            `- task list loaded: ${probeYesNo(report.task_list_loaded)}`,
+            `- working tree clean (tracked-only): ${probeValueOrUnknown(report.working_tree_clean_tracked)}`,
+            `- current git branch: ${probeValueOrUnknown(report.current_branch)}`,
+            `- workflow_mode: ${report.workflow_mode}`,
+            `- harness engeneering health: ${report.harness_health.status}`,
+        ];
+        if (report.harness_health.reasons.length > 0) {
+            lines.push(`  - reasons: ${report.harness_health.reasons.join(", ")}`);
+        }
+        lines.push("- approval gates:", `  - require_plan: ${String(report.approvals.require_plan)}`, `  - require_verify: ${String(report.approvals.require_verify)}`, `  - require_network: ${String(report.approvals.require_network)}`, "- outside-repo: not needed");
+        if (report.next_actions.length > 0) {
+            lines.push("Next actions:");
+            for (const action of report.next_actions) {
+                lines.push(`- ${action.command}: ${action.reason}`);
+            }
+        }
+        output.lines(lines);
+        return 0;
+    });
+}
+export const runPreflight = (ctx, parsed) => {
+    return cmdPreflight({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride,
+        json: parsed.json,
+        mode: parsed.mode,
+    });
+};

package/dist/cli/run-cli/commands/core/quickstart.d.ts

@@ -0,0 +1,8 @@
+import type { CommandHandler, CommandSpec } from "../../../spec/spec.js";
+type QuickstartParsed = {
+    json: boolean;
+};
+export declare const quickstartSpec: CommandSpec<QuickstartParsed>;
+export declare const runQuickstart: CommandHandler<QuickstartParsed>;
+export {};
+//# sourceMappingURL=quickstart.d.ts.map

package/dist/cli/run-cli/commands/core/quickstart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/core/quickstart.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAMzE,KAAK,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAcxD,CAAC;AA4BF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC"}

package/dist/cli/run-cli/commands/core/quickstart.js

@@ -0,0 +1,43 @@
+import { renderQuickstart } from "../../../command-guide.js";
+import { createCliEmitter } from "../../../output.js";
+import { wrapCommand } from "../wrap-command.js";
+const output = createCliEmitter();
+export const quickstartSpec = {
+    id: ["quickstart"],
+    group: "Core",
+    summary: "Print the canonical agent bootstrap path and startup guidance.",
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit compact machine-readable output for agent runtimes.",
+        },
+    ],
+    examples: [{ cmd: "agentplane quickstart", why: "Show quickstart." }],
+    parse: (raw) => ({ json: raw.opts.json === true }),
+};
+async function cmdQuickstart(opts) {
+    return wrapCommand({ command: "quickstart", rootOverride: opts.rootOverride }, () => {
+        const text = renderQuickstart();
+        if (opts.json) {
+            const lines = text
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            output.json({
+                source_of_truth: {
+                    workflow_policy: "AGENTS.md|CLAUDE.md",
+                    cli_syntax: "quickstart/role output",
+                },
+                lines,
+            });
+            return 0;
+        }
+        output.line(text);
+        return 0;
+    });
+}
+export const runQuickstart = (ctx, parsed) => {
+    return cmdQuickstart({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, json: parsed.json });
+};

package/dist/cli/run-cli/commands/core/role.d.ts

@@ -0,0 +1,9 @@
+import type { CommandHandler, CommandSpec } from "../../../spec/spec.js";
+type RoleParsed = {
+    role: string;
+    json: boolean;
+};
+export declare const roleSpec: CommandSpec<RoleParsed>;
+export declare const runRole: CommandHandler<RoleParsed>;
+export {};
+//# sourceMappingURL=role.d.ts.map

package/dist/cli/run-cli/commands/core/role.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/core/role.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAazE,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAe5C,CAAC;AA+GF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAO9C,CAAC"}

package/dist/cli/run-cli/commands/core/role.js

@@ -0,0 +1,128 @@
+import { getRoleSupplementLines, listRoles, renderRole } from "../../../command-guide.js";
+import { createCliEmitter } from "../../../output.js";
+import { usageError } from "../../../spec/errors.js";
+import { dedupeStrings } from "../../../../shared/strings.js";
+import { listAgentProfileIds, normalizeRoleId, readAgentProfile, toRoleProfileGuide, } from "./agent-profiles.js";
+import { wrapCommand } from "../wrap-command.js";
+const output = createCliEmitter();
+export const roleSpec = {
+    id: ["role"],
+    group: "Core",
+    summary: "Show role-specific workflow guidance.",
+    args: [{ name: "role", required: true, valueHint: "<role>" }],
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit compact machine-readable role payload.",
+        },
+    ],
+    examples: [{ cmd: "agentplane role ORCHESTRATOR", why: "Show ORCHESTRATOR guide." }],
+    parse: (raw) => ({ role: String(raw.args.role ?? ""), json: raw.opts.json === true }),
+};
+async function cmdRole(opts) {
+    return wrapCommand({ command: "role", rootOverride: opts.rootOverride }, async () => {
+        const roleRaw = opts.role.trim();
+        if (!roleRaw) {
+            throw usageError({
+                spec: roleSpec,
+                command: "role",
+                message: "Missing required argument: role",
+            });
+        }
+        const normalizedRole = normalizeRoleId(roleRaw);
+        const agentProfile = await readAgentProfile({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            roleId: normalizedRole,
+        });
+        const normalizedProfile = agentProfile
+            ? toRoleProfileGuide({
+                filename: agentProfile.filename,
+                roleId: normalizedRole,
+                profile: agentProfile.profile,
+            })
+            : null;
+        const guide = renderRole(normalizedRole, { profile: normalizedProfile });
+        if (!guide && !agentProfile) {
+            const builtin = listRoles();
+            const agentIds = await listAgentProfileIds({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride,
+            });
+            const discovered = agentIds ? agentIds.ids : [];
+            const availableList = dedupeStrings([...builtin, ...discovered]).toSorted();
+            const available = availableList.length > 0 ? `\nAvailable roles: ${availableList.join(", ")}` : "";
+            throw usageError({
+                spec: roleSpec,
+                command: "role",
+                message: `Unknown role: ${roleRaw}.${available}`,
+            });
+        }
+        if (guide) {
+            if (opts.json) {
+                const payload = {
+                    role: normalizedRole,
+                    guide: guide
+                        .split("\n")
+                        .map((line) => line.trim())
+                        .filter((line) => line.length > 0),
+                };
+                const supplementLines = getRoleSupplementLines(normalizedRole);
+                if (supplementLines) {
+                    payload.builtin_guide = supplementLines;
+                }
+                if (agentProfile) {
+                    payload.agent_profile = {
+                        filename: agentProfile.filename,
+                        profile: agentProfile.profile,
+                    };
+                }
+                output.json(payload);
+                return 0;
+            }
+            output.line(guide);
+            return 0;
+        }
+        if (!agentProfile) {
+            throw usageError({
+                spec: roleSpec,
+                command: "role",
+                message: `Unknown role: ${roleRaw}.`,
+            });
+        }
+        const block = renderRole(normalizedRole, { profile: normalizedProfile });
+        if (!block) {
+            throw usageError({
+                spec: roleSpec,
+                command: "role",
+                message: `Unknown role: ${roleRaw}.`,
+            });
+        }
+        if (opts.json) {
+            output.json({
+                role: normalizedRole,
+                guide: block
+                    .split("\n")
+                    .map((line) => line.trim())
+                    .filter((line) => line.length > 0),
+                agent_profile: {
+                    filename: agentProfile.filename,
+                    profile: agentProfile.profile,
+                },
+            });
+            return 0;
+        }
+        output.line(block);
+        return 0;
+    });
+}
+export const runRole = (ctx, parsed) => {
+    return cmdRole({
+        cwd: ctx.cwd,
+        rootOverride: ctx.rootOverride,
+        role: parsed.role,
+        json: parsed.json,
+    });
+};

package/dist/cli/run-cli/commands/core.d.ts

@@ -1,25 +1,5 @@
-import type { CommandHandler, CommandSpec } from "../../spec/spec.js";
-import type { RunDeps } from "../command-catalog.js";
-type QuickstartParsed = {
-    json: boolean;
-};
-export declare const quickstartSpec: CommandSpec<QuickstartParsed>;
-export declare const runQuickstart: CommandHandler<QuickstartParsed>;
-type PreflightMode = "quick" | "full";
-type PreflightParsed = {
-    json: boolean;
-    mode: PreflightMode;
-};
-export declare const preflightSpec: CommandSpec<PreflightParsed>;
-export declare const runPreflight: CommandHandler<PreflightParsed>;
-type RoleParsed = {
-    role: string;
-    json: boolean;
-};
-export declare const roleSpec: CommandSpec<RoleParsed>;
-export declare const runRole: CommandHandler<RoleParsed>;
-type AgentsParsed = Record<string, never>;
-export declare const agentsSpec: CommandSpec<AgentsParsed>;
-export declare function makeRunAgentsHandler(deps: RunDeps): CommandHandler<AgentsParsed>;
-export {};
+export { agentsSpec, makeRunAgentsHandler } from "./core/agents.js";
+export { preflightSpec, runPreflight } from "./core/preflight.js";
+export { quickstartSpec, runQuickstart } from "./core/quickstart.js";
+export { roleSpec, runRole } from "./core/role.js";
 //# sourceMappingURL=core.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAatE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,KAAK,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAcxD,CAAC;AA6BF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC;AAEF,KAAK,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AACtC,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAkP9D,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAuCtD,CAAC;AAiDF,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,eAAe,CAExD,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAe5C,CAAC;AA4OF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAE9C,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CA0FhF"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}