@timekast/factory 0.1.0

package/dist/lib/lockfile.js

@@ -0,0 +1,282 @@
+/**
+ * Lockfile engine: read / write / diff of `.timekast/lockfile.json` plus the
+ * normalized hashing the 4-bucket diff relies on (design §7.0–§7.2, §7.6).
+ *
+ * The lockfile IS the embedded `manifest.json` of the currently-installed
+ * version (design §7.0 table): a top-level `{ version, profile, files }` shape
+ * where each `files[]` entry is `{ path, hash }`. There is no per-entry version
+ * (the version lives once at the top).
+ *
+ * Two version semantics live at the top level (design §3 — dual version):
+ *   - `version`        = `agentKitVersion`: the installed brain version. ADVANCES
+ *                        on every `update` (it is whatever the new manifest carries).
+ *   - `factoryVersion` = the birth stamp: the kit version at install time
+ *                        (`new` / `add`), FROZEN thereafter and PRESERVED across
+ *                        every `update`. Optional for backward-compat: a lockfile
+ *                        written before this field exists (or the builder's embedded
+ *                        manifest, which only carries `version`) simply omits it.
+ *                        `writeInitialLockfile` promotes the manifest's `version`
+ *                        into `factoryVersion` so the birth stamp is recorded.
+ *
+ * 🔒 HASH PARITY — DO NOT DIVERGE.
+ * `normalizeThenHash` MUST produce byte-for-byte the same digest as the
+ * distribution builder's `hashContent` (`distribution/build-dist.ts`). The
+ * builder normalizes with EXACTLY:
+ *     raw.replace(/\r\n/g, '\n').replace(/[ \t\r\n]+$/, '')
+ * then SHA-256 (hex) over the utf8 bytes of the normalized string. Any drift
+ * here (different trim, different EOL handling, hashing raw bytes) would make
+ * every kit file in a derived repo show up as a conflict on the first `update`.
+ * If you change one side, change both and re-run the parity tests.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from './cli-error.js';
+import { LOCKFILE_FILE, MANIFEST_FILE, TIMEKAST_DIR } from './constants.js';
+/**
+ * Write the initial lockfile in `destDir/.timekast/lockfile.json` (used by
+ * `new` / `add`). On the initial install the lockfile carries the tarball's
+ * embedded manifest (same `version` / `profile` / `files`, no hash recompute —
+ * the diff engine is `update`) PLUS the birth stamp: `factoryVersion` is set to
+ * the manifest's `version` (install time = birth). It is frozen there and
+ * preserved by every later `update`.
+ *
+ * A stale unpacked `manifest.json` left in `.timekast/` is removed so only the
+ * stamped lockfile remains.
+ */
+export function writeInitialLockfile(destDir, manifestRaw) {
+    const timekastDir = path.join(destDir, TIMEKAST_DIR);
+    mkdirSync(timekastDir, { recursive: true });
+    // Parse the embedded manifest and stamp the birth seal (factoryVersion =
+    // manifest.version at install). Reuse parseLockfile so a corrupt embedded
+    // manifest is rejected here too (source label keeps the error accurate).
+    const manifest = parseLockfile(manifestRaw, 'manifest');
+    const stamped = { ...manifest, factoryVersion: manifest.version };
+    // If the tarball already unpacked manifest.json into .timekast/, drop it: the
+    // stamped lockfile is the SSOT and we do not keep a duplicate manifest around.
+    const unpackedManifest = path.join(timekastDir, MANIFEST_FILE);
+    if (existsSync(unpackedManifest)) {
+        rmSync(unpackedManifest, { force: true });
+    }
+    writeLockfile(destDir, stamped);
+}
+// ---------------------------------------------------------------------------
+// Hashing — parity-locked with the builder (see header).
+// ---------------------------------------------------------------------------
+/**
+ * Normalize content the same way the builder does, then SHA-256 it (hex).
+ *
+ * Normalization: CRLF → LF, then strip trailing whitespace/newlines at the end
+ * of the file. This absorbs the common false-conflict causes (Windows CRLF,
+ * prettier's final-newline) so a clean kit file hashes identically across
+ * platforms. MUST stay byte-for-byte identical to `hashContent` in
+ * `distribution/build-dist.ts`.
+ */
+export function normalizeThenHash(content) {
+    const normalized = content.replace(/\r\n/g, '\n').replace(/[ \t\r\n]+$/, '');
+    return createHash('sha256').update(normalized, 'utf8').digest('hex');
+}
+// ---------------------------------------------------------------------------
+// Read / write
+// ---------------------------------------------------------------------------
+/** Absolute path to the lockfile inside a derived project root. */
+export function lockfilePath(rootDir) {
+    return path.join(rootDir, TIMEKAST_DIR, LOCKFILE_FILE);
+}
+/** True when the derived project already has a lockfile. */
+export function hasLockfile(rootDir) {
+    return existsSync(lockfilePath(rootDir));
+}
+/**
+ * Validate a parsed object is a well-formed lockfile/manifest: a `version`
+ * string, a `profile`, and a `files` array of `{ path, hash }`. Used both for
+ * the lockfile on disk and the embedded manifest of a downloaded tarball
+ * (the swap preflight rejects a corrupt/empty manifest with this).
+ *
+ * @throws {CLIError} with a clear message when the structure is invalid.
+ */
+export function parseLockfile(raw, source = 'lockfile') {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CLIError(`El ${source} no es JSON válido; no se puede continuar de forma segura.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CLIError(`El ${source} no tiene la estructura esperada (objeto con version + files).`);
+    }
+    const obj = parsed;
+    if (typeof obj.version !== 'string' || obj.version.length === 0) {
+        throw new CLIError(`El ${source} no declara un \`version\` válido; está corrupto o vacío.`);
+    }
+    if (obj.profile !== 'core' && obj.profile !== 'full') {
+        throw new CLIError(`El ${source} no declara un \`profile\` válido ('core' | 'full').`);
+    }
+    if (!Array.isArray(obj.files)) {
+        throw new CLIError(`El ${source} no declara un arreglo \`files\`; está corrupto o vacío.`);
+    }
+    const files = obj.files.map((entry, i) => {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new CLIError(`El ${source} tiene una entrada inválida en files[${i}].`);
+        }
+        const e = entry;
+        if (typeof e.path !== 'string' || typeof e.hash !== 'string') {
+            throw new CLIError(`El ${source} tiene una entrada sin \`path\`/\`hash\` en files[${i}].`);
+        }
+        return { path: e.path, hash: e.hash };
+    });
+    return {
+        version: obj.version,
+        profile: obj.profile,
+        files,
+        // Optional birth stamp — present in stamped lockfiles, absent in the
+        // builder's embedded manifest and in legacy lockfiles (back-compat).
+        ...(typeof obj.factoryVersion === 'string' ? { factoryVersion: obj.factoryVersion } : {}),
+    };
+}
+/** Read + validate the lockfile from a derived project root. */
+export function readLockfile(rootDir) {
+    const file = lockfilePath(rootDir);
+    if (!existsSync(file)) {
+        throw new CLIError('No hay `.timekast/lockfile.json` en este repo.');
+    }
+    return parseLockfile(readFileSync(file, 'utf8'), 'lockfile');
+}
+/** Write the lockfile (pretty-printed, trailing newline) to a project root. */
+export function writeLockfile(rootDir, lockfile) {
+    const dir = path.join(rootDir, TIMEKAST_DIR);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(lockfilePath(rootDir), `${JSON.stringify(lockfile, null, 2)}\n`, 'utf8');
+}
+/**
+ * Classify every file into the 4 buckets + conflicts (design §7.2).
+ *
+ * Profile stickiness is the caller's job: `newManifest` is already the manifest
+ * of the SAME profile recorded in `oldLock` (an `sk-*` only present in `full`
+ * never appears in a `core` manifest, so it can never reach `add` for a `core`
+ * repo). This function only diffs the two manifests it is handed.
+ *
+ * Buckets:
+ *   - add:             in newManifest, absent on disk.
+ *   - overwriteSilent: in both manifests, localHash == registeredHash.
+ *   - deleteSilent:    in oldLock, absent from newManifest (kit-retired).
+ *   - ignoreLocal:     on disk under a tracked dir but in NO manifest → untouched.
+ *                      (Populated by the caller from the disk scan; here we only
+ *                      surface paths present on disk that are in neither manifest
+ *                      when they were passed in `diskHashes`.)
+ *   - conflicts:       localHash != registeredHash AND newHash != registeredHash.
+ *
+ * Note on a file in newManifest, present on disk, localHash == newHash already:
+ * it is treated as overwriteSilent (re-writing identical bytes is a no-op the
+ * swap performs harmlessly) UNLESS localHash != registeredHash AND
+ * newHash != registeredHash → then it is a conflict (the dev edited it and the
+ * Factory changed it, even if they happened to converge we still surface it per
+ * the design's binary rule). We special-case convergence below to avoid a
+ * pointless prompt when local already equals the incoming version.
+ */
+export function diffLockfiles(oldLock, newManifest, diskHashes) {
+    const oldByPath = new Map(oldLock.files.map((f) => [f.path, f]));
+    const newByPath = new Map(newManifest.files.map((f) => [f.path, f]));
+    const diff = {
+        add: [],
+        overwriteSilent: [],
+        deleteSilent: [],
+        ignoreLocal: [],
+        conflicts: [],
+    };
+    // Walk the new manifest: add / overwriteSilent / conflicts.
+    for (const newEntry of newManifest.files) {
+        const localHash = diskHashes.get(newEntry.path);
+        const registered = oldByPath.get(newEntry.path);
+        if (localHash === undefined) {
+            // Not on disk → brand-new kit file.
+            diff.add.push(newEntry);
+            continue;
+        }
+        const registeredHash = registered?.hash;
+        if (registeredHash === undefined) {
+            // On disk but not in the old lockfile: untracked-but-present. Treat as a
+            // conflict only if the disk content differs from the incoming version;
+            // otherwise it is already correct → silent.
+            if (localHash === newEntry.hash) {
+                diff.overwriteSilent.push(newEntry);
+            }
+            else {
+                diff.conflicts.push({
+                    path: newEntry.path,
+                    localHash,
+                    registeredHash: localHash, // no prior record; treat current as baseline
+                    newHash: newEntry.hash,
+                });
+            }
+            continue;
+        }
+        const localEdited = localHash !== registeredHash;
+        const factoryChanged = newEntry.hash !== registeredHash;
+        if (!localEdited) {
+            // Clean kit file (matches the lockfile) → silent overwrite.
+            diff.overwriteSilent.push(newEntry);
+        }
+        else if (!factoryChanged) {
+            // Dev edited it, Factory did NOT change it → keep the dev's version.
+            // Not a conflict and not an overwrite: leave it (no bucket = untouched).
+            // Recorded as ignoreLocal so the summary can stay accurate.
+            diff.ignoreLocal.push(newEntry.path);
+        }
+        else if (localHash === newEntry.hash) {
+            // Converged: dev's edit happens to equal the new version → silent.
+            diff.overwriteSilent.push(newEntry);
+        }
+        else {
+            // Edited locally AND changed by the Factory, diverging → conflict.
+            diff.conflicts.push({
+                path: newEntry.path,
+                localHash,
+                registeredHash,
+                newHash: newEntry.hash,
+            });
+        }
+    }
+    // Walk the old lockfile: deleteSilent (in old, gone from new).
+    for (const oldEntry of oldLock.files) {
+        if (!newByPath.has(oldEntry.path)) {
+            diff.deleteSilent.push(oldEntry);
+        }
+    }
+    // Any disk path present in NEITHER manifest is dev-owned → ignoreLocal.
+    for (const diskPath of diskHashes.keys()) {
+        if (!newByPath.has(diskPath) && !oldByPath.has(diskPath)) {
+            diff.ignoreLocal.push(diskPath);
+        }
+    }
+    return diff;
+}
+/**
+ * Classify a legacy repo (no lockfile) against the latest manifest by PATH, not
+ * hash (design §6.3 "Baseline legacy por path-match, NO por hash"). Files that
+ * evolved between birth and now would never match by hash even though they are
+ * 100% kit-owned, so path-match is the only safe baseline.
+ *
+ * @param manifest   The fresh manifest (the profile being installed).
+ * @param repoPaths  The set of paths currently present under the kit-managed
+ *                   tree (`.claude/` + tracked root files) in the repo.
+ */
+export function planAutoRegister(manifest, repoPaths) {
+    const manifestPaths = new Set(manifest.files.map((f) => f.path));
+    const plan = { kitOwned: [], toAdd: [], ambiguous: [] };
+    for (const entry of manifest.files) {
+        if (repoPaths.has(entry.path)) {
+            plan.kitOwned.push(entry);
+        }
+        else {
+            plan.toAdd.push(entry);
+        }
+    }
+    for (const repoPath of repoPaths) {
+        if (!manifestPaths.has(repoPath)) {
+            plan.ambiguous.push(repoPath);
+        }
+    }
+    return plan;
+}

