@ionivetech/mugiwara 0.6.4 → 0.6.6

package/src/continue.ts

@@ -0,0 +1,243 @@
+// src/continue.ts
+// Deterministic resume-point reader. Powers `mugiwara continue` and
+// `mugiwara status` — pure fs + JSON, zero model judgement. The prose skills
+// used to describe this scan so the host model would perform it; that cost a
+// full reasoning turn to answer "what is in flight?". This is the same answer
+// in one process spawn.
+//
+// Reads what scripts/savepoint.sh writes:
+//   .mugiwara/continue/<mission>/state.json    (solo)
+//   .mugiwara/continue/<mission>/<member>.json (team)
+//   .mugiwara/state/<mission>/...              (same shape, more fields)
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/** Mission/member allowlist — identical to savepoint.sh and mission.ts. */
+const SAFE = /^[A-Za-z0-9._-]+$/;
+const isSafeKey = (s: string): boolean => SAFE.test(s) && !/^\.+$/.test(s);
+
+export type ContinueEntry = {
+  mission: string;
+  member: string | null;
+  actor: string;
+  branch: string;
+  flow: number;
+  mode: string;
+  tasks_done: number;
+  tasks_total: number;
+  lane: string;
+  next_action: string;
+  next_session_prompt: string;
+  updated_at: string;
+};
+
+export type StateEntry = ContinueEntry & {
+  lane_reason: string;
+  lane_rose: boolean;
+  lane_prev: string;
+  lane_peak: string;
+  blockers_open: number;
+  heal_cycle: number;
+  heal_max_cycles: number;
+  heal_halt: boolean;
+  delegate_threshold: number;
+  delegate_due: boolean;
+  tokens_est: number;
+  budget: number;
+  budget_status: string;
+  files_touched: number;
+  evidence: string[];
+};
+
+const num = (v: unknown): number => {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+};
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+
+/**
+ * Resolve the git actor exactly as scripts/savepoint.sh does:
+ * STATE_ACTOR → GIT_AUTHOR_NAME → "name <email>" → USER. A byte difference
+ * here silently filters every mission out of the listing.
+ */
+export function gitActor(cwd: string): string {
+  const env = (process.env.STATE_ACTOR ?? '').trim();
+  if (env) return env;
+  const author = (process.env.GIT_AUTHOR_NAME ?? '').trim();
+  if (author) return author;
+  const git = (args: string[]): string => {
+    try {
+      return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {
+      return '';
+    }
+  };
+  const name = git(['config', 'user.name']);
+  const email = git(['config', 'user.email']);
+  if (name && email) return `${name} <${email}>`;
+  // USERNAME is the Windows spelling of USER; savepoint.sh resolves the same
+  // chain, and the two must stay byte-identical or the actor filter drops rows.
+  return name || process.env.USER || process.env.USERNAME || '';
+}
+
+/** Read every JSON under `.mugiwara/<root>/<mission>/*.json`. Corrupt files are skipped. */
+function scan<T>(projectDir: string, root: string, map: (raw: Record<string, unknown>, member: string | null) => T): T[] {
+  const base = join(projectDir, '.mugiwara', root);
+  if (!existsSync(base)) return [];
+  const out: T[] = [];
+  const missions = readdirSync(base, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isSafeKey(e.name))
+    .map((e) => e.name)
+    .sort();
+  for (const mission of missions) {
+    const dir = join(base, mission);
+    for (const f of readdirSync(dir).filter((n) => n.endsWith('.json')).sort()) {
+      // state.json is the solo (member-less) file; <member>.json is a team member
+      const stem = f.slice(0, -'.json'.length);
+      const member = stem === 'state' ? null : stem;
+      if (member !== null && !isSafeKey(member)) continue;
+      try {
+        const raw = JSON.parse(readFileSync(join(dir, f), 'utf8')) as Record<string, unknown>;
+        // trust the path over the file body: a mission field that disagrees
+        // with its own directory is a corrupt or hand-edited file
+        if (text(raw.mission) !== mission) continue;
+        out.push(map(raw, member));
+      } catch {
+        // corrupt savepoint — skip, never crash the listing
+      }
+    }
+  }
+  return out;
+}
+
+export function readContinue(projectDir: string): ContinueEntry[] {
+  return scan(projectDir, 'continue', (r, member) => ({
+    mission: text(r.mission),
+    member,
+    actor: text(r.actor),
+    branch: text(r.branch),
+    flow: num(r.flow ?? r.wave),
+    mode: text(r.mode) || 'guided',
+    tasks_done: num(r.tasks_done),
+    tasks_total: num(r.tasks_total),
+    lane: text(r.lane) || 'direct',
+    next_action: text(r.next_action),
+    next_session_prompt: text(r.next_session_prompt),
+    updated_at: text(r.updated_at),
+  }));
+}
+
+export function readState(projectDir: string): StateEntry[] {
+  return scan(projectDir, 'state', (r, member) => {
+    const tasks = (r.tasks ?? {}) as Record<string, unknown>;
+    return {
+      mission: text(r.mission),
+      member,
+      actor: text(r.actor),
+      branch: text(r.branch),
+      flow: num(r.flow ?? r.wave),
+      mode: text(r.mode) || 'guided',
+      tasks_done: num(tasks.done),
+      tasks_total: num(tasks.total),
+      lane: text(r.lane) || 'direct',
+      lane_reason: text(r.lane_reason),
+      lane_rose: r.lane_rose === true,
+      lane_prev: text(r.lane_prev),
+      lane_peak: text(r.lane_peak),
+      next_action: '',
+      next_session_prompt: '',
+      updated_at: text(r.updated_at),
+      blockers_open: num(r.blockers_open),
+      heal_cycle: num(r.heal_cycle),
+      heal_max_cycles: num(r.heal_max_cycles) || 3,
+      heal_halt: r.heal_halt === true,
+      delegate_threshold: num(r.delegate_threshold) || 60,
+      delegate_due: r.delegate_due === true,
+      tokens_est: num(r.tokens_est),
+      budget: num(r.budget),
+      budget_status: text(r.budget_status) || 'ok',
+      files_touched: num(r.files_touched),
+      evidence: Array.isArray(r.evidence) ? r.evidence.map(text).filter(Boolean) : [],
+    };
+  });
+}
+
+export type Resolution =
+  | { kind: 'none' }
+  | { kind: 'missions'; entries: ContinueEntry[] }
+  | { kind: 'members'; mission: string; entries: ContinueEntry[] }
+  | { kind: 'unknown-mission'; mission: string; known: string[] }
+  | { kind: 'unknown-member'; mission: string; member: string; known: string[] }
+  | { kind: 'resume'; entry: ContinueEntry };
+
+/**
+ * The three command forms, decided from disk alone:
+ *   (none)            → list every in-flight mission
+ *   <mission>         → solo resumes; team lists its members
+ *   <mission> <member>→ resume that member
+ *
+ * Solo-vs-team needs no plan-doc parse: savepoint writes `state.json` with a
+ * null member for solo and `<member>.json` per team member.
+ */
+export function resolveContinue(entries: ContinueEntry[], mission?: string, member?: string): Resolution {
+  if (!entries.length) return { kind: 'none' };
+
+  if (!mission) {
+    const missions = [...new Set(entries.map((e) => e.mission))];
+    if (missions.length === 1) return resolveContinue(entries, missions[0], member);
+    return { kind: 'missions', entries };
+  }
+
+  const inMission = entries.filter((e) => e.mission === mission);
+  if (!inMission.length) {
+    return { kind: 'unknown-mission', mission, known: [...new Set(entries.map((e) => e.mission))] };
+  }
+
+  if (member) {
+    const hit = inMission.find((e) => e.member === member);
+    if (!hit) {
+      return {
+        kind: 'unknown-member',
+        mission,
+        member,
+        known: inMission.map((e) => e.member ?? '(solo)'),
+      };
+    }
+    return { kind: 'resume', entry: hit };
+  }
+
+  const solo = inMission.find((e) => e.member === null);
+  // a solo file resumes directly; anything else needs the member picked, and
+  // is never guessed — resuming the wrong member's work is unrecoverable
+  if (solo && inMission.length === 1) return { kind: 'resume', entry: solo };
+  return { kind: 'members', mission, entries: inMission };
+}
+
+function pad(s: string, n: number): string {
+  return s.length >= n ? s : s + ' '.repeat(n - s.length);
+}
+
+/** Fixed-width table — the whole point is that the host prints this verbatim. */
+export function formatTable(entries: ContinueEntry[]): string {
+  const rows = entries.map((e) => [
+    e.mission,
+    e.member ?? '—',
+    String(e.flow),
+    `${e.tasks_done}/${e.tasks_total}`,
+    e.lane,
+    e.mode,
+  ]);
+  const head = ['MISSION', 'MEMBER', 'FLOW', 'TASKS', 'LANE', 'MODE'];
+  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const line = (cells: string[]): string =>
+    '  ' + cells.map((c, i) => pad(c, widths[i])).join('  ').trimEnd();
+  return [line(head), ...rows.map(line)].join('\n');
+}
+
+/** The single resume line the mugiwara-resume skill contracts for. */
+export function formatResume(e: ContinueEntry): string {
+  const scope = e.member ? ` [${e.member}]` : '';
+  const next = e.next_session_prompt || '(no next_session_prompt recorded)';
+  return `Resumed: ${e.mission}${scope}, Flow ${e.flow}, ${e.tasks_done}/${e.tasks_total} tasks — next_action: ${e.next_action} — run: ${next}`;
+}

package/src/installer.ts

@@ -44,6 +44,15 @@ export interface Target {
   transformSkillFull?(data: FrontmatterData, body: string): TransformOut | null;
   transformAgentFull?(data: FrontmatterData, body: string): TransformOut | null;
   postInstall?(opts: { scope: Scope; projectDir: string; home: string; dryRun: boolean; files: string[] }): { written: string[]; notes: string[] };
+  /**
+   * Undo anything postInstall did to a file mugiwara does not own.
+   *
+   * Files listed in the manifest are deleted wholesale on uninstall, so a
+   * shared file we merely EDITED (settings.json) must never be reported as
+   * written — deleting it destroys the user's own configuration. Such files are
+   * un-merged here instead.
+   */
+  postUninstall?(opts: { scope: Scope; projectDir: string; home: string; dryRun: boolean }): { changed: string[]; notes: string[] };
 }
 
 export const CONTENT_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'content');
