@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync.ts

@@ -0,0 +1,360 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_FILE, findRoot, loadConfig, type ResolvedConfig } from "./config.ts";
+import { canonicalPath } from "./scripts/workspace-root.ts";
+import { normalizeRel, prunePaths, readManifest, renderManifest } from "./sync/manifest.ts";
+import { gitFiles, ignoreBlockLines, strayIgnoreFiles, untrackedEntries, type PostPass } from "./sync/git-files.ts";
+import {
+  applyMigration,
+  conflictLines,
+  generatedFiles,
+  planAdoption,
+  planMigration,
+  planRuleUpgrade,
+} from "./sync/migrate.ts";
+import { isSelf, stockRoot } from "./sync/stock.ts";
+import { type GitRun, markHooksExecutable, standards, syncHooksPath } from "./sync/standards.ts";
+import { GENERATORS, type Generator, type Output, type SyncContext } from "./sync/outputs.ts";
+import { type FormatEntry, validateOutputs } from "./sync/validate.ts";
+import { isCurrent, writeAll } from "./sync/write.ts";
+import { readWorkspace, type Workspace } from "./sync/workspace.ts";
+
+/** Where repo sync prints; each call gets whole lines. */
+export type SyncIo = { cwd: string; stdout: (s: string) => void; stderr: (s: string) => void };
+
+/** Seams for tests: the generators to run, the config reader, the output formats to validate against, the platform links are made for, and how one output is written. */
+export type SyncDeps = {
+  generators?: readonly Generator[];
+  /** Run in order over the generators' outputs, each also seeing the outputs of those before it; `POST_PASSES` when omitted. */
+  post?: readonly PostPass[];
+  formats?: readonly FormatEntry[];
+  /** Reads the config; `loadConfig` when omitted. */
+  load?: typeof loadConfig;
+  platform?: NodeJS.Platform;
+  writeOutput?: (root: string, output: Output, platform: NodeJS.Platform) => string | null;
+  /** Runs git for the `core.hooksPath` step; `runGit` when omitted. */
+  git?: GitRun;
+};
+
+type Mode = { check: boolean; postinstall: boolean };
+type ModeResult = { ok: true; mode: Mode } | { ok: false; error: string };
+
+const PREFIX = "repo sync: ";
+
+/** The passes over the generators' outputs: standards first, so the git files pass ignores its configs. */
+export const POST_PASSES: readonly PostPass[] = [standards, gitFiles];
+
+/**
+ * Runs every generator in order, then each pass of `post` over their outputs and those of the passes before it;
+ * nothing is written, so all errors surface before any file changes. A generator that fails on the file system
+ * reports its message as an error, like any other it found.
+ */
+export function planSync(
+  ctx: SyncContext,
+  generators: readonly Generator[] = GENERATORS,
+  post: readonly PostPass[] = POST_PASSES,
+): { outputs: Output[]; errors: string[] } {
+  const outputs: Output[] = [];
+  const errors: string[] = [];
+  const planner = new Map<string, string>();
+  const collect = (label: string, run: () => { outputs: Output[]; errors: string[] }) => {
+    try {
+      const result = run();
+      for (const output of result.outputs) {
+        const first = planner.get(output.path);
+        if (first === undefined) planner.set(output.path, label);
+        else errors.push(`${output.path}: planned by ${first} and ${label}; rename one`);
+      }
+      outputs.push(...result.outputs);
+      errors.push(...result.errors);
+    } catch (error) {
+      errors.push((error as Error).message);
+    }
+  };
+  for (const generator of generators) collect(generator.name, () => generator(ctx));
+  for (const pass of post) {
+    const planned = [...outputs];
+    collect(pass.name, () => pass(ctx, planned));
+  }
+  return { outputs, errors };
+}
+
+/** Every generator's outputs for what is on disk under `root` now, as normalized paths; the errors when any generator or path is wrong. */
+export function computeOutputs(
+  root: string,
+  config: ResolvedConfig,
+  workspace: Workspace,
+  generators?: readonly Generator[],
+  post?: readonly PostPass[],
+): { ok: true; outputs: Output[] } | { ok: false; errors: string[] } {
+  const readErrors: string[] = [];
+  const plan = planSync({ root, config, workspace, read: (rel) => readText(root, rel, readErrors) }, generators, post);
+  // An unreadable file reads as missing to the generators, so its error is the cause of anything they report.
+  if (readErrors.length > 0) return { ok: false, errors: readErrors };
+  if (plan.errors.length > 0) return { ok: false, errors: plan.errors };
+  // One spelling per path: outputs and manifest entries are compared only in the normalized form.
+  const normalized: Output[] = [];
+  const badPaths: string[] = [];
+  for (const output of plan.outputs) {
+    const rel = normalizeRel(output.path, root);
+    if (rel === null) badPaths.push(`${output.path}: not a path inside the repo`);
+    else normalized.push({ ...output, path: rel });
+  }
+  return badPaths.length > 0 ? { ok: false, errors: badPaths } : { ok: true, outputs: normalized };
+}
+
+/**
+ * `repo sync [--check | --postinstall]`: validates the config and every output, writes the outputs that changed,
+ * removes what the last run wrote and no output names now, then records every output path in the manifest.
+ * `--check` writes nothing and fails on drift; `--postinstall` reports errors but exits 0.
+ */
+export async function runSync(args: string[], io: SyncIo, deps: SyncDeps = {}): Promise<number> {
+  const platform = deps.platform ?? process.platform;
+  const parsed = parseMode(args);
+  if (!parsed.ok) {
+    io.stderr(`${PREFIX}${parsed.error}\n`);
+    return 1;
+  }
+  const { check, postinstall } = parsed.mode;
+  const fail = (errors: string[]): number => {
+    for (const error of errors) io.stderr(`${PREFIX}${error}\n`);
+    return postinstall ? 0 : 1;
+  };
+
+  // A refusal before any output is written ends by saying so; `--check` writes nothing, so it has nothing to say about "written".
+  const refuse = (errors: string[]): number => fail(check ? errors : [...errors, "nothing written"]);
+
+  const root = findRoot(io.cwd);
+  if (root === null) return fail([`no ${CONFIG_FILE} in ${io.cwd} or any parent; run \`bun repo init\``]);
+
+  const load = deps.load ?? loadConfig;
+  const config = await load(root);
+  if (!config.ok) return refuse(config.errors);
+  // Here the trees are the stock source; without the agents pack sync would prune them.
+  if (isSelf(root) && !config.config.packs.includes("agents")) {
+    return refuse([`${CONFIG_FILE}: this repo ships the agent trees as its stock source; keep "agents" in packs`]);
+  }
+
+  const workspace = readWorkspace(root);
+  if (!workspace.ok) return refuse(workspace.errors);
+  let resolved = config.config;
+  // Nothing is migrated, adopted or written from outputs that would not parse or beside an ignore file sync refuses; `--check` has nothing to say about "written".
+  const invalid = (outputs: Output[]): number | null => {
+    const problems = [
+      ...strayIgnoreFiles(
+        root,
+        workspace.workspace,
+        ignoreBlockLines(workspace.workspace.manifest.name, resolved.agents.hosts, outputs),
+      ),
+      ...validateOutputs(root, outputs, deps.formats),
+    ];
+    if (problems.length === 0) return null;
+    return refuse(problems);
+  };
+  const compute = () => computeOutputs(root, resolved, workspace.workspace, deps.generators, deps.post);
+  // Old-format `.repo/` rules and subagents are rewritten, and marked where they replace a stock one, before anything reads them.
+  const upgrade = async (): Promise<void> => {
+    for (const line of await applyMigration(root, planRuleUpgrade(root, stockRoot(root)))) io.stdout(`${line}\n`);
+  };
+  if (!isSelf(root)) {
+    const pending = planRuleUpgrade(root, stockRoot(root)).length;
+    if (pending > 0 && check) {
+      io.stderr(`${PREFIX}${pending} migration step${pending === 1 ? "" : "s"} pending; run \`bun repo sync\`\n`);
+      return 1;
+    }
+    try {
+      await upgrade();
+    } catch (error) {
+      return fail([(error as Error).message]);
+    }
+  }
+  let planned = compute();
+  if (!planned.ok) return refuse(planned.errors);
+  const firstInvalid = invalid(planned.outputs);
+  if (firstInvalid !== null) return firstInvalid;
+
+  let migrated = false;
+  // A copied install moves to .repo/ and references/ before anything is planned from them; this repo never does.
+  // It has no overlay yet, so what sync plans now is the stock's own generated text, the base its copies are compared with.
+  if (!isSelf(root)) {
+    const steps = planMigration(
+      root,
+      stockRoot(root),
+      generatedFiles(planned.outputs),
+      untrackedEntries(resolved.agents.hosts, planned.outputs),
+    );
+    const conflicts = conflictLines(steps);
+    if (conflicts.length > 0) {
+      for (const line of conflicts) io.stderr(`${line}\n`);
+      return postinstall ? 0 : 1;
+    }
+    if (steps.length > 0 && check) {
+      io.stderr(
+        `${PREFIX}${steps.length} migration step${steps.length === 1 ? "" : "s"} pending; run \`bun repo sync\`\n`,
+      );
+      return 1;
+    }
+    migrated = steps.length > 0;
+    if (steps.length > 0) {
+      try {
+        for (const line of await applyMigration(root, steps)) io.stdout(`${line}\n`);
+        await upgrade();
+      } catch (error) {
+        return fail([(error as Error).message]);
+      }
+      const reloaded = await load(root);
+      if (!reloaded.ok) return fail(reloaded.errors);
+      resolved = reloaded.config;
+      planned = compute();
+      if (!planned.ok) return refuse(planned.errors);
+      const afterMigration = invalid(planned.outputs);
+      if (afterMigration !== null) return afterMigration;
+    }
+  }
+
+  // What a consumer already keeps where sync generates moves into `.repo/` before it is overwritten; a copied install did that in its migration.
+  if (!isSelf(root) && !migrated) {
+    const manifestPaths = readManifest(root).paths.flatMap((entry) => normalizeRel(entry, root) ?? []);
+    const steps = planAdoption(root, stockRoot(root), resolved, planned.outputs, manifestPaths);
+    const conflicts = conflictLines(steps);
+    if (conflicts.length > 0) {
+      for (const line of conflicts) io.stderr(`${line}\n`);
+      return postinstall ? 0 : 1;
+    }
+    if (steps.length > 0 && check) {
+      io.stderr(
+        `${PREFIX}${steps.length} adoption step${steps.length === 1 ? "" : "s"} pending; run \`bun repo sync\`\n`,
+      );
+      return 1;
+    }
+    if (steps.length > 0) {
+      try {
+        for (const line of await applyMigration(root, steps)) io.stdout(`${line}\n`);
+        await upgrade();
+      } catch (error) {
+        return fail([(error as Error).message]);
+      }
+      // The overlay changed what the generators read.
+      planned = compute();
+      if (!planned.ok) return refuse(planned.errors);
+      const afterAdoption = invalid(planned.outputs);
+      if (afterAdoption !== null) return afterAdoption;
+    }
+  }
+  const outputs = planned.outputs;
+
+  const changed = outputs.filter((output) => !isCurrentOutput(root, output, platform));
+  const prune = prunePaths(
+    readManifest(root),
+    outputs.map((output) => output.path),
+    root,
+  ).filter((rel) => isPrunable(path.join(root, rel)));
+  const manifest = renderManifest(outputs.map((output) => output.path));
+  if (check) {
+    for (const output of changed) io.stderr(`${PREFIX}${output.path} is out of date; run \`bun repo sync\`\n`);
+    for (const rel of prune) io.stderr(`${PREFIX}${rel} is stale and would be removed; run \`bun repo sync\`\n`);
+    if (changed.length === 0 && prune.length === 0) io.stdout(`${PREFIX}up to date\n`);
+    return changed.length === 0 && prune.length === 0 ? 0 : 1;
+  }
+
+  const written = writeAll(root, changed, prune, manifest, { platform, writeOutput: deps.writeOutput });
+  if (!written.ok) return fail(written.refused ? [...written.errors, "nothing written"] : written.errors);
+  const parts = [];
+  if (changed.length > 0) parts.push(`wrote ${summarize(changed.map((output) => output.path))}`);
+  if (prune.length > 0) parts.push(`removed ${summarize(prune)}`);
+  // Machine state, not repo content, so `--check` never gets here.
+  const hooks = syncHooksPath(root, resolved.packs.includes("standards"), deps.git);
+  const modes = resolved.packs.includes("standards")
+    ? markHooksExecutable(root, platform, deps.git)
+    : { done: [], warnings: [] };
+  parts.push(...hooks.done, ...modes.done);
+  for (const warning of [...hooks.warnings, ...modes.warnings]) io.stderr(`${PREFIX}${warning}\n`);
+  io.stdout(`${PREFIX}${parts.length === 0 ? "up to date" : parts.join("; ")}\n`);
+  return 0;
+}
+
+/** Path list for the summary line: outputs sharing a top dir collapse to `dir/ (n)`, single files keep their name. */
+function summarize(paths: readonly string[]): string {
+  const top = (rel: string) => (rel.includes("/") ? rel.slice(0, rel.indexOf("/")) : null);
+  const counts = new Map<string, number>();
+  for (const rel of paths) {
+    const dir = top(rel);
+    if (dir !== null) counts.set(dir, (counts.get(dir) ?? 0) + 1);
+  }
+  const seen = new Set<string>();
+  const parts: string[] = [];
+  for (const rel of paths) {
+    const dir = top(rel);
+    if (dir === null || counts.get(dir) === 1) parts.push(rel);
+    else if (!seen.has(dir)) {
+      parts.push(`${dir}/ (${counts.get(dir)})`);
+      seen.add(dir);
+    }
+  }
+  return parts.join(", ");
+}
+
+function parseMode(args: string[]): ModeResult {
+  const mode: Mode = { check: false, postinstall: false };
+  for (const arg of args) {
+    if (arg === "--check") mode.check = true;
+    else if (arg === "--postinstall") mode.postinstall = true;
+    else return { ok: false, error: `unknown flag ${arg}; use --check or --postinstall` };
+  }
+  if (mode.check && mode.postinstall) return { ok: false, error: "use --check or --postinstall, not both" };
+  return { ok: true, mode };
+}
+
+/** A root-relative file's text, or null when it is missing; any other failure is recorded in `errors`. */
+function readText(root: string, rel: string, errors: string[]): string | null {
+  try {
+    return fs.readFileSync(path.join(root, rel), "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    errors.push(`${rel}: cannot read: ${(error as Error).message}`);
+    return null;
+  }
+}
+
+/**
+ * Whether the output is on disk exactly as planned: same bytes for a file; for a link the same text, so a link
+ * that reaches its target through another generated link is rewritten before that one is pruned. A win32
+ * junction holds an absolute target, so it only has to name the same path once its parent dirs are resolved
+ * (8.3 short names, drive case); its last segment is never followed, so a junction into another link is stale.
+ */
+function isCurrentOutput(root: string, output: Output, platform: NodeJS.Platform): boolean {
+  const abs = path.join(root, output.path);
+  if (output.kind === "file") {
+    // A hook git cannot run is out of date even with the right bytes; win32 has no execute bit.
+    return isCurrent(abs, output.content) && (output.executable !== true || platform === "win32" || isExecutable(abs));
+  }
+  try {
+    if (!fs.lstatSync(abs).isSymbolicLink()) return false;
+    if (platform !== "win32") return fs.readlinkSync(abs) === output.target;
+    const here = path.dirname(abs);
+    return (
+      parentCanonical(path.resolve(here, fs.readlinkSync(abs))) === parentCanonical(path.resolve(here, output.target))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Whether the owner may run the file at `abs`, which exists. */
+function isExecutable(abs: string): boolean {
+  return (fs.statSync(abs).mode & 0o100) !== 0;
+}
+
+/** `abs` with its parent dirs in canonical spelling and its last segment as written. */
+function parentCanonical(abs: string): string {
+  return path.join(canonicalPath(path.dirname(abs)), path.basename(abs));
+}
+
+/** Whether a manifest path is on disk and removable: a file or a link; a real directory is left alone. */
+function isPrunable(abs: string): boolean {
+  try {
+    return !fs.lstatSync(abs).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/cli/tdd-scope.test.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { ownerLookup } from "./tdd-scope.ts";
+
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function tree(files: Record<string, string>): (file: string) => ReturnType<ReturnType<typeof ownerLookup>> {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "owners-"));
+  temps.push(root);
+  for (const [rel, text] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), text);
+  }
+  return ownerLookup(root);
+}
+
+it("finds the nearest package.json up to the root, and whether it is private", () => {
+  const owner = tree({
+    "package.json": "{}",
+    "packages/a/package.json": '{ "private": true }',
+    "packages/b/package.json": '{ "private": false }',
+  });
+  expect(owner("packages/a/src/x.ts")).toEqual({ dir: "packages/a", public: false });
+  expect(owner("packages/b/x.ts")).toEqual({ dir: "packages/b", public: true });
+  expect(owner("cli/x.ts")).toEqual({ dir: ".", public: true });
+});
+
+it("treats a file with no manifest, or one it cannot read or parse, as private", () => {
+  expect(tree({})("x.ts")).toEqual({ dir: ".", public: false });
+  expect(tree({ "a/package.json": "{ nope" })("a/x.ts")).toEqual({ dir: "a", public: false });
+});

package/cli/tdd-scope.ts

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { NameStatus } from "./red-proof.ts";
+import { isSource, isTestFile } from "./test-files.ts";
+
+/** The package that owns a file: its dir relative to the root (`.` for the root), and whether it is public. */
+export type Owner = { dir: string; public: boolean };
+
+/** Whether the manifest at `file` leaves the package public (`private` is not `true`); a missing or invalid one does not. */
+function isPublic(file: string): boolean {
+  try {
+    return (
+      (JSON.parse(fs.readFileSync(file, "utf8")) /* only private is read */ as { private?: unknown }).private !== true
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Looks up the owner of a repo-relative file at `root`: the package of its nearest `package.json` up to the root, or
+ * the root itself when none is found. A missing or invalid manifest makes the owner private.
+ */
+export function ownerLookup(root: string): (file: string) => Owner {
+  return (file) => {
+    let dir = path.dirname(file);
+    while (dir !== "." && !fs.existsSync(path.join(root, dir, "package.json"))) dir = path.dirname(dir);
+    return { dir, public: isPublic(path.join(root, dir, "package.json")) };
+  };
+}
+
+/**
+ * Whether red-proof applies to `change`: always with `tdd`, else when a changed source file belongs to a public
+ * package, or, with no source file changed, a changed test file does.
+ */
+export function proofApplies(change: readonly NameStatus[], tdd: boolean, owners: (file: string) => Owner): boolean {
+  if (tdd) return true;
+  const sources = change.filter((entry) => isSource(entry.path));
+  const files = sources.length > 0 ? sources : change.filter((entry) => isTestFile(entry.path));
+  return files.some((entry) => owners(entry.path).public);
+}

package/cli/test-files.ts

@@ -0,0 +1,16 @@
+const CODE = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+
+/** True when the path is a test: a `*.test.*` or `*.spec.*` file, or a file under an `e2e/` folder. */
+export function isTestFile(file: string): boolean {
+  return /\.(test|spec)\.[^/]+$/.test(file) || /(^|\/)e2e\//.test(file);
+}
+
+/** True when the path is a code file (`.ts .tsx .mts .cts .js .jsx .mjs .cjs`). */
+export const isCodeFile = (file: string): boolean => CODE.test(file);
+
+/** A code file a change counts as source: not a test, a fixture, a snapshot, a mock or a config. */
+export const isSource = (file: string): boolean =>
+  CODE.test(file) &&
+  !isTestFile(file) &&
+  !/(^|\/)(fixtures|__snapshots__|__mocks__)\//.test(file) &&
+  !/\.config\.[^/]+$/.test(file);

package/cli/ts-program.ts

@@ -0,0 +1,69 @@
+/**
+ * The compiler options a script checks a file with: those of the `tsconfig.json` nearest above it (its owner), or of a
+ * config beside that one, such as the strict `tsconfig.src.json`. Shared by the magic and rejection checks.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import type { Result } from "./scripts/lint-baseline.ts";
+import { RUNTIME_CONFIG } from "./tsconfig.constants.ts";
+
+/** A program's options, and the files its tsconfig includes, as program paths. */
+export type Setup = { options: ts.CompilerOptions; fileNames: readonly string[] };
+
+const TOP = ".";
+const SOURCE = /\.(?:tsx?|mts|cts)$/;
+const DECLARATION = /\.d\.[cm]?ts$/;
+const TEST = /\.(?:test|spec|e2e)\./;
+/** Code that must not compile, which `check-rejections.ts` checks instead. */
+const REJECT = /\.reject\.tsx?$/;
+const SKIPPED_DIRS = ["fixtures", "e2e", "vendor", "node_modules"];
+/** The options a file with no tsconfig.json above it is checked with: strict, resolved as a bundler would. */
+const DEFAULTS: ts.CompilerOptions = {
+  strict: true,
+  target: ts.ScriptTarget.ESNext,
+  module: ts.ModuleKind.Preserve,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  allowImportingTsExtensions: true,
+  noEmit: true,
+  skipLibCheck: true,
+};
+
+/** Whether a root-relative file is TypeScript outside a fixture, e2e or vendored dir, and not a declaration or reject file. */
+function isScripted(rel: string): boolean {
+  const dirs = path.posix.dirname(rel).split("/");
+  const skipped = DECLARATION.test(rel) || REJECT.test(rel) || dirs.some((dir) => SKIPPED_DIRS.includes(dir));
+  return SOURCE.test(rel) && !skipped;
+}
+
+/** A root-relative source file the script checks read: TypeScript, not a declaration, test, fixture, e2e or vendored file. */
+export const isChecked = (rel: string): boolean => isScripted(rel) && !TEST.test(path.posix.basename(rel));
+
+/** A root-relative test file whose asserts the script checks read: a TypeScript test outside a fixture or e2e dir. */
+export const isTest = (rel: string): boolean => isScripted(rel) && TEST.test(path.posix.basename(rel));
+
+/** `file` with forward slashes, the spelling typescript keys its source files by. */
+export const posix = (file: string): string => file.split(path.sep).join("/");
+
+/** The root-relative dir of the tsconfig.json nearest above `rel`, up to the root; null when there is none. */
+export function ownerOf(root: string, rel: string): string | null {
+  let dir = path.posix.dirname(rel);
+  for (;;) {
+    if (fs.existsSync(path.join(root, dir, RUNTIME_CONFIG))) return dir;
+    if (dir === TOP) return null;
+    dir = path.posix.dirname(dir);
+  }
+}
+
+/** The setup of `config` in the owner `dir` (root-relative), the defaults for no owner, or why it cannot be read. */
+export function setupOf(root: string, dir: string | null, config: string): Result<Setup> {
+  if (dir === null) return { ok: true, value: { options: DEFAULTS, fileNames: [] } };
+  const file = posix(path.join(root, dir, config));
+  const read = ts.readConfigFile(file, ts.sys.readFile);
+  if (read.error !== undefined) {
+    const message = ts.flattenDiagnosticMessageText(read.error.messageText, " ");
+    return { ok: false, errors: [`${path.posix.join(dir, config)}: ${message}`] };
+  }
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(file), undefined, file);
+  return { ok: true, value: { options: { ...parsed.options, noEmit: true }, fileNames: parsed.fileNames } };
+}

package/cli/tsconfig.constants.ts

@@ -0,0 +1,8 @@
+/** The file names `repo check` and `repo turn` look for beside each other in a package. */
+
+/** The config each package checks its code and tests with. */
+export const RUNTIME_CONFIG = "tsconfig.json";
+/** The strict config beside each `tsconfig.json`, over the folder's non-test sources. */
+export const SRC_CONFIG = "tsconfig.src.json";
+/** The ts-reset file every base lists under `files`. */
+export const RESET = "reset.d.ts";

package/cli/workerstack-config.types.ts

@@ -0,0 +1,21 @@
+import type { Host, LintSkip, Pack, SkillPack } from "./config.ts";
+import type { KnipIgnoreEntry } from "./knip-schema.ts";
+
+/** What workerstack.config.ts default-exports, as `defineConfig` takes it; config.ts checks its schema against it. */
+export type WorkerstackConfig = {
+  packs?: readonly Pack[] | undefined;
+  agents?: { hosts?: readonly Host[] | undefined; skills?: readonly SkillPack[] | undefined } | undefined;
+  commit?: { maxChangedLines?: number | undefined } | undefined;
+  coverage?:
+    | {
+        floors?: string | undefined;
+        knownFailures?: string | undefined;
+        mutate?: readonly string[] | undefined;
+        mutationFloors?: string | undefined;
+      }
+    | undefined;
+  nightly?: { shards?: number | undefined; secrets?: readonly string[] | undefined } | undefined;
+  tdd?: boolean | undefined;
+  lint?: { skip?: readonly LintSkip[] | undefined } | undefined;
+  knip?: { ignore?: readonly KnipIgnoreEntry[] | undefined } | undefined;
+};

package/dist/cli/env.d.ts

@@ -0,0 +1,10 @@
+/** Every variable this repo's code reads, sorted; add a name here to read it. */
+declare const ENV_VARIABLES: readonly ["CI", "CLAUDE_EFFORT", "CLAUDE_PROJECT_DIR", "CLAUDE_SESSION_ID", "ELEVENLABS_API_KEY", "ELEVENLABS_MODEL_ID", "ELEVENLABS_VOICE_ID", "GITHUB_ACTIONS", "GIT_CONFIG_GLOBAL", "GIT_DIR", "GROK_HOOK_EVENT", "GROK_SESSION_ID", "GROK_WORKSPACE_ROOT", "HOME", "LISTEN_DEVICE", "LISTEN_FFMPEG_FORMAT", "LISTEN_MODEL", "LISTEN_SECONDS", "LISTEN_STT", "LISTEN_WHISPER_MODEL", "NODE_PATH", "OPENAI_API_KEY", "OPENAI_TTS_MODEL", "OPENAI_TTS_VOICE", "PATH", "PATHEXT", "REPO_BOARD_HOME", "REPO_BOARD_PROVIDER", "REPO_BOARD_SESSION", "REPO_BROWSER", "REPO_E2E_KEEP", "REPO_E2E_ROOT", "REPO_E2E_TARBALL", "SPEAK_PROVIDER", "TURN_RECORD", "TYPESAFE_API_KEY", "USERPROFILE", "WHISPER_MODEL", "WORKSPACE_ACCOUNT"];
+export type Env = {
+    [Name in (typeof ENV_VARIABLES)[number]]?: string | undefined;
+};
+/** The environment parsed against the schema; throws a line per bad variable. */
+export declare function readEnv(source?: Record<string, unknown>): Env;
+/** A copy of the environment with `overrides` applied and every undefined value dropped, for spawn. */
+export declare function childEnv(overrides?: Record<string, string | undefined>): Record<string, string>;
+export {};

package/dist/cli/env.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/** Every variable this repo's code reads, sorted; add a name here to read it. */
+const ENV_VARIABLES = [
+    "CI",
+    "CLAUDE_EFFORT",
+    "CLAUDE_PROJECT_DIR",
+    "CLAUDE_SESSION_ID",
+    "ELEVENLABS_API_KEY",
+    "ELEVENLABS_MODEL_ID",
+    "ELEVENLABS_VOICE_ID",
+    "GITHUB_ACTIONS",
+    "GIT_CONFIG_GLOBAL",
+    "GIT_DIR",
+    "GROK_HOOK_EVENT",
+    "GROK_SESSION_ID",
+    "GROK_WORKSPACE_ROOT",
+    "HOME",
+    "LISTEN_DEVICE",
+    "LISTEN_FFMPEG_FORMAT",
+    "LISTEN_MODEL",
+    "LISTEN_SECONDS",
+    "LISTEN_STT",
+    "LISTEN_WHISPER_MODEL",
+    "NODE_PATH",
+    "OPENAI_API_KEY",
+    "OPENAI_TTS_MODEL",
+    "OPENAI_TTS_VOICE",
+    "PATH",
+    "PATHEXT",
+    "REPO_BOARD_HOME",
+    "REPO_BOARD_PROVIDER",
+    "REPO_BOARD_SESSION",
+    "REPO_BROWSER",
+    "REPO_E2E_KEEP",
+    "REPO_E2E_ROOT",
+    "REPO_E2E_TARBALL",
+    "SPEAK_PROVIDER",
+    "TURN_RECORD",
+    "TYPESAFE_API_KEY",
+    "USERPROFILE",
+    "WHISPER_MODEL",
+    "WORKSPACE_ACCOUNT",
+];
+/** Each variable is an optional string, unless a command cannot run without it. */
+function envSchema() {
+    const text = z.string().optional();
+    return z.object(Object.fromEntries(ENV_VARIABLES.map((name) => [name, text])));
+}
+/** `repo: environment: <NAME>: <issue>`, one line per bad variable. */
+function describe(error) {
+    return error.issues.map((issue) => `repo: environment: ${issue.path.join(".")}: ${issue.message}`).join("\n");
+}
+/** The environment parsed against the schema; throws a line per bad variable. */
+export function readEnv(source = process.env) {
+    const parsed = envSchema().safeParse(source);
+    if (!parsed.success)
+        throw new Error(describe(parsed.error));
+    return parsed.data;
+}
+/** A copy of the environment with `overrides` applied and every undefined value dropped, for spawn. */
+export function childEnv(overrides = {}) {
+    const merged = { ...process.env, ...overrides };
+    return Object.fromEntries(Object.entries(merged).filter((entry) => entry[1] !== undefined));
+}

package/dist/presets/temp-root-env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Where a run's tests get their temp dir: `<real tmpdir>/repo-test-<pid>` of the vitest main process. The config
+ * may be evaluated more than once per project, so the path comes from the pid, not from chance.
+ */
+export declare function rootPath(pid?: number): string;
+/**
+ * The environment that makes the root the temp dir of test processes only (workers and what they spawn); the main
+ * process, and the tools it runs in-process such as miniflare, keep the real one.
+ */
+export declare function rootEnv(root?: string): Record<string, string>;

package/dist/presets/temp-root-env.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ROOT_PREFIX } from "./temp-root.constants.js";
+/**
+ * Where a run's tests get their temp dir: `<real tmpdir>/repo-test-<pid>` of the vitest main process. The config
+ * may be evaluated more than once per project, so the path comes from the pid, not from chance.
+ */
+export function rootPath(pid = process.pid) {
+    return path.join(fs.realpathSync(os.tmpdir()), `${ROOT_PREFIX}${pid}`);
+}
+/**
+ * The environment that makes the root the temp dir of test processes only (workers and what they spawn); the main
+ * process, and the tools it runs in-process such as miniflare, keep the real one.
+ */
+export function rootEnv(root = rootPath()) {
+    // Node's compile cache defaults to <tmpdir>/node-compile-cache; a worker would put it in the root.
+    const cache = process.env.NODE_COMPILE_CACHE ?? path.join(path.dirname(root), "node-compile-cache");
+    return { TMPDIR: root, TEMP: root, TMP: root, NODE_COMPILE_CACHE: cache };
+}