agentplane 0.3.15 → 0.3.17

package/dist/commands/task/finish-close.js

@@ -0,0 +1,119 @@
+import { resolveBaseBranch } from "@agentplaneorg/core";
+import { readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { exitCodeForError } from "../../cli/exit-codes.js";
+import { CliError } from "../../shared/errors.js";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+import { gitBranchExists, gitCurrentBranch } from "../shared/git-ops.js";
+import { taskCloseAlreadyRecordedOnBase } from "./close-tail-state.js";
+import { createTaskCloseCommit } from "./finish-shared.js";
+export async function clearDirectWorkLockIfMatches(opts) {
+    const lockPath = path.join(opts.agentplaneDir, "cache", "direct-work.json");
+    try {
+        const text = await readFile(lockPath, "utf8");
+        const parsed = JSON.parse(text);
+        const lockTaskId = parsed && typeof parsed.task_id === "string" ? parsed.task_id : null;
+        if (!lockTaskId)
+            return;
+        if (!opts.taskIds.includes(lockTaskId))
+            return;
+        await rm(lockPath, { force: true });
+    }
+    catch {
+        // best-effort
+    }
+}
+export async function ensureFinishRunsOnBaseBranch(opts) {
+    if (opts.ctx.config.workflow_mode !== "branch_pr")
+        return;
+    const baseBranch = await resolveBaseBranch({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+        cliBaseOpt: opts.baseBranchOverride ?? null,
+        mode: opts.ctx.config.workflow_mode,
+    });
+    if (!baseBranch) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_USAGE"),
+            code: "E_USAGE",
+            message: "Base branch could not be resolved (use `agentplane branch base set` or --base).",
+        });
+    }
+    const currentBranch = await gitCurrentBranch(opts.ctx.resolvedProject.gitRoot);
+    if (currentBranch === baseBranch)
+        return;
+    throw new CliError({
+        exitCode: exitCodeForError("E_GIT"),
+        code: "E_GIT",
+        message: `finish must run on base branch ${baseBranch} in branch_pr mode ` +
+            `(current: ${currentBranch}); integrate first or reconcile from the base checkout.`,
+    });
+}
+async function readHeadCommitHash(gitRoot) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+        cwd: gitRoot,
+        env: gitEnv(),
+    });
+    const hash = stdout.trim();
+    if (!hash) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_GIT"),
+            code: "E_GIT",
+            message: "Failed to resolve HEAD while preparing a branch_pr close tail.",
+        });
+    }
+    return hash;
+}
+function branchPrCloseBranchName(taskId, headCommitHash) {
+    return `task-close/${taskId}/${headCommitHash.slice(0, 12)}`;
+}
+export async function materializeBranchPrCloseTail(opts) {
+    const gitRoot = opts.ctx.resolvedProject.gitRoot;
+    const baseBranch = await gitCurrentBranch(gitRoot);
+    const alreadyClosedOnBase = await taskCloseAlreadyRecordedOnBase({
+        gitRoot,
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        baseBranch,
+    });
+    if (alreadyClosedOnBase) {
+        return null;
+    }
+    const headCommitHash = await readHeadCommitHash(gitRoot);
+    const closeBranch = branchPrCloseBranchName(opts.taskId, headCommitHash);
+    const branchExists = await gitBranchExists(gitRoot, closeBranch);
+    await execFileAsync("git", branchExists ? ["checkout", closeBranch] : ["checkout", "-b", closeBranch], { cwd: gitRoot, env: gitEnv() });
+    let checkoutError = null;
+    try {
+        await createTaskCloseCommit({
+            ctx: opts.ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+            baseBranchOverride: opts.baseBranchOverride,
+            quiet: opts.quiet,
+            closeUnstageOthers: opts.closeUnstageOthers,
+            allowPolicy: opts.allowPolicy,
+        });
+    }
+    finally {
+        try {
+            await execFileAsync("git", ["checkout", baseBranch], {
+                cwd: gitRoot,
+                env: gitEnv(),
+            });
+        }
+        catch (error) {
+            checkoutError = error;
+        }
+    }
+    if (checkoutError) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_GIT"),
+            code: "E_GIT",
+            message: `Created ${closeBranch} but failed to return to ${baseBranch}; ` +
+                "inspect the local checkout before continuing.",
+        });
+    }
+    return closeBranch;
+}

