@timekast/factory 2.3.0 → 2.4.0

package/dist/lib/prune-git.js

@@ -0,0 +1,81 @@
+/**
+ * Git plumbing for `factory prune`: list what the repo tracks, and commit a set of
+ * untrack + add operations WITHOUT going through the shared index.
+ *
+ * Why a private index and not the kit's usual commit-by-pathspec (`GIT.md §3.6.1`): a
+ * pathspec commit takes the listed paths' content from the WORKING TREE, so a path removed
+ * with `git rm --cached` (still on disk, now ignored) is put right back — the commit records
+ * no deletion and the methodology stays published. Staging the removal in the real index
+ * instead would leave it there for any other commit to swallow. A throwaway index seeded from
+ * HEAD gives both properties: the commit holds exactly these operations, and nothing another
+ * session staged can ride along.
+ */
+import { existsSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { CLIError } from './cli-error.js';
+/** Every path the index tracks (POSIX, repo-relative). */
+export async function trackedFiles(rootDir) {
+    const res = await execa('git', ['ls-files', '-z'], { cwd: rootDir, reject: false });
+    if (res.exitCode !== 0) {
+        throw new CLIError(`No se pudo listar los archivos del repo (\`git ls-files\`): ${res.stderr}`);
+    }
+    return res.stdout.split('\0').filter(Boolean);
+}
+/**
+ * Commit `remove` + `add` on top of HEAD through a private index, then bring the real index
+ * of those paths in line with the new HEAD. Hooks run as for any commit. Nothing to commit →
+ * `{ committed: false }`, no empty commit.
+ */
+export async function commitWithPrivateIndex(rootDir, input) {
+    const gitDirRes = await execa('git', ['rev-parse', '--absolute-git-dir'], {
+        cwd: rootDir,
+        reject: false,
+    });
+    if (gitDirRes.exitCode !== 0) {
+        throw new CLIError('Esto no es un repo git.');
+    }
+    const indexFile = path.join(gitDirRes.stdout.trim(), `tk-prune-index-${process.pid}`);
+    const env = { ...process.env, GIT_INDEX_FILE: indexFile };
+    const run = (args) => execa('git', args, { cwd: rootDir, env, reject: false });
+    try {
+        const head = await execa('git', ['rev-parse', '--verify', '-q', 'HEAD'], {
+            cwd: rootDir,
+            reject: false,
+        });
+        const seeded = await run(head.exitCode === 0 ? ['read-tree', 'HEAD'] : ['read-tree', '--empty']);
+        if (seeded.exitCode !== 0)
+            throw new CLIError(`\`git read-tree\` falló: ${seeded.stderr}`);
+        if (input.remove.length > 0) {
+            const rm = await run(['rm', '--cached', '-q', '--ignore-unmatch', '--', ...input.remove]);
+            if (rm.exitCode !== 0)
+                throw new CLIError(`\`git rm --cached\` falló: ${rm.stderr}`);
+        }
+        if (input.add.length > 0) {
+            const add = await run(['add', '-f', '--', ...input.add]);
+            if (add.exitCode !== 0)
+                throw new CLIError(`\`git add\` falló: ${add.stderr}`);
+        }
+        const diff = await run(['diff', '--cached', '--quiet']);
+        if (diff.exitCode === 0)
+            return { committed: false };
+        const commit = await run(['commit', '-q', '-m', input.message]);
+        if (commit.exitCode !== 0) {
+            throw new CLIError(`El commit falló (¿un hook lo rechazó o falta identidad git?):\n${commit.stderr || commit.stdout}`);
+        }
+        const sha = await execa('git', ['rev-parse', '--short', 'HEAD'], { cwd: rootDir });
+        // The real index still holds the pre-commit state of these paths: reset them to the new
+        // HEAD so `git status` shows the removals as done, not as staged re-additions.
+        await execa('git', ['reset', '-q', '--', ...input.remove, ...input.add], {
+            cwd: rootDir,
+            reject: false,
+        });
+        return { committed: true, sha: sha.stdout.trim() };
+    }
+    finally {
+        for (const f of [indexFile, `${indexFile}.lock`]) {
+            if (existsSync(f))
+                rmSync(f, { force: true });
+        }
+    }
+}

package/dist/lib/prune-pr-check.js

@@ -0,0 +1,119 @@
+/**
+ * The hard refusal `/integrate` runs on a collaborator's pull request BEFORE checking it out
+ * (`factory prune check-pr`). A member runs the PR's code on their own machine — a risk the
+ * org accepted for product code, and only for product code — so any change to what runs
+ * around the product (hooks, CI, scripts, tooling config, the methodology, the prune switch)
+ * is refused by path, mechanically, never by the agent's judgement. A PR refused here goes
+ * back to the collaborator, or a member redoes it.
+ *
+ * SSOT of the list: `REJECTED_PATHS` below. `tk-integrate/methodology/rejected-paths.md`
+ * explains it and points here.
+ */
+import { CLIError } from './cli-error.js';
+export const REJECTED_PATHS = [
+    { pattern: '.claude/', why: 'el cerebro del kit (reglas, hooks del agente, políticas)' },
+    { pattern: 'CLAUDE.md', why: 'instrucciones del agente' },
+    { pattern: '.husky/', why: 'hooks de git: corren en la máquina de quien commitea' },
+    { pattern: '.github/', why: 'CI y configuración de GitHub' },
+    { pattern: 'scripts/', why: 'scripts que corren los hooks y `pnpm verify`' },
+    { pattern: '.gitignore', why: 'decide qué de la metodología entra al repo' },
+    { pattern: '.timekast/', why: 'el interruptor del repo compartido y el estado del kit' },
+    {
+        pattern: '**/*.config.*',
+        why: 'configuración de herramientas (next, vitest, eslint, playwright…)',
+    },
+    { pattern: 'vitest.setup*', why: 'código que corre antes de cada test' },
+    { pattern: '.npmrc', why: 'configuración de pnpm (registro, scripts)' },
+    { pattern: '.pnpmfile.cjs', why: 'código que pnpm ejecuta al instalar' },
+    { pattern: 'pnpm-workspace.yaml', why: 'configuración de pnpm' },
+];
+/** The `package.json` fields a PR may not change (scripts run on the member's machine). */
+export const REJECTED_PACKAGE_FIELDS = ['scripts', 'pnpm'];
+function segmentRx(pattern) {
+    return new RegExp(`^${pattern
+        .split('*')
+        .map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('[^/]*')}$`);
+}
+/** Does `relPath` fall under `pattern`? A leading `**` + `/` matches the basename at any depth. */
+export function pathRejected(pattern, relPath) {
+    if (pattern.startsWith('**/')) {
+        const base = relPath.split('/').pop() ?? relPath;
+        return segmentRx(pattern.slice(3)).test(base);
+    }
+    if (pattern.endsWith('/'))
+        return relPath.startsWith(pattern);
+    return segmentRx(pattern).test(relPath);
+}
+/** Read the PR's files from GitHub (no checkout) and apply the refusal. */
+export async function checkPr(repo, pr, deps) {
+    const filesRes = await deps.gh([
+        'api',
+        '--paginate',
+        `repos/${repo}/pulls/${pr}/files?per_page=100`,
+        '--jq',
+        '.[] | [.filename, (.previous_filename // "")] | @tsv',
+    ]);
+    if (filesRes.exitCode !== 0) {
+        throw new CLIError(`No pude leer los archivos del PR #${pr} de \`${repo}\`: ${filesRes.stderr}`);
+    }
+    const files = [
+        ...new Set(filesRes.stdout
+            .split('\n')
+            .flatMap((line) => line.split('\t'))
+            .map((p) => p.trim())
+            .filter(Boolean)),
+    ].sort();
+    const rejected = [];
+    for (const p of files) {
+        const hit = REJECTED_PATHS.find((r) => pathRejected(r.pattern, p));
+        if (hit)
+            rejected.push({ path: p, why: hit.why });
+    }
+    const packageFields = [];
+    if (files.includes('package.json')) {
+        const meta = await deps.gh([
+            'pr',
+            'view',
+            String(pr),
+            '--repo',
+            repo,
+            '--json',
+            'baseRefOid,headRefOid',
+            '--jq',
+            '[.baseRefOid, .headRefOid] | @tsv',
+        ]);
+        if (meta.exitCode !== 0)
+            throw new CLIError(`No pude leer el PR #${pr}: ${meta.stderr}`);
+        const [base, head] = meta.stdout.trim().split('\t');
+        const read = async (ref) => {
+            const r = await deps.gh([
+                'api',
+                `repos/${repo}/contents/package.json?ref=${ref}`,
+                '-H',
+                'Accept: application/vnd.github.raw',
+            ]);
+            if (r.exitCode !== 0)
+                return null;
+            try {
+                return JSON.parse(r.stdout);
+            }
+            catch {
+                return null;
+            }
+        };
+        const [before, after] = [await read(base), await read(head)];
+        if (!before || !after) {
+            // Unreadable or invalid JSON on either side: the comparison cannot clear it.
+            packageFields.push('(no se pudo comparar package.json)');
+        }
+        else {
+            for (const field of REJECTED_PACKAGE_FIELDS) {
+                if (JSON.stringify(before[field] ?? null) !== JSON.stringify(after[field] ?? null)) {
+                    packageFields.push(field);
+                }
+            }
+        }
+    }
+    return { rejected, packageFields, files };
+}

package/dist/lib/prune-remote.js

@@ -0,0 +1,464 @@
+/**
+ * The GitHub side of `factory prune`: the cut to a repo whose history never held the
+ * methodology (`cutover`), inviting collaborators (`invite`), closing the old repo (`finish`)
+ * and auditing a repo's history (`audit`).
+ *
+ * Everything runs with the `gh` session of the member who runs it — their permissions, never
+ * a token of the org. `gh`, the push URL and the mirror clone are injected (`PruneDeps`) so the
+ * suite drives every branch against local bare repos and a scripted `gh`, never GitHub.
+ *
+ * The cut is the one irreversible step, so its order is the safety argument:
+ *   1. read-only preflight that refuses on anything doubtful (and stops there without
+ *      `--confirm`);
+ *   2. a snapshot of `main` with the tier applied, built and VALIDATED locally;
+ *   3. `<repo>-next` created and pushed — the original is untouched until here;
+ *   4. the original's `main` re-checked, then two renames (`<repo>` → `<repo>-legacy`,
+ *      `<repo>-next` → `<repo>`), with the first undone if the second fails.
+ * Progress is saved in the git dir, so `--resume` continues where a failure stopped.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import { CLIError } from './cli-error.js';
+import { GITIGNORE_FILE } from './constants.js';
+import { syncManagedBlock } from './gitattributes.js';
+import { PRUNE_MARKER_PATH, PRUNE_TIERS_PATH, getTier, isRestricted, readPruneTiers, renderGitignoreBlock, stripLegacyCollabBlock, validatePruneTiers, writePruneMarker, } from './prune-tiers.js';
+export const defaultPruneDeps = {
+    gh: async (args) => {
+        const r = await execa('gh', args, { reject: false });
+        return { exitCode: r.exitCode ?? 1, stdout: r.stdout, stderr: r.stderr };
+    },
+    pushUrl: (repo) => `https://github.com/${repo}.git`,
+    cloneMirror: async (repo, dir) => {
+        const r = await execa('gh', ['repo', 'clone', repo, dir, '--', '--mirror', '-q'], {
+            reject: false,
+        });
+        if (r.exitCode !== 0)
+            throw new CLIError(`No se pudo clonar \`${repo}\`: ${r.stderr}`);
+    },
+};
+async function git(cwd, args, input) {
+    const r = await execa('git', args, {
+        cwd,
+        reject: false,
+        ...(input !== undefined ? { input } : {}),
+    });
+    return { exitCode: r.exitCode ?? 1, stdout: r.stdout, stderr: r.stderr };
+}
+async function gitOk(cwd, args, what) {
+    const r = await git(cwd, args);
+    if (r.exitCode !== 0)
+        throw new CLIError(`${what} falló: ${r.stderr || r.stdout}`);
+    return r.stdout;
+}
+async function ghOk(deps, args, what) {
+    const r = await deps.gh(args);
+    if (r.exitCode !== 0)
+        throw new CLIError(`${what} falló: ${r.stderr || r.stdout}`);
+    return r.stdout;
+}
+/** `gh api <path>` succeeded? (404 and every other failure → false). */
+async function ghExists(deps, apiPath) {
+    return (await deps.gh(['api', apiPath, '--silent'])).exitCode === 0;
+}
+function splitRepo(repo) {
+    const m = /^([A-Za-z0-9-]+)\/([A-Za-z0-9._-]+)$/.exec(repo);
+    if (!m)
+        throw new CLIError(`\`${repo}\` no tiene la forma \`owner/nombre\`.`);
+    return { owner: m[1], name: m[2] };
+}
+/** `owner/name` of the `origin` remote (https or ssh). */
+export async function originRepo(rootDir) {
+    const url = (await git(rootDir, ['remote', 'get-url', 'origin'])).stdout.trim();
+    const m = /github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/.exec(url);
+    if (!m) {
+        throw new CLIError(`No pude leer el repo de GitHub de \`origin\` (${url || 'sin remote'}). Pásalo con \`--repo=owner/nombre\`.`);
+    }
+    return `${m[1]}/${m[2]}`;
+}
+// ---------------------------------------------------------------------------
+// Snapshot
+// ---------------------------------------------------------------------------
+/**
+ * Apply the tier to a working tree: the managed `.gitignore` block + the switch. CMLL's
+ * hand-written block is removed first, or the sync would add a second one beside it.
+ * Returns whether that legacy block was there.
+ */
+export function applyTierFiles(dir, tierName, tier, at) {
+    const gitignorePath = path.join(dir, GITIGNORE_FILE);
+    let legacyBlockRemoved = false;
+    if (existsSync(gitignorePath)) {
+        const stripped = stripLegacyCollabBlock(readFileSync(gitignorePath, 'utf8'));
+        if (stripped.removed) {
+            writeFileSync(gitignorePath, stripped.content, 'utf8');
+            legacyBlockRemoved = true;
+        }
+    }
+    syncManagedBlock(dir, renderGitignoreBlock(tierName, tier), GITIGNORE_FILE);
+    writePruneMarker(dir, { tier: tierName, at });
+    return legacyBlockRemoved;
+}
+/**
+ * Build, in `outDir`, a one-commit repo holding `sha`'s tree with the tier applied. The
+ * snapshot's own registry decides (it is what the new repo will enforce); a `main` that does
+ * not carry it yet falls back to the working tree's.
+ */
+export async function buildSnapshot(rootDir, sha, tierName, outDir, message) {
+    mkdirSync(outDir, { recursive: true });
+    await gitOk(outDir, ['init', '-q', '-b', 'main'], '`git init` del snapshot');
+    const tar = path.join(outDir, '..', `snapshot-${process.pid}.tar`);
+    try {
+        await gitOk(rootDir, ['archive', '--format=tar', '--output', tar, sha], '`git archive`');
+        const x = await execa('tar', ['-xf', tar, '-C', outDir], { reject: false });
+        if (x.exitCode !== 0)
+            throw new CLIError(`No se pudo extraer el snapshot: ${x.stderr}`);
+    }
+    finally {
+        rmSync(tar, { force: true });
+    }
+    const tiers = existsSync(path.join(outDir, PRUNE_TIERS_PATH))
+        ? readPruneTiers(outDir)
+        : readPruneTiers(rootDir);
+    const tier = getTier(tiers, tierName);
+    applyTierFiles(outDir, tierName, tier, new Date().toISOString());
+    await gitOk(outDir, ['add', '-A'], '`git add` del snapshot');
+    // The snapshot is a fresh repo: it only sees the global git identity. The member's identity
+    // as the source repo resolves it (local over global) authors the commit instead.
+    const identity = [];
+    for (const key of ['user.name', 'user.email']) {
+        const value = (await git(rootDir, ['config', key])).stdout.trim();
+        if (value)
+            identity.push('-c', `${key}=${value}`);
+    }
+    await gitOk(outDir, [...identity, 'commit', '-q', '-m', message], 'El commit del snapshot');
+    return { sha: (await gitOk(outDir, ['rev-parse', 'HEAD'], '`rev-parse`')).trim(), tier };
+}
+/**
+ * Restricted paths the snapshot would publish — by the classifier AND by git's own reading of
+ * the generated `.gitignore` (`check-ignore --no-index`). Either one non-empty aborts the cut.
+ */
+export async function snapshotOffenders(dir, tier) {
+    const files = (await gitOk(dir, ['ls-tree', '-r', '--name-only', 'HEAD'], '`ls-tree`'))
+        .split('\n')
+        .filter(Boolean);
+    const byTier = files.filter((p) => isRestricted(tier, p));
+    const ignored = await git(dir, ['check-ignore', '--no-index', '--stdin'], files.join('\n'));
+    const byGit = ignored.stdout.split('\n').filter(Boolean);
+    return [...new Set([...byTier, ...byGit])].sort();
+}
+/**
+ * Mirror-clone `repo` and check its whole history: one root, and no restricted path in any
+ * commit of any ref (pull-request refs included — a member's old clone pushed through a PR
+ * is exactly what this catches). The tier is the one the repo's own HEAD declares.
+ */
+export async function pruneAudit(repo, deps) {
+    const tmp = mkdtempSync(path.join(tmpdir(), 'tk-prune-audit-'));
+    try {
+        const dir = path.join(tmp, 'mirror.git');
+        await deps.cloneMirror(repo, dir);
+        const show = (rel) => git(dir, ['show', `HEAD:${rel}`]);
+        const marker = await show(PRUNE_MARKER_PATH);
+        const registry = await show(PRUNE_TIERS_PATH);
+        if (marker.exitCode !== 0 || registry.exitCode !== 0) {
+            throw new CLIError(`\`${repo}\` no es un repo podado: su HEAD no trae \`${PRUNE_MARKER_PATH}\` y \`${PRUNE_TIERS_PATH}\`.`);
+        }
+        const tierName = JSON.parse(marker.stdout).tier;
+        const data = JSON.parse(registry.stdout);
+        const errors = validatePruneTiers(data);
+        if (errors.length > 0)
+            throw new CLIError(`\`${PRUNE_TIERS_PATH}\` del repo es inválido.`);
+        const tier = getTier(data, tierName);
+        const roots = (await gitOk(dir, ['rev-list', '--max-parents=0', '--all'], '`rev-list`'))
+            .split('\n')
+            .filter(Boolean);
+        // Every path that ever existed was added by some commit, so the union of the paths each
+        // commit touches is the union of every tree in the history.
+        const touched = await gitOk(dir, ['log', '--all', '--name-only', '--no-renames', '--format='], '`git log`');
+        const leaks = [...new Set(touched.split('\n').filter(Boolean))]
+            .filter((p) => isRestricted(tier, p))
+            .sort();
+        return { tierName, roots, leaks };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+async function statePath(rootDir) {
+    const gitDir = (await gitOk(rootDir, ['rev-parse', '--absolute-git-dir'], '`rev-parse`')).trim();
+    return path.join(gitDir, 'tk-prune-cutover.json');
+}
+/** Read-only checks; throws a `CLIError` naming the first thing that blocks the cut. */
+export async function cutoverPreflight(rootDir, flags, deps) {
+    const repo = flags.repo ?? (await originRepo(rootDir));
+    const { owner, name } = splitRepo(repo);
+    const info = await deps.gh([
+        'api',
+        `repos/${repo}`,
+        '--jq',
+        '{admin: .permissions.admin, default: .default_branch, ownerType: .owner.type}',
+    ]);
+    if (info.exitCode !== 0)
+        throw new CLIError(`No pude leer \`${repo}\`: ${info.stderr}`);
+    const meta = JSON.parse(info.stdout);
+    if (!meta.admin)
+        throw new CLIError(`Necesitas ser admin de \`${repo}\` para el corte.`);
+    if (meta.ownerType !== 'Organization') {
+        throw new CLIError(`\`${repo}\` no pertenece a una organización; el corte es para repos de la org.`);
+    }
+    const login = (await ghOk(deps, ['api', 'user', '--jq', '.login'], 'Leer tu usuario')).trim();
+    const role = await deps.gh(['api', `orgs/${owner}/memberships/${login}`, '--jq', '.role']);
+    if (role.stdout.trim() !== 'admin') {
+        const can = await deps.gh([
+            'api',
+            `orgs/${owner}`,
+            '--jq',
+            '.members_can_create_private_repositories',
+        ]);
+        if (can.stdout.trim() !== 'true') {
+            throw new CLIError(`La org \`${owner}\` no deja a sus miembros crear repos privados y no eres owner: pide el corte a un owner.`);
+        }
+    }
+    const fetched = await git(rootDir, ['fetch', '-q', 'origin']);
+    if (fetched.exitCode !== 0)
+        throw new CLIError(`\`git fetch origin\` falló: ${fetched.stderr}`);
+    if ((await git(rootDir, ['status', '--porcelain'])).stdout.trim() !== '') {
+        throw new CLIError('Tienes cambios sin commitear. Commitéalos o descártalos antes del corte.');
+    }
+    const unpushed = (await git(rootDir, ['log', '--branches', '--not', '--remotes', '--oneline'])).stdout.trim();
+    if (unpushed !== '') {
+        throw new CLIError(`Tienes commits sin pushear; el corte no los llevaría:\n${unpushed}`);
+    }
+    const mainSha = (await gitOk(rootDir, ['rev-parse', 'origin/main'], 'Leer `origin/main`')).trim();
+    const hasDevelop = (await git(rootDir, ['rev-parse', '-q', '--verify', 'origin/develop'])).exitCode === 0;
+    const developAhead = hasDevelop
+        ? (await gitOk(rootDir, ['log', '--oneline', 'origin/main..origin/develop'], '`git log`'))
+            .split('\n')
+            .filter(Boolean)
+        : [];
+    if (developAhead.length > 0 && !flags.discardDevelop) {
+        throw new CLIError(`\`develop\` tiene ${developAhead.length} commit(s) que no están en \`main\`, y el repo nuevo ` +
+            'nace de `main`: se perderían.\n' +
+            developAhead.map((l) => `  • ${l}`).join('\n') +
+            '\nLlévalos a `main` primero (/deploy), o confirma por escrito que se pierden con `--discard-develop`.');
+    }
+    const next = `${owner}/${name}-next`;
+    const legacy = `${owner}/${name}-legacy`;
+    if (!flags.resume) {
+        for (const taken of [next, legacy]) {
+            if (await ghExists(deps, `repos/${taken}`)) {
+                throw new CLIError(`\`${taken}\` ya existe. Renómbralo o bórralo antes del corte.`);
+            }
+        }
+    }
+    return { repo, next, legacy, mainSha, defaultBranch: meta.default, developAhead };
+}
+/** The cut. Without `flags.confirm`, returns `null` after the preflight. */
+export async function pruneCutover(rootDir, flags, deps) {
+    const file = await statePath(rootDir);
+    const prior = flags.resume && existsSync(file)
+        ? JSON.parse(readFileSync(file, 'utf8'))
+        : null;
+    if (flags.resume && !prior)
+        throw new CLIError('No hay un corte a medias que retomar.');
+    const preflight = await cutoverPreflight(rootDir, prior ? { ...flags, repo: prior.repo } : flags, deps);
+    if (!flags.confirm)
+        return { preflight, result: null };
+    const { repo, next, legacy } = preflight;
+    const state = prior ?? {
+        repo,
+        mainSha: preflight.mainSha,
+        defaultBranch: preflight.defaultBranch,
+        done: [],
+    };
+    const save = () => writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+    const mark = (step) => {
+        state.done.push(step);
+        save();
+    };
+    const warnings = [];
+    let snapshot = '(retomado)';
+    if (!state.done.includes('pushed')) {
+        const tmp = mkdtempSync(path.join(tmpdir(), 'tk-prune-snapshot-'));
+        try {
+            const outDir = path.join(tmp, 'repo');
+            const built = await buildSnapshot(rootDir, state.mainSha, flags.tier, outDir, `chore: start ${splitRepo(repo).name} without the methodology (from main ${state.mainSha.slice(0, 7)})`);
+            snapshot = built.sha.slice(0, 7);
+            const offenders = await snapshotOffenders(outDir, built.tier);
+            if (offenders.length > 0) {
+                throw new CLIError(`El snapshot trae ${offenders.length} ruta(s) restringida(s); no subí nada:\n` +
+                    offenders.map((p) => `  • ${p}`).join('\n'));
+            }
+            await ghOk(deps, ['repo', 'create', next, '--private'], `Crear \`${next}\``);
+            save();
+            await gitOk(outDir, ['push', '-q', deps.pushUrl(next), 'HEAD:refs/heads/main', 'HEAD:refs/heads/develop'], `Subir el snapshot a \`${next}\``);
+            mark('pushed');
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+    }
+    if (!state.done.includes('renamed-legacy')) {
+        const live = (await ghOk(deps, ['api', `repos/${repo}/branches/main`, '--jq', '.commit.sha'], 'Releer `main`')).trim();
+        if (live !== state.mainSha) {
+            throw new CLIError(`\`main\` de \`${repo}\` cambió durante el corte (${state.mainSha.slice(0, 7)} → ${live.slice(0, 7)}). ` +
+                `No renombré nada; \`${next}\` quedó creado. Bórralo y vuelve a empezar.`);
+        }
+        await ghOk(deps, ['api', '-X', 'PATCH', `repos/${repo}`, '-f', `name=${splitRepo(legacy).name}`], `Renombrar \`${repo}\` a \`${legacy}\``);
+        mark('renamed-legacy');
+    }
+    if (!state.done.includes('renamed-new')) {
+        const renamed = await deps.gh([
+            'api',
+            '-X',
+            'PATCH',
+            `repos/${next}`,
+            '-f',
+            `name=${splitRepo(repo).name}`,
+        ]);
+        if (renamed.exitCode !== 0) {
+            const back = await deps.gh([
+                'api',
+                '-X',
+                'PATCH',
+                `repos/${legacy}`,
+                '-f',
+                `name=${splitRepo(repo).name}`,
+            ]);
+            state.done = state.done.filter((s) => s !== 'renamed-legacy');
+            save();
+            throw new CLIError(`No pude renombrar \`${next}\` a \`${repo}\` (${renamed.stderr.trim()}). ` +
+                (back.exitCode === 0
+                    ? `Regresé \`${legacy}\` a \`${repo}\`; el original quedó como estaba.`
+                    : `🔴 Tampoco pude regresar \`${legacy}\` a \`${repo}\`: hazlo a mano en GitHub.`));
+        }
+        mark('renamed-new');
+    }
+    if (!state.done.includes('settings')) {
+        const tries = [
+            [
+                ['api', '-X', 'PATCH', `repos/${repo}`, '-f', `default_branch=${state.defaultBranch}`],
+                `rama default \`${state.defaultBranch}\``,
+            ],
+            [
+                ['api', '-X', 'PATCH', `repos/${repo}`, '-F', 'allow_forking=true'],
+                'permitir forks en el repo',
+            ],
+            [
+                [
+                    'api',
+                    '-X',
+                    'PUT',
+                    `repos/${repo}/actions/permissions/fork-pr-workflows-private-repos`,
+                    '-F',
+                    'run_workflows_from_fork_pull_requests=false',
+                ],
+                'no correr workflows de PRs de forks',
+            ],
+        ];
+        for (const [args, what] of tries) {
+            const r = await deps.gh(args);
+            if (r.exitCode !== 0)
+                warnings.push(`No se aplicó: ${what} (${r.stderr.trim()}). Hazlo en GitHub.`);
+        }
+        mark('settings');
+    }
+    const notMigrated = await listNotMigrated(legacy, deps);
+    rmSync(file, { force: true });
+    return { preflight, result: { repo, legacy, snapshot, notMigrated, warnings } };
+}
+/** What lives on the old repo and does not travel with the snapshot (read-only). */
+async function listNotMigrated(legacy, deps) {
+    const probes = [
+        [
+            `repos/${legacy}/actions/variables`,
+            '[.variables[].name] | join(", ")',
+            'Variables de GitHub Actions',
+        ],
+        [`repos/${legacy}/environments`, '[.environments[].name] | join(", ")', 'Environments'],
+        [`repos/${legacy}/hooks`, 'length', 'Webhooks'],
+        [`repos/${legacy}/keys`, 'length', 'Deploy keys'],
+        [`repos/${legacy}/issues?state=open&per_page=100`, 'length', 'Issues y PRs abiertos'],
+    ];
+    const out = [];
+    for (const [apiPath, jq, label] of probes) {
+        const r = await deps.gh(['api', apiPath, '--jq', jq]);
+        const value = r.stdout.trim();
+        if (r.exitCode !== 0)
+            out.push(`${label}: no se pudo leer — revísalo en \`${legacy}\``);
+        else if (value !== '' && value !== '0')
+            out.push(`${label}: ${value}`);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Invite
+// ---------------------------------------------------------------------------
+/** Invite an outside collaborator with read access, after checking they are not a member. */
+export async function pruneInvite(repo, user, deps) {
+    const { owner } = splitRepo(repo);
+    if (!/^[A-Za-z0-9-]+$/.test(user))
+        throw new CLIError(`\`${user}\` no es un usuario de GitHub válido.`);
+    if (!(await ghExists(deps, `repos/${repo}/contents/${PRUNE_MARKER_PATH}`))) {
+        throw new CLIError(`\`${repo}\` no está podado (falta \`${PRUNE_MARKER_PATH}\` en su rama default). ` +
+            'Un colaborador externo vería la metodología: corre el corte primero.');
+    }
+    if (await ghExists(deps, `orgs/${owner}/members/${user}`)) {
+        throw new CLIError(`\`${user}\` es miembro de \`${owner}\`: los socios clonan y corren \`factory update\`, no se invitan como colaboradores.`);
+    }
+    const r = await deps.gh([
+        'api',
+        '-X',
+        'PUT',
+        `repos/${repo}/collaborators/${user}`,
+        '-f',
+        'permission=pull',
+    ]);
+    if (r.exitCode !== 0) {
+        if (/403|Forbidden|must have admin/i.test(r.stderr)) {
+            throw new CLIError(`GitHub rechazó la invitación (403). La org \`${owner}\` probablemente no deja a los admins de repo ` +
+                'invitar colaboradores externos: pídeselo a un owner de la org.');
+        }
+        throw new CLIError(`No se pudo invitar a \`${user}\`: ${r.stderr}`);
+    }
+}
+/** Close the legacy repo once the new one has deployed to Production, then audit it. */
+export async function pruneFinish(repo, deps) {
+    const { owner, name } = splitRepo(repo);
+    const legacy = `${owner}/${name}-legacy`;
+    const ids = (await ghOk(deps, ['api', `repos/${repo}/deployments?environment=Production&per_page=20`, '--jq', '.[].id'], 'Leer los deployments'))
+        .split('\n')
+        .filter(Boolean);
+    let deployed = false;
+    for (const id of ids) {
+        const state = await deps.gh([
+            'api',
+            `repos/${repo}/deployments/${id}/statuses?per_page=1`,
+            '--jq',
+            '.[0].state',
+        ]);
+        if (state.stdout.trim() === 'success') {
+            deployed = true;
+            break;
+        }
+    }
+    if (!deployed) {
+        throw new CLIError(`\`${repo}\` no tiene un deployment de Production exitoso todavía. Reconecta Vercel al repo nuevo, ` +
+            'haz el primer deploy y vuelve a correr `factory prune finish`.');
+    }
+    // The legacy repo can no longer be edited once archived, so everything goes first.
+    await ghOk(deps, ['api', '-X', 'PATCH', `repos/${legacy}`, '-F', 'allow_forking=false'], `Apagar los forks de \`${legacy}\``);
+    const outside = (await ghOk(deps, [
+        'api',
+        `repos/${legacy}/collaborators?affiliation=outside&per_page=100`,
+        '--jq',
+        '.[].login',
+    ], `Listar colaboradores de \`${legacy}\``))
+        .split('\n')
+        .filter(Boolean);
+    for (const login of outside) {
+        await ghOk(deps, ['api', '-X', 'DELETE', `repos/${legacy}/collaborators/${login}`], `Quitar a \`${login}\` de \`${legacy}\``);
+    }
+    await ghOk(deps, ['api', '-X', 'PATCH', `repos/${legacy}`, '-F', 'archived=true'], `Archivar \`${legacy}\``);
+    return { removedCollaborators: outside, audit: await pruneAudit(repo, deps) };
+}