moshcode 0.24.0

package/src/prd.mjs

@@ -0,0 +1,341 @@
+// OpenPRD — DIP-style numbered product requirements docs, published in-repo.
+// moshcode is a conductor: `/prd` publishes a numbered proposal into the local
+// repo per the OpenPRD standard from LogicSRC, then hands it to a coding engine
+// to author. Layout mirrors a BIP/EIP/DIP process:
+//   prd/README.md          index (maintained by this tool)
+//   prd/0000-template.md   the template
+//   prd/NNNN-slug.md       one numbered PRD per file (committed, NOT gitignored)
+// Standard: https://github.com/profullstack/logicsrc/blob/master/docs/openprd.md
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+export const OPENPRD = {
+  version: "0.2",
+  dir: "prd",
+  standard: "https://github.com/profullstack/logicsrc/blob/master/docs/openprd.md",
+};
+
+const INDEX_START = "<!-- PRD-INDEX:START -->";
+const INDEX_END = "<!-- PRD-INDEX:END -->";
+
+/** kebab-case slug from an idea/title. */
+export function slugify(text) {
+  const s = String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .split("-").slice(0, 8).join("-");
+  return s || "untitled";
+}
+
+function titleFrom(idea) {
+  const raw = String(idea || "").trim();
+  const t = raw.length > 80 ? raw.slice(0, 80).trim() + "…" : raw;
+  return t ? t.charAt(0).toUpperCase() + t.slice(1) : "Untitled PRD";
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function yamlString(value) {
+  return JSON.stringify(String(value ?? ""));
+}
+
+function gitEmail(root) {
+  try {
+    return execSync("git config user.email", { cwd: root, stdio: ["ignore", "pipe", "ignore"] })
+      .toString().trim() || "you@example.com";
+  } catch { return "you@example.com"; }
+}
+
+export function prdDir(root = process.cwd()) {
+  return path.join(root, OPENPRD.dir);
+}
+
+/** The canonical OpenPRD template (prd/0000-template.md), mirroring the standard. */
+export function templateFile() {
+  return `---
+openprd: "${OPENPRD.version}"
+id: "0000"
+title: "Short imperative title — start with a verb if possible"
+status: Draft
+authors:
+  - you@example.com
+created: 2026-01-01
+updated: 2026-01-01
+repo:
+discussion:
+implementation:
+tags:
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+The user/business problem, and why it matters now.
+
+## Goals
+
+What success looks like, as outcomes (not features).
+
+## Non-Goals
+
+Explicitly out of scope, to bound the work.
+
+## Users
+
+Who this is for; personas or segments.
+
+## Requirements
+
+- R1 [P0] First required capability.
+- R2 [P1] Next capability.
+
+## UX Notes
+
+Flows, states, and constraints that shape the experience.
+
+## Success Metrics
+
+How the goals will be measured.
+
+## Risks & Open Questions
+
+- Known risk or decision still owed.
+`;
+}
+
+// The seed marker is a hidden HTML comment, so a `-->` inside the idea would
+// close it early and render the rest of the idea (plus the real closer) as
+// visible text at the top of the Problem section. Neutralise the terminator.
+function commentSafe(text) {
+  return String(text).replace(/--+>/g, (run) => `${run.slice(0, -1)}&gt;`);
+}
+
+/** A numbered PRD body (prd/NNNN-slug.md), seeded from an idea. */
+export function renderPrd({ id, title, idea, author }) {
+  const seed = idea && idea !== title ? `\n<!-- seed: ${commentSafe(idea)} -->` : "";
+  return `---
+openprd: "${OPENPRD.version}"
+id: "${id}"
+title: ${yamlString(title)}
+status: Draft
+authors:
+  - ${author}
+created: ${today()}
+updated: ${today()}
+repo:
+discussion:
+implementation:
+tags:
+supersedes:
+superseded-by:
+---
+
+## Problem
+${seed}
+_Describe the user/business problem, and why it matters now._
+
+## Goals
+_What success looks like, as outcomes (not features)._
+
+## Non-Goals
+_Explicitly out of scope._
+
+## Users
+_Who this is for; personas or segments._
+
+## Requirements
+- R1 [P0] _First required capability._
+- R2 [P1] _Next capability._
+
+## UX Notes
+_Flows, states, and constraints that shape the experience._
+
+## Success Metrics
+_How the goals will be measured._
+
+## Risks & Open Questions
+- _Known risk or decision still owed._
+`;
+}
+
+/** Static README preamble + the auto-maintained index markers. */
+function readmeShell() {
+  return `# PRDs
+
+Product requirements documents for this repo, following the
+[OpenPRD](${OPENPRD.standard}) standard — a numbered, committed proposal
+collection (like a BIP/EIP/DIP process).
+
+Each PRD is one file: \`NNNN-slug.md\`. \`0000-template.md\` is the template.
+Lifecycle: **Draft → Review → Accepted → Final** (or Rejected / Withdrawn /
+Superseded). Status lives in each file's front-matter.
+
+Start one with \`moshcode prd "<idea>"\` (TUI: \`/prd\`).
+
+## Index
+
+${INDEX_START}
+${INDEX_END}
+`;
+}
+
+// Read a front-matter scalar back to its plain text. renderPrd writes the title
+// as a quoted YAML string so metacharacters stay valid, so the quotes (and any
+// escapes inside them) are syntax, not part of the title — strip them, or every
+// listing and index row shows `"My title"` instead of `My title`.
+function unquoteYaml(value) {
+  const raw = String(value).trim();
+  if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+    try { return JSON.parse(raw); } catch { return raw.slice(1, -1); }
+  }
+  if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1).replace(/''/g, "'");
+  }
+  return raw;
+}
+
+// The front matter is the block between the leading `---` and its closing
+// `---`; everything after that is prose. Reading a fixed window of leading
+// lines instead let a body line that merely starts with `title:`/`status:` —
+// a YAML sample in a fenced code block, say — win, because the scan kept the
+// last match it saw anywhere in the window. It also cut off longer front
+// matter. Return the block itself, or nothing when the file has none.
+function frontMatter(text) {
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return [];
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+  return end === -1 ? [] : lines.slice(1, end);
+}
+
+/** List numbered PRDs (NNNN-slug.md, excluding the 0000 template). */
+export function listPrds(root = process.cwd()) {
+  const base = prdDir(root);
+  let entries = [];
+  try { entries = fs.readdirSync(base); } catch { return []; }
+  const out = [];
+  for (const name of entries) {
+    const m = name.match(/^(\d{4})-(.+)\.md$/);
+    if (!m || m[1] === "0000") continue;
+    const file = path.join(base, name);
+    let title = m[2], status = "?";
+    try {
+      const head = frontMatter(fs.readFileSync(file, "utf8"));
+      for (const l of head) {
+        const t = l.match(/^title:\s*(.+)$/); if (t) title = unquoteYaml(t[1]);
+        const s = l.match(/^status:\s*(.+)$/); if (s) status = unquoteYaml(s[1]);
+      }
+    // A file this cannot read is still a PRD, and its number is still taken.
+    // Dropping it contradicts what the rest of this loop does: a PRD whose
+    // front matter will not parse is deliberately kept on the slug/"?"
+    // fallbacks above rather than discarded. Worse, `nextId` takes its max
+    // from this list, so dropping one hands its number straight back out and
+    // two PRDs end up numbered the same — in a scheme where the number is the
+    // identity. A committed symlink whose target is not checked out is enough
+    // to trigger it: `readFileSync` throws ENOENT. Keep the entry on the same
+    // fallbacks; the id stays reserved and the index row keeps its link.
+    } catch { /* unreadable: keep it with the file-name fallbacks */ }
+    out.push({ id: m[1], slug: m[2], title, status, file: name, path: file });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** Next zero-padded 4-digit id (max existing + 1, min 0001). */
+export function nextId(root = process.cwd()) {
+  const ids = listPrds(root).map((p) => parseInt(p.id, 10)).filter(Number.isFinite);
+  const max = ids.length ? Math.max(...ids) : 0;
+  return String(max + 1).padStart(4, "0");
+}
+
+/** Rewrite the README index table from the current PRDs on disk. */
+export function regenerateIndex(root = process.cwd()) {
+  const readme = path.join(prdDir(root), "README.md");
+  let body;
+  try { body = fs.readFileSync(readme, "utf8"); } catch { return false; }
+  const prds = listPrds(root);
+  // A `|` in a title would close its table cell early and shift every column
+  // after it, so escape it for the markdown table. Escape `\` first: escaping
+  // the pipe alone turns `a\|b` into `a\\|b`, which markdown reads as an escaped
+  // backslash followed by a *live* pipe — the very break this is preventing.
+  // A newline would end the row outright, so flatten it to a space.
+  const cell = (text) => String(text)
+    .replace(/\\/g, "\\\\")
+    .replace(/\|/g, "\\|")
+    .replace(/\r\n?|\n/g, " ");
+  // The same reasoning applies to the link cell, which `cell` cannot help with:
+  // a file name is a link *destination*, so it has to end up a valid URL, not
+  // just an escaped table cell. `listPrds` accepts any `NNNN-<anything>.md` on
+  // disk — the test suite treats "a doc dropped into prd/" as supported, and a
+  // doc exported from a writing tool arrives as `0002-Search Ranking.md` — so
+  // the name is not always the slug `createPrd` would have produced. A space
+  // ends the destination early and the link dies; a `|` closes the cell and
+  // shifts every column after it, dropping Status off the row entirely.
+  // Percent-encode it: `p.file` is a bare readdir entry, never a path, so
+  // encodeURIComponent is safe here, and `(`/`)` are added by hand because it
+  // leaves those alone and an unescaped `)` would close the link early.
+  const linkTarget = (file) => encodeURIComponent(file)
+    .replace(/\(/g, "%28")
+    .replace(/\)/g, "%29");
+  const rows = prds.length
+    ? ["| # | Title | Status |", "|---|---|---|",
+       ...prds.map((p) => `| [${p.id}](${linkTarget(p.file)}) | ${cell(p.title)} | ${cell(p.status)} |`)].join("\n")
+    : "_No PRDs yet._";
+  // Use a function replacement so `$`-sequences in a PRD title (e.g. `$&`, `$1`,
+  // `$\`` ) are inserted verbatim instead of being read as String.replace special
+  // patterns, which would otherwise splice the match back in and corrupt the index.
+  const block = `${INDEX_START}\n${rows}\n${INDEX_END}`;
+  const next = body.replace(
+    new RegExp(`${INDEX_START}[\\s\\S]*${INDEX_END}`),
+    () => block,
+  );
+  if (next === body) return false;
+  fs.writeFileSync(readme, next);
+  return true;
+}
+
+/** Create prd/README.md + prd/0000-template.md if missing. Returns true if it bootstrapped. */
+export function ensureBootstrap(root = process.cwd()) {
+  const base = prdDir(root);
+  fs.mkdirSync(base, { recursive: true });
+  let did = false;
+  const tpl = path.join(base, "0000-template.md");
+  if (!fs.existsSync(tpl)) { fs.writeFileSync(tpl, templateFile()); did = true; }
+  const readme = path.join(base, "README.md");
+  if (!fs.existsSync(readme)) { fs.writeFileSync(readme, readmeShell()); did = true; }
+  return did;
+}
+
+/**
+ * Publish a numbered PRD into the local repo. Bootstraps prd/ on first use.
+ * Returns { id, slug, path, existed, bootstrapped }.
+ */
+export function createPrd(idea, root = process.cwd()) {
+  const bootstrapped = ensureBootstrap(root);
+  const slug = slugify(idea);
+  const title = titleFrom(idea);
+  // Reuse an existing PRD if the same slug already has a number.
+  const existing = listPrds(root).find((p) => p.slug === slug);
+  const id = existing ? existing.id : nextId(root);
+  const file = path.join(prdDir(root), `${id}-${slug}.md`);
+  const existed = fs.existsSync(file);
+  if (!existed) fs.writeFileSync(file, renderPrd({ id, title, idea, author: gitEmail(root) }));
+  regenerateIndex(root);
+  return { id, slug, path: file, existed, bootstrapped };
+}
+
+/** Prompt handed to a coding engine to author the scaffolded PRD in place. */
+export function authoringPrompt({ path: file, idea }) {
+  return [
+    `Author a product requirements document at ${file} following the OpenPRD standard`,
+    `(${OPENPRD.standard}).`,
+    idea ? `The idea: ${idea}.` : "",
+    `Fill every one of the 8 sections (Problem, Goals, Non-Goals, Users, Requirements,`,
+    `UX Notes, Success Metrics, Risks & Open Questions), replacing the placeholder text.`,
+    `Keep the YAML front-matter and its keys (leave status: Draft). Number requirements`,
+    `R1, R2, … each with a [P0]/[P1]/[P2] priority. Be concrete and specific to this codebase.`,
+  ].filter(Boolean).join(" ");
+}

package/src/pty.mjs

@@ -0,0 +1,176 @@
+// PTY capture for the session mirror.
+//
+// Children are launched with `stdio: "inherit"` so they own the real terminal —
+// which is why an engine or tool feels native, and also why the mirror never
+// saw a byte of their output: those writes go to the tty's file descriptors and
+// never pass through this process (see src/mirror.mjs).
+//
+// To see them we have to be in the middle, but a plain pipe is not an option:
+// every one of these programs checks isTTY and degrades (no colour, no prompts,
+// no full-screen UI) the moment it is talking to a pipe. So we run the child
+// under a real pseudo-terminal and read a copy of the stream from the side.
+//
+// node-pty would be the obvious tool and is deliberately not used: it is a
+// native module, and moshcode installs by untarring a release and running node
+// (see install.sh) — there is no compiler in that path. `script(1)` allocates
+// the same pseudo-terminal using nothing but the base system.
+//
+// Capability detection is required, not optional: util-linux and BSD/macOS
+// `script` disagree on both flag names and argument order, and anything we
+// cannot positively identify falls back to today's plain `inherit`.
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+
+/**
+ * POSIX single-quote escaping, for argv that has to survive being flattened
+ * into the single command string util-linux `script -c` accepts. A bare
+ * interpolation here would let an argument like `it's` break the command, or
+ * worse, run something else.
+ */
+export function shQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Which `script(1)` this machine has: "util-linux", "bsd", or null when there
+ * is none we can drive. util-linux answers `--version`; BSD's has no version
+ * flag and exits non-zero on it, so darwin is identified by platform.
+ */
+export function scriptFlavor({ platform = process.platform, runner = spawnSync } = {}) {
+  let out = "";
+  try {
+    const r = runner("script", ["--version"], { encoding: "utf8" });
+    if (r?.error) return null;
+    out = `${r?.stdout || ""}${r?.stderr || ""}`;
+  } catch {
+    return null;
+  }
+  if (/util-linux/i.test(out)) return "util-linux";
+  // BSD script printed a usage error rather than a version — that is still a
+  // usable script, but only on darwin do we know the flag set for certain.
+  if (platform === "darwin") return "bsd";
+  return null;
+}
+
+/**
+ * The spawn spec that runs `cmd args…` under a pseudo-terminal while recording
+ * a copy of everything to `transcript`. Returns null for an unknown flavour.
+ *
+ * -q / -Q suppress script's own "Script started/done" banner, so the transcript
+ * holds the child's bytes and nothing else. -f / -F flush on every write, which
+ * is what makes this realtime rather than a post-mortem log. util-linux -e
+ * makes script exit with the child's status, which callers rely on.
+ */
+export function ptySpec(cmd, args = [], transcript, flavor) {
+  if (!cmd || !transcript) return null;
+  if (flavor === "util-linux") {
+    const line = [cmd, ...args].map(shQuote).join(" ");
+    return { cmd: "script", args: ["-q", "-e", "-f", "-c", line, transcript] };
+  }
+  if (flavor === "bsd") {
+    // BSD takes the transcript first and then a real argv, so no quoting.
+    return { cmd: "script", args: ["-q", "-F", transcript, cmd, ...args] };
+  }
+  return null;
+}
+
+/**
+ * Follow a transcript as it is written, handing each new slice to `onChunk`.
+ *
+ * Polls the size rather than using fs.watch: watch is unreliable across
+ * platforms and filesystems for a file being appended to by another process,
+ * and the mirror already batches on a 150ms timer, so a short poll costs
+ * nothing in perceived latency. Returns a stop() that drains whatever landed
+ * after the last tick before closing — the tail of a session is usually the
+ * part you care about.
+ *
+ * Bytes are decoded through a StringDecoder rather than per-slice toString:
+ * a slice boundary lands wherever the poll happened to catch the file, which
+ * is regularly in the middle of a multi-byte character. Engines draw their
+ * full-screen UI out of box-drawing characters (three UTF-8 bytes each), so
+ * decoding each slice independently turns them into U+FFFD in the mirror. The
+ * decoder holds the incomplete tail back until the rest of it arrives.
+ */
+export function followFile(file, onChunk, { intervalMs = 100 } = {}) {
+  let fd = null;
+  let offset = 0;
+  let stopped = false;
+  let decoder = new StringDecoder("utf8");
+
+  const readNew = () => {
+    try {
+      if (fd === null) {
+        if (!existsSync(file)) return;
+        fd = openSync(file, "r");
+      }
+      const { size } = statSync(file);
+      // A transcript only grows; a smaller size means it was rotated or
+      // replaced, so resync rather than read garbage from the middle. Any
+      // half-character held back belongs to the old file, so drop it too.
+      if (size < offset) {
+        offset = 0;
+        decoder = new StringDecoder("utf8");
+      }
+      while (offset < size) {
+        const buf = Buffer.allocUnsafe(Math.min(65536, size - offset));
+        const read = readSync(fd, buf, 0, buf.length, offset);
+        if (read <= 0) break;
+        offset += read;
+        const text = decoder.write(buf.subarray(0, read));
+        if (text) onChunk(text);
+      }
+    } catch {
+      /* the child owns this file; a transient read error is not our problem */
+    }
+  };
+
+  const timer = setInterval(readNew, intervalMs);
+  timer.unref?.(); // never hold the process open for the sake of the mirror
+
+  return function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+    readNew(); // final drain
+    // Nothing more is coming, so a character still held back really is
+    // truncated. Emit it rather than swallowing the last bytes of a session.
+    const tail = decoder.end();
+    if (tail) onChunk(tail);
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* already gone */ }
+      fd = null;
+    }
+  };
+}
+
+// `script -q` silences the "Script started/done" notices on the terminal but
+// still writes them into the transcript, so without this the mirror opens every
+// engine session with a line of script(1) bookkeeping — including the fully
+// quoted command line — and closes it with an exit-code footer. Both are
+// anchored (header at the very start, footer at the very end), so this never
+// touches output that merely happens to contain the words.
+const HEADER = /^Script started on [^\n]*\n/;
+const FOOTER = /\r?\nScript done on [^\n]*\n?$/;
+
+/**
+ * Remove script(1)'s own bookkeeping from a transcript slice. `first` marks the
+ * opening slice, the only place a header can legitimately appear.
+ */
+export function stripScriptBanner(text, first = false) {
+  const withoutHeader = first ? String(text).replace(HEADER, "") : String(text);
+  return withoutHeader.replace(FOOTER, "");
+}
+
+/**
+ * Should we capture this launch? Only when someone is actually watching (a
+ * mirror sink is attached) and the box has a script(1) we understand. Users who
+ * are not mirroring keep the exact `inherit` path they have today, so the
+ * blast radius of this feature is limited to mirrored sessions.
+ * MOSHCODE_MIRROR_PTY=0 forces it off.
+ */
+export function ptyEnabled(sink, flavor = scriptFlavor()) {
+  if (typeof sink !== "function") return false;
+  if (process.env.MOSHCODE_MIRROR_PTY === "0") return false;
+  return Boolean(flavor);
+}

