@ree-auz/nook 0.0.0-stage → 0.1.0

package/src/hooks.mjs

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { createWriteStream, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import spawn from "cross-spawn";
+import { which } from "./agents.mjs";
+import { NookError } from "./errors.mjs";
+import { line, useColor, indenter } from "./ui.mjs";
+
+export const HOOK_EVENTS = ["create", "open", "remove"];
+
+/** Extensions tried for a hook, in order. Platform scripts first, then portable ones. */
+export function hookExtensions(platform = process.platform) {
+  return platform === "win32" ? [".ps1", ".cmd", ".mjs", ".py"] : [".sh", ".mjs", ".py"];
+}
+
+/** Every hook in `<dir>/.nook/` for this platform. */
+export function findHooks(dir, platform = process.platform) {
+  return HOOK_EVENTS.map((event) => findHook(dir, event, platform)).filter(Boolean);
+}
+
+/** The hook file for `event` in `<dir>/.nook/`, or null. */
+export function findHook(dir, event, platform = process.platform) {
+  let entries;
+  try {
+    entries = readdirSync(join(dir, ".nook"));
+  } catch {
+    return null;
+  }
+  for (const ext of hookExtensions(platform)) {
+    const name = event + ext;
+    if (entries.includes(name)) return { event, ext, name, file: join(dir, ".nook", name) };
+  }
+  return null;
+}
+
+/**
+ * Fingerprint of a hook's content. Line endings are normalized, so a Windows
+ * checkout (CRLF) and the same file with LF count as one version.
+ */
+export function hookHash(file) {
+  const text = readFileSync(file, "latin1").replace(/\r\n/g, "\n");
+  return createHash("sha256").update(text, "latin1").digest("hex");
+}
+
+/** How to run a hook file: { command, args }. */
+export function hookCommand(hook, { platform = process.platform, find = which } = {}) {
+  switch (hook.ext) {
+    case ".ps1": {
+      const shell = find("pwsh") ?? (platform === "win32" ? "powershell.exe" : "pwsh");
+      return { command: shell, args: ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", hook.file] };
+    }
+    case ".cmd":
+      return { command: hook.file, args: [] };
+    case ".sh":
+      return { command: find("bash") ?? "sh", args: [hook.file] };
+    case ".mjs":
+      return { command: process.execPath, args: [hook.file] };
+    case ".py": {
+      const python = find("python3") ?? find("python") ?? "python3";
+      return { command: python, args: [hook.file] };
+    }
+    default:
+      throw new NookError(`Unknown hook type: ${hook.name}`);
+  }
+}
+
+/** "trusted", "new" or "changed" for a hook of a repository. */
+export function trustState(repoConfig, hook) {
+  const saved = repoConfig.hooks?.[hook.name];
+  if (!saved) return "new";
+  return saved === hookHash(hook.file) ? "trusted" : "changed";
+}
+
+/**
+ * Asks once before hooks run for the first time, and again after one changes,
+ * listing every such hook of the repository (like worktrunk's approval prompt).
+ * The file contents are not printed; the paths say where to read them.
+ * `ui` is the command context (warn, info, item, note). Calls `save` after a yes.
+ */
+export async function ensureTrusted({ repoName, repoConfig, hooks, prompter, save, ui }) {
+  const pending = hooks.filter((hook) => trustState(repoConfig, hook) !== "trusted");
+  if (!pending.length) return;
+  const changed = pending.some((hook) => trustState(repoConfig, hook) === "changed");
+  const count = pending.length === 1 ? "1 hook" : `${pending.length} hooks`;
+  ui.warn(`${repoName} needs approval to run ${count}${changed ? " (changed since you allowed them)" : ""}:`);
+  for (const hook of pending)
+    ui.item(`${hook.event}: .nook/${hook.name}${trustState(repoConfig, hook) === "changed" ? " (changed)" : ""}`);
+  ui.info(`Read them in ${dirname(pending[0].file)}`);
+  let ok;
+  try {
+    ok = await prompter.confirm("Allow and remember?", false);
+  } catch {
+    throw new NookError(`Hooks of ${repoName} need your OK. Run nk in a terminal once, or nk init --allow-hooks after reading them`);
+  }
+  if (!ok) throw new NookError("Hooks were not allowed; nothing ran. Allow them by answering yes in a terminal, or with nk init --allow-hooks after reading them");
+  repoConfig.hooks ??= {};
+  for (const hook of pending) repoConfig.hooks[hook.name] = hookHash(hook.file);
+  save();
+}
+
+function stamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+/**
+ * Runs a hook in the workspace. Output goes to the terminal and to a log file.
+ * Resolves to { status, log }.
+ */
+export function runHook(hook, { cwd, env, logsDir, label, output = process.stderr }) {
+  mkdirSync(logsDir, { recursive: true });
+  const log = join(logsDir, `${label}-${hook.event}-${stamp()}.log`);
+  const stream = createWriteStream(log);
+  const { command, args } = hookCommand(hook);
+  output.write(`${line("step", `Running ${hook.event} hook .nook/${hook.name}`, useColor(output))}\n`);
+  return new Promise((done) => {
+    const child = spawn(command, args, { cwd, env, stdio: ["inherit", "pipe", "pipe"], windowsHide: true });
+    // Indented under the "Running … hook" line; the log keeps the output as it was.
+    const forward = (indent) => (chunk) => {
+      stream.write(chunk);
+      output.write(indent(chunk));
+    };
+    child.stdout.on("data", forward(indenter()));
+    child.stderr.on("data", forward(indenter()));
+    let finished = false;
+    const finish = (status, error) => {
+      if (finished) return;
+      finished = true;
+      if (error) stream.write(`\n${error.message}\n`);
+      stream.end(() => done({ status, log }));
+    };
+    child.on("error", (error) => finish(127, error));
+    child.on("close", (code, signal) => finish(code ?? (signal ? 1 : 0)));
+  });
+}

package/src/names.mjs

@@ -0,0 +1,65 @@
+import { NookError } from "./errors.mjs";
+
+export const SUBCOMMANDS = ["init", "ls", "rm", "clean", "hooks", "forget", "doctor", "help", "version"];
+
+/**
+ * Workspace name = branch name = folder name.
+ * Lowercase letters, digits, "-" and "."; no "/"; not a subcommand.
+ * Returns an error message, or null when the name is valid.
+ */
+export function nameProblem(name) {
+  if (typeof name !== "string" || name === "") return "name is empty";
+  if (name.length > 100) return "name is longer than 100 characters";
+  if (name.includes("/")) return `"${name}" contains "/"; use "-" instead`;
+  if (!/^[a-z0-9.-]+$/.test(name))
+    return `"${name}" may only use lowercase letters, digits, "-" and "."`;
+  if (!/^[a-z0-9]/.test(name)) return `"${name}" must start with a letter or digit`;
+  if (name.endsWith(".") || name.endsWith(".lock"))
+    return `"${name}" cannot end with "." or ".lock"`;
+  if (name.includes("..")) return `"${name}" cannot contain ".."`;
+  if (SUBCOMMANDS.includes(name)) return `"${name}" is a nk command; pick another name`;
+  return null;
+}
+
+export function assertName(name, what = "workspace") {
+  const problem = nameProblem(name);
+  if (problem) throw new NookError(`Invalid ${what} name: ${problem}`);
+  return name;
+}
+
+/**
+ * Turns any branch-like text into a valid name, so callers (trackers, scripts,
+ * people) can pass what they have: lowercase it, turn "/", spaces, non-ASCII
+ * and other characters into "-", and tidy the ends.
+ * "REE-267-Nook-第-1-步：建-nook" -> "ree-267-nook-1-nook"; "feat/Login" -> "feat-login".
+ */
+export function normalizeName(input) {
+  return String(input)
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/\.{2,}/g, ".")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[^a-z0-9]+/, "")
+    .replace(/(\.lock)+$/, "")
+    .replace(/[.-]+$/, "")
+    .slice(0, 100)
+    .replace(/[.-]+$/, "");
+}
+
+/** Normalizes, then checks what normalizing cannot fix (empty, command names). */
+export function toName(input) {
+  const name = normalizeName(input);
+  const problem = nameProblem(name);
+  if (problem) throw new NookError(`Cannot use "${input}" as a workspace name: ${problem}`);
+  return name;
+}
+
+/** Turns a folder name into a repository short name suggestion. */
+export function suggestRepoName(folder) {
+  const name = folder
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/^[^a-z0-9]+/, "")
+    .replace(/[.-]+$/, "");
+  return nameProblem(name) ? "repo" : name;
+}

