wize-dev-kit 0.26.1 → 0.27.2

package/tools/installer/commands/version-check.js

@@ -6,33 +6,92 @@
 // by a human, or by an AI agent shelling out from a skill instruction where
 // stdout is never a TTY — so it always answers, in `--json` when a caller
 // needs to parse it.
+//
+// The answer carries the project's state and one `action` with the exact
+// command to run, so a caller never compares versions itself.
 
 'use strict';
 
-const { getVersionCheckResult } = require('../version-check.js');
+const path = require('node:path');
+const { getVersionCheckDetailed } = require('../version-check.js');
+const { getProjectStatus, ACTION_EXIT_CODES } = require('../project-status.js');
+
+const DEFAULT_KIT_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+const ACTION_TEXT = {
+  hydrate: (s) => `This checkout is not hydrated (${s.reason}): run \`${s.commands.hydrate}\``,
+  'use-pin': (s) => `Project pinned ${s.pin} is newer than this kit (${s.installed}): run \`${s.commands.hydrate}\``,
+  install: (s) => `No .wize/config/project.toml here: run \`${s.commands.install}\``,
+  update: (s) => `Project pinned ${s.pin || 'none'} (${s.reason}): run \`${s.commands.update}\``
+};
+
+const KIT_NOT_ON_BRANCH_TEXT = (s) => `The kit is installed on ${s.kit_at}'s branch but not on this one (kit-not-on-branch): merge the kit into this branch, or pass --here to install here (\`${s.commands.install} --here\`)`;
 