@@ -151,6 +160,36 @@ export function installTo(target: Target, opts: InstallOptions): InstallResult {
     result.written.push(...post.written);
     result.notes.push(...post.notes);
   }
+
+  // TASK 8: a fresh install must be immediately usable — write a default
+  // .mugiwara/config (the same defaults `mugiwara onboard` would write) so no
+  // key silently falls back. Only for project scope; global installs don't own
+  // a project config. Never overwrite an existing config.
+  if (scope === 'project') {
+    const configPath = join(projectDir, '.mugiwara', 'config');
+    // lstat, not existsSync: a pre-created symlinked config must not be
+    // followed and overwritten (TOCTOU / symlink defense-in-depth).
+    let configExists = false;
+    try { configExists = lstatSync(configPath).isFile() || lstatSync(configPath).isSymbolicLink(); } catch { configExists = false; }
+    if (!configExists) {
+      const body = [
+        'mode=guided',
+        'branch=feature/{type}-{issue}-{slug}',
+        'commit=conventional',
+        'auto_commit=on',
+        'coverage_new=90',
+        'coverage_modified=80',
+        'review_depth=full',
+        'quality_depth=full',
+        'delegate_threshold=60',
+        'heal_max_cycles=3',
+        'verbosity=normal',
+      ].join('\n') + '\n';
+      if (!dryRun) { mkdirSync(dirname(configPath), { recursive: true }); writeFileSync(configPath, body); }
+      result.written.push(configPath);
+      result.notes.push(`default config written: ${configPath} (run \`mugiwara onboard\` to customise)`);
+    }
+  }
   return result;
 }
 

