@aipper/aiws 0.0.23 → 0.0.25

package/src/commands/change-finish.js

@@ -0,0 +1,484 @@
+import path from "node:path";
+
+/**
+ * @param {string} gitRoot
+ * @param {string} branch
+ * @param {string | undefined} preferredRemote
+ * @param {{ runCommand: typeof import("../exec.js").runCommand }} deps
+ */
+export async function resolvePushTarget(gitRoot, branch, preferredRemote, deps) {
+  const remoteRaw = String(preferredRemote || "").trim();
+  const branchRemoteRes = await deps.runCommand("git", ["config", "--get", `branch.${branch}.remote`], { cwd: gitRoot });
+  const trackedRemote = String(branchRemoteRes.stdout || "").trim();
+
+  const branchMergeRes = await deps.runCommand("git", ["config", "--get", `branch.${branch}.merge`], { cwd: gitRoot });
+  const trackedMergeRef = String(branchMergeRes.stdout || "").trim();
+  const trackedBranch = trackedMergeRef.startsWith("refs/heads/") ? trackedMergeRef.slice("refs/heads/".length) : "";
+
+  const remote = remoteRaw || trackedRemote || "origin";
+  const remoteBranch = trackedBranch || branch;
+  const refspec = remoteBranch === branch ? branch : `${branch}:${remoteBranch}`;
+
+  return { remote, remoteBranch, refspec, trackedRemote, trackedMergeRef };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} worktreePath
+ * @param {{
+ *   checkGitClean: (gitRoot: string) => Promise<{ clean: true } | { clean: false, details: string }>,
+ *   listGitWorktrees: (gitRoot: string) => Promise<Array<{ worktree: string, locked: boolean, lockReason: string }>>,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   runCommand: typeof import("../exec.js").runCommand,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function cleanupWorktreePath(gitRoot, worktreePath, deps) {
+  const abs = path.resolve(worktreePath);
+  if (abs === path.resolve(gitRoot)) {
+    return { status: "skipped", reason: "current_worktree", worktree: abs };
+  }
+
+  const worktrees = await deps.listGitWorktrees(gitRoot);
+  const worktreeEntry = worktrees.find((worktree) => path.resolve(worktree.worktree) === abs);
+  if (worktreeEntry?.locked) {
+    return { status: "skipped", reason: "locked", worktree: abs, details: worktreeEntry.lockReason };
+  }
+
+  if (!(await deps.pathExists(abs))) {
+    const prune = await deps.runCommand("git", ["worktree", "prune"], { cwd: gitRoot });
+    if (prune.code !== 0) {
+      throw new deps.UserError("Failed to prune stale git worktree metadata.", { details: prune.stderr || prune.stdout });
+    }
+    return { status: "pruned-missing", worktree: abs };
+  }
+
+  const clean = await deps.checkGitClean(abs);
+  if (!clean.clean) {
+    return { status: "skipped", reason: "dirty", worktree: abs, details: clean.details };
+  }
+
+  let rm = await deps.runCommand("git", ["worktree", "remove", abs], { cwd: gitRoot });
+  if (rm.code !== 0) {
+    const out = `${rm.stderr || ""}\n${rm.stdout || ""}`;
+    if (out.includes("working trees containing submodules cannot be moved or removed")) {
+      rm = await deps.runCommand("git", ["worktree", "remove", "--force", abs], { cwd: gitRoot });
+    }
+  }
+  if (rm.code !== 0) {
+    throw new deps.UserError("Failed to remove change worktree.", { details: rm.stderr || rm.stdout });
+  }
+
+  const prune = await deps.runCommand("git", ["worktree", "prune"], { cwd: gitRoot });
+  if (prune.code !== 0) {
+    throw new deps.UserError("Failed to prune git worktree metadata after remove.", { details: prune.stderr || prune.stdout });
+  }
+
+  return { status: "removed", worktree: abs };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {{ pathExists: (path: string) => Promise<boolean>, runCommand: typeof import("../exec.js").runCommand }} deps
+ * @returns {Promise<Array<{ name: string, path: string }>>}
+ */
+export async function listSubmodulesFromGitmodules(gitRoot, deps) {
+  const gitmodules = path.join(gitRoot, ".gitmodules");
+  if (!(await deps.pathExists(gitmodules))) return [];
+
+  const list = await deps.runCommand("git", ["config", "--file", ".gitmodules", "--get-regexp", "^submodule\\..*\\.path$"], { cwd: gitRoot });
+  if (list.code !== 0) return [];
+
+  /** @type {Array<{ name: string, path: string }>} */
+  const subs = [];
+  for (const raw of String(list.stdout || "").split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    const idx = line.indexOf(" ");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    const subPath = line.slice(idx + 1).trim();
+    const match = key.match(/^submodule\.(.+)\.path$/);
+    if (!match) continue;
+    const name = String(match[1] || "").trim();
+    if (!name || !subPath) continue;
+    subs.push({ name, path: subPath });
+  }
+  return subs;
+}
+
+/**
+ * @param {string} targetsPath
+ * @param {{ pathExists: (path: string) => Promise<boolean>, readText: (path: string) => Promise<string> }} deps
+ */
+export async function parseSubmoduleTargetsFile(targetsPath, deps) {
+  /** @type {Map<string, { branch: string, remote: string }>} */
+  const parsed = new Map();
+  /** @type {string[]} */
+  const errors = [];
+
+  if (!(await deps.pathExists(targetsPath))) {
+    return { parsed, errors };
+  }
+
+  const text = await deps.readText(targetsPath);
+  const lines = String(text || "").split(/\r?\n/);
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i] || "";
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const parts = line.split(/\s+/).filter(Boolean);
+    if (parts.length < 2) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} invalid line (expected: <path> <target_branch> [remote])`);
+      continue;
+    }
+    const subPath = String(parts[0] || "").trim();
+    const targetBranch = String(parts[1] || "").trim();
+    const remote = String(parts[2] || "origin").trim() || "origin";
+    if (!subPath) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} missing submodule path`);
+      continue;
+    }
+    if (parsed.has(subPath)) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} duplicate submodule path: ${subPath}`);
+      continue;
+    }
+    if (!targetBranch || ["<fill-me>", "<fill_me>", "tbd", "TBD"].includes(targetBranch)) {
+      errors.push(`${path.basename(targetsPath)}:${i + 1} missing/placeholder target_branch for ${subPath}`);
+      continue;
+    }
+    parsed.set(subPath, { branch: targetBranch, remote });
+  }
+
+  return { parsed, errors };
+}
+
+/**
+ * @param {string} repoPath
+ * @param {string} rev
+ * @param {{ pathExists: (path: string) => Promise<boolean>, runCommand: typeof import("../exec.js").runCommand }} deps
+ */
+async function gitHasRevision(repoPath, rev, deps) {
+  if (!(await deps.pathExists(repoPath))) return false;
+  const res = await deps.runCommand("git", ["-C", repoPath, "cat-file", "-e", `${rev}^{commit}`], { cwd: repoPath });
+  return res.code === 0;
+}
+
+/**
+ * @param {string} repoPath
+ * @param {{ pathExists: (path: string) => Promise<boolean>, runCommand: typeof import("../exec.js").runCommand }} deps
+ * @returns {Promise<boolean>}
+ */
+export async function isGitRepository(repoPath, deps) {
+  if (!(await deps.pathExists(repoPath))) return false;
+  const res = await deps.runCommand("git", ["-C", repoPath, "rev-parse", "--git-dir"], { cwd: repoPath });
+  return res.code === 0;
+}
+
+/**
+ * @param {string} targetRepoPath
+ * @param {string} sha
+ * @param {string | undefined} fallbackRepoPath
+ * @param {{
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   runCommand: typeof import("../exec.js").runCommand,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+async function ensureRevisionAvailable(targetRepoPath, sha, fallbackRepoPath, deps) {
+  if (await gitHasRevision(targetRepoPath, sha, deps)) return;
+  const fallback = String(fallbackRepoPath || "").trim();
+  if (!fallback) {
+    throw new deps.UserError("Required submodule commit is not available locally.", {
+      details: `repo: ${targetRepoPath}\ncommit: ${sha}`,
+    });
+  }
+  if (!(await gitHasRevision(fallback, sha, deps))) {
+    throw new deps.UserError("Required submodule commit is missing in both target and change worktrees.", {
+      details: `target_repo: ${targetRepoPath}\nchange_repo: ${fallback}\ncommit: ${sha}`,
+    });
+  }
+  const fetch = await deps.runCommand("git", ["-C", targetRepoPath, "fetch", fallback, sha], { cwd: targetRepoPath });
+  if (fetch.code !== 0 || !(await gitHasRevision(targetRepoPath, sha, deps))) {
+    throw new deps.UserError("Failed to import submodule commit from change worktree.", {
+      details: `target_repo: ${targetRepoPath}\nchange_repo: ${fallback}\ncommit: ${sha}\n\n${fetch.stderr || fetch.stdout}`,
+    });
+  }
+}
+
+/**
+ * @param {string} repoPath
+ * @param {string} remote
+ * @param {string} branch
+ * @param {string} sha
+ * @param {{ runCommand: typeof import("../exec.js").runCommand, UserError: typeof import("../errors.js").UserError }} deps
+ */
+async function pushSubmoduleBranch(repoPath, remote, branch, sha, deps) {
+  const fetch = await deps.runCommand("git", ["-C", repoPath, "fetch", remote, "--prune"], { cwd: repoPath });
+  if (fetch.code !== 0) {
+    throw new deps.UserError("Failed to fetch submodule remote before push.", {
+      details: `repo: ${repoPath}\nremote: ${remote}\n\n${fetch.stderr || fetch.stdout}`,
+    });
+  }
+
+  const remoteRef = `refs/remotes/${remote}/${branch}`;
+  const hasRemoteBranch = await deps
+    .runCommand("git", ["-C", repoPath, "show-ref", "--verify", "--quiet", remoteRef], { cwd: repoPath })
+    .then((result) => result.code === 0);
+  if (!hasRemoteBranch) {
+    throw new deps.UserError("Submodule target branch does not exist on remote.", {
+      details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}`,
+    });
+  }
+
+  const remoteAncestor = await deps
+    .runCommand("git", ["-C", repoPath, "merge-base", "--is-ancestor", remoteRef, sha], { cwd: repoPath })
+    .then((result) => result.code === 0);
+  if (remoteAncestor) {
+    const push = await deps.runCommand("git", ["-C", repoPath, "push", remote, `${sha}:refs/heads/${branch}`], { cwd: repoPath });
+    if (push.code !== 0) {
+      throw new deps.UserError("Failed to fast-forward push submodule target branch.", {
+        details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}\ncommit: ${sha}\n\n${push.stderr || push.stdout}`,
+      });
+    }
+    return { status: "pushed", remoteRef };
+  }
+
+  const shaContained = await deps
+    .runCommand("git", ["-C", repoPath, "merge-base", "--is-ancestor", sha, remoteRef], { cwd: repoPath })
+    .then((result) => result.code === 0);
+  if (shaContained) {
+    return { status: "already-contained", remoteRef };
+  }
+
+  throw new deps.UserError("Submodule target branch diverged from gitlink commit.", {
+    details: `repo: ${repoPath}\nremote: ${remote}\nbranch: ${branch}\ncommit: ${sha}\n\nHint: reconcile the submodule branch manually, then retry.`,
+  });
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {string} baseBranch
+ * @param {string | undefined} changeWorktreePath
+ * @param {{
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   readText: (path: string) => Promise<string>,
+ *   runCommand: typeof import("../exec.js").runCommand,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function pushSubmodulesForFinish(gitRoot, changeId, baseBranch, changeWorktreePath, deps) {
+  const subs = await listSubmodulesFromGitmodules(gitRoot, deps);
+  if (subs.length === 0) return { processed: 0 };
+
+  const targetsPath = path.join(gitRoot, "changes", changeId, "submodules.targets");
+  if (!(await deps.pathExists(targetsPath))) {
+    throw new deps.UserError("Missing submodules.targets for submodule-aware finish.", {
+      details: `required: ${path.relative(gitRoot, targetsPath)}\n\nHint: add one entry per submodule path before running \`aiws change finish --push\`.`,
+    });
+  }
+
+  const parsedTargets = await parseSubmoduleTargetsFile(targetsPath, deps);
+  if (parsedTargets.errors.length > 0) {
+    throw new deps.UserError("Invalid submodules.targets.", { details: parsedTargets.errors.join("\n") });
+  }
+
+  const missingPaths = subs.filter((submodule) => !parsedTargets.parsed.has(submodule.path)).map((submodule) => submodule.path);
+  if (missingPaths.length > 0) {
+    throw new deps.UserError("submodules.targets missing declared submodule paths.", {
+      details: `file: ${path.relative(gitRoot, targetsPath)}\nmissing: ${missingPaths.join(", ")}`,
+    });
+  }
+
+  /** @type {Array<{ name: string, path: string, sha: string, branch: string, remote: string, pinBranch: string }>} */
+  const specs = [];
+  for (const sub of subs) {
+    const target = parsedTargets.parsed.get(sub.path);
+    if (!target) continue;
+    const targetBranch = target.branch === "." ? baseBranch : target.branch;
+    const gitlink = await deps.runCommand("git", ["rev-parse", `HEAD:${sub.path}`], { cwd: gitRoot });
+    if (gitlink.code !== 0) {
+      throw new deps.UserError("Failed to resolve submodule gitlink commit from merged superproject.", {
+        details: `path: ${sub.path}\n\n${gitlink.stderr || gitlink.stdout}`,
+      });
+    }
+    const sha = String(gitlink.stdout || "").trim();
+    specs.push({
+      name: sub.name,
+      path: sub.path,
+      sha,
+      branch: targetBranch,
+      remote: target.remote,
+      pinBranch: `aiws/pin/${targetBranch}`,
+    });
+  }
+
+  for (const spec of specs) {
+    const targetRepoPath = path.join(gitRoot, spec.path);
+    const changeRepoPath = changeWorktreePath ? path.join(changeWorktreePath, spec.path) : "";
+    const targetRepoReady = await isGitRepository(targetRepoPath, deps);
+    const changeRepoReady = changeRepoPath ? await isGitRepository(changeRepoPath, deps) : false;
+    if (!targetRepoReady && !changeRepoReady) {
+      throw new deps.UserError("Submodule repository is not initialized in either target or change worktree.", {
+        details: `path: ${spec.path}\nHint: initialize submodules before finish, or keep using worktree mode for changes involving submodules.`,
+      });
+    }
+
+    const sourceRepoPath =
+      (targetRepoReady && (await gitHasRevision(targetRepoPath, spec.sha, deps))) ? targetRepoPath : changeRepoReady ? changeRepoPath : targetRepoPath;
+    if (!(await gitHasRevision(sourceRepoPath, spec.sha, deps))) {
+      throw new deps.UserError("Merged submodule gitlink commit is not available locally.", {
+        details: `path: ${spec.path}\ncommit: ${spec.sha}\nsource_repo: ${sourceRepoPath}`,
+      });
+    }
+
+    const pushResult = await pushSubmoduleBranch(sourceRepoPath, spec.remote, spec.branch, spec.sha, deps);
+    console.log(
+      `submodule push: ${spec.path} (${spec.remote} ${spec.branch}${pushResult.status === "pushed" ? ` <= ${spec.sha}` : ", already contained"})`,
+    );
+  }
+
+  const sync = await deps.runCommand("git", ["submodule", "update", "--init", "--recursive"], { cwd: gitRoot });
+  if (sync.code !== 0) {
+    throw new deps.UserError("Submodule push succeeded, but failed to sync target worktree submodules.", {
+      details: sync.stderr || sync.stdout,
+    });
+  }
+
+  for (const spec of specs) {
+    const targetRepoPath = path.join(gitRoot, spec.path);
+    if (!(await isGitRepository(targetRepoPath, deps))) {
+      throw new deps.UserError("Submodule repo missing after sync.", { details: `path: ${spec.path}` });
+    }
+    await ensureRevisionAvailable(targetRepoPath, spec.sha, changeWorktreePath ? path.join(changeWorktreePath, spec.path) : "", deps);
+    const fetch = await deps.runCommand("git", ["-C", targetRepoPath, "fetch", spec.remote, "--prune"], { cwd: targetRepoPath });
+    if (fetch.code !== 0) {
+      throw new deps.UserError("Failed to refresh target worktree submodule remote.", {
+        details: `path: ${spec.path}\nremote: ${spec.remote}\n\n${fetch.stderr || fetch.stdout}`,
+      });
+    }
+    const checkout = await deps.runCommand("git", ["-C", targetRepoPath, "checkout", "-B", spec.pinBranch, spec.sha], { cwd: targetRepoPath });
+    if (checkout.code !== 0) {
+      throw new deps.UserError("Failed to attach target worktree submodule to pin branch.", {
+        details: `path: ${spec.path}\npin_branch: ${spec.pinBranch}\ncommit: ${spec.sha}\n\n${checkout.stderr || checkout.stdout}`,
+      });
+    }
+    await deps.runCommand("git", ["-C", targetRepoPath, "branch", "--set-upstream-to", `${spec.remote}/${spec.branch}`, spec.pinBranch], {
+      cwd: targetRepoPath,
+    });
+  }
+
+  return { processed: specs.length };
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {{ changeId?: string, into?: string, base?: string }} options
+ * @param {{
+ *   assertValidChangeId: (changeId: string) => void,
+ *   checkGitClean: (gitRoot: string) => Promise<{ clean: true } | { clean: false, details: string }>,
+ *   currentBranch: (gitRoot: string) => Promise<string>,
+ *   listGitWorktrees: (gitRoot: string) => Promise<Array<{ worktree: string, branch: string }>>,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   readText: (path: string) => Promise<string>,
+ *   resolveChangeId: (gitRoot: string, changeId: string | undefined, options: { command: string }) => Promise<string>,
+ *   runCommand: typeof import("../exec.js").runCommand,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function resolveFinishContext(gitRoot, options, deps) {
+  const changeId = await deps.resolveChangeId(gitRoot, options.changeId, { command: "finish" });
+  deps.assertValidChangeId(changeId);
+
+  const changeBranch = `change/${changeId}`;
+  const changeBranchRef = `refs/heads/${changeBranch}`;
+
+  const hasChangeBranch = await deps
+    .runCommand("git", ["show-ref", "--verify", "--quiet", changeBranchRef], { cwd: gitRoot })
+    .then((result) => result.code === 0);
+  if (!hasChangeBranch) {
+    throw new deps.UserError(`Missing change branch: ${changeBranch}`, {
+      details: "Hint: create it with `aiws change start <change-id>` (or `git switch -c change/<id>`).",
+    });
+  }
+
+  const clean = await deps.checkGitClean(gitRoot);
+  if (!clean.clean) {
+    throw new deps.UserError("Refusing to finish with a dirty working tree.", {
+      details: `${clean.details}\n\nHint: commit or stash your changes, then retry.`,
+    });
+  }
+
+  const cur = await deps.currentBranch(gitRoot);
+  const intoRaw = String(options.into || "").trim();
+  const baseRaw = String(options.base || "").trim();
+  if (intoRaw && baseRaw && intoRaw !== baseRaw) {
+    throw new deps.UserError("change finish: cannot combine --into with --base (values differ).", {
+      details: `--into=${intoRaw}\n--base=${baseRaw}`,
+    });
+  }
+
+  /** @type {string} */
+  let into = intoRaw || baseRaw;
+
+  if (!into) {
+    if (!cur) {
+      throw new deps.UserError("Detached HEAD: cannot infer target branch for finish.", {
+        details: "Hint: switch to the target branch (e.g. main) and retry, or pass `aiws change finish <id> --into <branch>`.",
+      });
+    }
+    if (cur !== changeBranch) {
+      into = cur;
+    } else {
+      const metaPath = path.join(gitRoot, "changes", changeId, ".ws-change.json");
+      /** @type {any} */
+      let meta = null;
+      if (await deps.pathExists(metaPath)) {
+        try {
+          meta = JSON.parse(await deps.readText(metaPath));
+        } catch {
+          meta = null;
+        }
+      }
+      if (!meta) {
+        const show = await deps.runCommand("git", ["show", `${changeBranch}:changes/${changeId}/.ws-change.json`], { cwd: gitRoot });
+        if (show.code === 0) {
+          try {
+            meta = JSON.parse(String(show.stdout || ""));
+          } catch {
+            meta = null;
+          }
+        }
+      }
+      const inferred = meta && typeof meta === "object" ? String(meta.base_branch || "").trim() : "";
+      if (!inferred) {
+        throw new deps.UserError("Cannot infer base branch for finish.", {
+          details: "Hint: run from the target branch (e.g. main), or pass: `aiws change finish <id> --into <branch>`.",
+        });
+      }
+      into = inferred;
+    }
+  }
+
+  if (into === changeBranch) {
+    throw new deps.UserError("change finish: target branch cannot be the change branch.", { details: `target=${into}` });
+  }
+
+  const worktrees = await deps.listGitWorktrees(gitRoot);
+  const intoRef = `refs/heads/${into}`;
+  const intoWt = worktrees.find((worktree) => String(worktree.branch || "") === intoRef);
+  if (intoWt && path.resolve(intoWt.worktree) !== path.resolve(gitRoot)) {
+    throw new deps.UserError("Target branch is checked out in another worktree.", {
+      details: `branch: ${into}\nworktree: ${intoWt.worktree}\n\nHint: run finish in that worktree:\n  cd ${intoWt.worktree}\n  aiws change finish ${changeId}`,
+    });
+  }
+
+  const hasIntoBranch = await deps.runCommand("git", ["show-ref", "--verify", "--quiet", intoRef], { cwd: gitRoot }).then((result) => result.code === 0);
+  if (!hasIntoBranch) {
+    throw new deps.UserError("Target branch does not exist.", { details: `branch: ${into}` });
+  }
+
+  const changeWt = worktrees.find((worktree) => String(worktree.branch || "") === changeBranchRef);
+  return { changeId, changeBranch, changeBranchRef, into, cur, worktrees, changeWt };
+}

package/src/commands/change-git-status.js

@@ -0,0 +1,53 @@
+import { runCommand } from "../exec.js";
+import { UserError } from "../errors.js";
+
+const CONFLICT_STATUS_RE = /^(DD|AU|UD|UA|DU|AA|UU)$/;
+
+/**
+ * @param {string} output
+ */
+export function parseGitStatusPorcelain(output) {
+  const lines = String(output || "")
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+
+  let staged = 0;
+  let unstaged = 0;
+  let untracked = 0;
+  let conflicted = 0;
+
+  for (const line of lines) {
+    const xy = line.slice(0, 2);
+    if (xy === "??") {
+      untracked += 1;
+      continue;
+    }
+    if (CONFLICT_STATUS_RE.test(xy)) {
+      conflicted += 1;
+      continue;
+    }
+    if (xy[0] && xy[0] !== " " && xy[0] !== "?") staged += 1;
+    if (xy[1] && xy[1] !== " ") unstaged += 1;
+  }
+
+  return {
+    clean: lines.length === 0,
+    total: lines.length,
+    staged,
+    unstaged,
+    untracked,
+    conflicted,
+  };
+}
+
+/**
+ * @param {string} gitRoot
+ */
+export async function collectGitStatus(gitRoot) {
+  const res = await runCommand("git", ["status", "--porcelain", "--untracked-files=all"], { cwd: gitRoot });
+  if (res.code !== 0) {
+    throw new UserError("Failed to inspect git status for change governance.", { details: res.stderr || res.stdout });
+  }
+  return parseGitStatusPorcelain(res.stdout || "");
+}

package/src/commands/change-lifecycle-entry.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string
+ * }} input
+ * @param {{
+ *   changeDirAbs: (gitRoot: string, changeId: string) => string,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   runChangeSyncWorkflow: (input: any, deps: any) => Promise<{ output: string }>,
+ *   workflowDeps: Record<string, any>,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function runChangeSyncCommand(input, deps) {
+  const changeDir = deps.changeDirAbs(input.gitRoot, input.changeId);
+  if (!(await deps.pathExists(changeDir))) {
+    throw new deps.UserError(`Missing change dir: ${path.relative(input.gitRoot, changeDir)}`);
+  }
+  return deps.runChangeSyncWorkflow(
+    {
+      gitRoot: input.gitRoot,
+      changeId: input.changeId,
+      changeDir,
+    },
+    deps.workflowDeps,
+  );
+}
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   options: { datePrefix?: string, force: boolean }
+ * }} input
+ * @param {{
+ *   changeDirAbs: (gitRoot: string, changeId: string) => string,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   runChangeArchiveWorkflow: (input: any, deps: any) => Promise<{ output: string }>,
+ *   workflowDeps: Record<string, any>,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function runChangeArchiveCommand(input, deps) {
+  const changeDir = deps.changeDirAbs(input.gitRoot, input.changeId);
+  if (!(await deps.pathExists(changeDir))) {
+    throw new deps.UserError(`Missing change dir: ${path.relative(input.gitRoot, changeDir)}`);
+  }
+  return deps.runChangeArchiveWorkflow(
+    {
+      gitRoot: input.gitRoot,
+      changeId: input.changeId,
+      changeDir,
+      datePrefix: input.options.datePrefix,
+      force: input.options.force,
+    },
+    deps.workflowDeps,
+  );
+}