@timekast/factory 2.3.1 → 2.5.0

package/dist/commands/prune.js

@@ -0,0 +1,305 @@
+/**
+ * `factory prune <sub>` — share a derived repo with outside collaborators WITHOUT the
+ * methodology. The member who runs it acts with their own `gh` session and permissions.
+ *
+ * Model (`.claude/docs/working-with-collaborators.md`): members of the org clone the repo and
+ * run `factory update`, which drops the whole kit on their disk — the restricted part is
+ * gitignored, so it never enters the repository. Collaborators fork and open PRs; they see the
+ * product, the always-on rules and the kit systems, never the content of the procedures.
+ *
+ * Everything here is switched on per repo by `.timekast/prune.json`, which only `prepare`
+ * writes. A repo without it behaves exactly as before.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { CLIError } from '../lib/cli-error.js';
+import { GITIGNORE_FILE } from '../lib/constants.js';
+import { readValueFlag } from '../lib/flags.js';
+import { commitWithPrivateIndex, trackedFiles } from '../lib/prune-git.js';
+import { checkPr, REJECTED_PACKAGE_FIELDS } from '../lib/prune-pr-check.js';
+import { BRANCH_DEPLOY_RULE, VERCEL_JSON, ensureBranchDeployRule, hasBranchDeployRule, pruneVercelRelink, resolveVercelProject, } from '../lib/prune-vercel.js';
+import { readVercelToken } from '../lib/provision-preflight.js';
+import { applyTierFiles, defaultPruneDeps, originRepo, pruneAudit, pruneCutover, pruneFinish, pruneInvite, } from '../lib/prune-remote.js';
+import { DEFAULT_PRUNE_TIER, PRUNE_MARKER_PATH, getTier, isRestricted, readPruneMarker, readPruneTiers, } from '../lib/prune-tiers.js';
+import { detectRepo } from '../lib/repo-detection.js';
+const PRUNE_USAGE = 'Uso: `factory prune prepare [--tier=collab] [--skip-verify]` · ' +
+    '`factory prune cutover [--confirm] [--discard-develop] [--resume] [--repo=owner/nombre]` · ' +
+    '`factory prune vercel [--confirm] [--repo=owner/nombre] [--project=prj_…] [--team=team_…]` · ' +
+    '`factory prune invite <usuario-github> [--read] [--repo=owner/nombre]` · ' +
+    '`factory prune finish [--repo=owner/nombre]` · `factory prune audit [--repo=owner/nombre]` · ' +
+    '`factory prune check-pr <número> [--repo=owner/nombre] [--json]`.';
+export function parsePrunePrepareFlags(argv) {
+    return {
+        tier: readValueFlag(argv, 'tier') ?? DEFAULT_PRUNE_TIER,
+        skipVerify: argv.includes('--skip-verify'),
+    };
+}
+/**
+ * Write the tier's `.gitignore` block and the switch, untrack what the block now ignores, and
+ * commit all of it in one go. Idempotent: a second run on a prepared repo changes nothing and
+ * commits nothing.
+ */
+export async function prunePrepare(rootDir, flags) {
+    const head = await execa('git', ['rev-parse', '--verify', '-q', 'HEAD'], {
+        cwd: rootDir,
+        reject: false,
+    });
+    if (head.exitCode !== 0) {
+        throw new CLIError('El repo no tiene commits todavía; haz el primer commit antes de `prune`.');
+    }
+    const tier = getTier(readPruneTiers(rootDir), flags.tier);
+    // The two files this command owns must not carry someone's uncommitted work: the commit
+    // below takes them whole.
+    const dirty = await execa('git', ['status', '--porcelain', '--', GITIGNORE_FILE, PRUNE_MARKER_PATH, VERCEL_JSON], { cwd: rootDir, reject: false });
+    if (dirty.stdout.trim() !== '') {
+        throw new CLIError(`\`${GITIGNORE_FILE}\`, \`${PRUNE_MARKER_PATH}\` o \`${VERCEL_JSON}\` tienen cambios sin commitear. ` +
+            'Commitéalos o descártalos y vuelve a correr `factory prune prepare`.');
+    }
+    // 1. The block and the switch — `at` survives a re-run with the same tier, so a re-run
+    // changes nothing.
+    const prior = readPruneMarker(rootDir);
+    const legacyBlockRemoved = applyTierFiles(rootDir, flags.tier, tier, prior?.tier === flags.tier ? prior.at : new Date().toISOString());
+    // 2. On Vercel, only `main` and `develop` deploy on push: a collaborator's branch would
+    //    start a deployment Vercel blocks (author without a seat).
+    const branchDeployRuleAdded = ensureBranchDeployRule(rootDir) === 'added';
+    // 3. Untrack what the tier restricts, and commit it with the block, the switch and the rule.
+    const untracked = (await trackedFiles(rootDir)).filter((p) => isRestricted(tier, p));
+    const commit = await commitWithPrivateIndex(rootDir, {
+        remove: untracked,
+        add: [GITIGNORE_FILE, PRUNE_MARKER_PATH, ...(branchDeployRuleAdded ? [VERCEL_JSON] : [])],
+        message: `chore(prune): keep the methodology local (tier ${flags.tier})`,
+    });
+    return {
+        tier: flags.tier,
+        untracked,
+        branchDeployRuleAdded,
+        legacyBlockRemoved,
+        ...(commit.committed ? { commit: commit.sha } : {}),
+    };
+}
+/** Group untracked paths by their first two segments, for a summary a person can read. */
+function summarizePaths(paths) {
+    const groups = new Map();
+    for (const p of paths) {
+        const key = p.split('/').slice(0, 2).join('/');
+        groups.set(key, (groups.get(key) ?? 0) + 1);
+    }
+    return [...groups].sort().map(([k, n]) => `  • ${k}/ (${n})`);
+}
+async function runPrunePrepare(flags) {
+    const rootDir = requireRepoRoot();
+    const result = await prunePrepare(rootDir, flags);
+    if (result.legacyBlockRemoved) {
+        console.log('✔ Quité el bloque `timekast:collab` hecho a mano; lo reemplaza el bloque del kit.');
+    }
+    if (!result.commit) {
+        console.log(`✔ El repo ya estaba preparado con el tier \`${result.tier}\`; no cambió nada.`);
+    }
+    else {
+        console.log(`✔ Tier \`${result.tier}\` aplicado y commiteado (${result.commit}, sin push). ` +
+            `Dejé de trackear ${result.untracked.length} archivo(s); siguen en tu disco:`);
+        for (const line of summarizePaths(result.untracked))
+            console.log(line);
+        if (result.branchDeployRuleAdded) {
+            console.log(`✔ \`${VERCEL_JSON}\`: sólo \`main\` y \`develop\` despliegan con cada push — las ramas de ` +
+                'los colaboradores no intentan un deploy que Vercel bloquearía.');
+        }
+    }
+    if (flags.skipVerify)
+        return;
+    const pkgPath = path.join(rootDir, 'package.json');
+    const hasVerify = existsSync(pkgPath) &&
+        Boolean(JSON.parse(readFileSync(pkgPath, 'utf8')).scripts
+            ?.verify);
+    if (!hasVerify) {
+        console.log('ℹ️  Este repo no tiene `pnpm verify`; no corrí la verificación.');
+        return;
+    }
+    console.log('\n▸ Corriendo `pnpm verify`…');
+    const verify = await execa('pnpm', ['verify'], { cwd: rootDir, stdio: 'inherit', reject: false });
+    if (verify.exitCode !== 0) {
+        process.exitCode = 1;
+        console.error('✖ `pnpm verify` falló. Revísalo antes de seguir con el corte.');
+    }
+}
+// ---------------------------------------------------------------------------
+// cutover · invite · finish · audit (GitHub, with the member's `gh` session)
+// ---------------------------------------------------------------------------
+export function parseCutoverFlags(argv) {
+    return {
+        repo: readValueFlag(argv, 'repo'),
+        tier: readValueFlag(argv, 'tier') ?? DEFAULT_PRUNE_TIER,
+        confirm: argv.includes('--confirm'),
+        discardDevelop: argv.includes('--discard-develop'),
+        resume: argv.includes('--resume'),
+    };
+}
+async function runPruneCutover(flags, deps) {
+    const rootDir = requireRepoRoot();
+    const { preflight, result } = await pruneCutover(rootDir, flags, deps);
+    if (!result) {
+        console.log([
+            `✔ Preflight del corte de \`${preflight.repo}\` en verde. No toqué nada.`,
+            '',
+            'Plan:',
+            `  1. Snapshot de \`main\` (${preflight.mainSha.slice(0, 7)}) con el tier aplicado, validado sin rutas restringidas.`,
+            `  2. Crear \`${preflight.next}\` (privado) y subir el snapshot como \`main\` y \`develop\` — un solo commit.`,
+            `  3. Renombrar \`${preflight.repo}\` → \`${preflight.legacy}\` y \`${preflight.next}\` → \`${preflight.repo}\`.`,
+            '  4. Permitir forks SOLO en el repo nuevo; sin workflows de PRs de forks.',
+            ...(preflight.developAhead.length > 0
+                ? [
+                    `  ⚠  Se pierden ${preflight.developAhead.length} commit(s) de \`develop\` (--discard-develop).`,
+                ]
+                : []),
+            '',
+            'Para ejecutarlo: `factory prune cutover --confirm`.',
+        ].join('\n'));
+        return;
+    }
+    console.log(`✔ Corte hecho: \`${result.repo}\` es el repo nuevo (un commit, ${result.snapshot}); ` +
+        `el anterior quedó como \`${result.legacy}\`.`);
+    for (const w of result.warnings)
+        console.warn(`⚠  ${w}`);
+    if (result.notMigrated.length > 0) {
+        console.log(`\nNo migró (sigue en \`${result.legacy}\`):`);
+        for (const line of result.notMigrated)
+            console.log(`  • ${line}`);
+    }
+    console.log('\nSiguiente: reconecta el proyecto de Vercel al repo nuevo (`factory prune vercel`), ' +
+        'pide a los socios volver a clonar, y corre `factory prune finish` cuando Production despliegue.');
+}
+function printAudit(repo, audit) {
+    const clean = audit.roots.length === 1 && audit.leaks.length === 0;
+    if (clean) {
+        console.log(`✔ Historia de \`${repo}\` limpia: una raíz, ninguna ruta del tier \`${audit.tierName}\`.`);
+        return true;
+    }
+    if (audit.roots.length !== 1) {
+        console.error(`✖ \`${repo}\` tiene ${audit.roots.length} commits raíz (esperado: 1) — ` +
+            'probablemente un clon viejo pusheó la historia anterior.');
+    }
+    if (audit.leaks.length > 0) {
+        console.error(`✖ ${audit.leaks.length} ruta(s) restringida(s) en la historia (incluye refs de PRs):`);
+        for (const p of audit.leaks)
+            console.error(`    ${p}`);
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+function requireRepoRoot() {
+    const root = detectRepo(process.cwd()).repoRoot;
+    if (!root)
+        throw new CLIError('Corre `factory prune` dentro de un repo git.');
+    return root;
+}
+async function repoFrom(argv) {
+    return readValueFlag(argv, 'repo') ?? (await originRepo(requireRepoRoot()));
+}
+/** `factory prune <sub> [...]` — dispatch lives here so every branch is testable. */
+export async function runPruneCommand(args, deps = defaultPruneDeps, vercel = {}) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'prepare':
+            await runPrunePrepare(parsePrunePrepareFlags(rest));
+            return;
+        case 'cutover':
+            await runPruneCutover(parseCutoverFlags(rest), deps);
+            return;
+        case 'invite': {
+            const user = rest.find((a) => !a.startsWith('-') && rest[rest.indexOf(a) - 1] !== '--repo');
+            if (!user)
+                throw new CLIError(`Falta el usuario de GitHub del colaborador. ${PRUNE_USAGE}`);
+            const repo = await repoFrom(rest);
+            const read = rest.includes('--read');
+            await pruneInvite(repo, user, deps, read ? 'pull' : 'push');
+            console.log(read
+                ? `✔ Invité a \`${user}\` a \`${repo}\` con lectura. Tiene que aceptar la invitación; ` +
+                    'después forkea y abre PRs a la rama de trabajo.'
+                : `✔ Invité a \`${user}\` a \`${repo}\` con escritura. Tiene que aceptar la invitación; ` +
+                    'después trabaja en ramas del repo y abre PRs a la rama de trabajo. El hook `pre-push` ' +
+                    'del repo le rechaza el push a `main` y `develop` (no cubre la web de GitHub).');
+            return;
+        }
+        case 'vercel': {
+            const repo = await repoFrom(rest);
+            const { projectId, teamId } = resolveVercelProject(requireRepoRoot(), {
+                project: readValueFlag(rest, 'project'),
+                team: readValueFlag(rest, 'team'),
+            });
+            const token = await (vercel.token ?? (() => readVercelToken()))();
+            const result = await pruneVercelRelink({ repo, projectId, teamId, token, confirm: rest.includes('--confirm') }, { gh: deps.gh, ...(vercel.fetchImpl ? { fetchImpl: vercel.fetchImpl } : {}) });
+            if (hasBranchDeployRule(requireRepoRoot()) === false) {
+                console.warn(`⚠ \`${VERCEL_JSON}\` no limita los deploys por push: cada rama de un colaborador intentará ` +
+                    'un deploy que Vercel bloquea (autor sin asiento). Agrega y commitea:\n' +
+                    `    "git": { "deploymentEnabled": ${JSON.stringify(BRANCH_DEPLOY_RULE)} }`);
+            }
+            if (result.status === 'already-linked') {
+                console.log(`✔ El proyecto de Vercel ya despliega desde \`${result.link.repo}\`. Nada que hacer.`);
+            }
+            else if (result.status === 'plan') {
+                console.log([
+                    `Plan: el proyecto de Vercel (\`${projectId}\`) despliega desde ` +
+                        `${result.from ? `\`${result.from.repo}\`` : 'ningún repo'}.`,
+                    `  1. Desconectarlo${result.from ? ` de \`${result.from.repo}\`` : ''} (variables, dominios y deploys se quedan).`,
+                    `  2. Conectarlo a \`${result.to}\` y releer el vínculo para confirmarlo.`,
+                    '  No dispara ningún deploy.',
+                    '',
+                    'Para ejecutarlo: `factory prune vercel --confirm`.',
+                ].join('\n'));
+            }
+            else {
+                console.log(`✔ El proyecto de Vercel ahora despliega desde \`${result.to.repo}\`` +
+                    `${result.from ? ` (antes: \`${result.from.repo}\`)` : ''}. ` +
+                    'El primer deploy sale con el siguiente push a `main` (p. ej. un commit vacío).');
+            }
+            return;
+        }
+        case 'finish': {
+            const repo = await repoFrom(rest);
+            const done = await pruneFinish(repo, deps);
+            console.log(`✔ \`${repo}-legacy\`: forks apagados, ${done.removedCollaborators.length} colaborador(es) ` +
+                'externo(s) quitado(s) y archivado.');
+            if (!printAudit(repo, done.audit))
+                process.exitCode = 1;
+            return;
+        }
+        case 'check-pr': {
+            const raw = rest.find((a) => /^\d+$/.test(a));
+            if (!raw)
+                throw new CLIError(`Falta el número del PR. ${PRUNE_USAGE}`);
+            const repo = await repoFrom(rest);
+            const result = await checkPr(repo, Number(raw), deps);
+            const refused = result.rejected.length > 0 || result.packageFields.length > 0;
+            if (rest.includes('--json')) {
+                console.log(JSON.stringify({ refused, ...result }, null, 2));
+            }
+            else if (!refused) {
+                console.log(`✔ PR #${raw}: ningún archivo fuera del producto (${result.files.length} archivo(s)).`);
+            }
+            else {
+                console.error(`✖ PR #${raw} rechazado antes del checkout — toca lo que corre alrededor del producto:`);
+                for (const r of result.rejected)
+                    console.error(`    ${r.path} — ${r.why}`);
+                for (const f of result.packageFields) {
+                    console.error(`    package.json#${f} — ${REJECTED_PACKAGE_FIELDS.includes(f) ? 'comandos que corren en tu máquina' : 'revísalo a mano'}`);
+                }
+                console.error('  Regrésalo al colaborador, o que un socio rehaga ese cambio.');
+            }
+            if (refused)
+                process.exitCode = 1;
+            return;
+        }
+        case 'audit': {
+            const repo = await repoFrom(rest);
+            if (!printAudit(repo, await pruneAudit(repo, deps)))
+                process.exitCode = 1;
+            return;
+        }
+        default:
+            throw new CLIError(`Subcomando de prune desconocido: \`${sub ?? '(ninguno)'}\`. ${PRUNE_USAGE}`);
+    }
+}