-async function cmdVersionCheck({ currentVersion, json = false, log = console.log } = {}) {
-  const result = await getVersionCheckResult(currentVersion);
+async function cmdVersionCheck({
+  currentVersion,
+  kitRoot = DEFAULT_KIT_ROOT,
+  projectRoot = null,
+  cwd = process.cwd(),
+  json = false,
+  refresh = false,
+  quiet = false,
+  exitCode = false,
+  log = console.log
+} = {}) {
+  const { published_versions: published, ...base } = await getVersionCheckDetailed(currentVersion, { skipCache: refresh });
+
+  // The background refresher: fetch, write the cache, say nothing.
+  if (refresh && quiet) return { ...base, exitCode: 0 };
+
+  const status = getProjectStatus({ kitRoot, cwd: projectRoot || cwd, latest: base.latest, latestSource: base.latest_source, published });
+  const hasProject = !!status.root;
+  const result = {
+    ...base,
+    schema: 2,
+    project: hasProject ? {
+      root: status.root,
+      pin: status.pin,
+      pin_status: status.pin_status,
+      hydrated: status.hydrated,
+      missing_targets: status.missing_targets,
+      marker_version: status.marker_version,
+      user_toml: status.user_toml
+    } : null,
+    git: status.git,
+    ...(status.kit_at ? { kit_at: status.kit_at } : {}),
+    skew: status.skew,
+    action: status.action,
+    reason: status.reason,
+    commands: status.commands
+  };
+  result.exitCode = exitCode ? (ACTION_EXIT_CODES[status.action] ?? 0) : 0;
 
   if (json) {
-    log(JSON.stringify(result));
+    const { exitCode: _omit, ...printable } = result;
+    log(JSON.stringify(printable));
     return result;
   }
 
   if (result.disabled) {
     log('Update check disabled (WIZE_DISABLE_UPDATE_CHECK=1).');
-    return result;
-  }
-  if (!result.latest) {
+  } else if (!result.latest) {
     log(`wize-dev-kit ${result.installed} (could not reach the registry — offline or timed out).`);
-    return result;
-  }
-  if (result.updateAvailable) {
+  } else if (result.updateAvailable) {
     log(`↑ Update available: wize-dev-kit ${result.installed} → ${result.latest}`);
     log('  Run `npx wize-dev-kit@latest update` in your project to refresh adapters — or `/wize-update` from inside your AI harness.');
   } else {
     log(`wize-dev-kit ${result.installed} is up to date.`);
   }
+
+  if (status.reason === 'kit-not-on-branch') {
+    log(`→ ${KIT_NOT_ON_BRANCH_TEXT(status)}`);
+    return result;
+  }
+
+  const covered = status.action === 'update' && result.updateAvailable;
+  if (status.action !== 'none' && !covered && ACTION_TEXT[status.action]) {
+    log(`→ ${ACTION_TEXT[status.action](status)}`);
+  }
   return result;
 }
 

package/tools/installer/document-project/modes/full-rescan.js

@@ -9,7 +9,7 @@ const { runInitialScan } = require('./initial-scan.js');
 
 function runFullRescan(projectRoot, options = {}) {
   archiveOldState(projectRoot);
-  return runInitialScan(projectRoot, { ...options, mode: 'full_rescan' });
+  return runInitialScan(projectRoot, { ...options, mode: 'full_rescan', overwrite: true });
 }
 
 module.exports = { runFullRescan };

package/tools/installer/document-project/modes/initial-scan.js

@@ -39,7 +39,7 @@ function existingDocs(root) {
   return candidates.filter(f => fs.existsSync(path.join(root, f))).map(f => path.join(root, f));
 }
 
-function runInitialScan(projectRoot, { scanLevel = 'quick', log = console.log, csvPath } = {}) {
+function runInitialScan(projectRoot, { scanLevel = 'quick', log = console.log, csvPath, overwrite = false } = {}) {
   const classification = classifyProject(projectRoot, csvPath ? { csvPath } : {});
   const state = initState(projectRoot, 'initial_scan', scanLevel);
 
@@ -68,9 +68,10 @@ function runInitialScan(projectRoot, { scanLevel = 'quick', log = console.log, c
     });
   }
 
-  // Always write baseline + index.
-  const quick = runQuick(projectRoot, { log });
-  generated.push(...quick.written.map(f => path.join(projectRoot, '.wize', 'knowledge', 'document-project', f)));
+  // Write the missing baseline files (existing ones are kept unless overwrite) + index.
+  const quick = runQuick(projectRoot, { log, overwrite });
+  const baselineDir = path.join(projectRoot, '.wize', 'knowledge', 'document-project');
+  generated.push(...[...quick.written, ...(quick.skipped || [])].map(f => path.join(baselineDir, f)));
 
   const indexResult = renderIndex(projectRoot, {
     projectTypes: classification.projectTypes,

package/tools/installer/document-project/modes/quick.js

@@ -196,16 +196,23 @@ function runQuick(projectRoot, opts = {}) {
   const dir = path.join(projectRoot, '.wize', 'knowledge', 'document-project');
   fs.mkdirSync(dir, { recursive: true });
 
+  const overwrite = opts.overwrite === true;
   const written = [];
+  const skipped = [];
   for (const [name, factory] of Object.entries(BASELINE_FILES)) {
     const file = path.join(dir, name);
-    const content = factory(projectRoot, pkg);
-    fs.writeFileSync(file, content, 'utf-8');
+    if (!overwrite && fs.existsSync(file)) {
+      skipped.push(name);
+      continue;
+    }
+    fs.writeFileSync(file, factory(projectRoot, pkg), 'utf-8');
     written.push(name);
   }
 
-  if (opts.log) opts.log(`Quick baseline written to ${dir}`);
-  return { changed: true, mode: 'quick', written };
+  if (opts.log) {
+    opts.log(`Quick baseline: wrote ${written.length}, kept ${skipped.length} existing (use --force to overwrite)`);
+  }
+  return { changed: written.length > 0, mode: 'quick', written, skipped };
 }
 
 module.exports = { runQuick, BASELINE_FILES, countLines };

package/tools/installer/git-context.js

@@ -0,0 +1,219 @@
+// Read-only git facts about a project root: is it a repo, a linked worktree,
+// which branch, where the primary checkout lives. Every call is bounded and
+// failure-safe; a missing git binary degrades to a `.git` file/dir probe.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { real } = require('./util.js');
+
+function git(root, args, { timeout = 3000 } = {}) {
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+      timeout,
+      encoding: 'utf-8',
+      maxBuffer: 256 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+  } catch {
+    return null;
+  }
+}
+
+function revParseTriple(root) {
+  let out = git(root, ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-dir', '--git-common-dir']);
+  if (out === null) out = git(root, ['rev-parse', '--show-toplevel', '--git-dir', '--git-common-dir']);
+  if (out === null) return null;
+  const lines = out.split('\n').filter(Boolean);
+  if (lines.length < 3) return null;
+  return lines.slice(0, 3).map(l => real(path.resolve(root, l)));
+}
+
+// Parses `git worktree list --porcelain` into [{ path, head, branch, detached, bare }].
+function worktreeList(root) {
+  const out = git(root, ['worktree', 'list', '--porcelain']);
+  if (out === null) return null;
+  const list = [];
+  let cur = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      cur = { path: line.slice('worktree '.length), head: null, branch: null, detached: false, bare: false };
+      list.push(cur);
+    } else if (!cur) {
+      continue;
+    } else if (line.startsWith('HEAD ')) cur.head = line.slice(5);
+    else if (line.startsWith('branch ')) cur.branch = line.slice(7).replace(/^refs\/heads\//, '');
+    else if (line === 'detached') cur.detached = true;
+    else if (line === 'bare') cur.bare = true;
+  }
+  return list;
+}
+
+function fallbackContext(root) {
+  const base = { isRepo: false, toplevel: null, gitDir: null, commonDir: null, linked: false, primary: null, branch: null, detached: false, head: null };
+  // git failed: a .git above the root (monorepo subdir) still means a repo,
+  // so the root's caller must keep its git guards on instead of going non-git.
+  let top = root;
+  let st;
+  for (;;) {
+    try { st = fs.statSync(path.join(top, '.git')); break; } catch { /* keep walking */ }
+    const up = path.dirname(top);
+    if (up === top) return base;
+    top = up;
+  }
+  const dotGit = path.join(top, '.git');
+  if (st.isDirectory()) {
+    return { ...base, isRepo: true, toplevel: real(top), gitDir: real(dotGit), commonDir: real(dotGit), primary: real(top) };
+  }
+  let gitDir = null;
+  try {
+    const m = fs.readFileSync(dotGit, 'utf-8').match(/^gitdir:\s*(.+)$/m);
+    if (m) gitDir = real(path.resolve(top, m[1].trim()));
+  } catch { /* unreadable .git file */ }
+  return { ...base, isRepo: true, linked: true, toplevel: real(top), gitDir };
+}
+
+function gitContext(root) {
+  const triple = revParseTriple(root);
+  if (!triple) return fallbackContext(root);
+  const [toplevel, gitDir, commonDir] = triple;
+
+  let primary = null;
+  const wt = worktreeList(root);
+  if (wt && wt.length) primary = real(wt[0].path);
+  else if (path.basename(commonDir) === '.git') primary = path.dirname(commonDir);
+
+  const branchOut = git(root, ['symbolic-ref', '--short', '-q', 'HEAD']);
+  const branch = branchOut ? branchOut.trim() || null : null;
+  const headOut = git(root, ['rev-parse', '--short', 'HEAD']);
+  const head = headOut ? headOut.trim() || null : null;
+
+  return {
+    isRepo: true,
+    toplevel,
+    gitDir,
+    commonDir,
+    linked: gitDir !== commonDir,
+    primary,
+    branch,
+    detached: branch === null,
+    head
+  };
+}
+
+function localBranchExists(root, name) {
+  return git(root, ['rev-parse', '--verify', '-q', `refs/heads/${name}`]) !== null;
+}
+
+// origin/HEAD target, else the first existing local branch among
+// init.defaultBranch, main, master; null when none exists.
+function defaultBranch(root) {
+  const head = git(root, ['symbolic-ref', '--short', '-q', 'refs/remotes/origin/HEAD']);
+  if (head && head.trim()) return head.trim().replace(/^origin\//, '');
+  const configured = git(root, ['config', 'init.defaultBranch']);
+  const candidates = [configured && configured.trim(), 'main', 'master'].filter(Boolean);
+  for (const name of candidates) {
+    if (localBranchExists(root, name)) return name;
+  }
+  return null;
+}
+
+// Absolute paths of every tracked file in the repository that contains `root`
+// (listed from the toplevel, so a project in a monorepo subdirectory still sees
+// tracked files elsewhere in the repo that a symlink could lead to; paths are
+// resolved through the real toplevel, so symlinked checkouts compare equal). A submodule
+// (gitlink) is tracked as one entry, so `has()` also answers true for any path
+// inside one: a write there would change another repository's tracked files.
+// An empty Set means a repo with nothing tracked; null means git failed
+// (missing binary, "dubious ownership"), so the caller must not assume
+// nothing is tracked.
+class TrackedPaths extends Set {
+  constructor() {
+    super();
+    this.gitlinks = [];
+  }
+
+  has(abs) {
+    if (super.has(abs)) return true;
+    return this.gitlinks.some(g => abs.startsWith(g + path.sep));
+  }
+}
+
+function trackedSet(root) {
+  const top = git(root, ['rev-parse', '--show-toplevel']);
+  if (top === null || !top.trim()) return null;
+  const toplevel = path.resolve(root, top.trim());
+  const out = git(toplevel, ['ls-files', '-s', '-z', '--full-name'], { timeout: 15000 });
+  if (out === null) return null;
+  const base = real(toplevel);
+  const set = new TrackedPaths();
+  for (const entry of out.split('\0')) {
+    const tab = entry.indexOf('\t');
+    if (tab < 0) continue;
+    const abs = path.resolve(base, entry.slice(tab + 1));
+    set.add(abs);
+    if (entry.startsWith('160000 ')) set.gitlinks.push(abs);
+  }
+  return set;
+}
+
+// Tracked files (paths relative to `root`) under the given pathspecs; empty
+// when not a repo or git fails.
+function trackedUnder(root, pathspecs) {
+  if (!pathspecs || !pathspecs.length) return [];
+  const out = git(root, ['ls-files', '-z', '--', ...pathspecs], { timeout: 15000 });
+  return out ? out.split('\0').filter(Boolean) : [];
+}
+
+// Absolute paths of tracked files with uncommitted changes (staged or not),
+// listed from the repository toplevel so a tracked symlinked output directory
+// that leads elsewhere in the repo is covered too. Null when git fails.
+function dirtyTrackedSet(root) {
+  const top = git(root, ['rev-parse', '--show-toplevel']);
+  if (top === null || !top.trim()) return null;
+  const toplevel = real(path.resolve(root, top.trim()));
+  const out = git(toplevel, ['status', '--porcelain', '-z', '--untracked-files=no'], { timeout: 15000 });
+  if (out === null) return null;
+  const set = new Set();
+  const parts = out.split('\0');
+  for (let i = 0; i < parts.length; i++) {
+    const entry = parts[i];
+    if (entry.length < 4) continue;
+    set.add(path.resolve(toplevel, entry.slice(3)));
+    if (/[RC]/.test(entry.slice(0, 2))) i++; // a rename/copy carries its source as the next entry
+  }
+  return set;
+}
+
+function hasRemote(root, name = 'origin') {
+  const out = git(root, ['remote']);
+  return !!out && out.split('\n').map(s => s.trim()).includes(name);
+}
+
+// Lines of `git status --porcelain` (limited to `paths` when given); null when
+// git is unavailable or fails.
+function statusPorcelain(root, paths = []) {
+  const out = git(root, ['status', '--porcelain', ...(paths.length ? ['--', ...paths] : [])], { timeout: 15000 });
+  if (out === null) return null;
+  return out.split('\n').filter(Boolean);
+}
+
+// `git config user.name` as seen from `root`; null when unset.
+function configUserName(root) {
+  const out = git(root, ['config', 'user.name']);
+  return out && out.trim() ? out.trim() : null;
+}
+
+// Whether `ref` resolves to a commit.
+function refExists(root, ref) {
+  return git(root, ['rev-parse', '--verify', '-q', `${ref}^{commit}`]) !== null;
+}
+
+module.exports = {
+  gitContext, defaultBranch, trackedSet, dirtyTrackedSet, trackedUnder, hasRemote, worktreeList, statusPorcelain, configUserName,
+  localBranchExists, refExists
+};

package/tools/installer/git-ops.js

@@ -0,0 +1,211 @@
+// Mutating and network git/gh operations used by `update`. Every wrapper uses
+// execFileSync (no shell), never throws, and returns { ok, out, err } so the
+// caller decides what a failure means. Read-only facts live in git-context.js.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { defaultBranch, gitContext } = require('./git-context.js');
+const { real } = require('./util.js');
+
+function run(cmd, cwd, args, { timeout = 60000, env = null } = {}) {
+  try {
+    const out = execFileSync(cmd, args, {
+      cwd,
+      timeout,
+      encoding: 'utf-8',
+      maxBuffer: 256 * 1024 * 1024,
+      env: { ...process.env, ...(env || {}) },
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return { ok: true, out, err: '' };
+  } catch (e) {
+    const out = e && e.stdout ? String(e.stdout) : '';
+    const err = [e && e.stderr ? String(e.stderr) : '', out].join('').trim() || (e && e.message) || 'failed';
+    return { ok: false, out, err };
+  }
+}
+
+const git = (cwd, args, opts) => run('git', cwd, args, opts);
+const NO_PROMPT = { GIT_TERMINAL_PROMPT: '0' };
+
+// ---- reads against a ref -------------------------------------------------
+
+// Content of `rel` (relative to cwd) at `ref`; null when absent or not a
+// regular file. A symlink blob would read back as its target text and a
+// gitlink is a submodule, so neither is ever treated as file content.
+function treeMode(cwd, ref, rel) {
+  const t = git(cwd, ['ls-tree', '-z', ref, '--', rel]);
+  if (!t.ok) return null;
+  const entry = t.out.split('\0').filter(Boolean)[0];
+  return entry ? entry.split(' ')[0] : null;
+}
+
+// True when `rel` exists at `ref` but is not a regular file (symlink, gitlink).
+function isSpecialAt(cwd, ref, rel) {
+  const mode = treeMode(cwd, ref, rel);
+  return mode !== null && mode !== '100644' && mode !== '100755';
+}
+
+function showFile(cwd, ref, rel) {
+  if (treeMode(cwd, ref, rel) === null || isSpecialAt(cwd, ref, rel)) return null;
+  const r = git(cwd, ['show', `${ref}:./${rel}`]);
+  return r.ok ? r.out : null;
+}
+
+// Files tracked at `ref` under `paths` (relative to cwd, no leading `./`).
+function lsTree(cwd, ref, paths) {
+  const r = git(cwd, ['ls-tree', '-r', '--name-only', '-z', ref, '--', ...paths]);
+  return r.ok ? r.out.split('\0').filter(Boolean) : [];
+}
+
+// Files in the index under `paths`.
+function lsFiles(cwd, paths) {
+  const r = git(cwd, ['ls-files', '-z', '--', ...paths]);
+  return r.ok ? r.out.split('\0').filter(Boolean) : [];
+}
+
+// Paths (relative to the repository top level) that differ between two commits.
+// null when git fails.
+function diffNames(cwd, from, to) {
+  const r = git(cwd, ['diff', '--name-only', '--no-renames', '-z', from, to]);
+  return r.ok ? r.out.split('\0').filter(Boolean) : null;
+}
+
+function headSha(cwd) {
+  const r = git(cwd, ['rev-parse', 'HEAD']);
+  return r.ok ? r.out.trim() : null;
+}
+
+// ---- guards --------------------------------------------------------------
+
+// Hard guard: throws when `cwd` is checked out on the default branch.
+function assertNotDefaultBranch(cwd) {
+  const ctx = gitContext(cwd);
+  if (!ctx.isRepo) return;
+  const def = defaultBranch(cwd);
+  if (ctx.branch && (ctx.branch === def || ctx.branch === 'main' || ctx.branch === 'master')) {
+    throw new Error(`refusing to commit on ${ctx.branch}`);
+  }
+}
+
+// ---- worktrees -----------------------------------------------------------
+
+// A detached, fully checked-out worktree of `ref`. Commit hooks assume a
+// working tree that matches the index (`git add -u` would stage the deletion of
+// every file a sparse checkout left out, and tools such as the pre-commit
+// framework read their config from disk), so the tree is complete. LFS
+// objects are not downloaded (pointer files are checked out) and hooks are
+// disabled for the checkout itself, since post-checkout can run arbitrary
+// project code; the commit still runs the project's hooks.
+function worktreeAdd(cwd, dir, ref) {
+  const env = { GIT_LFS_SKIP_SMUDGE: '1' };
+  return git(cwd, ['-c', 'core.hooksPath=/dev/null', 'worktree', 'add', '--detach', '-q', dir, ref], { timeout: 300000, env });
+}
+
+function worktreeRemove(cwd, dir) {
+  return git(cwd, ['worktree', 'remove', '--force', dir]);
+}
+
+// Drops the admin data of the worktree at `dir` only, when `worktree remove`
+// could not. A repo-wide `git worktree prune` would also delete the entries of
+// unrelated worktrees whose directory is momentarily missing (an unmounted
+// volume, a directory moved by hand).
+function worktreeForget(cwd, dir) {
+  const common = git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!common.ok) return;
+  const admin = path.join(common.out.trim(), 'worktrees');
+  const wanted = real(path.join(dir, '.git'));
+  let names;
+  try { names = fs.readdirSync(admin); } catch { return; }
+  for (const name of names) {
+    try {
+      const recorded = fs.readFileSync(path.join(admin, name, 'gitdir'), 'utf-8').trim();
+      if (real(recorded) === wanted) fs.rmSync(path.join(admin, name), { recursive: true, force: true });
+    } catch { /* not ours or unreadable: leave it */ }
+  }
+}
+
+// ---- index and history ---------------------------------------------------
+
+function add(cwd, paths) {
+  return git(cwd, ['add', '--', ...paths]);
+}
+
+function rmCached(cwd, paths) {
+  return git(cwd, ['rm', '--cached', '-q', '--', ...paths]);
+}
+
+// Never passes --no-verify: the project's hooks decide.
+function commit(cwd, subject, body) {
+  assertNotDefaultBranch(cwd);
+  return git(cwd, ['commit', '-q', '-m', subject, ...(body ? ['-m', body] : [])], { timeout: 300000 });
+}
+
+function branchCreate(cwd, name, sha) {
+  return git(cwd, ['branch', name, sha]);
+}
+
+// Compare-and-swap: fails unless the branch still points at `oldSha`.
+function updateRef(cwd, branch, newSha, oldSha) {
+  return git(cwd, ['update-ref', `refs/heads/${branch}`, newSha, oldSha]);
+}
+
+// ---- remote --------------------------------------------------------------
+
+function fetch(cwd, remote, branch) {
+  return git(cwd, ['fetch', '--quiet', remote, branch], { timeout: 30000, env: NO_PROMPT });
+}
+
+// Never forces.
+function push(cwd, remote, branch) {
+  return git(cwd, ['push', '-u', remote, `refs/heads/${branch}:refs/heads/${branch}`], { timeout: 120000, env: NO_PROMPT });
+}
+
+// https://github.com/<owner>/<repo> for a GitHub origin (ssh or https); else null.
+function originWebUrl(cwd) {
+  const r = git(cwd, ['remote', 'get-url', 'origin']);
+  if (!r.ok) return null;
+  const url = r.out.trim();
+  const m = url.match(/^(?:git@|ssh:\/\/git@|https?:\/\/(?:[^@/]+@)?)github\.com[:/]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+  return m ? `https://github.com/${m[1]}/${m[2]}` : null;
+}
+
+// ---- gh ------------------------------------------------------------------
+
+function ghAvailable() {
+  return run('gh', process.cwd(), ['--version'], { timeout: 10000 }).ok;
+}
+
+// { url, state } of the PR for `branch`, or null.
+function ghPrView(cwd, branch) {
+  const r = run('gh', cwd, ['pr', 'view', branch, '--json', 'url,state'], { timeout: 30000, env: NO_PROMPT });
+  if (!r.ok) return null;
+  try {
+    const data = JSON.parse(r.out);
+    return data && data.url ? { url: data.url, state: data.state || null } : null;
+  } catch {
+    return null;
+  }
+}
+
+// Returns { ok, url, err }.
+function ghPrCreate(cwd, { base, head, title, body }) {
+  const r = run('gh', cwd, ['pr', 'create', '--base', base, '--head', head, '--title', title, '--body', body], { timeout: 60000, env: NO_PROMPT });
+  if (!r.ok) return { ok: false, url: null, err: r.err };
+  const url = r.out.split('\n').map(s => s.trim()).filter(Boolean).pop() || null;
+  return { ok: true, url, err: '' };
+}
+
+// Best-effort removal of a temp directory a failed `worktree remove` left behind.
+function rmDir(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+module.exports = {
+  run, showFile, isSpecialAt, lsTree, lsFiles, diffNames, headSha, assertNotDefaultBranch,
+  worktreeAdd, worktreeRemove, worktreeForget, add, rmCached, commit, branchCreate, updateRef,
+  fetch, push, originWebUrl, ghAvailable, ghPrView, ghPrCreate, rmDir
+};