package/dist/commands/task/finish-command.d.ts

@@ -0,0 +1,3 @@
+import type { FinishOptions } from "./finish-types.js";
+export declare function cmdFinish(options: FinishOptions): Promise<number>;
+//# sourceMappingURL=finish-command.d.ts.map

package/dist/commands/task/finish-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-command.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish-command.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CA8CvE"}

package/dist/commands/task/finish-command.js

@@ -0,0 +1,56 @@
+import { mapBackendError } from "../../cli/error-map.js";
+import { CliError } from "../../shared/errors.js";
+import { emitTraceEvent } from "../../shared/trace-events.js";
+import { ensureActionApproved } from "../shared/approval-requirements.js";
+import { ensureReconciledBeforeMutation } from "../shared/reconcile-check.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { ensureFinishRunsOnBaseBranch } from "./finish-close.js";
+import { executeFinishPlan } from "./finish-execute.js";
+import { resolveFinishExecutionPlan } from "./finish-plan.js";
+export async function cmdFinish(options) {
+    try {
+        const ctx = options.ctx ??
+            (await loadCommandContext({ cwd: options.cwd, rootOverride: options.rootOverride ?? null }));
+        emitTraceEvent({
+            component: "task-finish",
+            event: "finish_started",
+            details: { task_count: options.taskIds.length, backend: ctx.backendId },
+        });
+        await ensureReconciledBeforeMutation({ ctx, command: "finish" });
+        await ensureFinishRunsOnBaseBranch({
+            ctx,
+            cwd: options.cwd,
+            rootOverride: options.rootOverride,
+            baseBranchOverride: options.baseBranchOverride,
+        });
+        if (options.force) {
+            await ensureActionApproved({
+                action: "force_action",
+                config: ctx.config,
+                yes: options.yes === true,
+                reason: "finish --force",
+            });
+        }
+        const plan = resolveFinishExecutionPlan({ ctx, options });
+        const code = await executeFinishPlan({ ctx, options, plan });
+        emitTraceEvent({
+            component: "task-finish",
+            event: "finish_completed",
+            details: { task_count: options.taskIds.length, exit_code: code },
+        });
+        return code;
+    }
+    catch (err) {
+        emitTraceEvent({
+            component: "task-finish",
+            event: "finish_failed",
+            details: {
+                task_count: options.taskIds.length,
+                error: err instanceof Error ? err.name : "UnknownError",
+            },
+        });
+        if (err instanceof CliError)
+            throw err;
+        throw mapBackendError(err, { command: "finish", root: options.rootOverride ?? null });
+    }
+}

package/dist/commands/task/finish-execute.d.ts

@@ -0,0 +1,8 @@
+import type { CommandContext } from "../shared/task-backend.js";
+import type { FinishExecutionPlan, FinishOptions } from "./finish-types.js";
+export declare function executeFinishPlan(opts: {
+    ctx: CommandContext;
+    options: FinishOptions;
+    plan: FinishExecutionPlan;
+}): Promise<number>;
+//# sourceMappingURL=finish-execute.d.ts.map

package/dist/commands/task/finish-execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-execute.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish-execute.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAmBhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE5E,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,cAAc,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,EAAE,mBAAmB,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CAuGlB"}

package/dist/commands/task/finish-execute.js

