@timekast/factory 0.1.0

package/dist/commands/update.js

@@ -0,0 +1,344 @@
+/**
+ * `factory update` — refresh the brain (`.claude/` + tracked scripts) of a
+ * derived project without clobbering local work (design §6.3, §7.0–§7.6).
+ *
+ * Flow:
+ *   1. Preflight (gh) — reused from DIST-003, never reimplemented.
+ *   2. Read the lockfile → the STICKY profile (`core` | `full`). Download the
+ *      tarball of the SAME profile (never cross-grade). A `core` repo therefore
+ *      never receives `sk-*` (not in the core manifest); a new `kb-*` in the
+ *      core manifest does land.
+ *   3. Stage + validate the embedded manifest (the swap preflight rejects a
+ *      corrupt/empty manifest before touching the FS).
+ *   4. Diff the new manifest against the lockfile → the 4 buckets + conflicts.
+ *   5. Resolve conflicts: `--theirs-all` / `--mine-all`, else prompt PER FILE
+ *      with NO default option (design §7.3) — the file is not modified until the
+ *      dev chooses.
+ *   6. Apply atomically (backup + rollback guard, design §7.5).
+ *   7. Write the lockfile (= the new manifest) ONLY after a clean apply.
+ *   8. Surgically ensure `factory:update` is in package.json (design §7.4).
+ *
+ * Auto-register (no lockfile, pre-CLI repo, design §6.3): path-match — repo
+ * paths matching the manifest are kit-owned (overwrite); `.claude/` paths absent
+ * from the manifest are logged "ambiguous" and NOT deleted on the first sync.
+ * The dev is warned before proceeding.
+ *
+ * `--verify`: compares disk vs lockfile and reports drift WITHOUT modifying
+ * anything. `--resume`: re-applies a persisted mid-flight state without
+ * re-downloading.
+ *
+ * `update` NEVER touches `src/` — files outside the lockfile/manifest are
+ * invisible (design §9 out-of-scope).
+ */
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import prompts from 'prompts';
+import { applyPlan, clearUpdateState, defaultBackupDir, hasUpdateState, readUpdateState, validateStagedManifest, writeUpdateState, } from '../lib/atomic-swap.js';
+import { CLIError } from '../lib/cli-error.js';
+import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
+import { insertFactoryUpdateScript } from '../lib/package-json.js';
+import { runPreflight } from '../lib/preflight.js';
+import { downloadProfileTarball, stageProfileTarball } from '../lib/unpack.js';
+/** Parse `update`'s argv slice into flags. Unknown flags are ignored here. */
+export function parseUpdateFlags(argv) {
+    return {
+        theirsAll: argv.includes('--theirs-all'),
+        mineAll: argv.includes('--mine-all'),
+        resume: argv.includes('--resume'),
+        verify: argv.includes('--verify'),
+    };
+}
+/** Default acquire: download the sticky-profile tarball, stage + validate it. */
+async function acquireFromRelease(profile) {
+    const tmpRoot = mkdtempSync(path.join(tmpdir(), 'tk-update-'));
+    const tarball = await downloadProfileTarball(profile, tmpRoot);
+    const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpRoot);
+    const manifest = validateStagedManifest(stagedDir, manifestRaw);
+    return { stagedDir, manifest, tmpRoot };
+}
+/**
+ * Recursively collect repo-relative paths of files under `.claude/` plus any
+ * tracked root files the manifest references at the top level. Used both for
+ * disk hashing and auto-register path-match. Only descends into `.claude/`;
+ * `src/` and everything else is invisible (design §7.2).
+ */
+function collectClaudePaths(rootDir) {
+    const out = [];
+    const walk = (rel) => {
+        const abs = path.join(rootDir, rel);
+        if (!existsSync(abs))
+            return;
+        if (statSync(abs).isDirectory()) {
+            for (const entry of readdirSync(abs)) {
+                walk(path.posix.join(rel, entry));
+            }
+        }
+        else {
+            out.push(rel);
+        }
+    };
+    walk('.claude');
+    return out;
+}
+/**
+ * Hash the disk content (normalized) of every path in `paths` that exists.
+ * A missing file is simply absent from the returned map.
+ */
+function hashDiskPaths(rootDir, paths) {
+    const map = new Map();
+    for (const rel of paths) {
+        const abs = path.join(rootDir, rel);
+        if (existsSync(abs) && statSync(abs).isFile()) {
+            map.set(rel, normalizeThenHash(readFileSync(abs, 'utf8')));
+        }
+    }
+    return map;
+}
+/** Resolve a single conflict via prompt — NO default option (design §7.3). */
+async function resolveConflict(conflict, stagedDir, rootDir) {
+    for (;;) {
+        console.log(`\n⚠ ${conflict.path}: lo modificaste local y el Factory también cambió.\n` +
+            '   [1] Mantener el mío   [2] Tomar el del Factory   [3] Ver diff');
+        const { choice } = await prompts({
+            type: 'select',
+            name: 'choice',
+            message: 'Elige cómo resolver este conflicto',
+            // No `initial` → no option is highlighted by default (design §7.3).
+            choices: [
+                { title: '[1] Mantener el mío', value: 'mine' },
+                { title: '[2] Tomar el del Factory', value: 'theirs' },
+                { title: '[3] Ver diff', value: 'diff' },
+            ],
+        });
+        if (choice === undefined) {
+            throw new CLIError('Operación cancelada; no se modificó ningún archivo.', 130);
+        }
+        if (choice === 'diff') {
+            const local = readFileSync(path.join(rootDir, conflict.path), 'utf8');
+            const incoming = readFileSync(path.join(stagedDir, conflict.path), 'utf8');
+            console.log(`\n--- local (${conflict.path}) ---\n${local}\n--- Factory ---\n${incoming}\n`);
+            continue;
+        }
+        return choice;
+    }
+}
+/**
+ * Build the apply plan from a diff + the resolved conflicts. `writes` = adds +
+ * silent overwrites + conflicts resolved "theirs"; `deletes` = silent deletes.
+ * Conflicts resolved "mine" are simply omitted (the local file stays).
+ */
+function buildPlan(diff, theirsConflicts) {
+    const writes = [
+        ...diff.add.map((e) => e.path),
+        ...diff.overwriteSilent.map((e) => e.path),
+        ...theirsConflicts,
+    ];
+    const deletes = diff.deleteSilent.map((e) => e.path);
+    return { writes, deletes };
+}
+/** `--verify`: report disk-vs-lockfile drift, modify nothing. */
+function runVerify(rootDir) {
+    if (!hasLockfile(rootDir)) {
+        throw new CLIError('No hay lockfile que verificar. Corre `factory update` primero.');
+    }
+    const lock = readLockfile(rootDir);
+    const disk = hashDiskPaths(rootDir, lock.files.map((f) => f.path));
+    const missing = [];
+    const drifted = [];
+    for (const entry of lock.files) {
+        const localHash = disk.get(entry.path);
+        if (localHash === undefined) {
+            missing.push(entry.path);
+        }
+        else if (localHash !== entry.hash) {
+            drifted.push(entry.path);
+        }
+    }
+    if (missing.length === 0 && drifted.length === 0) {
+        console.log('✔ El estado del disco coincide con el lockfile. Sin discrepancias.');
+        return;
+    }
+    console.log('Discrepancias respecto al lockfile (no se modificó nada):');
+    for (const p of missing)
+        console.log(`  • faltante en disco: ${p}`);
+    for (const p of drifted)
+        console.log(`  • modificado localmente: ${p}`);
+}
+/**
+ * `--resume`: re-apply a persisted mid-flight state without re-downloading
+ * (design §7.5). Reads the staged dir + plan from `.timekast/.update-state.json`.
+ */
+function runResume(rootDir) {
+    const state = readUpdateState(rootDir);
+    if (!existsSync(state.stagedDir)) {
+        throw new CLIError('El directorio temporal del update anterior ya no existe; vuelve a correr `factory update` sin `--resume`.');
+    }
+    // The lockfile on disk is still the PRE-update one (it is rewritten only after a
+    // clean apply), so it carries the birth stamp to preserve. A legacy resume (no
+    // prior lockfile) seals the birth at the persisted manifest's version.
+    const priorLock = hasLockfile(rootDir) ? readLockfile(rootDir) : undefined;
+    const newLock = priorLock
+        ? { ...state.newManifest, factoryVersion: priorLock.factoryVersion ?? priorLock.version }
+        : { ...state.newManifest, factoryVersion: state.newManifest.version };
+    applyPlan(rootDir, state.stagedDir, state.plan, state.backupDir);
+    writeLockfile(rootDir, newLock);
+    clearUpdateState(rootDir);
+    const pkgPath = path.join(rootDir, 'package.json');
+    if (existsSync(pkgPath))
+        warnOnScriptConflict(insertFactoryUpdateScript(pkgPath).action, pkgPath);
+    rmSync(state.stagedDir, { recursive: true, force: true });
+    console.log('✔ `update` retomado y completado.');
+}
+/**
+ * Stamp the birth seal onto the new manifest before it becomes the lockfile.
+ * `factoryVersion` is FROZEN at install: preserve the old lockfile's value, and
+ * fall back to its top-level `version` for repos that predate this field. The
+ * top-level `version` of the returned lockfile stays the new manifest's version
+ * (agentKitVersion advances on every update).
+ */
+function stampBirth(oldLock, newManifest) {
+    return { ...newManifest, factoryVersion: oldLock.factoryVersion ?? oldLock.version };
+}
+/** Warn (never fail) when package.json holds a divergent factory:update value. */
+function warnOnScriptConflict(action, _pkgPath) {
+    if (action === 'conflict') {
+        console.warn('Aviso: `factory:update` ya existe en package.json con otro valor; no se sobrescribió.');
+    }
+}
+/** Print the deletes (design §7.6 — visible, not silent) + a one-line summary. */
+function reportSummary(diff) {
+    if (diff.deleteSilent.length > 0) {
+        console.log('\nArchivos retirados por el Factory en esta versión:');
+        for (const e of diff.deleteSilent)
+            console.log(`  Archivos retirados: ${e.path}`);
+    }
+    console.log(`\n✔ update: ${diff.add.length} agregados, ${diff.overwriteSilent.length} actualizados, ` +
+        `${diff.deleteSilent.length} retirados, ${diff.conflicts.length} conflictos.`);
+}
+/**
+ * Run `factory update`. Orchestrates the full flow; `deps.acquire` is the only
+ * network seam (tests inject a local fixture).
+ */
+export async function runUpdate(flags, deps = {}) {
+    const rootDir = process.cwd();
+    // --verify and --resume short-circuit (no download).
+    if (flags.verify) {
+        runVerify(rootDir);
+        return;
+    }
+    if (flags.resume) {
+        if (!hasUpdateState(rootDir)) {
+            throw new CLIError('No hay un `update` pendiente para retomar.');
+        }
+        runResume(rootDir);
+        return;
+    }
+    if (flags.theirsAll && flags.mineAll) {
+        throw new CLIError('No puedes combinar `--theirs-all` con `--mine-all`.');
+    }
+    // Preflight (gh) before any download — reused, not reimplemented.
+    await runPreflight();
+    const legacy = !hasLockfile(rootDir);
+    // Sticky profile: a lockfile pins the installed profile; a legacy repo with no
+    // lockfile defaults to `core` (the additive baseline a pre-CLI repo carries).
+    let oldLock;
+    let profile;
+    if (legacy) {
+        profile = 'core';
+        oldLock = { version: '0.0.0', profile, files: [] };
+        await confirmLegacy();
+    }
+    else {
+        oldLock = readLockfile(rootDir);
+        profile = oldLock.profile;
+    }
+    const acquire = deps.acquire ?? acquireFromRelease;
+    const { stagedDir, manifest, tmpRoot } = await acquire(profile);
+    try {
+        if (legacy) {
+            await applyLegacy(rootDir, stagedDir, manifest);
+            return;
+        }
+        // Hash only the union of tracked paths (old lock ∪ new manifest). Files
+        // outside both are never read (design §7.2 "ni lo mira").
+        const trackedPaths = new Set([
+            ...oldLock.files.map((f) => f.path),
+            ...manifest.files.map((f) => f.path),
+        ]);
+        const disk = hashDiskPaths(rootDir, trackedPaths);
+        const diff = diffLockfiles(oldLock, manifest, disk);
+        // Resolve conflicts.
+        const theirsConflicts = [];
+        for (const conflict of diff.conflicts) {
+            let decision;
+            if (flags.theirsAll)
+                decision = 'theirs';
+            else if (flags.mineAll)
+                decision = 'mine';
+            else
+                decision = await resolveConflict(conflict, stagedDir, rootDir);
+            if (decision === 'theirs')
+                theirsConflicts.push(conflict.path);
+        }
+        const plan = buildPlan(diff, theirsConflicts);
+        const backupDir = defaultBackupDir(tmpRoot);
+        // Persist resume state BEFORE applying, so a crash mid-apply is recoverable
+        // without re-downloading (design §7.5).
+        writeUpdateState(rootDir, { stagedDir, backupDir, plan, newManifest: manifest });
+        applyPlan(rootDir, stagedDir, plan, backupDir);
+        // Lockfile written ONLY after a clean apply. The birth stamp is preserved
+        // (agentKitVersion advances; factoryVersion stays frozen).
+        writeLockfile(rootDir, stampBirth(oldLock, manifest));
+        clearUpdateState(rootDir);
+        const pkgPath = path.join(rootDir, 'package.json');
+        if (existsSync(pkgPath))
+            warnOnScriptConflict(insertFactoryUpdateScript(pkgPath).action, pkgPath);
+        reportSummary(diff);
+    }
+    finally {
+        rmSync(tmpRoot, { recursive: true, force: true });
+    }
+}
+/** Warn the dev before a legacy auto-register sync (design §8 edge case). */
+async function confirmLegacy() {
+    const { proceed } = await prompts({
+        type: 'confirm',
+        name: 'proceed',
+        message: 'Este repo no tiene lockfile. Se hará un auto-registro por paths. Los archivos del cerebro ' +
+            'que coincidan se sobrescribirán con la última versión. ¿Continuar?',
+        initial: false,
+    });
+    if (!proceed) {
+        throw new CLIError('Operación cancelada.', 130);
+    }
+}
+/**
+ * Legacy auto-register (no lockfile): path-match against the fresh manifest.
+ * Kit-owned + new files are written; ambiguous `.claude/` paths are logged and
+ * NOT deleted on the first sync (design §6.3). Builds the lockfile from the
+ * normalized hashes of the installed files.
+ */
+async function applyLegacy(rootDir, stagedDir, manifest) {
+    const repoPaths = new Set(collectClaudePaths(rootDir));
+    const plan = planAutoRegister(manifest, repoPaths);
+    // Everything in the manifest is written (kit-owned overwrite + adds). No
+    // deletes on the first sync.
+    const writes = manifest.files.map((f) => f.path);
+    const backupDir = defaultBackupDir(path.dirname(stagedDir));
+    applyPlan(rootDir, stagedDir, { writes, deletes: [] }, backupDir);
+    // The lockfile = the manifest (its hashes are already the normalized hashes of
+    // the just-installed files) PLUS the birth stamp. A legacy auto-register is the
+    // first sync this repo records, so the birth seal = the manifest's version.
+    writeLockfile(rootDir, { ...manifest, factoryVersion: manifest.version });
+    const pkgPath = path.join(rootDir, 'package.json');
+    if (existsSync(pkgPath))
+        warnOnScriptConflict(insertFactoryUpdateScript(pkgPath).action, pkgPath);
+    if (plan.ambiguous.length > 0) {
+        console.log('\nArchivos en `.claude/` que no están en el manifest (revisar manualmente):');
+        for (const p of plan.ambiguous)
+            console.log(`  • ambiguo — revisar manualmente: ${p}`);
+    }
+    console.log(`\n✔ Auto-registro completo: ${plan.kitOwned.length} kit-owned, ${plan.toAdd.length} agregados, ` +
+        `${plan.ambiguous.length} ambiguos.`);
+}

