harnery 0.22.1 → 0.24.0

package/src/commands/workflow.ts

@@ -1,12 +1,15 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
-import { workflowSubscriptionOnly } from "../core/config.ts";
+import { resolveBinName, workflowSubscriptionOnly } from "../core/config.ts";
 import { createBuiltinHarnessRegistry } from "../core/harnesses/index.ts";
 import { findCoordRoot } from "../core/hooks/resolve/coord-root.ts";
 import type { PolicyIsolation } from "../core/policy/index.ts";
 import { loadPolicyFile } from "../core/policy/index.ts";
-import type { WorkflowApprovalStatus } from "../core/workflow/approvals.ts";
+import type { WorkflowApproval, WorkflowApprovalStatus } from "../core/workflow/approvals.ts";
 import { WorkflowParkedError } from "../core/workflow/engine.ts";
+import type { WorkspaceProvider } from "../core/workflow/index.ts";
 
 /**
  * `workflow run <script>`: execute a workflow script — bounded, schema-gated,
@@ -28,6 +31,7 @@ interface WorkflowRunOpts {
   allowApiBilling?: boolean;
   policy?: string;
   isolation?: PolicyIsolation;
+  workspaceRoot?: string;
   approvalTo?: string;
   json?: boolean;
 }
@@ -47,6 +51,21 @@ interface WorkflowApprovalDecisionOpts {
   json?: boolean;
 }
 
+interface WorkflowIntegrationPrepareOpts {
+  policy?: string;
+  reviewer?: string;
+  reason?: string;
+  targetRoot?: string;
+  acceptUnknown?: string[];
+  approvalTo?: string;
+  json?: boolean;
+}
+
+interface WorkflowConfirmedMutationOpts {
+  yes?: boolean;
+  json?: boolean;
+}
+
 export function registerWorkflowCommand(program: Command, emit: EmitContext): void {
   const registry = createBuiltinHarnessRegistry();
   const harnesses = registry.ids();
@@ -89,6 +108,10 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
       "--isolation <mode>",
       "Host-created execution boundary: shared | worktree | sandbox | remote (default shared)",
     )
+    .option(
+      "--workspace-root <dir>",
+      "Explicit writable parent for the built-in local Git worktree provider (requires --isolation worktree)",
+    )
     .option("--approval-to <address>", "Address durable ASK requests (default: operator)")
     .option("--json", "Emit the full RunReport as JSON")
     .action(async (script: string, opts: WorkflowRunOpts) => {
@@ -117,6 +140,13 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         });
         process.exit(1);
       }
+      if (opts.workspaceRoot && opts.isolation !== "worktree") {
+        emit.error({
+          code: "bad_workspace_root",
+          message: "--workspace-root requires --isolation worktree",
+        });
+        process.exit(1);
+      }
       // Flag beats config; the two flags contradict each other by design.
       const subscriptionOnly = opts.subscriptionOnly || workflowSubscriptionOnly(coordRoot);
       if (subscriptionOnly && opts.allowApiBilling) {
@@ -129,7 +159,15 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         process.exit(1);
       }
       try {
-        const { runWorkflow } = await import("../core/workflow/engine.ts");
+        const { createLocalGitWorktreeProvider, runWorkflow } = await import(
+          "../core/workflow/index.ts"
+        );
+        const workspace = opts.workspaceRoot
+          ? {
+              provider: createLocalGitWorktreeProvider({ coordRoot }),
+              writableRoots: [resolve(opts.workspaceRoot)],
+            }
+          : undefined;
         const report = await runWorkflow(script, {
           coordRoot,
           spawners: registry.spawners(),
@@ -152,6 +190,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
           approvalMode: "park",
           approvalAddressee: opts.approvalTo,
           isolation: opts.isolation,
+          workspace,
           // CLI harness subprocesses inherit the host network. A policy that
           // forbids network must therefore deny dispatch unless a future host
           // adapter creates and declares a network-disabled boundary.
@@ -189,7 +228,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
             emit.text(
               `run ${err.runId} parked\napproval: ${err.approvalId}\n` +
                 `journal: ${err.journalPath}\n` +
-                `resume after resolution: harn workflow resume ${err.runId}\n`,
+                `resume after resolution: ${resolveBinName()} workflow resume ${err.runId}\n`,
             );
           }
           return;
@@ -220,14 +259,25 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
         process.exit(1);
       }
       try {
-        const { assertWorkflowRunResumable, runWorkflow } = await import(
-          "../core/workflow/index.ts"
-        );
+        const { assertWorkflowRunResumable, createLocalGitWorktreeProvider, runWorkflow } =
+          await import("../core/workflow/index.ts");
         const { manifest } = assertWorkflowRunResumable(coordRoot, runId);
+        const binding = manifest.execution.workspace_binding;
+        if (binding && binding.provider.id !== "local-git-worktree") {
+          throw new Error(
+            `workflow run ${runId} requires unavailable workspace provider ${binding.provider.id}`,
+          );
+        }
         const report = await runWorkflow(manifest.script.path, {
           coordRoot,
           spawners: registry.spawners(),
           resumeRunId: runId,
+          workspace: binding
+            ? {
+                provider: createLocalGitWorktreeProvider({ coordRoot }),
+                writableRoots: [binding.writable_root.configured],
+              }
+            : undefined,
           harnessEvidence: Object.fromEntries(
             registry
               .list()
@@ -281,6 +331,273 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
       }
     });
 
+  workflow
+    .command("workspace <run-id>")
+    .description("Show validated allocation, verification, integration, and cleanup state.")
+    .option("--json", "Emit the validated workspace status as JSON")
+    .action(async (runId: string, opts: { json?: boolean }) => {
+      const coordRoot = findCoordRoot();
+      if (!coordRoot) {
+        emit.error({
+          code: "no_coord_root",
+          message: "no .harnery/ coordination root found; run `init` first",
+        });
+        process.exit(1);
+      }
+      const { inspectWorkflowWorkspace, renderWorkflowWorkspaceStatus } = await import(
+        "../core/workflow/index.ts"
+      );
+      const inspection = inspectWorkflowWorkspace(coordRoot, runId);
+      if (!inspection.ok) {
+        emit.error({ code: "workflow_workspace_invalid", message: inspection.error });
+        process.exit(1);
+      }
+      if (opts.json) {
+        emit.config({ format: "json" });
+        emit.data(inspection.value);
+        return;
+      }
+      emit.text(renderWorkflowWorkspaceStatus(inspection.value));
+    });
+
+  workflow
+    .command("workspaces")
+    .description("List validated isolated and shared-compatibility workspace decisions.")
+    .option("--json", "Emit workspace inspections as JSON")
+    .action(async (opts: { json?: boolean }) => {
+      const coordRoot = findCoordRoot();
+      if (!coordRoot) {
+        emit.error({
+          code: "no_coord_root",
+          message: "no .harnery/ coordination root found; run `init` first",
+        });
+        process.exit(1);
+      }
+      const { listWorkflowWorkspaceInspections } = await import("../core/workflow/index.ts");
+      const inspections = listWorkflowWorkspaceInspections(coordRoot).filter(
+        (inspection) => !inspection.ok || inspection.value.selection !== "shared",
+      );
+      if (opts.json) {
+        emit.config({ format: "json" });
+        emit.data(inspections);
+        return;
+      }
+      if (inspections.length === 0) {
+        emit.text("no isolated or shared-compatibility workspace runs\n");
+        return;
+      }
+      emit.text(
+        `${inspections
+          .map((inspection) =>
+            inspection.ok
+              ? [
+                  inspection.value.run_id,
+                  inspection.value.selection,
+                  inspection.value.lifecycle.state,
+                  `verify=${inspection.value.verification.status}`,
+                  `integration=${inspection.value.integration.state}`,
+                  `cleanup=${inspection.value.cleanup.state}`,
+                ].join("\t")
+              : `${inspection.run_id}\tinvalid\t${inspection.error}`,
+          )
+          .join("\n")}\n`,
+      );
+    });
+
+  const integration = workflow
+    .command("integration")
+    .description("Prepare and apply proof-gated isolated-workspace integration.");
+
+  integration
+    .command("prepare <run-id>")
+    .description("Preview integration and write exact review and policy authority.")
+    .option("--policy <file>", "Current host policy JSON/JSONC for the Git mutation")
+    .option("--reviewer <name>", "Explicit reviewer for a standalone workflow")
+    .option("--reason <text>", "Reason recorded with the standalone review")
+    .option("--target-root <dir>", "Explicit target checkout (default: frozen source checkout)")
+    .option(
+      "--accept-unknown <code>",
+      "Accept one verification unknown by code (repeatable)",
+      collectOption,
+      [],
+    )
+    .option("--approval-to <address>", "Address a durable policy ASK request")
+    .option("--json", "Emit the durable integration plan as JSON")
+    .action(async (runId: string, opts: WorkflowIntegrationPrepareOpts) => {
+      const coordRoot = findCoordRoot();
+      if (!coordRoot) {
+        emit.error({
+          code: "no_coord_root",
+          message: "no .harnery/ coordination root found; run `init` first",
+        });
+        process.exit(1);
+      }
+      if (!opts.policy) {
+        emit.error({
+          code: "integration_policy_required",
+          message: "integration prepare requires --policy <file>",
+        });
+        process.exit(1);
+      }
+      if (opts.reason && !opts.reviewer) {
+        emit.error({
+          code: "integration_reviewer_required",
+          message: "--reason requires --reviewer <name>",
+        });
+        process.exit(1);
+      }
+      try {
+        const provider = await builtInProviderForRun(coordRoot, runId);
+        const { IntegrationPrepareParkedError, prepareIntegration } = await import(
+          "../core/workflow/index.ts"
+        );
+        try {
+          const plan = await prepareIntegration({
+            coordRoot,
+            runId,
+            provider,
+            policy: loadPolicyFile(opts.policy),
+            targetRoot: opts.targetRoot,
+            review: opts.reviewer ? { actor: opts.reviewer, reason: opts.reason } : undefined,
+            acceptedUnknowns: opts.acceptUnknown,
+            approvalAddressee: opts.approvalTo,
+          });
+          if (opts.json) {
+            emit.config({ format: "json" });
+            emit.data(plan);
+            return;
+          }
+          emit.text(
+            `integration plan ${plan.plan_id} authorized\n` +
+              `source: ${plan.provider_preview.source_commit}\n` +
+              `target: ${plan.provider_preview.target_ref} at ${plan.provider_preview.target_commit}\n` +
+              `changes: ${plan.provider_preview.changed_paths.length}\n` +
+              `apply: ${resolveBinName()} workflow integration apply ${runId} --yes\n`,
+          );
+        } catch (error) {
+          if (error instanceof IntegrationPrepareParkedError) {
+            if (opts.json) {
+              emit.config({ format: "json" });
+              emit.data({
+                status: "parked",
+                runId: error.runId,
+                planId: error.planId,
+                approvalId: error.approvalId,
+              });
+            } else {
+              emit.text(
+                `integration preparation parked\n` +
+                  `run: ${error.runId}\n` +
+                  `plan: ${error.planId}\n` +
+                  `approval: ${error.approvalId}\n` +
+                  `approve: ${resolveBinName()} workflow approvals approve ${error.approvalId}\n`,
+              );
+            }
+            return;
+          }
+          throw error;
+        }
+      } catch (error) {
+        emit.error({
+          code: "workflow_integration_prepare_failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+      }
+    });
+
+  integration
+    .command("apply <run-id>")
+    .description("Apply an authorized durable integration plan.")
+    .option("--yes", "Confirm the target-branch mutation")
+    .option("--json", "Emit the durable integration receipt as JSON")
+    .action(async (runId: string, opts: WorkflowConfirmedMutationOpts) => {
+      const coordRoot = findCoordRoot();
+      if (!coordRoot) {
+        emit.error({
+          code: "no_coord_root",
+          message: "no .harnery/ coordination root found; run `init` first",
+        });
+        process.exit(1);
+      }
+      if (!opts.yes) {
+        emit.error({
+          code: "integration_confirmation_required",
+          message: "integration apply changes the target branch; pass --yes to confirm",
+        });
+        process.exit(1);
+      }
+      try {
+        const provider = await builtInProviderForRun(coordRoot, runId);
+        const { applyIntegration } = await import("../core/workflow/index.ts");
+        const receipt = await applyIntegration({ coordRoot, runId, provider });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(receipt);
+          return;
+        }
+        emit.text(
+          `integration ${receipt.status}: ${receipt.target_ref} at ${receipt.target_commit}\n` +
+            `receipt: ${receipt.receipt_id}\n` +
+            `cleanup: ${resolveBinName()} workflow cleanup ${runId} --yes\n`,
+        );
+      } catch (error) {
+        emit.error({
+          code: "workflow_integration_apply_failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+      }
+    });
+
+  workflow
+    .command("cleanup <run-id>")
+    .description("Conservatively release a provider-owned isolated workspace.")
+    .option("--yes", "Confirm the worktree and provider-branch removal attempt")
+    .option("--json", "Emit the cleanup attempt or receipt as JSON")
+    .action(async (runId: string, opts: WorkflowConfirmedMutationOpts) => {
+      const coordRoot = findCoordRoot();
+      if (!coordRoot) {
+        emit.error({
+          code: "no_coord_root",
+          message: "no .harnery/ coordination root found; run `init` first",
+        });
+        process.exit(1);
+      }
+      if (!opts.yes) {
+        emit.error({
+          code: "cleanup_confirmation_required",
+          message: "workspace cleanup may remove a worktree and branch; pass --yes to confirm",
+        });
+        process.exit(1);
+      }
+      try {
+        const provider = await builtInProviderForRun(coordRoot, runId);
+        const { cleanupWorkspace } = await import("../core/workflow/index.ts");
+        const result = await cleanupWorkspace({ coordRoot, runId, provider });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+          return;
+        }
+        const receipt =
+          "receipt_id" in result && typeof result.receipt_id === "string"
+            ? `\nreceipt: ${result.receipt_id}`
+            : "";
+        const reason =
+          "reason" in result && typeof result.reason === "string"
+            ? `\nreason: ${result.reason}`
+            : "";
+        emit.text(`workspace cleanup ${result.status}: ${result.binding_id}${receipt}${reason}\n`);
+      } catch (error) {
+        emit.error({
+          code: "workflow_cleanup_failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+      }
+    });
+
   const approvals = workflow
     .command("approvals")
     .description("Inspect and resolve durable workflow policy approvals.");
@@ -382,7 +699,7 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
             emit.text(
               `${renderWorkflowApproval(resolved.approval)}` +
                 `${resolved.applied ? "decision recorded" : "decision already recorded"}\n` +
-                `resume: harn workflow resume ${resolved.approval.request.run_id}\n`,
+                approvalNextActionHint(coordRoot, resolved.approval),
             );
           }
         } catch (err) {
@@ -427,3 +744,44 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
       }
     });
 }
+
+async function builtInProviderForRun(coordRoot: string, runId: string): Promise<WorkspaceProvider> {
+  const { createLocalGitWorktreeProvider, readWorkflowRunManifest } = await import(
+    "../core/workflow/index.ts"
+  );
+  const manifest = readWorkflowRunManifest(coordRoot, runId);
+  const binding = manifest.execution.workspace_binding;
+  if (!binding) {
+    throw new Error(`workflow run ${runId} has no isolated workspace binding`);
+  }
+  if (binding.provider.id !== "local-git-worktree") {
+    throw new Error(
+      `workflow run ${runId} requires unavailable workspace provider ${binding.provider.id}`,
+    );
+  }
+  return createLocalGitWorktreeProvider({ coordRoot });
+}
+
+function collectOption(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+/** Next operator command after resolving an approval. Mid-run parks resume the
+ * workflow; integration prepare parks after the run is already terminal, so
+ * the durable plan is authorized by re-running prepare (resume would fail). */
+function approvalNextActionHint(coordRoot: string, approval: WorkflowApproval): string {
+  const bin = resolveBinName();
+  const runId = approval.request.run_id;
+  const integrationPlanPath = join(
+    coordRoot,
+    ".harnery",
+    "workflows",
+    runId,
+    "integration",
+    "plan.json",
+  );
+  if (existsSync(integrationPlanPath)) {
+    return `prepare: ${bin} workflow integration prepare ${runId}\n`;
+  }
+  return `resume: ${bin} workflow resume ${runId}\n`;
+}