@@ -0,0 +1,272 @@
+import { invalidValueMessage } from "../../cli/output.js";
+import { CliError } from "../../shared/errors.js";
+import { collectTaskIncidents, renderIncidentCollectionPlanOutcome } from "../incidents/shared.js";
+import { createTaskCloseCommit, existingCommitInfo, loadTaskForFinish, writeFinishedTasks, } from "./finish-shared.js";
+import { clearDirectWorkLockIfMatches, materializeBranchPrCloseTail } from "./finish-close.js";
+import { appendFinishStructuredFinding } from "./finish-findings.js";
+import { defaultCommitEmojiForStatus, enforceStatusCommitPolicy, prepareTaskTransitionComment, readCommitInfo, runTaskTransitionCommentCommit, } from "./shared.js";
+export async function executeFinishPlan(opts) {
+    const { ctx, options, plan } = opts;
+    await appendStructuredFindingIfNeeded({ ctx, options, plan });
+    const loadedState = await loadFinishTasks({ ctx, options, plan });
+    await collectIncidentsForLoadedTasks({
+        ctx,
+        taskIds: options.taskIds,
+        loadedTasks: loadedState.loadedTasks,
+        write: false,
+    });
+    const tasksMissingCommit = loadedState.loadedTasks
+        .filter(({ task }) => !existingCommitInfo(task))
+        .map(({ taskId }) => taskId);
+    if (!options.commitFromComment && !options.commit && tasksMissingCommit.length > 0) {
+        throw new CliError({
+            exitCode: 2,
+            code: "E_USAGE",
+            message: "finish requires --commit <hash> or existing task commit metadata on every task; implicit HEAD fallback was removed.",
+        });
+    }
+    if (options.commitFromComment || plan.statusCommitRequested) {
+        enforceStatusCommitPolicy({
+            policy: ctx.config.status_commit_policy,
+            action: "finish",
+            confirmed: options.confirmStatusCommit,
+            quiet: options.quiet,
+            statusFrom: loadedState.primaryStatusFrom ?? "UNKNOWN",
+            statusTo: "DONE",
+        });
+    }
+    const taskCommitInfo = await resolveTaskCommitInfo({
+        ctx,
+        options,
+        plan,
+        primaryStatusFrom: loadedState.primaryStatusFrom,
+        primaryTag: loadedState.primaryTag,
+    });
+    await writeFinishedTasks({
+        ctx,
+        loadedTasks: loadedState.loadedTasks,
+        metaTaskId: plan.metaTaskId,
+        author: options.author,
+        body: options.body,
+        force: options.force,
+        resultProvided: plan.resultProvided,
+        resultSummary: plan.resultSummary,
+        riskLevel: plan.riskLevel,
+        breaking: plan.breaking,
+        taskCommitInfo,
+    });
+    const incidentOutcome = await collectIncidentsForLoadedTasks({
+        ctx,
+        taskIds: options.taskIds,
+        loadedTasks: loadedState.loadedTasks,
+        write: true,
+    });
+    const promotedIncidents = incidentOutcome.plans.reduce((sum, candidate) => sum + candidate.promotable.length, 0);
+    await finalizeCloseTail({
+        ctx,
+        options,
+        plan,
+        primaryTaskId: plan.primaryTaskId,
+        promotedIncidents,
+    });
+    if (ctx.config.workflow_mode === "direct") {
+        await clearDirectWorkLockIfMatches({
+            agentplaneDir: ctx.resolvedProject.agentplaneDir,
+            taskIds: options.taskIds,
+        });
+    }
+    if (!options.quiet) {
+        const incidentPlan = incidentOutcome.plans[0] ?? {
+            candidates: [],
+            skipped: [],
+            promotable: [],
+            duplicates: [],
+        };
+        process.stdout.write(`${renderIncidentCollectionPlanOutcome(incidentPlan, {
+            wrote: promotedIncidents > 0,
+            context: "finish",
+            promotedIds: incidentPlan.promotable.map((item) => item.entry.id),
+            registryPaths: incidentOutcome.registryPaths[0] ?? [],
+            taskId: options.taskIds[0] ?? null,
+        })}\n`);
+        process.stdout.write("finished\n");
+    }
+    return 0;
+}
+async function appendStructuredFindingIfNeeded(opts) {
+    const { ctx, options, plan } = opts;
+    if (!plan.finishFinding || !plan.primaryTaskId)
+        return;
+    await loadTaskForFinish({
+        ctx,
+        store: plan.store,
+        useStore: plan.useStore,
+        taskId: plan.primaryTaskId,
+        taskCount: options.taskIds.length,
+        metaTaskId: plan.metaTaskId,
+        resultProvided: plan.resultProvided,
+        resultSummary: plan.resultSummary,
+        force: options.force,
+        capturePrimaryLifecycleMeta: false,
+    });
+    await appendFinishStructuredFinding({
+        ctx,
+        taskId: plan.primaryTaskId,
+        author: options.author,
+        finding: plan.finishFinding,
+    });
+}
+async function loadFinishTasks(opts) {
+    const { ctx, options, plan } = opts;
+    let primaryStatusFrom = null;
+    let primaryTag = null;
+    const loadedTasks = [];
+    for (const taskId of options.taskIds) {
+        const loaded = await loadTaskForFinish({
+            ctx,
+            store: plan.store,
+            useStore: plan.useStore,
+            taskId,
+            taskCount: options.taskIds.length,
+            metaTaskId: plan.metaTaskId,
+            resultProvided: plan.resultProvided,
+            resultSummary: plan.resultSummary,
+            force: options.force,
+            capturePrimaryLifecycleMeta: taskId === plan.primaryTaskId,
+        });
+        loadedTasks.push(loaded.loaded);
+        if (taskId === plan.primaryTaskId) {
+            primaryStatusFrom = loaded.primaryStatusFrom;
+            primaryTag = loaded.primaryTag;
+        }
+    }
+    return { loadedTasks, primaryStatusFrom, primaryTag };
+}
+async function collectIncidentsForLoadedTasks(opts) {
+    const plans = [];
+    const registryPaths = [];
+    for (const taskId of opts.taskIds) {
+        const loadedTask = opts.loadedTasks.find((candidate) => candidate.taskId === taskId) ?? null;
+        const collected = await collectTaskIncidents({
+            ctx: opts.ctx,
+            taskId,
+            task: loadedTask?.task ?? null,
+            write: opts.write,
+        });
+        plans.push(collected.plan);
+        registryPaths.push(collected.registryPaths);
+    }
+    return { plans, registryPaths };
+}
+async function resolveTaskCommitInfo(opts) {
+    const { ctx, options, plan, primaryStatusFrom, primaryTag } = opts;
+    let taskCommitInfo = options.commit
+        ? await readCommitInfo(ctx.resolvedProject.gitRoot, options.commit)
+        : null;
+    const preparedComment = options.commitFromComment || plan.statusCommitRequested
+        ? prepareTaskTransitionComment({
+            body: options.body,
+            enabled: true,
+            config: ctx.config,
+        })
+        : null;
+    if (options.commitFromComment) {
+        if (typeof options.commitEmoji === "string" && options.commitEmoji.trim() !== "✅") {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: invalidValueMessage("--commit-emoji", options.commitEmoji, "✅ (finish commits must use a checkmark)"),
+            });
+        }
+        taskCommitInfo = await runTaskTransitionCommentCommit({
+            ctx,
+            cwd: options.cwd,
+            rootOverride: options.rootOverride,
+            taskId: plan.primaryTaskId,
+            primaryTag: primaryTag ?? "meta",
+            author: options.author,
+            statusFrom: primaryStatusFrom ?? undefined,
+            statusTo: "DONE",
+            commentBody: options.body,
+            formattedComment: preparedComment?.formattedComment ?? null,
+            emoji: options.commitEmoji ?? defaultCommitEmojiForStatus("DONE"),
+            allow: options.commitAllow,
+            autoAllow: false,
+            allowTasks: options.commitAllowTasks,
+            requireClean: options.commitRequireClean,
+            quiet: options.quiet,
+            progressMessage: "creating commit from verification comment",
+            resolveExecutorAgent: true,
+        });
+    }
+    if (plan.statusCommitRequested) {
+        if (typeof options.statusCommitEmoji === "string" &&
+            options.statusCommitEmoji.trim() !== "✅") {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: invalidValueMessage("--status-commit-emoji", options.statusCommitEmoji, "✅ (finish commits must use a checkmark)"),
+            });
+        }
+        await runTaskTransitionCommentCommit({
+            ctx,
+            cwd: options.cwd,
+            rootOverride: options.rootOverride,
+            taskId: plan.primaryTaskId,
+            primaryTag: primaryTag ?? "meta",
+            author: options.author,
+            statusFrom: primaryStatusFrom ?? undefined,
+            statusTo: "DONE",
+            commentBody: options.body,
+            formattedComment: preparedComment?.formattedComment ?? null,
+            emoji: options.statusCommitEmoji ?? defaultCommitEmojiForStatus("DONE"),
+            allow: options.statusCommitAllow,
+            autoAllow: false,
+            allowTasks: true,
+            requireClean: options.statusCommitRequireClean,
+            quiet: options.quiet,
+            progressMessage: "creating status commit",
+            resolveExecutorAgent: true,
+        });
+    }
+    return taskCommitInfo;
+}
+async function finalizeCloseTail(opts) {
+    const { ctx, options, plan, primaryTaskId, promotedIncidents } = opts;
+    if (!plan.shouldCloseCommit || !primaryTaskId)
+        return;
+    if (!options.quiet) {
+        process.stdout.write("task marked DONE; creating deterministic close commit\n");
+    }
+    const closeUnstageOthers = options.closeCommit === true && options.closeUnstageOthers === true;
+    if (ctx.config.workflow_mode === "branch_pr") {
+        const closeBranch = await materializeBranchPrCloseTail({
+            ctx,
+            cwd: options.cwd,
+            rootOverride: options.rootOverride,
+            taskId: primaryTaskId,
+            baseBranchOverride: options.baseBranchOverride,
+            quiet: options.quiet,
+            closeUnstageOthers,
+            allowPolicy: promotedIncidents > 0,
+        });
+        if (options.quiet)
+            return;
+        if (closeBranch) {
+            process.stdout.write(`branch_pr close tail ready on ${closeBranch}; push that branch and open it with task hosted-close-pr if hosted automation does not create the closure PR for you.\n`);
+            return;
+        }
+        process.stdout.write("branch_pr close tail already exists on base; skipping local task-close branch materialization.\n");
+        return;
+    }
+    await createTaskCloseCommit({
+        ctx,
+        cwd: options.cwd,
+        rootOverride: options.rootOverride,
+        taskId: primaryTaskId,
+        baseBranchOverride: options.baseBranchOverride,
+        quiet: options.quiet,
+        closeUnstageOthers,
+        allowPolicy: promotedIncidents > 0,
+    });
+}

