@timekast/factory 0.1.0

package/dist/commands/add.js

@@ -0,0 +1,78 @@
+/**
+ * `factory add` — install the `core` brain into an existing repo (design §6.2).
+ *
+ * Flow: detect a git repo (cwd or ancestor) → refuse with an actionable message
+ * if none → preflight (gh) → download the `core` profile (literal, never `full`)
+ * → extract to temp + validate the embedded manifest → move the staged contents
+ * into the cwd (only the manifest's files) → write `.timekast/lockfile.json`.
+ *
+ * Invariants:
+ *   - `add` ONLY ever installs `core`. The profile is the literal `PROFILES.core`,
+ *     never a flag — `full` is structurally unreachable from this command.
+ *   - `add` never touches `src/`, `package.json`, `pj-*`, or any file outside the
+ *     `core` manifest. The `core` tarball contains only `core` files, so moving
+ *     its contents in cannot reach dev-owned paths; files in the cwd that are not
+ *     in the tarball are left byte-identical.
+ *   - `add` overwrites manifest files without prompting — the conflict prompt is
+ *     exclusive to `update` (DIST-005). Documented in the command's `--help`.
+ *   - Atomicity (§7.5): extract + validate in a temp dir before touching the cwd;
+ *     a failure mid-flight never leaves a partial `.claude/`.
+ *
+ * Expected failures throw `CLIError`; the top-level handler prints + exits.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { CLIError } from '../lib/cli-error.js';
+import { PROFILES } from '../lib/constants.js';
+import { writeInitialLockfile } from '../lib/lockfile.js';
+import { runPreflight } from '../lib/preflight.js';
+import { detectRepo } from '../lib/repo-detection.js';
+import { downloadProfileTarball, moveContentsInto, stageProfileTarball } from '../lib/unpack.js';
+/** Message shown when `add` runs outside any git repo context. */
+const NO_REPO_MESSAGE = 'No hay repositorio git aquí. Ejecuta `git init` primero, o usa `factory new` para crear un proyecto desde cero.';
+export async function runAdd() {
+    const cwd = process.cwd();
+    // 1. Require a git repo context (cwd or any ancestor). Refuse before any
+    //    network call or write — nothing is touched when there is no repo.
+    const { hasRepo } = detectRepo(cwd);
+    if (!hasRepo) {
+        throw new CLIError(NO_REPO_MESSAGE);
+    }
+    // 2. Preflight: gh installed + authed + org member. Runs before any download.
+    await runPreflight();
+    // 3. Download + unpack into a temp dir, validate, then move into place (§7.5).
+    const tmpDir = mkdtempSync(path.join(tmpdir(), 'tk-add-'));
+    const cleanup = () => {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    const onSignal = () => {
+        cleanup();
+        process.exit(130);
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        // `add` is structurally `core`-only: the literal is passed, never a flag.
+        const tarball = await downloadProfileTarball(PROFILES.core, tmpDir);
+        // Extract + validate the embedded manifest before touching the destination.
+        const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpDir);
+        // Move only the tarball's (core) contents into the cwd. Files outside the
+        // manifest — src/, package.json, pj-* — are never visited, so they stay
+        // byte-identical.
+        moveContentsInto(stagedDir, cwd);
+        // Write the lockfile = the tarball's embedded manifest (no hash recompute).
+        writeInitialLockfile(cwd, manifestRaw);
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        cleanup();
+    }
+    console.log('\n✔ Cerebro `core` instalado. Lockfile escrito en `.timekast/lockfile.json`.');
+}

package/dist/commands/doctor.js