package/dist/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * `@timekast/factory` — public, thin CLI entrypoint.
+ *
+ * Dispatches subcommands. All five commands are wired: `new` / `add` / `update`
+ * / `status` / `doctor` (DIST-003..006). The bin is deliberately thin — it
+ * imports nothing from the kit's `src/` or `.claude/`.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CLIError } from './lib/cli-error.js';
+import { runAdd } from './commands/add.js';
+import { runDoctor } from './commands/doctor.js';
+import { runNew } from './commands/new.js';
+import { runStatus } from './commands/status.js';
+import { parseUpdateFlags, runUpdate } from './commands/update.js';
+const HELP = `
+@timekast/factory — bootstrap y mantenimiento de proyectos derivados del Factory.
+
+Uso:
+  factory <comando> [opciones]
+
+Comandos:
+  new <Nombre>     Crea un proyecto derivado nuevo (repo + perfil + git init)
+  add              Instala el cerebro \`core\` (.claude/) en el repo actual
+  update           Actualiza el cerebro al día sin pisar tu trabajo local
+  status           Reporta la versión instalada vs. la última disponible
+  doctor           Detecta huérfanos y conflictos pendientes + aviso de seguridad
+
+Sobre \`add\`:
+  Requiere estar dentro de un repo git (al menos \`git init\`). Nunca toca tu
+  \`src/\`, tu \`package.json\` ni tus archivos propios (\`pj-*\`): solo escribe los
+  archivos del perfil \`core\`. Si un archivo del \`core\` ya existe, lo sobrescribe
+  sin preguntar (el manejo de conflictos es exclusivo de \`update\`).
+
+Sobre \`update\`:
+  Lee el perfil instalado del lockfile y baja el tarball del MISMO perfil (nunca
+  cross-grada). Compara contra el lockfile y aplica solo cambios de \`.claude/\`:
+  agrega lo nuevo, sobrescribe lo del kit sin cambios locales, retira lo que el
+  Factory borró, y pregunta (sin opción default) ante un conflicto. Nunca toca
+  \`src/\` ni tus archivos propios. Flags:
+    --theirs-all   Resuelve todos los conflictos con la versión del Factory
+    --mine-all     Conserva tu versión en todos los conflictos
+    --resume       Retoma un update interrumpido sin re-descargar
+    --verify       Reporta diferencias disco-vs-lockfile sin modificar nada
+
+Sobre \`status\` y \`doctor\`:
+  Solo diagnostican — nunca modifican archivos. \`status\` lee el lockfile y
+  consulta la última versión publicada (ignorando prereleases); sin lockfile o
+  sin conexión, avisa y termina con éxito. \`doctor\` lista huérfanos y conflictos
+  pendientes y siempre imprime el aviso de seguridad de \`src/\`.
+
+Opciones:
+  -h, --help       Muestra esta ayuda
+  -v, --version    Muestra la versión del CLI
+`.trim();
+/** Read this package's version from its own package.json. */
+function readVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // dist/index.js → ../package.json
+        const pkgPath = join(here, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === '-h' || command === '--help' || command === 'help') {
+        console.log(HELP);
+        return;
+    }
+    if (command === '-v' || command === '--version' || command === 'version') {
+        console.log(readVersion());
+        return;
+    }
+    switch (command) {
+        case 'new': {
+            const name = rest.find((arg) => !arg.startsWith('-'));
+            if (!name) {
+                throw new CLIError('Falta el nombre del proyecto. Uso: `factory new <Nombre>`.');
+            }
+            await runNew(name);
+            return;
+        }
+        case 'add': {
+            await runAdd();
+            return;
+        }
+        case 'update': {
+            await runUpdate(parseUpdateFlags(rest));
+            return;
+        }
+        case 'status': {
+            await runStatus();
+            return;
+        }
+        case 'doctor': {
+            runDoctor();
+            return;
+        }
+        default:
+            throw new CLIError(`Comando desconocido: \`${command}\`.\nEjecuta \`factory --help\` para ver los comandos disponibles.`);
+    }
+}
+main(process.argv.slice(2)).then(() => {
+    process.exit(0);
+}, (error) => {
+    if (error instanceof CLIError) {
+        console.error(`\n✖ ${error.message}`);
+        process.exit(error.exitCode);
+    }
+    // Unexpected error — surface it (this path is a bug, not a user error).
+    console.error('\n✖ Error inesperado:');
+    console.error(error);
+    process.exit(1);
+});