package/src/occupancy-windows.ps1

@@ -0,0 +1,59 @@
+# Lists processes whose current directory is inside -Root.
+# Prints JSON: { processes: [{ pid, name, reasons }], inaccessible }.
+param([Parameter(Mandatory = $true)][string]$Root)
+$ErrorActionPreference = 'Stop'
+if ([Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -ne 'X64') { throw 'Windows x64 is required for the process scan' }
+Add-Type -TypeDefinition @'
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+using System.Runtime.InteropServices;
+namespace Nook {
+ public class DirectoryProcess { public int pid; public string name; }
+ public class DirectoryScan { public DirectoryProcess[] processes; public int inaccessible; }
+ public static class DirectoryInspector {
+  [DllImport("kernel32.dll")] static extern IntPtr OpenProcess(uint access, bool inherit, int pid);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);
+  [DllImport("kernel32.dll")] static extern bool ReadProcessMemory(IntPtr process, IntPtr address, byte[] buffer, IntPtr size, out IntPtr read);
+  [DllImport("kernel32.dll")] static extern bool IsWow64Process(IntPtr process, out bool wow64);
+  [DllImport("ntdll.dll")] static extern int NtQueryInformationProcess(IntPtr process, int infoClass, byte[] info, int size, out int returned);
+  static byte[] Read(IntPtr process, long address, int size) {
+   byte[] data = new byte[size]; IntPtr read;
+   if (!ReadProcessMemory(process, new IntPtr(address), data, new IntPtr(size), out read) || read.ToInt64() != size) throw new InvalidOperationException();
+   return data;
+  }
+  public static DirectoryScan Scan(string root) {
+   string target = Path.GetFullPath(root).TrimEnd('\\');
+   var found = new List<DirectoryProcess>(); int unavailable = 0;
+   foreach (Process process in Process.GetProcesses()) {
+    using (process) {
+     IntPtr handle = OpenProcess(0x410, false, process.Id);
+     if (handle == IntPtr.Zero) { unavailable++; continue; }
+     try {
+      bool wow64;
+      if (!IsWow64Process(handle, out wow64) || wow64) { unavailable++; continue; }
+      byte[] info = new byte[48]; int returned;
+      if (NtQueryInformationProcess(handle, 0, info, info.Length, out returned) != 0) { unavailable++; continue; }
+      long peb = BitConverter.ToInt64(info, 8);
+      long parameters = BitConverter.ToInt64(Read(handle, peb + 0x20, 8), 0);
+      // 64-bit RTL_USER_PROCESS_PARAMETERS.CurrentDirectory.DosPath.
+      byte[] current = Read(handle, parameters + 0x38, 16);
+      int length = BitConverter.ToUInt16(current, 0);
+      if (length == 0 || length > 32766 || length % 2 != 0) continue;
+      string cwd = System.Text.Encoding.Unicode.GetString(Read(handle, BitConverter.ToInt64(current, 8), length)).TrimEnd('\\');
+      if (cwd.StartsWith(@"\\?\", StringComparison.Ordinal)) cwd = cwd.Substring(4);
+      if (cwd.Equals(target, StringComparison.OrdinalIgnoreCase) || cwd.StartsWith(target + "\\", StringComparison.OrdinalIgnoreCase))
+       found.Add(new DirectoryProcess { pid = process.Id, name = process.ProcessName });
+     } catch { unavailable++; }
+     finally { CloseHandle(handle); }
+    }
+   }
+   return new DirectoryScan { processes = found.ToArray(), inaccessible = unavailable };
+  }
+ }
+}
+'@
+$scan = [Nook.DirectoryInspector]::Scan($Root)
+$processes = @($scan.processes | ForEach-Object { [ordered]@{ pid = $_.pid; name = $_.name; reasons = @('working directory') } })
+[pscustomobject]@{ processes = $processes; inaccessible = $scan.inaccessible } | ConvertTo-Json -Depth 5 -Compress

package/src/occupancy.mjs

@@ -0,0 +1,131 @@
+import { spawnSync } from "node:child_process";
+import { readdirSync, readlinkSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { which } from "./agents.mjs";
+import { isInside, realPath } from "./home.mjs";
+
+function add(found, pid, name, reason) {
+  const current = found.get(pid);
+  if (current) {
+    if (!current.reasons.includes(reason)) current.reasons.push(reason);
+  } else found.set(pid, { pid, name, reasons: [reason] });
+}
+
+function linuxScan(root) {
+  const found = new Map();
+  let inaccessible = 0;
+  for (const entry of readdirSync("/proc")) {
+    if (!/^\d+$/.test(entry)) continue;
+    const pid = Number(entry);
+    if (pid === process.pid) continue;
+    let name = entry;
+    try {
+      name = readlinkSync(`/proc/${entry}/exe`).split("/").pop();
+    } catch {
+      /* Name is best effort. */
+    }
+    try {
+      if (isInside(readlinkSync(`/proc/${entry}/cwd`), root, "linux")) add(found, pid, name, "working directory");
+    } catch {
+      inaccessible++;
+    }
+  }
+  return { processes: [...found.values()], inaccessible };
+}
+
+/** Parses `lsof -d cwd -F pcfn` output and keeps working directories below `root`. */
+export function parseLsof(text, root, platform = "darwin") {
+  const found = new Map();
+  let pid = 0;
+  let name = "";
+  let fd = "";
+  for (const line of text.split(/\r?\n/)) {
+    const tag = line[0];
+    const value = line.slice(1);
+    if (tag === "p") {
+      pid = Number(value);
+      name = "";
+    } else if (tag === "c") name = value;
+    else if (tag === "f") fd = value;
+    else if (tag === "n" && pid && pid !== process.pid && value.startsWith("/") && isInside(value, root, platform))
+      fd === "cwd" && add(found, pid, name || String(pid), "working directory");
+  }
+  return [...found.values()];
+}
+
+function lsofScan(root, platform) {
+  const lsof = which("lsof") ?? (["/usr/sbin/lsof", "/usr/bin/lsof"].find((p) => which(p)) || null);
+  if (!lsof) return { processes: [], unsupported: "lsof not found" };
+  const result = spawnSync(lsof, ["-n", "-P", "-w", "-d", "cwd", "-F", "pcfn"], { encoding: "utf8", maxBuffer: 512 * 1024 * 1024 });
+  if (result.error) return { processes: [], unsupported: result.error.message };
+  return { processes: parseLsof(result.stdout, root, platform) };
+}
+
+function windowsScan(root) {
+  const script = fileURLToPath(new URL("./occupancy-windows.ps1", import.meta.url));
+  const shell = which("pwsh") ?? "powershell.exe";
+  const result = spawnSync(shell, ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", script, "-Root", root], {
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0)
+    return { processes: [], unsupported: (result.stderr || result.error?.message || "scan failed").trim().split(/\r?\n/)[0] };
+  const data = JSON.parse(result.stdout);
+  const list = Array.isArray(data.processes) ? data.processes : data.processes ? [data.processes] : [];
+  return {
+    processes: list.filter((item) => item.pid !== process.pid).map((item) => ({ pid: item.pid, name: item.name, reasons: [].concat(item.reasons) })),
+    inaccessible: data.inaccessible,
+  };
+}
+
+/**
+ * Processes whose working directory is inside `root`: terminals, dev servers
+ * and agents started there. Like worktrunk's `--reap`, open files are not
+ * scanned: that is slow and editors usually keep their directory elsewhere.
+ */
+export function findOccupants(root, platform = process.platform) {
+  const target = realPath(root);
+  if (platform === "linux") return linuxScan(target);
+  if (platform === "win32") return windowsScan(target);
+  return lsofScan(target, platform);
+}
+
+export function describeOccupants(processes) {
+  return processes.map((item) => `  ${item.name} (PID ${item.pid}): ${item.reasons.join(", ")}`).join("\n");
+}
+
+/**
+ * Ends the processes and their children. Windows uses taskkill /T /F; macOS and
+ * Linux send SIGTERM, then SIGKILL to what is still running after 3 seconds.
+ */
+export async function stopProcesses(processes, platform = process.platform) {
+  if (platform === "win32") {
+    for (const { pid } of processes) spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+    return;
+  }
+  const alive = (pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  for (const { pid } of processes) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      /* Already gone. */
+    }
+  }
+  for (let waited = 0; waited < 3000 && processes.some(({ pid }) => alive(pid)); waited += 100)
+    await new Promise((done) => setTimeout(done, 100));
+  for (const { pid } of processes) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      /* Already gone. */
+    }
+  }
+}

