@treeseed/sdk 0.4.6 → 0.4.8

package/dist/workflow/operations.js

@@ -1,23 +1,21 @@
-import { readFileSync, writeFileSync, existsSync, copyFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import {
   applyTreeseedEnvironmentToProcess,
+  applyTreeseedConfigValues,
+  applyTreeseedSafeRepairs,
   assertTreeseedCommandEnvironment,
   checkTreeseedProviderConnections,
-  createDefaultTreeseedMachineConfig,
+  collectTreeseedConfigContext,
+  collectTreeseedPrintEnvReport,
   ensureTreeseedActVerificationTooling,
   ensureTreeseedGitignoreEntries,
-  formatTreeseedConfigEnvironmentReport,
-  formatTreeseedProviderConnectionReport,
+  finalizeTreeseedConfig,
   getTreeseedMachineConfigPaths,
-  loadTreeseedMachineConfig,
-  resolveTreeseedMachineEnvironmentValues,
-  rotateTreeseedMachineKey,
-  runTreeseedConfigWizard,
-  writeTreeseedLocalEnvironmentFiles,
-  writeTreeseedMachineConfig
+  rotateTreeseedMachineKey
 } from "../operations/services/config-runtime.js";
+import { exportTreeseedCodebase } from "../operations/services/export-runtime.js";
 import {
   assertDeploymentInitialized,
   cleanupDestroyedState,
@@ -73,6 +71,10 @@ import {
 } from "../operations/services/workspace-save.js";
 import { run, workspaceRoot } from "../operations/services/workspace-tools.js";
 import { resolveTreeseedWorkflowState } from "../workflow-state.js";
+import {
+  classifyTreeseedBranchRole,
+  resolveTreeseedWorkflowPaths
+} from "./policy.js";
 class TreeseedWorkflowError extends Error {
   code;
   operation;
@@ -125,17 +127,6 @@ function withContextEnv(env, action) {
     }
   }
 }
-function runChild(command, args, context, cwd, label) {
-  const result = spawnSync(command, args, {
-    cwd,
-    env: { ...process.env, ...context.env ?? {} },
-    stdio: "inherit"
-  });
-  if (result.status !== 0) {
-    workflowError("dev", "unsupported_state", `${label} failed.`, { exitCode: result.status ?? 1 });
-  }
-  return result;
-}
 function runNodeScript(scriptName, context, cwd, label) {
   const result = spawnSync(process.execPath, [packageScriptPath(scriptName)], {
     cwd,
@@ -157,50 +148,51 @@ function normalizeConfigScopes(input) {
   }
   return ["local", "staging", "prod"].filter((scope) => requested.includes(scope));
 }
-function dedupeRepairActions(actions) {
-  const seen = /* @__PURE__ */ new Set();
-  return actions.filter((action) => {
-    if (seen.has(action.id)) return false;
-    seen.add(action.id);
-    return true;
-  });
+function resolveWorkflowStateSnapshot(cwd) {
+  return resolveTreeseedWorkflowState(cwd);
 }
-function applyTreeseedSafeRepairs(tenantRoot) {
-  const actions = [];
-  ensureTreeseedGitignoreEntries(tenantRoot);
-  actions.push({ id: "gitignore", detail: "Ensured Treeseed gitignore entries are present." });
-  const envLocalPath = resolve(tenantRoot, ".env.local");
-  const envLocalExamplePath = resolve(tenantRoot, ".env.local.example");
-  if (!existsSync(envLocalPath) && existsSync(envLocalExamplePath)) {
-    copyFileSync(envLocalExamplePath, envLocalPath);
-    actions.push({ id: "env-local", detail: "Created .env.local from .env.local.example." });
-  }
-  const deployConfig = loadCliDeployConfig(tenantRoot);
-  const { configPath } = getTreeseedMachineConfigPaths(tenantRoot);
-  if (!existsSync(configPath)) {
-    const machineConfig2 = createDefaultTreeseedMachineConfig({
-      tenantRoot,
-      deployConfig,
-      tenantConfig: void 0
-    });
-    writeTreeseedMachineConfig(tenantRoot, machineConfig2);
-    actions.push({ id: "machine-config", detail: "Created the default Treeseed machine config." });
+function resolveProjectRootOrThrow(operation, cwd) {
+  const resolved = resolveTreeseedWorkflowPaths(cwd);
+  if (!resolved.tenantRoot) {
+    workflowError(operation, "validation_failed", `Treeseed ${operation} requires a Treeseed project. Run the command from inside a tenant or initialize one first.`);
   }
-  resolveTreeseedMachineEnvironmentValues(tenantRoot, "local");
-  actions.push({ id: "machine-key", detail: "Ensured the Treeseed machine key exists." });
-  const machineConfig = loadTreeseedMachineConfig(tenantRoot);
-  writeTreeseedMachineConfig(tenantRoot, machineConfig);
-  writeTreeseedLocalEnvironmentFiles(tenantRoot);
-  actions.push({ id: "local-env", detail: "Regenerated .env.local and .dev.vars from the current machine config." });
-  for (const scope of ["local", "staging", "prod"]) {
-    const target = createPersistentDeployTarget(scope);
-    const state = loadDeployState(tenantRoot, deployConfig, { target });
-    if (state.readiness?.initialized || scope === "local") {
-      ensureGeneratedWranglerConfig(tenantRoot, { target });
-      actions.push({ id: `wrangler-${scope}`, detail: `Regenerated the ${scope} generated Wrangler config.` });
-    }
+  return resolved.cwd;
+}
+function resolveRepoState(repoDir) {
+  const branchName = currentBranch(repoDir) || null;
+  return {
+    repoDir,
+    branchName,
+    branchRole: classifyTreeseedBranchRole(branchName, repoDir),
+    dirtyWorktree: gitStatusPorcelain(repoDir).length > 0
+  };
+}
+function buildWorkflowResult(operation, cwd, payload, nextSteps) {
+  return {
+    ok: true,
+    operation,
+    payload: {
+      ...payload,
+      finalState: resolveWorkflowStateSnapshot(cwd)
+    },
+    nextSteps
+  };
+}
+function ensureLocalReadinessOrThrow(operation, tenantRoot) {
+  const state = resolveWorkflowStateSnapshot(tenantRoot);
+  if (!state.readiness.local.ready) {
+    workflowError(
+      operation,
+      "validation_failed",
+      [
+        `Treeseed ${operation} requires the local environment to be configured.`,
+        ...state.readiness.local.blockers,
+        "Run `treeseed config --environment local` first."
+      ].join("\n"),
+      { details: { readiness: state.readiness.local } }
+    );
   }
-  return dedupeRepairActions(actions);
+  return state;
 }
 function bumpRootPackageJson(root, level) {
   const packageJsonPath = resolve(root, "package.json");
@@ -342,6 +334,56 @@ function resolveDestroyConfirmation(context, expected, input) {
   }
   return false;
 }
+function syncCurrentBranchToOrigin(operation, repoDir, branch) {
+  try {
+    if (remoteBranchExists(repoDir, branch)) {
+      run("git", ["pull", "--rebase", "origin", branch], { cwd: repoDir });
+      run("git", ["push", "origin", branch], { cwd: repoDir });
+      return {
+        remoteBranchExisted: true,
+        pulledRebase: true,
+        pushed: true,
+        createdRemoteBranch: false,
+        conflicts: false
+      };
+    }
+    run("git", ["push", "-u", "origin", branch], { cwd: repoDir });
+    return {
+      remoteBranchExisted: false,
+      pulledRebase: false,
+      pushed: true,
+      createdRemoteBranch: true,
+      conflicts: false
+    };
+  } catch {
+    const report = collectMergeConflictReport(repoDir);
+    throw new TreeseedWorkflowError(operation, "merge_conflict", formatMergeConflictReport(report, repoDir, branch), {
+      details: { branch, report },
+      exitCode: 12
+    });
+  }
+}
+async function maybeAutoSaveCurrentTaskBranch(helpers, operation, input) {
+  const tenantRoot = resolveProjectRootOrThrow(operation, helpers.cwd());
+  const repoDir = gitWorkflowRoot(tenantRoot);
+  const before = resolveRepoState(repoDir);
+  if (!before.dirtyWorktree) {
+    return { performed: false, save: null };
+  }
+  if (input.autoSave === false) {
+    workflowError(operation, "validation_failed", `Treeseed ${operation} requires a clean worktree or autoSave enabled.`);
+  }
+  const saveResult = await workflowSave(helpers, {
+    message: operation === "close" ? `close: ${input.message}` : input.message,
+    verify: input.verify === true,
+    refreshPreview: false,
+    preview: input.preview
+  });
+  return {
+    performed: true,
+    save: saveResult.payload
+  };
+}
 async function workflowStatus(helpers) {
   return withContextEnv(helpers.context.env, () => createStatusResult(helpers.cwd()));
 }
@@ -351,7 +393,7 @@ async function workflowTasks(helpers) {
 async function workflowConfig(helpers, input = {}) {
   try {
     return await withContextEnv(helpers.context.env, async () => {
-      const tenantRoot = helpers.cwd();
+      const tenantRoot = resolveProjectRootOrThrow("config", helpers.cwd());
       const scopes = normalizeConfigScopes(input);
       const sync = input.syncProviders ?? input.sync ?? "all";
       const printEnv = input.printEnv === true;
@@ -367,23 +409,22 @@ async function workflowConfig(helpers, input = {}) {
       });
       ensureTreeseedGitignoreEntries(tenantRoot);
       const preflight = collectCliPreflight({ cwd: tenantRoot, requireAuth: false });
+      const contextSnapshot = collectTreeseedConfigContext({
+        tenantRoot,
+        scopes,
+        env: helpers.context.env
+      });
       if (printEnvOnly) {
-        const reports = scopes.map((scope) => ({
+        const reports2 = scopes.map((scope) => ({
           scope,
-          environmentReport: formatTreeseedConfigEnvironmentReport({
+          environment: collectTreeseedPrintEnvReport({
             tenantRoot,
             scope,
             env: helpers.context.env,
             revealSecrets
           }),
-          providerReport: formatTreeseedProviderConnectionReport(
-            checkTreeseedProviderConnections({ tenantRoot, scope, env: helpers.context.env })
-          )
+          provider: checkTreeseedProviderConnections({ tenantRoot, scope, env: helpers.context.env })
         }));
-        for (const report of reports) {
-          maybePrint(helpers.write, report.environmentReport);
-          maybePrint(helpers.write, report.providerReport);
-        }
         return {
           ok: true,
           operation: "config",
@@ -392,7 +433,7 @@ async function workflowConfig(helpers, input = {}) {
             scopes,
             sync,
             secretsRevealed: revealSecrets,
-            reports,
+            reports: reports2,
             repairs,
             preflight,
             toolHealth
@@ -421,31 +462,46 @@ async function workflowConfig(helpers, input = {}) {
           ])
         };
       }
-      const wizardResult = await runTreeseedConfigWizard({
+      const explicitUpdates = Array.isArray(input.updates) ? input.updates.map((update) => ({
+        scope: update.scope,
+        entryId: String(update.entryId ?? ""),
+        value: typeof update.value === "string" ? update.value : "",
+        reused: update.reused === true
+      })) : null;
+      const autoUpdates = scopes.flatMap(
+        (scope) => contextSnapshot.entriesByScope[scope].map((entry) => ({
+          scope,
+          entryId: entry.id,
+          value: entry.effectiveValue,
+          reused: entry.currentValue.length > 0 || entry.suggestedValue.length > 0
+        }))
+      );
+      const applyResult = applyTreeseedConfigValues({
+        tenantRoot,
+        updates: explicitUpdates ?? autoUpdates
+      });
+      const finalizeResult = finalizeTreeseedConfig({
         tenantRoot,
         scopes,
         sync,
-        authStatus: preflight.checks.auth,
-        env: helpers.context.env,
-        useInk: input.nonInteractive === true ? false : process.stdin.isTTY && process.stdout.isTTY,
-        printEnv,
-        revealSecrets,
-        write: (line) => maybePrint(helpers.write, line),
-        prompt: async (message) => {
-          if (input.nonInteractive === true) {
-            return "";
-          }
-          return String(await (helpers.context.prompt?.(message) ?? ""));
-        }
+        env: helpers.context.env
       });
-      writeTreeseedLocalEnvironmentFiles(tenantRoot);
-      applyTreeseedEnvironmentToProcess({ tenantRoot, scope: "local", override: true });
+      const reports = printEnv ? scopes.map((scope) => ({
+        scope,
+        environment: collectTreeseedPrintEnvReport({
+          tenantRoot,
+          scope,
+          env: helpers.context.env,
+          revealSecrets
+        }),
+        provider: finalizeResult.connectionChecks.find((report) => report.scope === scope) ?? checkTreeseedProviderConnections({ tenantRoot, scope, env: helpers.context.env })
+      })) : [];
       const { configPath, keyPath } = getTreeseedMachineConfigPaths(tenantRoot);
       const state = resolveTreeseedWorkflowState(tenantRoot);
-      return {
-        ok: true,
-        operation: "config",
-        payload: {
+      return buildWorkflowResult(
+        "config",
+        tenantRoot,
+        {
           mode: "configure",
           scopes,
           sync,
@@ -454,24 +510,37 @@ async function workflowConfig(helpers, input = {}) {
           repairs,
           preflight,
           toolHealth,
-          result: wizardResult,
-          state
+          context: contextSnapshot,
+          result: {
+            ...applyResult,
+            ...finalizeResult
+          },
+          reports,
+          state,
+          readiness: state.readiness
         },
-        nextSteps: createNextSteps([
+        createNextSteps([
           ...scopes.includes("local") ? [{ operation: "dev", reason: "Start the local Treeseed runtime on the initialized local environment." }] : [],
           ...scopes.includes("staging") ? [{ operation: "status", reason: "Confirm staging readiness after initializing shared services." }] : [],
           { operation: "switch", reason: "Create or resume a task branch once the runtime foundation is ready.", input: { branch: "feature/my-change", preview: true } }
         ])
-      };
+      );
     });
   } catch (error) {
     toError("config", error);
   }
 }
+async function workflowExport(helpers, input = {}) {
+  return await withContextEnv(helpers.context.env, async () => {
+    const directory = resolve(helpers.context.cwd ?? helpers.cwd(), input.directory ?? ".");
+    const exported = await exportTreeseedCodebase({ directory });
+    return buildWorkflowResult("export", exported.tenantRoot, exported);
+  });
+}
 async function workflowSwitch(helpers, input) {
   try {
     return withContextEnv(helpers.context.env, () => {
-      const tenantRoot = helpers.cwd();
+      const tenantRoot = resolveProjectRootOrThrow("switch", helpers.cwd());
       const branchName = String(input.branch ?? input.branchName ?? "").trim();
       if (!branchName) {
         workflowError("switch", "validation_failed", "Treeseed switch requires a branch name.");
@@ -503,10 +572,10 @@ async function workflowSwitch(helpers, input) {
         previewResult = deployBranchPreview(tenantRoot, branchName, helpers.context, { initialize: true });
       }
       const state = resolveTreeseedWorkflowState(tenantRoot);
-      return {
-        ok: true,
-        operation: "switch",
-        payload: {
+      return buildWorkflowResult(
+        "switch",
+        tenantRoot,
+        {
           branchName,
           created,
           resumed,
@@ -517,13 +586,16 @@ async function workflowSwitch(helpers, input) {
             lastDeploymentTimestamp: state.preview.lastDeploymentTimestamp
           },
           previewResult,
-          state
+          preconditions: {
+            cleanWorktreeRequired: true,
+            baseBranch: STAGING_BRANCH
+          }
         },
-        nextSteps: createNextSteps([
-          state.preview.enabled ? { operation: "save", reason: "Persist and verify the current task branch, then refresh its preview deployment.", input: { message: "describe your change" } } : { operation: "dev", reason: "Start the local development environment for this task branch." },
+        createNextSteps([
+          state.preview.enabled ? { operation: "save", reason: "Persist and verify the current task branch, then refresh its preview deployment.", input: { message: "describe your change", preview: true } } : { operation: "dev", reason: "Start the local development environment for this task branch." },
           { operation: "stage", reason: "Merge the task into staging once the task branch is verified.", input: { message: "describe the resolution" } }
         ])
-      };
+      );
     });
   } catch (error) {
     toError("switch", error);
@@ -535,7 +607,8 @@ async function workflowDev(helpers, input = {}) {
       if (helpers.context.transport === "api") {
         workflowError("dev", "unsupported_transport", "Treeseed dev is not supported over the HTTP workflow API.");
       }
-      const tenantRoot = helpers.cwd();
+      const tenantRoot = resolveProjectRootOrThrow("dev", helpers.cwd());
+      const readiness = ensureLocalReadinessOrThrow("dev", tenantRoot);
       applyTreeseedEnvironmentToProcess({ tenantRoot, scope: "local", override: true });
       assertTreeseedCommandEnvironment({ tenantRoot, scope: "local", purpose: "dev" });
       const args = [packageScriptPath("tenant-dev")];
@@ -553,38 +626,42 @@ async function workflowDev(helpers, input = {}) {
           stdio: input.stdio ?? "inherit",
           detached: process.platform !== "win32"
         });
-        return {
-          ok: true,
-          operation: "dev",
-          payload: {
-            watch: input.watch === true,
-            background: true,
-            command: process.execPath,
-            args,
-            cwd: tenantRoot,
-            pid: child.pid ?? null,
-            exitCode: null
-          }
-        };
+        return buildWorkflowResult("dev", tenantRoot, {
+          watch: input.watch === true,
+          background: true,
+          command: process.execPath,
+          args,
+          cwd: tenantRoot,
+          pid: child.pid ?? null,
+          exitCode: null,
+          runtime: {
+            mode: process.env.TREESEED_LOCAL_DEV_MODE ?? "cloudflare",
+            apiBaseUrl: process.env.TREESEED_API_BASE_URL ?? "http://127.0.0.1:3000",
+            webUrl: "http://127.0.0.1:8787"
+          },
+          readiness: readiness.readiness.local
+        });
       }
       const result = spawnSync(process.execPath, args, {
         cwd: tenantRoot,
         env,
         stdio: input.stdio ?? "inherit"
       });
-      return {
-        ok: (result.status ?? 1) === 0,
-        operation: "dev",
-        payload: {
-          watch: input.watch === true,
-          background: false,
-          command: process.execPath,
-          args,
-          cwd: tenantRoot,
-          pid: null,
-          exitCode: result.status ?? 1
-        }
-      };
+      return buildWorkflowResult("dev", tenantRoot, {
+        watch: input.watch === true,
+        background: false,
+        command: process.execPath,
+        args,
+        cwd: tenantRoot,
+        pid: null,
+        exitCode: result.status ?? 1,
+        runtime: {
+          mode: process.env.TREESEED_LOCAL_DEV_MODE ?? "cloudflare",
+          apiBaseUrl: process.env.TREESEED_API_BASE_URL ?? "http://127.0.0.1:3000",
+          webUrl: "http://127.0.0.1:8787"
+        },
+        readiness: readiness.readiness.local
+      });
     });
   } catch (error) {
     toError("dev", error);
@@ -593,7 +670,7 @@ async function workflowDev(helpers, input = {}) {
 async function workflowSave(helpers, input) {
   try {
     return withContextEnv(helpers.context.env, () => {
-      const tenantRoot = helpers.cwd();
+      const tenantRoot = resolveProjectRootOrThrow("save", helpers.cwd());
       const message = ensureMessage("save", input.message, "a commit message");
       const optionsHotfix = input.hotfix === true;
       const root = workspaceRoot(tenantRoot);
@@ -616,45 +693,49 @@ async function workflowSave(helpers, input) {
       if (input.verify !== false) {
         runWorkspaceSavePreflight({ cwd: root });
       }
-      if (!hasMeaningfulChanges(gitRoot)) {
-        workflowError("save", "validation_failed", "Treeseed save found no meaningful repository changes to commit.");
+      const hadMeaningfulChanges = hasMeaningfulChanges(gitRoot);
+      let head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot, capture: true }).trim();
+      let commitCreated = false;
+      if (hadMeaningfulChanges) {
+        run("git", ["add", "-A"], { cwd: gitRoot });
+        run("git", ["commit", "-m", message], { cwd: gitRoot });
+        head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot, capture: true }).trim();
+        commitCreated = true;
       }
-      run("git", ["add", "-A"], { cwd: gitRoot });
-      run("git", ["commit", "-m", message], { cwd: gitRoot });
-      const head = run("git", ["rev-parse", "HEAD"], { cwd: gitRoot, capture: true }).trim();
-      try {
-        if (remoteBranchExists(gitRoot, branch)) {
-          run("git", ["pull", "--rebase", "origin", branch], { cwd: gitRoot });
-          run("git", ["push", "origin", branch], { cwd: gitRoot });
-        } else {
-          run("git", ["push", "-u", "origin", branch], { cwd: gitRoot });
+      const branchSync = syncCurrentBranchToOrigin("save", gitRoot, branch);
+      let previewAction = { status: "skipped" };
+      if (beforeState.branchRole === "feature" && branch) {
+        if (input.preview === true) {
+          previewAction = {
+            status: beforeState.preview.enabled ? "refreshed" : "created",
+            details: deployBranchPreview(root, branch, helpers.context, { initialize: !beforeState.preview.enabled })
+          };
+        } else if (input.refreshPreview !== false && beforeState.preview.enabled) {
+          previewAction = {
+            status: "refreshed",
+            details: deployBranchPreview(root, branch, helpers.context, { initialize: false })
+          };
         }
-      } catch {
-        const report = collectMergeConflictReport(gitRoot);
-        throw new TreeseedWorkflowError("save", "merge_conflict", formatMergeConflictReport(report, gitRoot, branch), {
-          details: { branch, report },
-          exitCode: 12
-        });
-      }
-      let previewRefresh = null;
-      if (input.refreshPreview !== false && beforeState.branchRole === "feature" && beforeState.preview.enabled && branch) {
-        previewRefresh = deployBranchPreview(root, branch, helpers.context, { initialize: false });
       }
-      return {
-        ok: true,
-        operation: "save",
-        payload: {
+      return buildWorkflowResult(
+        "save",
+        root,
+        {
           branch,
           scope,
           hotfix: optionsHotfix,
           message,
           commitSha: head,
-          previewRefresh
+          commitCreated,
+          noChanges: !hadMeaningfulChanges,
+          branchSync,
+          previewAction,
+          mergeConflict: null
         },
-        nextSteps: createNextSteps([
+        createNextSteps([
           branch === STAGING_BRANCH ? { operation: "release", reason: "Promote the validated staging branch into production.", input: { bump: "patch" } } : branch === PRODUCTION_BRANCH ? { operation: "status", reason: "Inspect production state after the explicit hotfix save." } : { operation: "stage", reason: "Merge the verified task branch into staging.", input: { message: "describe the resolution" } }
         ])
-      };
+      );
     });
   } catch (error) {
     toError("save", error);
@@ -662,9 +743,13 @@ async function workflowSave(helpers, input) {
 }
 async function workflowClose(helpers, input) {
   try {
-    return withContextEnv(helpers.context.env, () => {
-      const tenantRoot = helpers.cwd();
+    return withContextEnv(helpers.context.env, async () => {
+      const tenantRoot = resolveProjectRootOrThrow("close", helpers.cwd());
       const message = ensureMessage("close", input.message, "a close reason");
+      const autoSave = await maybeAutoSaveCurrentTaskBranch(helpers, "close", {
+        message,
+        autoSave: input.autoSave
+      });
       const featureBranch = assertFeatureBranch(tenantRoot);
       const repoDir = gitWorkflowRoot(tenantRoot);
       assertCleanWorktree(tenantRoot);
@@ -675,21 +760,24 @@ async function workflowClose(helpers, input) {
       if (input.deleteBranch !== false) {
         deleteLocalBranch(repoDir, featureBranch);
       }
-      return {
-        ok: true,
-        operation: "close",
-        payload: {
+      return buildWorkflowResult(
+        "close",
+        tenantRoot,
+        {
           branchName: featureBranch,
           message,
+          autoSaved: autoSave.performed,
+          autoSaveResult: autoSave.save,
           deprecatedTag,
           previewCleanup,
           remoteDeleted,
-          localDeleted: input.deleteBranch !== false
+          localDeleted: input.deleteBranch !== false,
+          finalBranch: currentBranch(repoDir) || STAGING_BRANCH
         },
-        nextSteps: createNextSteps([
+        createNextSteps([
           { operation: "tasks", reason: "Inspect the remaining task branches after closing this one." }
         ])
-      };
+      );
     });
   } catch (error) {
     toError("close", error);
@@ -697,12 +785,25 @@ async function workflowClose(helpers, input) {
 }
 async function workflowStage(helpers, input) {
   try {
-    return withContextEnv(helpers.context.env, () => {
-      const tenantRoot = helpers.cwd();
+    return withContextEnv(helpers.context.env, async () => {
+      const tenantRoot = resolveProjectRootOrThrow("stage", helpers.cwd());
       const message = ensureMessage("stage", input.message, "a resolution message");
+      const autoSave = await maybeAutoSaveCurrentTaskBranch(helpers, "stage", {
+        message,
+        autoSave: input.autoSave
+      });
       const featureBranch = assertFeatureBranch(tenantRoot);
       runWorkspaceSavePreflight({ cwd: tenantRoot });
-      const repoDir = mergeCurrentBranchIntoStaging(tenantRoot, featureBranch);
+      let repoDir;
+      try {
+        repoDir = mergeCurrentBranchIntoStaging(tenantRoot, featureBranch);
+      } catch (error) {
+        const report = collectMergeConflictReport(gitWorkflowRoot(tenantRoot));
+        throw new TreeseedWorkflowError("stage", "merge_conflict", formatMergeConflictReport(report, gitWorkflowRoot(tenantRoot), STAGING_BRANCH), {
+          details: { branch: featureBranch, report, originalError: error instanceof Error ? error.message : String(error) },
+          exitCode: 12
+        });
+      }
       const stagingWait = input.waitForStaging === false ? { status: "skipped", reason: "disabled" } : waitForStagingAutomation(repoDir);
       const previewCleanup = input.deletePreview === false ? { performed: false } : destroyPreviewIfPresent(tenantRoot, featureBranch);
       const deprecatedTag = createDeprecatedTaskTag(repoDir, featureBranch, `stage: ${message}`);
@@ -710,24 +811,27 @@ async function workflowStage(helpers, input) {
       if (input.deleteBranch !== false) {
         deleteLocalBranch(repoDir, featureBranch);
       }
-      return {
-        ok: true,
-        operation: "stage",
-        payload: {
+      return buildWorkflowResult(
+        "stage",
+        tenantRoot,
+        {
           branchName: featureBranch,
           mergeTarget: STAGING_BRANCH,
           message,
+          autoSaved: autoSave.performed,
+          autoSaveResult: autoSave.save,
           deprecatedTag,
           stagingWait,
           previewCleanup,
           remoteDeleted,
-          localDeleted: input.deleteBranch !== false
+          localDeleted: input.deleteBranch !== false,
+          finalBranch: currentBranch(repoDir) || STAGING_BRANCH
         },
-        nextSteps: createNextSteps([
+        createNextSteps([
           { operation: "release", reason: "Promote the updated staging branch into production when ready.", input: { bump: "patch" } },
           { operation: "status", reason: "Inspect staging readiness after the task branch merge." }
         ])
-      };
+      );
     });
   } catch (error) {
     toError("stage", error);
@@ -737,7 +841,7 @@ async function workflowRelease(helpers, input) {
   try {
     return withContextEnv(helpers.context.env, () => {
       const level = input.bump ?? "patch";
-      const root = workspaceRoot(helpers.cwd());
+      const root = resolveProjectRootOrThrow("release", helpers.cwd());
       const gitRoot = repoRoot(root);
       prepareReleaseBranches(root);
       applyTreeseedEnvironmentToProcess({ tenantRoot: root, scope: "staging", override: true });
@@ -750,23 +854,32 @@ async function workflowRelease(helpers, input) {
       run("git", ["commit", "-m", `release: ${level} bump`], { cwd: gitRoot });
       pushBranch(gitRoot, STAGING_BRANCH);
       mergeStagingIntoMain(root);
+      const releasedCommit = run("git", ["rev-parse", PRODUCTION_BRANCH], { cwd: gitRoot, capture: true }).trim();
       run("git", ["tag", "-a", rootVersion, "-m", `release: ${rootVersion}`], { cwd: gitRoot });
       run("git", ["push", "origin", rootVersion], { cwd: gitRoot });
-      return {
-        ok: true,
-        operation: "release",
-        payload: {
+      syncBranchWithOrigin(gitRoot, STAGING_BRANCH);
+      return buildWorkflowResult(
+        "release",
+        root,
+        {
           level,
           rootVersion,
           releaseTag: rootVersion,
+          releasedCommit,
           stagingBranch: STAGING_BRANCH,
           productionBranch: PRODUCTION_BRANCH,
-          touchedPackages: [...plan.touched]
+          touchedPackages: [...plan.touched],
+          finalBranch: currentBranch(gitRoot) || STAGING_BRANCH,
+          pushStatus: {
+            stagingPushed: true,
+            productionPushed: true,
+            tagPushed: true
+          }
         },
-        nextSteps: createNextSteps([
+        createNextSteps([
           { operation: "status", reason: "Inspect release readiness and production state after the promotion." }
         ])
-      };
+      );
     });
   } catch (error) {
     toError("release", error);
@@ -832,6 +945,7 @@ export {
   workflowConfig,
   workflowDestroy,
   workflowDev,
+  workflowExport,
   workflowRelease,
   workflowSave,
   workflowStage,