package/dist/lib/package-json.js

@@ -0,0 +1,90 @@
+/**
+ * Surgical edits to a derived project's `package.json` (design §7.4).
+ *
+ * Both operations parse → mutate a single key → re-serialize with the original
+ * indentation, never rewriting the whole document. The dev's deps, scripts,
+ * field order and formatting are preserved.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { CLIError } from './cli-error.js';
+import { UPDATE_SCRIPT_CMD, UPDATE_SCRIPT_NAME } from './constants.js';
+/** Detect the indentation used by an existing JSON document (defaults to 2 spaces). */
+function detectIndent(raw) {
+    const match = raw.match(/^(\s+)"/m);
+    if (!match)
+        return 2;
+    const ws = match[1].replace(/\r?\n/g, '');
+    if (ws.includes('\t'))
+        return '\t';
+    return ws.length || 2;
+}
+/** Parse `package.json` content, raising a clean error if it is not valid JSON. */
+export function parsePackageJson(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error('not an object');
+        }
+        return parsed;
+    }
+    catch {
+        throw new CLIError('El `package.json` desempacado no es JSON válido; no se puede continuar de forma segura.');
+    }
+}
+/**
+ * Pure core of the script insertion: mutate `pkg.scripts` in place to ensure
+ * `factory:update` exists, never overwriting a divergent value. Shared by
+ * `applyPackageJsonEdits` (the `new` flow) and `insertFactoryUpdateScript`
+ * (the `update` flow) so both follow the same §7.4 rule.
+ */
+function ensureUpdateScript(pkg) {
+    const scripts = pkg.scripts ?? {};
+    const existing = scripts[UPDATE_SCRIPT_NAME];
+    pkg.scripts = scripts;
+    if (existing === undefined) {
+        scripts[UPDATE_SCRIPT_NAME] = UPDATE_SCRIPT_CMD;
+        return { action: 'added' };
+    }
+    if (existing === UPDATE_SCRIPT_CMD) {
+        return { action: 'already-correct' };
+    }
+    return { action: 'conflict', existingValue: existing };
+}
+/**
+ * Rename `package.json.name` and ensure the `factory:update` script exists,
+ * preserving everything else. Returns the serialized document (with the
+ * original indentation + trailing newline).
+ *
+ * If `factory:update` already exists with a different value it is left intact;
+ * `scriptAlreadyPresent` reports that so the caller can warn the user.
+ */
+export function applyPackageJsonEdits(raw, name) {
+    const indent = detectIndent(raw);
+    const pkg = parsePackageJson(raw);
+    pkg.name = name;
+    const result = ensureUpdateScript(pkg);
+    const content = `${JSON.stringify(pkg, null, indent)}\n`;
+    return { content, scriptAlreadyPresent: result.action === 'conflict' };
+}
+/**
+ * Surgically ensure the `factory:update` script exists in the `package.json` at
+ * `pkgPath` (design §7.4). Reads, mutates only the single key, and re-serializes
+ * with the original indentation + trailing newline. NEVER overwrites a divergent
+ * value and NEVER touches `name`, deps, or any other script.
+ *
+ * Writes the file only when something actually changed (`added`); for
+ * `already-correct` and `conflict` the file is left byte-identical.
+ *
+ * @param pkgPath Absolute path to the derived project's `package.json`.
+ * @returns What happened, plus the existing value when it conflicts.
+ */
+export function insertFactoryUpdateScript(pkgPath) {
+    const raw = readFileSync(pkgPath, 'utf8');
+    const indent = detectIndent(raw);
+    const pkg = parsePackageJson(raw);
+    const result = ensureUpdateScript(pkg);
+    if (result.action === 'added') {
+        writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
+    }
+    return result;
+}