package/src/pwd.mjs

@@ -0,0 +1,103 @@
+// `moshcode pwd` / `/pwd` — where am I? Shows the current directory and, when
+// inside a git repo, the repo root, branch, and origin. Zero-dependency: we
+// read the .git dir directly instead of spawning git (moshcode stays lean and
+// works even when git isn't on PATH).
+import fs from "node:fs";
+import path from "node:path";
+
+// Resolve a `.git` entry (dir or worktree/submodule file `gitdir: <path>`) to
+// its actual git directory, or null if it can't be read.
+function resolveGitDir(dotgit, dir) {
+  try {
+    const st = fs.statSync(dotgit);
+    if (st.isDirectory()) return dotgit;
+    if (st.isFile()) {
+      const m = /gitdir:\s*(.+)\s*/.exec(fs.readFileSync(dotgit, "utf8"));
+      return m ? path.resolve(dir, m[1].trim()) : null;
+    }
+  } catch { /* fall through */ }
+  return null;
+}
+
+// A linked worktree's git dir (.git/worktrees/<name>) holds only that
+// worktree's own HEAD and index — the shared config, and therefore the
+// remotes, stay in the main repo's git dir. Git names it in a `commondir`
+// file, usually as a path relative to the worktree's git dir. Resolve it so
+// origin is found from inside a worktree; outside one there is no such file
+// and the git dir is already the common one.
+function commonGitDir(gitDir) {
+  try {
+    const pointer = fs.readFileSync(path.join(gitDir, "commondir"), "utf8").trim();
+    if (pointer) return path.resolve(gitDir, pointer);
+  } catch { /* not a linked worktree */ }
+  return gitDir;
+}
+
+// Walk up from `start` until we find a `.git` with a readable HEAD (a real
+// repo). A bare `.git` dir with no HEAD — e.g. a stray /tmp/.git — is skipped,
+// not mistaken for a repo. Returns { root, gitDir } or null at the fs root.
+function findGit(start) {
+  let dir = start;
+  for (;;) {
+    const dotgit = path.join(dir, ".git");
+    if (fs.existsSync(dotgit)) {
+      const gitDir = resolveGitDir(dotgit, dir);
+      if (gitDir && fs.existsSync(path.join(gitDir, "HEAD"))) return { root: dir, gitDir };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null; // reached "/" (or a drive root)
+    dir = parent;
+  }
+}
+
+function readBranch(gitDir) {
+  try {
+    const head = fs.readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
+    const m = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
+    if (m) return m[1];
+    return head.slice(0, 12) + " (detached)"; // detached HEAD → short sha
+  } catch {
+    return null;
+  }
+}
+
+function readOrigin(gitDir) {
+  try {
+    const cfg = fs.readFileSync(path.join(gitDir, "config"), "utf8");
+    // Find the [remote "origin"] section's url. Fall back to the first remote.
+    const origin = /\[remote "origin"\][^[]*?url\s*=\s*(.+)/s.exec(cfg);
+    if (origin) return origin[1].split("\n")[0].trim();
+    const any = /\[remote "[^"]+"\][^[]*?url\s*=\s*(.+)/s.exec(cfg);
+    return any ? any[1].split("\n")[0].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve where we are. Returns { cwd, home, git }, where git is null outside a
+ * repo, else { root, name, branch, origin }.
+ */
+export function locate(cwd = process.cwd()) {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  const found = findGit(cwd);
+  if (!found || !found.gitDir) return { cwd, home, git: null };
+  return {
+    cwd,
+    home,
+    git: {
+      root: found.root,
+      name: path.basename(found.root),
+      // HEAD is per-worktree; config (and its remotes) is shared.
+      branch: readBranch(found.gitDir),
+      origin: readOrigin(commonGitDir(found.gitDir)),
+    },
+  };
+}
+
+// Collapse $HOME to `~` for tidy display.
+export function tilde(p, home) {
+  if (!home || p === home) return home ? "~" : p;
+  const relative = p.slice(home.length);
+  return p.startsWith(home) && relative.startsWith(path.sep) ? "~" + relative : p;
+}

package/src/registry.mjs

@@ -0,0 +1,37 @@
+// The moshscript command registry — the single source of truth for the verbs a
+// .mosh script can call.
+//
+// A command is a plain object: { name, summary, run(ctx, ...args) }.
+//   - name:    the identifier the script calls, e.g. "mosh" → mosh()
+//   - summary: one-liner for `moshcode commands` / help
+//   - run:     the implementation; receives the runtime ctx plus the JS call
+//              arguments spread out (so `notify("hi", "there")` → args = ["hi","there"]).
+//
+// The runtime (src/runtime.mjs) injects every registered command as a global of
+// the same name, so scripts call them bare: `mosh()`, `notify("…")`. New verbs —
+// engine launches, tool passthrough, fan-out — are added by registering more
+// commands here (or via registry.register(...) from a host), never by touching
+// the interpreter.
+
+export function createRegistry(commands = []) {
+  const byName = new Map();
+
+  const register = (cmd) => {
+    if (!cmd || typeof cmd.name !== "string" || typeof cmd.run !== "function") {
+      throw new Error("moshscript: a command needs { name, run() }");
+    }
+    byName.set(cmd.name, { summary: "", ...cmd });
+    return api;
+  };
+
+  const api = {
+    register,
+    has: (name) => byName.has(name),
+    get: (name) => byName.get(name),
+    all: () => [...byName.values()],
+    names: () => [...byName.keys()],
+  };
+
+  commands.forEach(register);
+  return api;
+}