package/src/onboard.ts

@@ -0,0 +1,207 @@
+// src/onboard.ts — zero-LLM onboarding wizard (6 questions, writes .mugiwara/config).
+// Runs on every platform via the `mugiwara onboard` CLI command. No LLM, no network.
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRl, choose, confirm, type Rl } from './prompt.ts';
+
+// Canonical key order for the written config. Keys the wizard does not ask
+// about (auto_commit, delegate_threshold, heal_max_cycles, verbosity) are
+// preserved from an existing config, never reset to defaults.
+const DEFAULT_ORDER = [
+  'mode', 'branch', 'commit', 'auto_commit', 'coverage_new', 'coverage_modified',
+  'review_depth', 'quality_depth', 'delegate_threshold', 'heal_max_cycles', 'verbosity',
+];
+
+// Defaults for keys the wizard does not ask about — used only when the key is
+// absent from an existing config (fresh install). Existing values always win.
+const DEFAULTS: Record<string, string> = {
+  auto_commit: 'on',
+  delegate_threshold: '60',
+  heal_max_cycles: '3',
+  verbosity: 'normal',
+};
+
+const BRANCH_PRESETS: Record<number, string> = {
+  1: 'feature/{type}-{issue}-{slug}',
+  2: 'feature/{slug}',
+  3: 'feat/{slug}',
+};
+
+const COMMIT_PRESETS: Record<number, string> = {
+  1: 'conventional',
+  2: 'gitmoji',
+  3: 'plain',
+};
+
+export function parseConfig(lines: string[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const line of lines) {
+    const t = line.trim();
+    if (!t || t.startsWith('#')) continue;
+    const eq = t.indexOf('=');
+    if (eq === -1) continue;
+    const k = t.slice(0, eq).trim();
+    const v = t.slice(eq + 1).trim();
+    if (!map.has(k)) map.set(k, v);
+  }
+  return map;
+}
+
+export function buildConfig(existing: Map<string, string>, updates: Record<string, string>): string {
+  const merged = new Map(existing);
+  for (const [k, v] of Object.entries(updates)) merged.set(k, v);
+  const lines: string[] = [];
+  for (const k of DEFAULT_ORDER) {
+    const v = merged.get(k) ?? DEFAULTS[k];
+    if (v === undefined) continue;
+    lines.push(`${k}=${v}`);
+    merged.delete(k);
+  }
+  for (const [k, v] of merged) lines.push(`${k}=${v}`);
+  return lines.join('\n') + '\n';
+}
+
+async function askFreeText(rl: Rl, prompt: string): Promise<string> {
+  for (;;) {
+    const v = (await rl.question(prompt)).trim();
+    if (v) return v;
+    console.log('  Cannot be empty.');
+  }
+}
+
+// Same guard the runtime helpers use: a symlinked config must never be
+// overwritten through the wizard (the target file is not ours to write).
+function assertNotSymlink(file: string): void {
+  if (!existsSync(file)) return;
+  try {
+    if (lstatSync(file).isSymbolicLink()) throw new Error(`refusing to follow symlink: ${file}`);
+  } catch (e) {
+    if ((e as { code?: string }).code === 'ENOENT') return;
+    throw e;
+  }
+}
+
+export async function runOnboard(projectDir: string): Promise<void> {
+  if (!process.stdin.isTTY) {
+    throw new Error('Not a terminal. Run `mugiwara onboard` in a terminal, or edit .mugiwara/config directly.');
+  }
+  const mugiwaraDir = join(projectDir, '.mugiwara');
+  const configPath = join(mugiwaraDir, 'config');
+  assertNotSymlink(configPath);
+  const existing = parseConfig(existsSync(configPath) ? readFileSync(configPath, 'utf8').split(/\r?\n/) : []);
+
+  const rl = createRl();
+  try {
+    console.log('');
+    console.log('╔══════════════════════════════════════╗');
+    console.log('║   Mugiwara Onboarding Wizard         ║');
+    console.log('╚══════════════════════════════════════╝');
+    console.log('');
+
+    if (existing.size > 0) {
+      const redo = await confirm(rl, 'Existing .mugiwara/config found. Re-onboard?');
+      if (!redo) {
+        console.log('Onboarding cancelled. Config preserved.');
+        return;
+      }
+      console.log('');
+    }
+
+    // Q1 — branch pattern
+    const branchChoice = await choose(rl, 'Q1 — Branch naming pattern:', [
+      'Trunk-based — feature/{type}-{issue}-{slug}',
+      'GitFlow — feature/{slug}',
+      'GitHub Flow — feat/{slug}',
+      'Custom — enter your own pattern',
+    ]);
+    let branch: string;
+    if (branchChoice === 3) {
+      branch = await askFreeText(rl, '  Branch pattern (placeholders: {type} {issue} {slug}, e.g. {issue}-{slug}): ');
+    } else {
+      branch = BRANCH_PRESETS[branchChoice + 1];
+    }
+
+    // Q2 — autonomy mode
+    const modeIdx = await choose(rl, 'Q2 — Autonomy mode:', [
+      'guided — ask before every wave transition',
+      'semi — auto-advance through waves, pause on failures',
+      'auto — full auto-pilot',
+    ]);
+    const mode = ['guided', 'semi', 'auto'][modeIdx];
+
+    // Q3 — review depth
+    const reviewIdx = await choose(rl, 'Q3 — Code review depth:', [
+      'full — breaking-change map, five-axis review, <=3 cycles',
+      'standard — five-axis review, 1 cycle',
+      'quick — diff-only, no caller-map',
+    ]);
+    const reviewDepth = ['full', 'standard', 'quick'][reviewIdx];
+
+    // Q4 — quality depth
+    const qualityIdx = await choose(rl, 'Q4 — Quality check depth:', [
+      'full — format, lint, typecheck, test, build',
+      'standard — lint, typecheck, test',
+      'quick — test only',
+    ]);
+    const qualityDepth = ['full', 'standard', 'quick'][qualityIdx];
+
+    // Q5 — coverage
+    const covIdx = await choose(rl, 'Q5 — Test coverage threshold:', [
+      '90/80 — new code 90%, modified 80%',
+      '80/70 — new code 80%, modified 70%',
+      'custom — enter your own values',
+      'none — 0/0, no coverage enforcement',
+    ]);
+    let coverageNew = 90;
+    let coverageModified = 80;
+    if (covIdx === 1) { coverageNew = 80; coverageModified = 70; }
+    else if (covIdx === 2) {
+      coverageNew = Number.parseInt(await askFreeText(rl, '  Coverage for new code (%): '), 10) || 0;
+      coverageModified = Number.parseInt(await askFreeText(rl, '  Coverage for modified code (%): '), 10) || 0;
+    } else if (covIdx === 3) { coverageNew = 0; coverageModified = 0; }
+
+    // Q6 — commit style
+    const commitChoice = await choose(rl, 'Q6 — Commit style:', [
+      'Conventional Commits — feat:, fix:, chore:, docs:',
+      'Gitmoji — emoji-prefixed conventional',
+      'Plain — no prefix, imperative sentence',
+      'Custom template — enter your own (placeholders: {type} {issue} {title})',
+    ]);
+    let commit: string;
+    if (commitChoice === 3) {
+      commit = await askFreeText(rl, '  Commit template (e.g. {issue}: {title}): ');
+    } else {
+      commit = COMMIT_PRESETS[commitChoice + 1];
+    }
+
+    // ---- Write config ----
+    if (!existsSync(mugiwaraDir)) mkdirSync(mugiwaraDir, { recursive: true });
+    const body = buildConfig(existing, {
+      mode,
+      branch,
+      commit,
+      coverage_new: String(coverageNew),
+      coverage_modified: String(coverageModified),
+      review_depth: reviewDepth,
+      quality_depth: qualityDepth,
+    });
+    writeFileSync(configPath, `# .mugiwara/config — written by mugiwara onboard on ${new Date().toISOString().slice(0, 10)}\n${body}`);
+
+    // ---- Summary ----
+    console.log('╔══════════════════════════════════════╗');
+    console.log('║   Onboarding Complete                ║');
+    console.log('╚══════════════════════════════════════╝');
+    console.log('');
+    console.log(`  Branch pattern:   ${branch}`);
+    console.log(`  Autonomy mode:    ${mode}`);
+    console.log(`  Review depth:     ${reviewDepth}`);
+    console.log(`  Quality depth:    ${qualityDepth}`);
+    console.log(`  Coverage:         ${coverageNew}/${coverageModified}`);
+    console.log(`  Commit style:     ${commit}`);
+    console.log('');
+    console.log(`  Config written:   ${configPath}`);
+    console.log('');
+  } finally {
+    rl.close();
+  }
+}