package/dist/lib/preflight.js

@@ -0,0 +1,79 @@
+/**
+ * Preflight checks shared by `new` / `add` / `update` (design §7.7).
+ *
+ * Verifies, in order:
+ *   1. `gh` is installed and on PATH.
+ *   2. `gh auth status` exits 0 (a valid, non-expired session).
+ *   3. The authenticated user is a member of the destination org.
+ *
+ * Any failure throws a `PreflightError` with an actionable message — never a
+ * cryptic spawn error or a stack trace.
+ */
+import { execa } from 'execa';
+import { PreflightError } from './cli-error.js';
+import { FACTORY_ORG } from './constants.js';
+/** True when the thrown error is execa's "command not found" (ENOENT). */
+function isCommandNotFound(error) {
+    const code = error?.code;
+    return code === 'ENOENT';
+}
+/** Step 1 — `gh` is installed on PATH. */
+async function assertGhInstalled() {
+    try {
+        await execa('gh', ['--version']);
+    }
+    catch (error) {
+        if (isCommandNotFound(error)) {
+            throw new PreflightError('GitHub CLI (`gh`) no está instalado o no está en el PATH.\n' +
+                'Instálalo desde https://cli.github.com y vuelve a intentar.');
+        }
+        throw new PreflightError('No se pudo ejecutar `gh`. Verifica tu instalación de GitHub CLI (https://cli.github.com).');
+    }
+}
+/** Step 2 — `gh auth status` returns exit 0. */
+async function assertGhAuthenticated() {
+    try {
+        await execa('gh', ['auth', 'status']);
+    }
+    catch {
+        throw new PreflightError('Tu sesión de GitHub CLI no es válida o expiró.\n' +
+            'Ejecuta `gh auth login` para autenticarte y vuelve a intentar.');
+    }
+}
+/**
+ * Step 3 — the authenticated user is a member of `FACTORY_ORG`.
+ *
+ * `gh api /user` resolves the login; `gh api /orgs/<org>/members/<login>`
+ * returns 204 for a member and 404 otherwise (the same 404 a non-member sees
+ * on the private repo). Either non-204 → not a verifiable member.
+ */
+async function assertOrgMembership() {
+    let login;
+    try {
+        const { stdout } = await execa('gh', ['api', '/user', '--jq', '.login']);
+        login = stdout.trim();
+    }
+    catch {
+        throw new PreflightError('No se pudo determinar tu usuario de GitHub con `gh api /user`.\n' +
+            'Verifica tu sesión con `gh auth status`.');
+    }
+    if (!login) {
+        throw new PreflightError('No se pudo determinar tu usuario de GitHub. Verifica tu sesión con `gh auth status`.');
+    }
+    try {
+        await execa('gh', ['api', `/orgs/${FACTORY_ORG}/members/${login}`]);
+    }
+    catch {
+        throw new PreflightError(`No se pudo verificar que \`${login}\` sea miembro del org \`${FACTORY_ORG}\`.\n` +
+            `Solicita acceso al org \`${FACTORY_ORG}\` o verifica tu sesión con \`gh auth status\`.`);
+    }
+}
+/**
+ * Run all preflight checks. Reusable by `add` / `update`.
+ * @throws {PreflightError} when any check fails.
+ */
+export async function runPreflight() {
+    await assertGhInstalled();
+    await assertGhAuthenticated();
+    await assertOrgMembership();
+}

