looply-cli 0.5.2 → 0.5.4

package/dist/gate-draft.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Which checks `looply init` drafts as gates, and why — the part of the profile
+ * that decides whether a round can ever be kept.
+ *
+ * 🔴 THE FAILURE THIS EXISTS FOR (real user, 2026-10-15). A NestJS API at the
+ * root with two Vite+React apps in `web/` and `admin/`, each with its own
+ * package.json, node_modules, `tsc` and `vitest run`. The old draft looked at
+ * the root only, so the gates were the root typecheck and the ROOT jest suite —
+ * a 30-minute, single-threaded, database-backed suite (`--runInBand`, a 6 GB
+ * heap, a `globalSetup` that brings Postgres up). It could never pass inside a
+ * round, every round was discarded, and the safety brake stopped the pursuit.
+ * Meanwhile the change asked for was UI in `web/` and `admin/`, which no gate
+ * checked at all.
+ *
+ * So three rules, all of them visible in the file this writes:
+ *
+ *   - **Every app gets checked.** Sub-apps one level down (and `packages/*`,
+ *     `apps/*`, declared workspaces) are profiled like the root.
+ *   - **A gate must fit inside a round.** A suite that is evidently slow or
+ *     service-backed is drafted COMMENTED OUT with the reason, never as a gate
+ *     that discards every round.
+ *   - **Say why.** Each drafted line carries what it checks and why it was
+ *     chosen or left out.
+ *
+ * Pure: the filesystem is injected. `listDirs` is optional — without it only
+ * the named common folders are probed.
+ */
+export interface DraftFs {
+    /** The file's text, or null when it does not exist or cannot be read. */
+    readFile(path: string): string | null;
+    /** Child directory names of `path` ('' or '.' for the root); [] when unreadable. */
+    listDirs?(path: string): string[];
+}
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+export interface DetectedStep {
+    name: string;
+    run: string;
+    timeoutS: number;
+}
+export interface DraftGate extends DetectedStep {
+    /** Glob — the step runs only when a changed path matches it. */
+    when?: string;
+    required: boolean;
+    /** One line: what it checks and why it was chosen. Written above the gate. */
+    why: string;
+    /** Set when the gate is drafted commented out: the reason it was left out. */
+    disabled?: string;
+}
+/** Per-step budgets. A gate must finish well inside one round. */
+export declare const TYPECHECK_TIMEOUT_S = 300;
+export declare const UNIT_TEST_TIMEOUT_S = 600;
+/**
+ * Source text with its comments removed — strings (", ' and `) kept intact.
+ *
+ * ⚠️ CONFIG PROBES MUST NOT READ COMMENTS. The real web/ app that motivated
+ * this file explains, in a vite.config comment, that the API's suite "boots a
+ * real PostgreSQL in globalSetup" — and the first version of the probe read
+ * that as the web suite having one, and left a fast suite out.
+ */
+export declare function stripComments(text: string): string;
+/** JSON with comments and trailing commas — what tsconfig files actually are. */
+export declare function parseJsonc(text: string): unknown;
+/** Script names projects actually use for this, in the order they are preferred. */
+export declare const TYPECHECK_SCRIPTS: readonly ["typecheck", "type-check", "types", "tsc", "check-types"];
+/** Directories one level down that hold an app or package with something to check. */
+export declare function findSubPackages(fs: DraftFs, workspaces: readonly string[]): string[];
+export interface GateDraft {
+    /** The root's own typecheck, when it has one. */
+    typecheck: DetectedStep | null;
+    /** The root's own suite, when it fits a round (null when left out). */
+    testRunner: DetectedStep | null;
+    subPackages: string[];
+    /** Every drafted gate in execution order, the left-out ones included. */
+    gates: DraftGate[];
+}
+export declare function draftGates(fs: DraftFs, opts: {
+    packageManager: PackageManager;
+    workspaces: readonly string[];
+}): GateDraft;
+export declare function gateLine(g: DraftGate): string;
+/**
+ * What a gate is and what `required` means — said where the person edits them.
+ *
+ * ⚠️ `required: false` DOES NOT MAKE A GATE ADVISORY. Every step that runs must
+ * pass, and the first red one discards the round (`gate.ts`, `mayCommit`).
+ * `required` only adds that the step must have RUN: a required step a `when:`
+ * filter skipped blocks the commit too. A person who believed otherwise left a
+ * 30-minute suite in place as "not required" and lost every round to it.
+ */
+export declare const GATES_HEADER: string;
+/**
+ * The gate list as it appears in the file: one comment line per gate saying
+ * what it checks and why, left-out suites commented out with their reason.
+ *
+ * `header` is the comment block written directly above `gates:`, so the whole
+ * section can be re-drafted in place by `init --refresh-gates`.
+ */
+export declare function renderGatesSection(gates: readonly DraftGate[], header: string): string;
+//# sourceMappingURL=gate-draft.d.ts.map