@@ -0,0 +1,127 @@
+/**
+ * `factory doctor` — diagnose the derived project's brain (design §6.4):
+ *
+ *   - ORPHANS: files under `.claude/` of the derived repo that are NOT in the
+ *     installed manifest (the lockfile). Either dev-owned (`pj-*`) or kit files
+ *     retired since birth — surfaced so the dev can decide; never auto-deleted.
+ *   - PENDING CONFLICTS: tracked files whose on-disk hash differs from the hash
+ *     recorded in the lockfile (`normalizeThenHash` reused from lockfile.ts, the
+ *     SAME normalization the builder + update engine use — no divergence). These
+ *     are local modifications not yet reconciled via `update`.
+ *   - A1 WARNING: a literal security notice (design §1 + §11, decision A1) that
+ *     `src/` + boilerplate deps are the derived project's responsibility
+ *     post-bootstrap, and that the patch channel for `src/` is EPIC 2 (agentic
+ *     update, not yet available).
+ *
+ * No lockfile (pre-CLI repo) → delegate to the "run factory:update" advice, exit
+ * 0, never abort (same pattern as `status` / the §8 edge case).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
+/**
+ * The A1 security notice (design §1 + §11, decision A1). Literal text emitted at
+ * the end of every `doctor` run so the dev always sees the `src/` responsibility
+ * boundary. Exported so tests can assert the rendered output contains it.
+ */
+export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus dependencias (Next.js, ' +
+    'NextAuth, Drizzle, etc.) quedan congelados en el momento del bootstrap y son ' +
+    'responsabilidad del proyecto derivado a partir de ahí. `factory:update` NO ' +
+    'actualiza `src/` ni las dependencias: solo refresca el cerebro (`.claude/`). ' +
+    'Un parche de seguridad para `src/` (un CVE en auth, middleware, headers o una ' +
+    'dependencia) NO llega por este canal. El canal de parches de `src/` es EPIC 2 ' +
+    '(update agentico con merge inteligente), aún no disponible. Mantén `src/` y tus ' +
+    'dependencias al día por tu cuenta mientras tanto.';
+/**
+ * Recursively collect repo-relative POSIX paths of files under `.claude/`. Only
+ * descends into `.claude/`; `src/` and everything else is invisible (design
+ * §7.2). Mirrors the `update` engine's `collectClaudePaths`.
+ */
+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;
+}
+/**
+ * Compute the doctor diagnosis. No lockfile → `noLockfile: true` (the caller
+ * renders the "run factory:update" advice). Otherwise diffs the on-disk
+ * `.claude/` tree against the lockfile:
+ *   - orphan  = `.claude/` path on disk, not in the manifest.
+ *   - conflict = tracked path whose normalized disk hash != recorded hash.
+ */
+export function computeDoctor(deps = {}) {
+    const rootDir = deps.rootDir ?? process.cwd();
+    if (!hasLockfile(rootDir)) {
+        return { orphans: [], conflicts: [], a1Warning: A1_WARNING, noLockfile: true };
+    }
+    const lock = readLockfile(rootDir);
+    const manifestPaths = new Set(lock.files.map((f) => f.path));
+    // Orphans: files under `.claude/` on disk that the manifest does not track.
+    const claudePaths = collectClaudePaths(rootDir);
+    const orphans = claudePaths.filter((p) => !manifestPaths.has(p)).sort();
+    // Pending conflicts: tracked file whose normalized on-disk hash drifted from
+    // the recorded hash (a local modification not yet resolved by `update`).
+    const conflicts = [];
+    for (const entry of lock.files) {
+        const abs = path.join(rootDir, entry.path);
+        if (!existsSync(abs) || !statSync(abs).isFile())
+            continue;
+        const localHash = normalizeThenHash(readFileSync(abs, 'utf8'));
+        if (localHash !== entry.hash) {
+            conflicts.push(entry.path);
+        }
+    }
+    conflicts.sort();
+    return { orphans, conflicts, a1Warning: A1_WARNING, noLockfile: false };
+}
+/** Render the doctor result to the console. The A1 notice is ALWAYS last. */
+function renderDoctor(result) {
+    if (result.noLockfile) {
+        console.log('Sin lockfile detectado.');
+        console.log('Ejecuta `factory:update` para inicializar el tracking de versión.');
+        // The A1 notice is emitted even without a lockfile (always present).
+        console.log(`\n${result.a1Warning}`);
+        return;
+    }
+    if (result.orphans.length === 0 && result.conflicts.length === 0) {
+        console.log('✔ Sin huérfanos ni conflictos pendientes.');
+    }
+    else {
+        if (result.conflicts.length > 0) {
+            console.log('Conflictos pendientes (modificado local + Factory actualizó):');
+            for (const p of result.conflicts) {
+                console.log(`  • ${p} — conflicto pendiente (modificado local + Factory actualizó)`);
+            }
+            console.log('  Sugerencia: corre `factory:update --verify` para re-chequear, o `factory:update` para reconciliar.');
+        }
+        if (result.orphans.length > 0) {
+            console.log('\nArchivos huérfanos (en `.claude/` fuera del manifest instalado):');
+            for (const p of result.orphans) {
+                console.log(`  • ${p} — huérfano (local del dev o retirado por el Factory)`);
+            }
+        }
+    }
+    // The A1 security notice is always emitted at the end (design §1 + §11).
+    console.log(`\n${result.a1Warning}`);
+}
+/**
+ * Run `factory doctor`. Always exits 0 — a missing lockfile is advisory, not a
+ * failure (DIST-006 §8). The A1 notice is emitted on every run.
+ */
+export function runDoctor(deps = {}) {
+    const result = computeDoctor(deps);
+    renderDoctor(result);
+}