package/dist/lib/atomic-swap.js

@@ -0,0 +1,160 @@
+/**
+ * Atomic apply engine for `update` (design §7.5).
+ *
+ * `update` never writes the destination file-by-file from the network. Instead:
+ *   1. The tarball is extracted + validated in a temp dir (unpack.ts).
+ *   2. The diff is computed and conflicts resolved (lockfile.ts + update.ts).
+ *   3. THIS module applies the resolved plan atomically: it backs up every file
+ *      it is about to overwrite or delete into a backup dir, then performs the
+ *      writes/deletes. If anything throws mid-apply, `rollback()` restores the
+ *      pre-update state from the backup so `.claude/` is never left partial.
+ *   4. The lockfile is written ONLY after the apply fully succeeds (the caller
+ *      does this, so a crash before it leaves the OLD lockfile intact).
+ *
+ * State for `--resume`: a `.timekast/.update-state.json` records the staged dir,
+ * the resolved plan, and the backup dir. If the process dies between steps,
+ * `--resume` reads it and re-applies WITHOUT re-downloading. After a clean
+ * apply + lockfile write the state file is removed.
+ *
+ * The applied set is always a subset of the lockfile/manifest (kit-managed
+ * paths). `src/` and dev-owned files are never in the plan, so they are never
+ * read, written, or deleted here (design §7.2, §9 out-of-scope).
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from './cli-error.js';
+import { TIMEKAST_DIR } from './constants.js';
+import { parseLockfile } from './lockfile.js';
+/** Name of the resume-state sidecar inside `.timekast/`. */
+export const UPDATE_STATE_FILE = '.update-state.json';
+/** Absolute path to the resume-state sidecar inside a project root. */
+export function updateStatePath(rootDir) {
+    return path.join(rootDir, TIMEKAST_DIR, UPDATE_STATE_FILE);
+}
+/** True when a resumable update state exists. */
+export function hasUpdateState(rootDir) {
+    return existsSync(updateStatePath(rootDir));
+}
+/** Read + validate the resume state. */
+export function readUpdateState(rootDir) {
+    const file = updateStatePath(rootDir);
+    if (!existsSync(file)) {
+        throw new CLIError('No hay un estado de `update` pendiente para retomar (`--resume`).');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new CLIError('El estado de `update` (`.timekast/.update-state.json`) está corrupto.');
+    }
+    const obj = parsed;
+    if (!obj ||
+        typeof obj.stagedDir !== 'string' ||
+        typeof obj.backupDir !== 'string' ||
+        !obj.plan ||
+        !Array.isArray(obj.plan.writes) ||
+        !Array.isArray(obj.plan.deletes) ||
+        !obj.newManifest) {
+        throw new CLIError('El estado de `update` está incompleto; no se puede retomar de forma segura.');
+    }
+    return obj;
+}
+/** Persist the resume state. */
+export function writeUpdateState(rootDir, state) {
+    mkdirSync(path.join(rootDir, TIMEKAST_DIR), { recursive: true });
+    writeFileSync(updateStatePath(rootDir), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+/** Remove the resume state (after a clean apply + lockfile write). */
+export function clearUpdateState(rootDir) {
+    rmSync(updateStatePath(rootDir), { force: true });
+}
+/**
+ * Validate the embedded manifest of a staged tarball (swap preflight, §7.5).
+ * Rejects a corrupt/empty manifest (missing `version`/`files`) before anything
+ * is touched, and verifies every file the manifest declares actually exists in
+ * the staged dir (an incomplete tarball must never reach the destination).
+ *
+ * @throws {CLIError} on any structural or completeness failure.
+ */
+export function validateStagedManifest(stagedDir, manifestRaw) {
+    const manifest = parseLockfile(manifestRaw, 'manifest embebido');
+    for (const entry of manifest.files) {
+        if (!existsSync(path.join(stagedDir, entry.path))) {
+            throw new CLIError(`El tarball está incompleto: falta \`${entry.path}\` declarado en el manifest. ` +
+                'No se tocó ningún archivo.');
+        }
+    }
+    return manifest;
+}
+/**
+ * Apply the plan atomically with a backup-and-rollback guard.
+ *
+ * For every write target and delete target that currently exists, a copy is
+ * saved into `backupDir` (preserving the relative path) BEFORE any mutation.
+ * Then writes (copy from staged) and deletes are performed. If any step throws,
+ * the partial changes are rolled back from the backup and the original error is
+ * rethrown — the destination ends in its exact pre-update state.
+ *
+ * Does NOT write the lockfile (the caller does that only after this returns
+ * cleanly) and does NOT remove the staged dir (kept for `--resume`).
+ *
+ * @param rootDir   Destination project root.
+ * @param stagedDir Validated staged tarball contents.
+ * @param plan      Resolved writes + deletes (tarball-relative paths).
+ * @param backupDir Directory to stash pre-update copies (created if missing).
+ * @param hooks     Test seam: optional callbacks fired between phases to inject
+ *                  a mid-flight failure (rollback test).
+ */
+export function applyPlan(rootDir, stagedDir, plan, backupDir, hooks) {
+    mkdirSync(backupDir, { recursive: true });
+    // 1. Back up everything we will touch (overwrite or delete), if it exists.
+    const touched = [...plan.writes, ...plan.deletes];
+    for (const rel of touched) {
+        const abs = path.join(rootDir, rel);
+        if (existsSync(abs)) {
+            const dest = path.join(backupDir, rel);
+            mkdirSync(path.dirname(dest), { recursive: true });
+            cpSync(abs, dest, { recursive: true });
+        }
+    }
+    // Record which touched paths existed pre-update (so rollback can re-delete
+    // files that were freshly added and must vanish on rollback).
+    const preExisting = new Set(touched.filter((rel) => existsSync(path.join(rootDir, rel))));
+    const rollback = () => {
+        // Restore backed-up files, and delete any file we created that did not
+        // exist before (a freshly-added file must not survive a rollback).
+        for (const rel of touched) {
+            const abs = path.join(rootDir, rel);
+            const backup = path.join(backupDir, rel);
+            if (existsSync(backup)) {
+                mkdirSync(path.dirname(abs), { recursive: true });
+                cpSync(backup, abs, { recursive: true });
+            }
+            else if (!preExisting.has(rel)) {
+                rmSync(abs, { force: true, recursive: true });
+            }
+        }
+    };
+    try {
+        hooks?.beforeWrites?.();
+        for (const rel of plan.writes) {
+            const src = path.join(stagedDir, rel);
+            const dst = path.join(rootDir, rel);
+            mkdirSync(path.dirname(dst), { recursive: true });
+            cpSync(src, dst, { recursive: true });
+        }
+        hooks?.afterWrites?.();
+        for (const rel of plan.deletes) {
+            rmSync(path.join(rootDir, rel), { force: true, recursive: true });
+        }
+    }
+    catch (error) {
+        rollback();
+        throw error;
+    }
+}
+/** Build the backup dir path under a staged temp root (kept off the dest tree). */
+export function defaultBackupDir(stagedRoot) {
+    return path.join(stagedRoot, 'backup');
+}

package/dist/lib/cli-error.js

@@ -0,0 +1,24 @@
+/**
+ * Typed errors for the CLI. Expected, user-facing failures throw `CLIError`
+ * (or a subclass) so the top-level handler can print a clean, actionable
+ * message and exit with the right code — never a raw stack trace.
+ */
+/** An expected, user-facing CLI failure. Carries an exit code. */
+export class CLIError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'CLIError';
+        this.exitCode = exitCode;
+        // Restore prototype chain for instanceof across transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** A preflight check failed (gh missing / not authed / not an org member). */
+export class PreflightError extends CLIError {
+    constructor(message, exitCode = 1) {
+        super(message, exitCode);
+        this.name = 'PreflightError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/lib/constants.js

@@ -0,0 +1,24 @@
+/**
+ * CLI-wide constants. v1 has no `--org` flag — the destination org is always
+ * `TimeKast` (design §6.1). Centralized here so it is a named constant, never
+ * an inline literal.
+ */
+/** Destination GitHub org for all derived projects (v1, no `--org` override). */
+export const FACTORY_ORG = 'TimeKast';
+/** The Factory monorepo, source of the distribution releases. */
+export const FACTORY_REPO = 'TimeKast/TimeKast-Factory';
+/** Distribution profiles selectable in `new`. */
+export const PROFILES = {
+    full: 'full',
+    core: 'core',
+};
+/** Relative path (inside a derived project) to the embedded manifest / lockfile. */
+export const TIMEKAST_DIR = '.timekast';
+export const MANIFEST_FILE = 'manifest.json';
+export const LOCKFILE_FILE = 'lockfile.json';
+/** The script the CLI injects into a derived project's package.json. */
+export const UPDATE_SCRIPT_NAME = 'factory:update';
+// `npx` so the script resolves in a fresh derived repo where @timekast/factory
+// is NOT a dependency (B3): a bare `@timekast/factory update` would be
+// "command not found". npx resolves the published package on demand.
+export const UPDATE_SCRIPT_CMD = 'npx @timekast/factory update';