package/dist/gate-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-draft.d.ts","sourceRoot":"","sources":["../src/gate-draft.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,OAAO;IACtB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACtC,oFAAoF;IACpF,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAiCvC;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA0BlD;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAkFD,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,qEAAsE,CAAC;AA6OrG,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CA0BpF;AAID,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,uEAAuE;IACvE,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,yEAAyE;IACzE,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,wBAAgB,UAAU,CACxB,EAAE,EAAE,OAAO,EACX,IAAI,EAAE;IAAE,cAAc,EAAE,cAAc,CAAC;IAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACtE,SAAS,CAoEX;AAOD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAI7C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,QAYb,CAAC;AAEb;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBtF"}

package/dist/gate-draft.js

@@ -0,0 +1,544 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATES_HEADER = exports.TYPECHECK_SCRIPTS = exports.UNIT_TEST_TIMEOUT_S = exports.TYPECHECK_TIMEOUT_S = void 0;
+exports.stripComments = stripComments;
+exports.parseJsonc = parseJsonc;
+exports.findSubPackages = findSubPackages;
+exports.draftGates = draftGates;
+exports.gateLine = gateLine;
+exports.renderGatesSection = renderGatesSection;
+const glob_1 = require("./glob");
+/** Per-step budgets. A gate must finish well inside one round. */
+exports.TYPECHECK_TIMEOUT_S = 300;
+exports.UNIT_TEST_TIMEOUT_S = 600;
+/** What a slow suite would have needed; only ever written commented out. */
+const SLOW_SUITE_TIMEOUT_S = 900;
+/** Folders that hold an app of their own in real repositories. */
+const COMMON_APP_DIRS = ['web', 'admin', 'app', 'client', 'frontend', 'server', 'api'];
+/** Folders whose children are packages, whether or not workspaces declare them. */
+const PACKAGE_PARENTS = ['packages', 'apps'];
+/** Never an app: build output, dependencies, tooling state. */
+const IGNORED_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    'coverage',
+    'tmp',
+    'temp',
+    'vendor',
+    'target',
+    'bin',
+    'obj',
+    'public',
+    'static',
+    'assets',
+    'docs',
+    'scripts',
+]);
+/** More than this and the gate list stops being something a person reads. */
+const MAX_SUB_PACKAGES = 12;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Source text with its comments removed — strings (", ' and `) kept intact.
+ *
+ * ⚠️ CONFIG PROBES MUST NOT READ COMMENTS. The real web/ app that motivated
+ * this file explains, in a vite.config comment, that the API's suite "boots a
+ * real PostgreSQL in globalSetup" — and the first version of the probe read
+ * that as the web suite having one, and left a fast suite out.
+ */
+function stripComments(text) {
+    let out = '';
+    let quote = null;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (quote) {
+            out += c;
+            if (c === '\\') {
+                out += text[i + 1] ?? '';
+                i++;
+            }
+            else if (c === quote)
+                quote = null;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === '`') {
+            quote = c;
+            out += c;
+        }
+        else if (c === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i++;
+            out += '\n';
+        }
+        else if (c === '/' && text[i + 1] === '*') {
+            i += 2;
+            while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
+                i++;
+            i++;
+        }
+        else
+            out += c;
+    }
+    return out;
+}
+/** JSON with comments and trailing commas — what tsconfig files actually are. */
+function parseJsonc(text) {
+    return JSON.parse(stripComments(text).replace(/,(\s*[}\]])/g, '$1'));
+}
+function readJson(fs, path) {
+    const text = fs.readFile(path);
+    if (text === null)
+        return null;
+    try {
+        const v = parseJsonc(text);
+        return isObj(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+const join = (dir, file) => (dir ? `${dir}/${file}` : file);
+function loadPkg(fs, dir) {
+    const json = readJson(fs, join(dir, 'package.json'));
+    const scripts = json && isObj(json['scripts']) ? json['scripts'] : {};
+    const dependencies = json?.['dependencies'];
+    const devDependencies = json?.['devDependencies'];
+    const deps = {
+        ...(isObj(dependencies) ? dependencies : {}),
+        ...(isObj(devDependencies) ? devDependencies : {}),
+    };
+    return { dir, json, scripts, deps };
+}
+const script = (pkg, name) => {
+    const s = pkg.scripts[name];
+    return typeof s === 'string' && s.trim() ? s.trim() : null;
+};
+/** `cd web && …` — gates run from the repository root, and the config has no cwd field. */
+const inDir = (dir, cmd) => (dir ? `cd ${dir} && ${cmd}` : cmd);
+/** How a local tool's entry point is reached from the package dir, or null when node_modules lacks it. */
+const BIN_ENTRIES = {
+    tsc: 'typescript/bin/tsc',
+    vitest: 'vitest/vitest.mjs',
+    jest: 'jest/bin/jest.js',
+};
+function localBin(fs, dir, tool) {
+    const entry = `node_modules/${BIN_ENTRIES[tool]}`;
+    if (fs.readFile(join(dir, entry)) !== null)
+        return entry;
+    // Hoisted to the root by a workspace install.
+    if (dir && fs.readFile(entry) !== null) {
+        const up = dir.split('/').map(() => '..').join('/');
+        return `${up}/${entry}`;
+    }
+    return null;
+}
+/**
+ * `node <entry> <args>` when the drafting can see the tool's own entry point —
+ * it does not depend on npx resolution, which is fragile inside the Windows
+ * sandbox — and `npx --no-install <tool> <args>` when it cannot.
+ */
+function toolCommand(fs, dir, tool, args) {
+    const bin = localBin(fs, dir, tool);
+    const tail = args ? ` ${args}` : '';
+    return bin ? { cmd: `node ${bin}${tail}`, local: true } : { cmd: `npx --no-install ${tool}${tail}`, local: false };
+}
+/** A script that is exactly one call of `tool`, with no shell around it: its args, else null. */
+function plainToolArgs(text, tool) {
+    if (/[&|;<>`$]/.test(text))
+        return null;
+    const m = new RegExp(`^${tool}(?:\\s+(.*))?$`).exec(text);
+    return m ? (m[1] ?? '').trim() : null;
+}
+/* ─────────────────────────────── typecheck ─────────────────────────────── */
+/** Script names projects actually use for this, in the order they are preferred. */
+exports.TYPECHECK_SCRIPTS = ['typecheck', 'type-check', 'types', 'tsc', 'check-types'];
+function tsconfigShape(fs, dir) {
+    const text = fs.readFile(join(dir, 'tsconfig.json'));
+    if (text === null)
+        return { exists: false, references: false, solution: false };
+    try {
+        const parsed = parseJsonc(text);
+        const refs = isObj(parsed) && Array.isArray(parsed['references']) && parsed['references'].length > 0;
+        const files = isObj(parsed) ? parsed['files'] : undefined;
+        const emptyFiles = Array.isArray(files) && files.length === 0;
+        return { exists: true, references: refs, solution: refs && emptyFiles };
+    }
+    catch {
+        // Unparseable even as JSONC: probe for the words rather than give up.
+        const refs = text.includes('"references"');
+        return { exists: true, references: refs, solution: refs && /"files"\s*:\s*\[\s*\]/.test(text) };
+    }
+}
+/** Whether a tsc argument string names a project or build mode. */
+const namesProject = (args) => /(^|\s)(-p|--project|-b|--build)(\s|=|$)/.test(args);
+/** The typecheck the tsconfig layout implies, for a package with no usable script. */
+function tsconfigTypecheck(fs, pkg, shape) {
+    if (shape.solution) {
+        // A Vite-style solution file: `tsc --noEmit` against it reads no source and
+        // exits 0. Check the app project, or build the references.
+        if (fs.readFile(join(pkg.dir, 'tsconfig.app.json')) !== null) {
+            return {
+                args: '-p tsconfig.app.json --noEmit',
+                why: 'tsconfig.json is a solution file (files: []), so the app project tsconfig.app.json is the one checked',
+            };
+        }
+        return { args: '-b', why: 'tsconfig.json is a solution file (files: []), so its references are built' };
+    }
+    const build = script(pkg, 'build');
+    const buildArgs = build ? /(?:^|&&\s*)tsc\s+([^&|;]*)/.exec(build)?.[1]?.trim() : undefined;
+    if (buildArgs !== undefined && /(^|\s)(-b|--build)(\s|$)/.test(buildArgs)) {
+        return { args: '-b', why: 'the package builds with `tsc -b`, so the gate does the same' };
+    }
+    if (buildArgs !== undefined && /(^|\s)(-p|--project)\s+\S+/.test(buildArgs)) {
+        const project = /(?:-p|--project)\s+(\S+)/.exec(buildArgs)[1];
+        return { args: `-p ${project} --noEmit`, why: `the package builds with \`tsc -p ${project}\`, so that project is checked` };
+    }
+    if (shape.references)
+        return { args: '-b', why: 'tsconfig.json has project references, so they are built' };
+    return { args: '--noEmit', why: 'type errors in tsconfig.json' };
+}
+function draftTypecheck(fs, pkg) {
+    const where = pkg.dir ? `${pkg.dir}/` : 'the root';
+    const shape = tsconfigShape(fs, pkg.dir);
+    for (const name of exports.TYPECHECK_SCRIPTS) {
+        const text = script(pkg, name);
+        if (!text)
+            continue;
+        const args = plainToolArgs(text, 'tsc');
+        if (args === null) {
+            // vue-tsc, svelte-check, a composite script: the repo's own script is the
+            // source of truth and npm is how it is reached.
+            return {
+                step: { name: 'typecheck', run: inDir(pkg.dir, `npm run ${name} --silent`), timeoutS: exports.TYPECHECK_TIMEOUT_S },
+                why: `TypeScript in ${where}, through the package's own "${name}" script`,
+            };
+        }
+        if (shape.solution && !namesProject(args)) {
+            // The trap the real user hit in admin/: `tsc --noEmit` against a solution
+            // file checks nothing and always passes. Do not trust it.
+            const t = tsconfigTypecheck(fs, pkg, shape);
+            const { cmd } = toolCommand(fs, pkg.dir, 'tsc', t.args);
+            return {
+                step: { name: 'typecheck', run: inDir(pkg.dir, cmd), timeoutS: exports.TYPECHECK_TIMEOUT_S },
+                why: `TypeScript in ${where}; its "${name}" script (\`${text}\`) checks nothing — ${t.why}`,
+            };
+        }
+        const { cmd, local } = toolCommand(fs, pkg.dir, 'tsc', args);
+        return {
+            step: {
+                name: 'typecheck',
+                run: inDir(pkg.dir, local ? cmd : `npm run ${name} --silent`),
+                timeoutS: exports.TYPECHECK_TIMEOUT_S,
+            },
+            why: `TypeScript in ${where}: the package's own "${name}" script (\`${text}\`)${local ? ', run with its local tsc' : ''}`,
+        };
+    }
+    if (!shape.exists)
+        return null;
+    const t = tsconfigTypecheck(fs, pkg, shape);
+    const { cmd } = toolCommand(fs, pkg.dir, 'tsc', t.args);
+    return {
+        step: { name: 'tsc', run: inDir(pkg.dir, cmd), timeoutS: exports.TYPECHECK_TIMEOUT_S },
+        why: `TypeScript in ${where}: ${t.why}`,
+    };
+}
+/* ─────────────────────────────── tests ─────────────────────────────── */
+const JEST_CONFIGS = ['jest.config.js', 'jest.config.ts', 'jest.config.cjs', 'jest.config.mjs', 'jest.config.json'];
+const VITEST_CONFIGS = [
+    'vitest.config.ts',
+    'vitest.config.js',
+    'vitest.config.mts',
+    'vitest.config.mjs',
+    'vite.config.ts',
+    'vite.config.js',
+    'vite.config.mts',
+    'vite.config.mjs',
+];
+/** Script names for a fast slice, tried when `test` itself is too slow for a round. */
+const FAST_TEST_SCRIPTS = ['test:unit', 'unit', 'test:fast'];
+/**
+ * Why a suite cannot be a per-round gate, or [] when nothing says so.
+ *
+ * Only what the repository states: the script's flags and name, the runner's
+ * config, and its dependencies. Each reason is one the person can check.
+ */
+function slowSuiteReasons(fs, pkg, scriptText, runner) {
+    const reasons = [];
+    if (scriptText) {
+        if (/--runInBand\b|(^|\s)-i(\s|$)/.test(scriptText))
+            reasons.push('runs in band (one test file at a time)');
+        const heap = /--max-old-space-size=(\d+)/.exec(scriptText);
+        if (heap && Number(heap[1]) >= 4096)
+            reasons.push(`needs a ${heap[1]} MB heap`);
+        const kind = /\b(e2e|integration|realdb|playwright|cypress)\b/i.exec(scriptText);
+        if (kind)
+            reasons.push(`runs ${kind[1].toLowerCase()} tests`);
+    }
+    const configTexts = [];
+    if (runner === 'jest' || runner === null) {
+        if (isObj(pkg.json?.['jest']))
+            configTexts.push(JSON.stringify(pkg.json['jest']));
+        for (const f of JEST_CONFIGS) {
+            const t = fs.readFile(join(pkg.dir, f));
+            if (t !== null)
+                configTexts.push(stripComments(t));
+        }
+    }
+    if (runner === 'vitest' || runner === null) {
+        for (const f of VITEST_CONFIGS) {
+            const t = fs.readFile(join(pkg.dir, f));
+            if (t !== null)
+                configTexts.push(stripComments(t));
+        }
+    }
+    const config = configTexts.join('\n');
+    if (/\bglobalSetup\b/.test(config))
+        reasons.push('its config has a globalSetup that starts something before the suite');
+    if (/\bmaxWorkers['"]?\s*:\s*['"]?1\b/.test(config))
+        reasons.push('its config limits it to one worker');
+    if (/testcontainers|docker/i.test(config) || Object.keys(pkg.deps).some((d) => /testcontainers/.test(d))) {
+        reasons.push('it starts containers');
+    }
+    return [...new Set(reasons)];
+}
+function runnerOf(pkg, text) {
+    if (text && /\bvitest\b/.test(text))
+        return 'vitest';
+    if (text && /\bjest\b/.test(text))
+        return 'jest';
+    if ('jest' in pkg.deps)
+        return 'jest';
+    if ('vitest' in pkg.deps)
+        return 'vitest';
+    return null;
+}
+function draftTests(fs, pkg, pm) {
+    const where = pkg.dir ? `${pkg.dir}/` : 'the root';
+    let scriptName = 'test';
+    let text = script(pkg, 'test');
+    // `npm init` seeds a test script that always exits 1. A gate built on it
+    // would fail every round of every run — that is the absence of a runner.
+    if (text && text.includes('no test specified'))
+        text = null;
+    let runner = runnerOf(pkg, text);
+    if (!text && !runner)
+        return null;
+    let slow = slowSuiteReasons(fs, pkg, text, runner);
+    let fastNote = '';
+    if (slow.length) {
+        // The repository may already name a fast slice. Prefer it to nothing.
+        for (const name of FAST_TEST_SCRIPTS) {
+            const alt = script(pkg, name);
+            if (!alt)
+                continue;
+            const altRunner = runnerOf(pkg, alt);
+            if (slowSuiteReasons(fs, pkg, alt, altRunner).length)
+                continue;
+            fastNote = `; "test" is too slow for a round (${slow.join(', ')}), so the "${name}" slice is used`;
+            scriptName = name;
+            text = alt;
+            runner = altRunner;
+            slow = [];
+            break;
+        }
+    }
+    const name = runner ?? 'test';
+    const timeoutS = slow.length ? SLOW_SUITE_TIMEOUT_S : exports.UNIT_TEST_TIMEOUT_S;
+    let run;
+    let how;
+    const plain = text && runner ? plainToolArgs(text, runner) : null;
+    if (runner && (plain !== null || !text)) {
+        // The script is exactly one runner call (or there is no script): run the
+        // runner directly, in its non-watch, CI form.
+        let args = plain ?? '';
+        if (runner === 'vitest' && !/(^|\s)(run|--run)(\s|$)/.test(args))
+            args = `run${args ? ` ${args}` : ''}`;
+        if (runner === 'jest' && !/(^|\s)--ci(\s|$)/.test(args))
+            args = `${args ? `${args} ` : ''}--ci`;
+        // A forked worker needs an IPC pipe, which the Windows gate sandbox cannot
+        // give it (win/contained-node.cjs fails that fast); worker threads and an
+        // in-band run need none, and behave the same on every platform.
+        if (runner === 'vitest' && !/(^|\s)--pool(=|\s)/.test(args))
+            args = `${args} --pool=threads`;
+        if (runner === 'jest' && !/(^|\s)(-i|--runInBand|-w|--maxWorkers)(=|\s|$)/.test(args))
+            args = `${args} --runInBand`;
+        const t = toolCommand(fs, pkg.dir, runner, args.trim());
+        run = inDir(pkg.dir, t.cmd);
+        how = text ? `its "${scriptName}" script (\`${text}\`)${t.local ? `, run with its local ${runner}` : ''}` : `${runner}, from its dependencies`;
+    }
+    else {
+        run = inDir(pkg.dir, scriptName === 'test' ? `${pm} test` : `${pm} run ${scriptName}`);
+        how = `its "${scriptName}" script (\`${text}\`)`;
+    }
+    const step = { name, run, timeoutS };
+    if (slow.length) {
+        return {
+            step,
+            why: `unit tests in ${where}: ${how}`,
+            disabled: `left out — ${slow.join(', ')}; a suite like that cannot finish inside a round, so every round would be discarded. Run it yourself before you release.`,
+        };
+    }
+    return { step, why: `${runner ? `${runner} tests` : 'tests'} in ${where}: ${how}${fastNote}` };
+}
+/* ─────────────────────────────── sub-packages ─────────────────────────────── */
+function usableDir(name) {
+    return !!name && !name.startsWith('.') && !IGNORED_DIRS.has(name);
+}
+/** Directories one level down that hold an app or package with something to check. */
+function findSubPackages(fs, workspaces) {
+    const list = (p) => (fs.listDirs ? fs.listDirs(p).filter(usableDir) : []);
+    const candidates = new Set();
+    for (const d of list(''))
+        candidates.add(d);
+    for (const d of COMMON_APP_DIRS)
+        candidates.add(d);
+    const parents = new Set(PACKAGE_PARENTS);
+    for (const ws of workspaces) {
+        const clean = ws.replace(/^\.\//, '').replace(/\/+$/, '');
+        if (clean.endsWith('/*') && !clean.slice(0, -2).includes('*'))
+            parents.add(clean.slice(0, -2));
+        else if (!clean.includes('*') && clean)
+            candidates.add(clean);
+    }
+    for (const parent of parents) {
+        candidates.delete(parent);
+        for (const child of list(parent))
+            candidates.add(`${parent}/${child}`);
+    }
+    const found = [];
+    for (const dir of [...candidates].sort()) {
+        if (dir.split('/').some((seg) => !usableDir(seg)))
+            continue;
+        const pkg = loadPkg(fs, dir);
+        if (!pkg.json)
+            continue;
+        const hasScript = ['typecheck', 'type-check', 'build', 'test'].some((s) => script(pkg, s) !== null);
+        const hasTsconfig = fs.readFile(join(dir, 'tsconfig.json')) !== null;
+        if (hasScript || hasTsconfig)
+            found.push(dir);
+    }
+    return found;
+}
+function draftGates(fs, opts) {
+    const root = loadPkg(fs, '');
+    const rootTc = draftTypecheck(fs, root);
+    const rootTest = draftTests(fs, root, opts.packageManager);
+    const subPackages = findSubPackages(fs, opts.workspaces);
+    const allSubs = subPackages.slice(0, MAX_SUB_PACKAGES);
+    const typechecks = [];
+    const tests = [];
+    if (rootTc)
+        typechecks.push({ ...rootTc.step, required: true, why: rootTc.why });
+    for (const dir of allSubs) {
+        const pkg = loadPkg(fs, dir);
+        const member = opts.workspaces.some((w) => (0, glob_1.matchesGlob)(dir, w.replace(/^\.\//, '').replace(/\/+$/, '')));
+        // A workspace member is part of one build: a change anywhere can break it,
+        // so its checks are unconditional, and the root's own covers it when there
+        // is one. A standalone app (its own install, not a workspace) is checked
+        // when something inside it changed — an API-only round should not pay for
+        // a frontend build, and a UI round must not go unchecked.
+        const when = member ? undefined : `${dir}/**`;
+        const scopeNote = member
+            ? 'a workspace package'
+            : `its own app (own package.json); runs only when something under ${dir}/ changed`;
+        if (!(member && rootTc)) {
+            const tc = draftTypecheck(fs, pkg);
+            if (tc) {
+                typechecks.push({
+                    ...tc.step,
+                    name: `${dir}:${tc.step.name}`,
+                    ...(when ? { when } : {}),
+                    required: !when,
+                    why: `${tc.why} — ${scopeNote}`,
+                });
+            }
+        }
+        if (!(member && rootTest && !rootTest.disabled)) {
+            const t = draftTests(fs, pkg, opts.packageManager);
+            if (t) {
+                tests.push({
+                    ...t.step,
+                    name: `${dir}:${t.step.name}`,
+                    ...(when ? { when } : {}),
+                    required: !when,
+                    why: `${t.why} — ${scopeNote}`,
+                    ...(t.disabled ? { disabled: t.disabled } : {}),
+                });
+            }
+        }
+    }
+    if (rootTest) {
+        tests.push({
+            ...rootTest.step,
+            required: true,
+            why: rootTest.why,
+            ...(rootTest.disabled ? { disabled: rootTest.disabled } : {}),
+        });
+    }
+    // Cheapest first — the order in the file is the execution order (DESIGN §4):
+    // a broken typecheck should not wait on a test suite.
+    return {
+        typecheck: rootTc?.step ?? null,
+        testRunner: rootTest && !rootTest.disabled ? rootTest.step : null,
+        subPackages,
+        gates: [...typechecks, ...tests],
+    };
+}
+/* ─────────────────────────────── rendering ─────────────────────────────── */
+/** YAML double-quoted scalars are a superset of JSON strings, so this is safe. */
+const yamlStr = (s) => JSON.stringify(s);
+function gateLine(g) {
+    const when = g.when ? `, when: ${yamlStr(g.when)}` : '';
+    const req = g.required ? ', required: true' : '';
+    return `- { name: ${yamlStr(g.name)}, run: ${yamlStr(g.run)}, timeout_s: ${g.timeoutS}${when}${req} }`;
+}
+/**
+ * What a gate is and what `required` means — said where the person edits them.
+ *
+ * ⚠️ `required: false` DOES NOT MAKE A GATE ADVISORY. Every step that runs must
+ * pass, and the first red one discards the round (`gate.ts`, `mayCommit`).
+ * `required` only adds that the step must have RUN: a required step a `when:`
+ * filter skipped blocks the commit too. A person who believed otherwise left a
+ * 30-minute suite in place as "not required" and lost every round to it.
+ */
+exports.GATES_HEADER = [
+    "# Gates decide whether a round's work is kept. They run top to bottom, cheapest",
+    '# first, and EVERY step that runs must pass: the first failure (or timeout)',
+    '# discards the round. There is no advisory gate.',
+    '#',
+    '# required: true adds one condition: the step must actually have run. A required',
+    '# step that its `when:` filter skipped blocks the commit, so steps with `when:`',
+    '# are not required. required: false does NOT make a step optional; to stop',
+    '# checking something, delete or comment out its line.',
+    '#',
+    '# Each gate must finish well inside one round. A suite that cannot (in band,',
+    '# huge heap, database or container setup) is drafted commented out, with why.',
+].join('\n');
+/**
+ * The gate list as it appears in the file: one comment line per gate saying
+ * what it checks and why, left-out suites commented out with their reason.
+ *
+ * `header` is the comment block written directly above `gates:`, so the whole
+ * section can be re-drafted in place by `init --refresh-gates`.
+ */
+function renderGatesSection(gates, header) {
+    const lines = [header, 'gates:'];
+    const active = gates.filter((g) => !g.disabled);
+    for (const g of gates) {
+        lines.push(`  # ${g.name}: ${g.why}`);
+        if (g.disabled) {
+            lines.push(`  # ${g.disabled}`, `  # ${gateLine(g)}`);
+        }
+        else {
+            lines.push(`  ${gateLine(g)}`);
+        }
+    }
+    if (!active.length) {
+        // `gates:` with only comments under it reads as null, and the loader says
+        // so — a config with no gate must not look like one that has them.
+        lines.push('  # none detected that can run inside a round (nothing detected) — add at least one, or a green round proves nothing');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=gate-draft.js.map