package/src/ports.mjs

@@ -0,0 +1,45 @@
+import { createServer } from "node:net";
+import { NookError } from "./errors.mjs";
+
+export const PORT_BLOCK = 10;
+export const DEFAULT_PORT_BASE = 20000;
+const MAX_PORT = 65535;
+
+/** First ports of every workspace that already has a block. */
+export function usedPorts(config) {
+  const used = [];
+  for (const repo of Object.values(config.repos ?? {}))
+    for (const ws of Object.values(repo.workspaces ?? {}))
+      if (Number.isInteger(ws.port)) used.push(ws.port);
+  return used;
+}
+
+function overlaps(start, used) {
+  return used.some((other) => start < other + PORT_BLOCK && other < start + PORT_BLOCK);
+}
+
+export function portFree(port, host = "127.0.0.1") {
+  return new Promise((done) => {
+    const server = createServer();
+    server.once("error", () => done(false));
+    server.listen({ port, host, exclusive: true }, () => server.close(() => done(true)));
+  });
+}
+
+export async function blockFree(start, isFree = portFree) {
+  for (let port = start; port < start + PORT_BLOCK; port++) if (!(await isFree(port))) return false;
+  return true;
+}
+
+/**
+ * Gives a workspace PORT_BLOCK ports in a row. Skips blocks other workspaces
+ * own and blocks where something is already listening.
+ */
+export async function allocatePort(config, { base = config.port_base ?? DEFAULT_PORT_BASE, isFree = portFree } = {}) {
+  const used = usedPorts(config);
+  for (let start = base; start + PORT_BLOCK - 1 <= MAX_PORT; start += PORT_BLOCK) {
+    if (overlaps(start, used)) continue;
+    if (await blockFree(start, isFree)) return start;
+  }
+  throw new NookError(`No free block of ${PORT_BLOCK} ports from ${base}`);
+}