package/src/run.ts

@@ -0,0 +1,82 @@
+// src/run.ts
+// `mugiwara run <script> [args...]` — runs a bundled harness script against the
+// current project.
+//
+// Why this exists: the skills tell the crew to run `scripts/savepoint.sh`, but
+// the installer only ever copied `content/` and `references/` into a project.
+// That path resolved against the project's cwd, where the file does not exist,
+// so every savepoint / lane / evidence / mission-report call silently did
+// nothing. Resolving from the package root fixes it for every install target at
+// once.
+import { existsSync, readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// src/ during dev, dist/ once bundled — scripts/ sits beside both
+export const SCRIPTS_DIR = join(here, '..', 'scripts');
+
+/** Scripts a project is meant to call. Anything else stays internal tooling. */
+export const RUNNABLE = ['savepoint.sh', 'lane.sh', 'evidence.sh', 'mission-report.sh'] as const;
+
+/**
+ * Locate a POSIX shell. Windows has none natively, but Git for Windows ships
+ * one and mugiwara is git-backed anyway — savepoint reads git to compute state,
+ * so a git-less machine cannot run a mission regardless.
+ */
+export function findBash(): string | null {
+  const explicit = process.env.MUGIWARA_BASH?.trim();
+  if (explicit) return existsSync(explicit) ? explicit : null;
+  const candidates =
+    process.platform === 'win32'
+      ? [
+          'C:\\Program Files\\Git\\bin\\bash.exe',
+          'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+          join(process.env.LOCALAPPDATA ?? '', 'Programs', 'Git', 'bin', 'bash.exe'),
+        ]
+      : // /bin/bash is not universal on Linux — Alpine and other busybox-based
+        // images ship /bin/sh only. Probing beats assuming: an assumed path
+        // spawns ENOENT, which surfaces as a stack trace instead of the
+        // actionable "no bash found" message below.
+        ['/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash', '/opt/homebrew/bin/bash'];
+  for (const p of candidates) {
+    if (p && existsSync(p)) return p;
+  }
+  // last resort: whatever is on PATH (Git Bash, WSL, MSYS, a nonstandard prefix)
+  const probe = spawnSync(process.platform === 'win32' ? 'where' : 'which', ['bash'], {
+    encoding: 'utf8',
+  });
+  const first = probe.stdout?.split(/\r?\n/).find((l) => l.trim());
+  return first?.trim() || null;
+}
+
+/** Platform-correct remedy for a missing bash — "install Git for Windows" is wrong advice on Linux. */
+export function noBashMessage(): string {
+  const remedy =
+    process.platform === 'win32'
+      ? 'Install Git for Windows (which ships bash)'
+      : 'Install bash with your package manager (e.g. `apk add bash`, `apt install bash`)';
+  return `no bash found. ${remedy}, or set MUGIWARA_BASH to a bash executable.`;
+}
+
+export function runScript(name: string, args: string[], projectDir: string): number {
+  // no path separators: `run` takes a script name, never an arbitrary path
+  if (!/^[a-z0-9-]+\.sh$/.test(name)) {
+    throw new Error(`invalid script name "${name}" (expected one of: ${RUNNABLE.join(', ')})`);
+  }
+  const script = join(SCRIPTS_DIR, name);
+  if (!existsSync(script)) {
+    const have = existsSync(SCRIPTS_DIR) ? readdirSync(SCRIPTS_DIR).filter((f) => f.endsWith('.sh')) : [];
+    throw new Error(`script not found: ${name}${have.length ? ` (available: ${have.join(', ')})` : ''}`);
+  }
+  const bash = findBash();
+  if (!bash) throw new Error(noBashMessage());
+  const r = spawnSync(bash, [script, ...args], {
+    cwd: resolve(projectDir),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  if (r.error) throw r.error;
+  return r.status ?? 1;
+}