package/dist/commands/new.js

@@ -0,0 +1,128 @@
+/**
+ * `factory new <Name>` — bootstrap a brand-new derived project (design §6.1).
+ *
+ * Flow: validate name → preflight (gh) → refuse if a repo already exists →
+ * confirm if the cwd is non-empty → choose profile (full | core) → create the
+ * GitHub repo → download the profile tarball → unpack (no Factory `.git/`) →
+ * `git init` → rename `package.json.name` → write the initial lockfile →
+ * inject the `factory:update` script.
+ *
+ * Expected failures throw `CLIError`; the top-level handler prints the message
+ * and exits with the carried code.
+ */
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import prompts from 'prompts';
+import { CLIError } from '../lib/cli-error.js';
+import { FACTORY_ORG, PROFILES } from '../lib/constants.js';
+import { writeInitialLockfile } from '../lib/lockfile.js';
+import { applyPackageJsonEdits } from '../lib/package-json.js';
+import { runPreflight } from '../lib/preflight.js';
+import { downloadProfileTarball, moveContentsInto, stageProfileTarball } from '../lib/unpack.js';
+import { validateProjectName } from '../lib/validate-name.js';
+/** Prompt the user to pick a profile (numbered options, checkpoint style). */
+async function promptProfile() {
+    const { choice } = await prompts({
+        type: 'select',
+        name: 'choice',
+        message: '¿Qué quieres crear?',
+        choices: [
+            { title: 'App completa (boilerplate + cerebro)', value: PROFILES.full },
+            { title: 'Solo el cerebro', value: PROFILES.core },
+        ],
+        initial: 0,
+    });
+    if (choice === undefined) {
+        // User aborted the prompt (Ctrl+C / Esc).
+        throw new CLIError('Operación cancelada.', 130);
+    }
+    return choice;
+}
+/** Confirm continuing into a non-empty (but non-repo) directory. */
+async function confirmNonEmptyDir() {
+    const { proceed } = await prompts({
+        type: 'confirm',
+        name: 'proceed',
+        message: 'El directorio actual no está vacío. ¿Deseas continuar de todos modos?',
+        initial: false,
+    });
+    if (!proceed) {
+        throw new CLIError('Operación cancelada: el directorio no está vacío.', 130);
+    }
+}
+/** Create the destination GitHub repo, surfacing gh's error cleanly. */
+async function createRepo(name) {
+    try {
+        await execa('gh', ['repo', 'create', `${FACTORY_ORG}/${name}`, '--private']);
+    }
+    catch (error) {
+        const stderr = error?.stderr?.trim();
+        const detail = stderr ? `\n${stderr}` : '';
+        throw new CLIError(`No se pudo crear el repo \`${FACTORY_ORG}/${name}\` en GitHub.${detail}`);
+    }
+}
+export async function runNew(name) {
+    // 1. Validate offline, before any network call.
+    const validName = validateProjectName(name);
+    // 2. Refuse to run inside an existing repo (before any destructive action).
+    const cwd = process.cwd();
+    if (existsSync(path.join(cwd, '.git'))) {
+        throw new CLIError('ya hay un repo aquí, usa `add`');
+    }
+    // 3. Preflight: gh installed + authed + org member.
+    await runPreflight();
+    // 4. Non-empty (but non-repo) directory → confirm instead of aborting.
+    const cwdEntries = readdirSync(cwd);
+    if (cwdEntries.length > 0) {
+        await confirmNonEmptyDir();
+    }
+    // 5. Choose profile.
+    const profile = await promptProfile();
+    // 6. Network: create the repo.
+    await createRepo(validName);
+    // 7. Download + unpack into a temp dir, validate, then move into place (M2).
+    const tmpDir = mkdtempSync(path.join(tmpdir(), 'tk-new-'));
+    const cleanup = () => {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    };
+    const onSignal = () => {
+        cleanup();
+        process.exit(130);
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        const tarball = await downloadProfileTarball(profile, tmpDir);
+        // Extract + validate the embedded manifest before touching the destination.
+        const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpDir);
+        // Move contents into cwd (without the Factory's git lineage).
+        moveContentsInto(stagedDir, cwd);
+        // git init (own lineage).
+        await execa('git', ['init'], { cwd });
+        // Rename package.json.name + inject factory:update (surgical, §7.4).
+        const pkgPath = path.join(cwd, 'package.json');
+        if (existsSync(pkgPath)) {
+            const { content, scriptAlreadyPresent } = applyPackageJsonEdits(readFileSync(pkgPath, 'utf8'), validName);
+            writeFileSync(pkgPath, content, 'utf8');
+            if (scriptAlreadyPresent) {
+                console.warn('Aviso: `factory:update` ya existía en package.json con otro valor; no se sobrescribió.');
+            }
+        }
+        // Write the initial lockfile = the tarball's embedded manifest verbatim
+        // (no hash recompute — that's DIST-005).
+        writeInitialLockfile(cwd, manifestRaw);
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        cleanup();
+    }
+    console.log(`\n✔ Proyecto \`${validName}\` listo. Repo: ${FACTORY_ORG}/${validName}`);
+}