package/dist/commands/task/finish-findings.d.ts

@@ -0,0 +1,20 @@
+import type { CommandContext } from "../shared/task-backend.js";
+export type FinishStructuredFindingInput = {
+    observation: string;
+    impact: string;
+    resolution: string;
+    localOnly: boolean;
+    repoFixable: boolean;
+    incidentScope?: string;
+    incidentTags: string[];
+    incidentMatch: string[];
+    incidentAdvice?: string;
+    incidentRule?: string;
+};
+export declare function appendFinishStructuredFinding(opts: {
+    ctx: CommandContext;
+    taskId: string;
+    author: string;
+    finding: FinishStructuredFindingInput;
+}): Promise<void>;
+//# sourceMappingURL=finish-findings.d.ts.map

package/dist/commands/task/finish-findings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-findings.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish-findings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE,MAAM,MAAM,4BAA4B,GAAG;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAsB,6BAA6B,CAAC,IAAI,EAAE;IACxD,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,4BAA4B,CAAC;CACvC,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB"}

package/dist/commands/task/finish-findings.js

@@ -0,0 +1,27 @@
+import { applyTaskMutation } from "../shared/task-mutation.js";
+import { buildStructuredFindingMutationPlan } from "./findings.js";
+export async function appendFinishStructuredFinding(opts) {
+    await applyTaskMutation({
+        ctx: opts.ctx,
+        taskId: opts.taskId,
+        build: (current) => {
+            const plan = buildStructuredFindingMutationPlan({
+                current,
+                config: opts.ctx.config,
+                observation: opts.finding.observation,
+                impact: opts.finding.impact,
+                resolution: opts.finding.resolution,
+                promote: !opts.finding.localOnly,
+                external: !opts.finding.localOnly,
+                fixability: opts.finding.repoFixable ? "repo-fixable" : null,
+                incidentScope: opts.finding.incidentScope,
+                incidentTags: opts.finding.incidentTags,
+                incidentMatch: opts.finding.incidentMatch,
+                incidentAdvice: opts.finding.incidentAdvice,
+                incidentRule: opts.finding.incidentRule,
+                updatedBy: opts.author,
+            });
+            return plan ? { intents: plan.intents } : null;
+        },
+    });
+}

package/dist/commands/task/finish-plan.d.ts

@@ -0,0 +1,7 @@
+import { type CommandContext } from "../shared/task-backend.js";
+import type { FinishExecutionPlan, FinishOptions } from "./finish-types.js";
+export declare function resolveFinishExecutionPlan(opts: {
+    ctx: CommandContext;
+    options: FinishOptions;
+}): FinishExecutionPlan;
+//# sourceMappingURL=finish-plan.d.ts.map

package/dist/commands/task/finish-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-plan.d.ts","sourceRoot":"","sources":["../../../src/commands/task/finish-plan.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAI3F,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEd,MAAM,mBAAmB,CAAC;AAE3B,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,cAAc,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB,GAAG,mBAAmB,CAqJtB"}