package/src/prompt.mjs

@@ -0,0 +1,100 @@
+import { createInterface } from "node:readline/promises";
+import { NookError } from "./errors.mjs";
+import { line, useColor } from "./ui.mjs";
+
+/**
+ * Asks questions on the terminal. With `yes`, every question takes its default.
+ * Without a terminal and without `yes`, asking is an error, so scripts never hang.
+ */
+export function createPrompter({ yes = false, input = process.stdin, output = process.stderr } = {}) {
+  const interactive = Boolean(input.isTTY);
+  // Questions get a mark like every other line, so their text lines up.
+  const mark = (text) => line("ask", text, useColor(output));
+
+  async function raw(question) {
+    if (!interactive)
+      throw new NookError(`Needs an answer ("${question.trim()}"); run it in a terminal`);
+    const rl = createInterface({ input, output });
+    try {
+      return (await rl.question(question)).trim();
+    } finally {
+      rl.close();
+    }
+  }
+
+  return {
+    yes,
+    interactive,
+    async ask(question, fallback = "") {
+      if (yes) return fallback;
+      const answer = await raw(mark(`${question}${fallback ? ` [${fallback}]` : ""}: `));
+      return answer || fallback;
+    },
+    /** Shows `initial` already typed so it can be edited; Enter keeps it. */
+    async edit(question, initial) {
+      if (yes || !interactive) return initial;
+      const rl = createInterface({ input, output });
+      try {
+        const pending = rl.question(mark(`${question}: `));
+        rl.write(initial);
+        return (await pending).trim() || initial;
+      } finally {
+        rl.close();
+      }
+    },
+    async confirm(question, fallback = false) {
+      if (yes) return fallback;
+      for (;;) {
+        const answer = (await raw(mark(`${question} ${fallback ? "[Y/n]" : "[y/N]"} `))).toLowerCase();
+        if (!answer) return fallback;
+        if (["y", "yes"].includes(answer)) return true;
+        if (["n", "no"].includes(answer)) return false;
+      }
+    },
+    /** choices: [{ key, label }]; returns the chosen key. */
+    async choose(question, choices, fallback) {
+      if (yes) return fallback;
+      output.write(`${mark(question)}\n`);
+      choices.forEach((choice, index) =>
+        output.write(`  ${index + 1}. ${choice.label}${choice.key === fallback ? " (default)" : ""}\n`),
+      );
+      for (;;) {
+        const answer = await raw(mark("Choose a number: "));
+        if (!answer) return fallback;
+        const picked = choices[Number(answer) - 1];
+        if (picked) return picked.key;
+      }
+    },
+  };
+}
+
+/** Splits "--a 'b c'" into ["--a", "b c"]. Supports single and double quotes. */
+export function splitArgs(text) {
+  const out = [];
+  let current = "";
+  let quote = null;
+  let started = false;
+  for (const char of text) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      started = true;
+    } else if (/\s/.test(char)) {
+      if (started) out.push(current);
+      current = "";
+      started = false;
+    } else {
+      current += char;
+      started = true;
+    }
+  }
+  if (quote) throw new NookError(`Unclosed quote in: ${text}`);
+  if (started) out.push(current);
+  return out;
+}
+
+export function joinArgs(args) {
+  return args.map((arg) => (/[\s"']/.test(arg) || arg === "" ? JSON.stringify(arg) : arg)).join(" ");
+}

package/src/shared.mjs

@@ -0,0 +1,97 @@
+import { copyFileSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { gitTry, ignoredPaths } from "./git.mjs";
+import { exists } from "./home.mjs";
+
+export const DEFAULT_INCLUDE = [".env*"];
+/** Suffixes that mark a committed template: `.env.example` is the template for `.env`. */
+export const TEMPLATE_SUFFIX = /^(.+)\.(example|sample|template|dist)$/;
+/** Ignored secret files other tools use; init offers them one by one. */
+export const KNOWN_SECRET_FILES = [".dev.vars", "config/master.key", ".envrc"];
+
+/** Patterns from .worktreeinclude (gitignore syntax), or the default `.env*`. */
+export function includePatterns(repo) {
+  const file = join(repo, ".worktreeinclude");
+  if (!exists(file)) return { patterns: DEFAULT_INCLUDE, source: "default" };
+  const patterns = readFileSync(file, "utf8")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#"));
+  return { patterns, source: ".worktreeinclude" };
+}
+
+/** Files in `repo` that match the patterns and that git ignores. Paths use "/". */
+export function sharedCandidates(repo, patterns) {
+  if (!patterns.length) return [];
+  const args = ["ls-files", "-z", "--others", "--ignored"];
+  for (const pattern of patterns) args.push(`--exclude=${pattern}`);
+  const listed = gitTry(args, { cwd: repo });
+  if (!listed.ok) return [];
+  const files = listed.out.split("\0").filter(Boolean);
+  const ignored = ignoredPaths(repo, files);
+  return files.filter((file) => ignored.has(file)).sort();
+}
+
+/**
+ * Committed templates for files git ignores, as { from, to }, in any folder:
+ * `.env.example` -> `.env`, `apps/api/.dev.vars.sample` -> `apps/api/.dev.vars`.
+ * A template whose target git does not ignore is a normal file and is left out.
+ */
+export function templateFiles(repo) {
+  const listed = gitTry(["ls-files", "-z"], { cwd: repo });
+  if (!listed.ok) return [];
+  const pairs = [];
+  for (const from of listed.out.split("\0").filter(Boolean)) {
+    const match = TEMPLATE_SUFFIX.exec(from);
+    // A library's own template in a committed vendor folder (showdoc's guzzle phpunit.xml.dist) is not the project's.
+    if (match && !match[1].endsWith("/") && !/(^|\/)(vendor|node_modules)\//.test(from)) pairs.push({ from, to: match[1] });
+  }
+  const ignored = ignoredPaths(repo, pairs.map((pair) => pair.to));
+  return pairs.filter((pair) => ignored.has(pair.to)).sort((a, b) => a.to.localeCompare(b.to));
+}
+
+export function knownSecretFiles(repo, already) {
+  const present = KNOWN_SECRET_FILES.filter((file) => exists(join(repo, file)) && !already.includes(file));
+  const ignored = ignoredPaths(repo, present);
+  return present.filter((file) => ignored.has(file));
+}
+
+/** Every file below `dir`, relative, with "/" separators. */
+export function listFiles(dir) {
+  if (!exists(dir)) return [];
+  const out = [];
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() || statSync(full).isFile()) out.push(relative(dir, full).split(sep).join("/"));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+export function copyFile(from, to) {
+  mkdirSync(dirname(to), { recursive: true });
+  copyFileSync(from, to);
+}
+
+/**
+ * Copies the shared folder into a new workspace. Only files git ignores in the
+ * workspace are copied, so a shared file never overwrites a tracked one.
+ */
+export function copyShared(sharedDir, workspace) {
+  const files = listFiles(sharedDir);
+  const ignored = ignoredPaths(workspace, files);
+  const copied = [];
+  const skipped = [];
+  for (const file of files) {
+    if (!ignored.has(file)) {
+      skipped.push(file);
+      continue;
+    }
+    copyFile(join(sharedDir, file), join(workspace, file));
+    copied.push(file);
+  }
+  return { copied, skipped };
+}

package/src/status.mjs

@@ -0,0 +1,30 @@
+import { exists } from "./home.mjs";
+import { gitTry, refExists } from "./git.mjs";
+
+/** Uncommitted changes, or null when the folder is missing or not readable. */
+export function changeCount(path) {
+  if (!exists(path)) return null;
+  const status = gitTry(["status", "--porcelain", "--untracked-files=normal"], { cwd: path });
+  if (!status.ok) return null;
+  return status.out ? status.out.split(/\r?\n/).length : 0;
+}
+
+/** Commits the branch has that `base` lacks (ahead), and the reverse (behind). */
+export function aheadBehind(repo, branch, base) {
+  if (!refExists(repo, `refs/heads/${branch}`)) return null;
+  const result = gitTry(["rev-list", "--left-right", "--count", `${base}...refs/heads/${branch}`], { cwd: repo });
+  if (!result.ok) return null;
+  const [behind, ahead] = result.out.split(/\s+/).map(Number);
+  return { ahead, behind };
+}
+
+export function branchTip(repo, branch) {
+  const result = gitTry(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: repo });
+  return result.ok ? result.out : null;
+}
+
+/** True when `commit` is `other` or one of its ancestors (false when either is unknown). */
+export function contains(repo, other, commit) {
+  if (commit === other) return true;
+  return gitTry(["merge-base", "--is-ancestor", commit, other], { cwd: repo }).ok;
+}