package/dist/lib/repo-detection.js

@@ -0,0 +1,32 @@
+/**
+ * Git repo detection for `add` (design §6.2, edge cases in DIST-004 §8).
+ *
+ * Walks up from `cwd` looking for a `.git/` entry (the same lineage discovery
+ * `git rev-parse --show-toplevel` does). A `.git` may be a directory (normal
+ * repo) or a file (worktree / submodule pointer) — both count as a repo context.
+ *
+ * Note: presence of `.git/` is enough; a repo with `git init` but zero commits
+ * is a valid context (DIST-004 §8). `add` installs in the CWD, not the repo
+ * root — `repoRoot` is informational (e.g. monorepo with `.git/` in an ancestor).
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * Detect whether `cwd` (or any ancestor) is inside a git repository.
+ *
+ * @param cwd Absolute or relative directory to start the upward search from.
+ */
+export function detectRepo(cwd) {
+    let current = path.resolve(cwd);
+    // Walk up until the filesystem root; `path.dirname('/') === '/'`.
+    for (;;) {
+        if (existsSync(path.join(current, '.git'))) {
+            return { hasRepo: true, repoRoot: current };
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return { hasRepo: false, repoRoot: null };
+}

package/dist/lib/unpack.js

@@ -0,0 +1,86 @@
+/**
+ * Shared download + unpack engine for `new` and `add` (design §7.0, §7.5).
+ *
+ * A profile tarball is self-describing: it ships a `.timekast/manifest.json`
+ * (list of files + hashes for that version) at its root. The engine:
+ *   1. Downloads the tarball for a given profile from the latest Factory release.
+ *   2. Extracts it into a staging dir under a caller-provided temp dir.
+ *   3. Validates the embedded manifest exists (atomicity guard — never touch the
+ *      destination until the tarball is proven well-formed).
+ *
+ * Moving the staged contents into the destination is `moveContentsInto`, kept
+ * separate so callers control the final placement step (the atomic swap of §7.5).
+ *
+ * Expected failures throw `CLIError`; the top-level handler prints + exits.
+ */
+import { existsSync, readdirSync, readFileSync, cpSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { extract } from 'tar';
+import { CLIError } from './cli-error.js';
+import { FACTORY_REPO, MANIFEST_FILE, TIMEKAST_DIR } from './constants.js';
+/** Download the profile tarball into `tmpDir`; returns the tarball path. */
+export async function downloadProfileTarball(profile, tmpDir) {
+    try {
+        await execa('gh', [
+            'release',
+            'download',
+            '--repo',
+            FACTORY_REPO,
+            '--pattern',
+            `tk-${profile}-*.tgz`,
+            '--dir',
+            tmpDir,
+        ]);
+    }
+    catch {
+        throw new CLIError(`No se encontró un release publicado con el perfil \`${profile}\` en \`${FACTORY_REPO}\`.\n` +
+            'Verifica que exista un release con los assets de distribución.');
+    }
+    const downloaded = readdirSync(tmpDir).filter((f) => f.endsWith('.tgz'));
+    if (downloaded.length === 0) {
+        throw new CLIError(`El release no contiene un asset para el perfil \`${profile}\`. ` +
+            'Verifica el release del Factory.');
+    }
+    return path.join(tmpDir, downloaded[0]);
+}
+/**
+ * Extract `tarball` into a fresh staging dir under `tmpDir` and validate that it
+ * carries an embedded `.timekast/manifest.json`. Returns the staging dir + the
+ * manifest text. Never touches the destination — that is the caller's job.
+ *
+ * @throws {CLIError} if the manifest is missing or empty (corrupt/incomplete tarball).
+ */
+export async function stageProfileTarball(tarball, tmpDir) {
+    const stagedDir = path.join(tmpDir, 'unpacked');
+    mkdirSync(stagedDir, { recursive: true });
+    await extract({ file: tarball, cwd: stagedDir });
+    const manifestPath = path.join(stagedDir, TIMEKAST_DIR, MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+        throw new CLIError('El tarball descargado no contiene `.timekast/manifest.json`; no se puede continuar.');
+    }
+    const manifestRaw = readFileSync(manifestPath, 'utf8');
+    if (manifestRaw.trim().length === 0) {
+        throw new CLIError('El manifest del tarball descargado está vacío; no se puede continuar. Reintenta `add`.');
+    }
+    return { stagedDir, manifestRaw };
+}
+/**
+ * Move the staged tarball contents into `destDir`. The tarball is packed from a
+ * staging dir, so its contents sit at the tarball root — never a Factory `.git/`
+ * (Filtro 2, design §4.3). Defensive: skip any `.git` that might slip in.
+ *
+ * Profile scoping is structural: a `core` tarball only contains `core` files, so
+ * moving its contents in never reaches `src/` or dev-owned paths. Files in the
+ * destination that are NOT in the tarball are left untouched (cpSync only writes
+ * the entries it iterates).
+ */
+export function moveContentsInto(stagedDir, destDir) {
+    for (const entry of readdirSync(stagedDir)) {
+        if (entry === '.git')
+            continue;
+        const src = path.join(stagedDir, entry);
+        const dst = path.join(destDir, entry);
+        cpSync(src, dst, { recursive: true });
+    }
+}

package/dist/lib/validate-name.js

@@ -0,0 +1,34 @@
+/**
+ * Project-name validation for `new`. Runs entirely offline, BEFORE any `gh`
+ * call, so an invalid name fails fast with a format hint instead of a cryptic
+ * GitHub API error.
+ *
+ * GitHub repo names allow alphanumerics, hyphen, underscore and period; they
+ * cannot be empty, cannot be `.`/`..`, and we additionally reject names that
+ * start with `-`/`.` (ambiguous with flags / hidden paths) per design §8.
+ */
+import { CLIError } from './cli-error.js';
+/** Allowed characters for a GitHub repository name. */
+const VALID_NAME = /^[A-Za-z0-9._-]+$/;
+const FORMAT_HINT = 'El nombre solo puede contener letras, números, guiones (-), guiones bajos (_) y puntos (.), ' +
+    'sin espacios, y no puede empezar con `-` ni `.`.';
+/**
+ * Validate a project name. Returns the trimmed name on success.
+ * @throws {CLIError} with the allowed-format hint on any invalid input.
+ */
+export function validateProjectName(raw) {
+    const name = (raw ?? '').trim();
+    if (!name) {
+        throw new CLIError(`Debes indicar un nombre de proyecto.\n${FORMAT_HINT}`);
+    }
+    if (name === '.' || name === '..') {
+        throw new CLIError(`Nombre inválido: \`${name}\`.\n${FORMAT_HINT}`);
+    }
+    if (name.startsWith('-') || name.startsWith('.')) {
+        throw new CLIError(`Nombre inválido: \`${name}\` no puede empezar con \`-\` ni \`.\`.\n${FORMAT_HINT}`);
+    }
+    if (!VALID_NAME.test(name)) {
+        throw new CLIError(`Nombre inválido: \`${name}\` contiene caracteres no permitidos.\n${FORMAT_HINT}`);
+    }
+    return name;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@timekast/factory",
+  "version": "0.1.0",
+  "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "author": "TimeKast",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TimeKast/TimeKast-Factory.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "timekast",
+    "factory",
+    "cli",
+    "scaffold",
+    "boilerplate"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "factory": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "execa": "^9.5.2",
+    "prompts": "^2.4.2",
+    "tar": "^7.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@types/prompts": "^2.4.9",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.4"
+  }
+}