package/dist/commands/status.js

@@ -0,0 +1,148 @@
+/**
+ * `factory status` — report the installed brain version vs. the latest available
+ * (design §6.4). Reads `.timekast/lockfile.json` for the installed
+ * `agentKitVersion` + `factoryVersion` (birth stamp), and queries the Factory
+ * repo's releases for the latest NON-prerelease version.
+ *
+ * Failure modes are graceful by design (DIST-006 §8 edge cases):
+ *   - No lockfile (pre-CLI repo, born <10): print "run factory:update" + exit 0,
+ *     NOT a cryptic error.
+ *   - Network down / `gh` unavailable when querying the latest release: report the
+ *     installed version with "(versión remota no disponible — sin conexión)" +
+ *     exit 0, NOT an unhandled exception.
+ *
+ * The latest-version query IS the only network seam — tests inject
+ * `deps.fetchLatest` so the engine runs with no `gh` and no network.
+ */
+import { execa } from 'execa';
+import { FACTORY_REPO } from '../lib/constants.js';
+import { hasLockfile, readLockfile } from '../lib/lockfile.js';
+/**
+ * Query the Factory repo for the latest published release, IGNORING prereleases
+ * (`-rc`, `-test`, etc.) so a release candidate is never reported as latest.
+ *
+ * `gh release list --json` returns each release's `tagName` + `isPrerelease`.
+ * The first non-prerelease entry is the latest stable (gh lists newest-first).
+ * Any failure (gh missing, not authed, network down) resolves to null — the
+ * caller renders the offline path, never throws.
+ */
+async function fetchLatestRelease() {
+    try {
+        const { stdout } = await execa('gh', [
+            'release',
+            'list',
+            '--repo',
+            FACTORY_REPO,
+            '--json',
+            'tagName,isPrerelease',
+            '--limit',
+            '30',
+        ]);
+        const releases = JSON.parse(stdout);
+        const stable = releases.find((r) => !r.isPrerelease);
+        if (!stable)
+            return null;
+        return stripVersionPrefix(stable.tagName);
+    }
+    catch {
+        return null;
+    }
+}
+/** Strip a leading `v` from a tag (`v9.5.0` → `9.5.0`); leave the rest as-is. */
+function stripVersionPrefix(tag) {
+    return tag.startsWith('v') ? tag.slice(1) : tag;
+}
+/**
+ * Compare two semver-ish strings. Returns 1 when `a` > `b`, -1 when `a` < `b`,
+ * 0 when equal. Non-numeric / malformed segments compare as 0 so a parse
+ * surprise never flips `hasUpdate` to a false positive.
+ */
+function compareVersions(a, b) {
+    const pa = a.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da > db)
+            return 1;
+        if (da < db)
+            return -1;
+    }
+    return 0;
+}
+/**
+ * Compute the status result. Pure given its inputs — the only side effect is the
+ * lockfile read (FS), and `fetchLatest` (network). Both are graceful: a missing
+ * lockfile sets `noLockfile`, a null `latest` sets `networkError`.
+ */
+export async function computeStatus(deps = {}) {
+    const rootDir = deps.rootDir ?? process.cwd();
+    const fetchLatest = deps.fetchLatest ?? fetchLatestRelease;
+    if (!hasLockfile(rootDir)) {
+        return {
+            installed: null,
+            factoryVersion: null,
+            latest: null,
+            hasUpdate: false,
+            noLockfile: true,
+            networkError: false,
+        };
+    }
+    const lock = readLockfile(rootDir);
+    const installed = lock.version;
+    // The top-level `version` IS the agentKitVersion (the installed brain version);
+    // the top-level `factoryVersion` is the birth stamp. A legacy lockfile without
+    // a birth stamp degrades to null (it is reported as "unknown", never crashes).
+    const factoryVersion = lock.factoryVersion ?? null;
+    const latest = await fetchLatest();
+    if (latest === null) {
+        return {
+            installed,
+            factoryVersion,
+            latest: null,
+            hasUpdate: false,
+            noLockfile: false,
+            networkError: true,
+        };
+    }
+    return {
+        installed,
+        factoryVersion,
+        latest,
+        hasUpdate: compareVersions(latest, installed) > 0,
+        noLockfile: false,
+        networkError: false,
+    };
+}
+/** Render the status result to the console. */
+function renderStatus(result) {
+    if (result.noLockfile) {
+        console.log('Sin lockfile detectado.');
+        console.log('Ejecuta `factory:update` para inicializar el tracking de versión.');
+        return;
+    }
+    console.log(`Instalado: v${result.installed}`);
+    if (result.factoryVersion) {
+        console.log(`Sello de nacimiento (factoryVersion): v${result.factoryVersion}`);
+    }
+    if (result.networkError) {
+        console.log('Última: (versión remota no disponible — sin conexión)');
+        return;
+    }
+    console.log(`Última: v${result.latest}`);
+    if (result.hasUpdate) {
+        console.log('⬆ Actualización disponible — ejecuta factory:update');
+    }
+    else {
+        console.log('✔ Estás en la última versión.');
+    }
+}
+/**
+ * Run `factory status`. Always exits 0 — a missing lockfile and a network error
+ * are advisory states, not failures (DIST-006 §8). Only an unexpected
+ * programming bug would surface through the top-level handler.
+ */
+export async function runStatus(deps = {}) {
+    const result = await computeStatus(deps);
+    renderStatus(result);
+}