@timekast/factory 1.2.0 → 1.4.0

package/dist/commands/add.js

@@ -85,6 +85,8 @@ export async function runAdd(flags = { core: false, full: false }) {
             mineAll: false,
             resume: false,
             verify: false,
+            commit: false,
+            noCommit: false,
         });
         return;
     }

package/dist/commands/new.js

@@ -19,6 +19,7 @@ import { CLIError } from '../lib/cli-error.js';
 import { FACTORY_ORG, PROFILES } from '../lib/constants.js';
 import { parseLockfile, writeInitialLockfile } from '../lib/lockfile.js';
 import { applyPackageJsonEdits } from '../lib/package-json.js';
+import { renderDerivedReadme } from '../lib/readme.js';
 import { runPreflight } from '../lib/preflight.js';
 import { downloadProfileTarball, moveContentsInto, stageProfileTarball } from '../lib/unpack.js';
 import { validateProjectName } from '../lib/validate-name.js';
@@ -100,13 +101,19 @@ export async function runNew(name) {
         await execa('git', ['init'], { cwd: destDir });
         // Rename package.json.name + inject factory:update (surgical, §7.4).
         const pkgPath = path.join(destDir, 'package.json');
-        if (existsSync(pkgPath)) {
+        const hasPackageJson = existsSync(pkgPath);
+        if (hasPackageJson) {
             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ó.');
             }
         }
+        // Replace the inherited README. The `full` tarball ships the Factory's own
+        // README (it documents the distribution CLI), which is wrong inside a derived
+        // app — overwrite it with one scoped to this project. Written either way so a
+        // brain-only `core` project also gets a README.
+        writeFileSync(path.join(destDir, 'README.md'), renderDerivedReadme(validName, profile, hasPackageJson), 'utf8');
         // Write the initial lockfile = the tarball's embedded manifest verbatim
         // (no hash recompute — that's DIST-005).
         writeInitialLockfile(destDir, manifestRaw);

package/dist/commands/update.js

@@ -36,11 +36,14 @@
 import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
+import { execa } from 'execa';
 import prompts from 'prompts';
 import { applyPlan, clearUpdateState, defaultBackupDir, hasUpdateState, readUpdateState, validateStagedManifest, writeUpdateState, } from '../lib/atomic-swap.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLIError } from '../lib/cli-error.js';
-import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
+import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, LOCKFILE_FILE, PROFILES, TIMEKAST_DIR, } from '../lib/constants.js';
+import { decideCommit } from '../lib/commit-decision.js';
+import { extractManagedBlock, syncManagedBlock } from '../lib/gitattributes.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
 import { detectProfile, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
@@ -55,6 +58,8 @@ export function parseUpdateFlags(argv) {
         verify: argv.includes('--verify'),
         core: argv.includes('--core'),
         full: argv.includes('--full'),
+        commit: argv.includes('--commit'),
+        noCommit: argv.includes('--no-commit'),
     };
 }
 /** Default acquire: download the sticky-profile tarball, stage + validate it. */
@@ -149,11 +154,66 @@ function runVerify(rootDir) {
     for (const p of drifted)
         console.log(`  • modificado localmente: ${p}`);
 }
+/**
+ * After a clean update, optionally commit the refreshed brain (local, NEVER push).
+ * Decision (`commit-decision.ts`): `--no-commit`→skip · `--commit`→commit · interactive
+ * → prompt y/n · headless → commit by default (the Agent Server needs it). Stages ONLY
+ * what the update touched (the applied manifest paths + lockfile + package.json +
+ * .gitattributes) — never `git add -A`. Best-effort: no identity / no repo → warn + skip.
+ */
+async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
+    const decision = decideCommit({
+        commit: flags.commit,
+        noCommit: flags.noCommit,
+        isTTY: Boolean(process.stdout.isTTY),
+    });
+    if (decision === 'skip')
+        return;
+    let doCommit = decision === 'commit';
+    if (decision === 'prompt') {
+        const { yes } = await prompts({
+            type: 'confirm',
+            name: 'yes',
+            message: `¿Commitear el cerebro actualizado (v${version})? No se pushea.`,
+            initial: true,
+        });
+        doCommit = yes === true;
+    }
+    if (!doCommit)
+        return;
+    const candidates = [
+        ...appliedPaths,
+        `${TIMEKAST_DIR}/${LOCKFILE_FILE}`,
+        ...(existsSync(path.join(rootDir, 'package.json')) ? ['package.json'] : []),
+        ...(existsSync(path.join(rootDir, GITATTRIBUTES_FILE)) ? [GITATTRIBUTES_FILE] : []),
+    ];
+    try {
+        await execa('git', ['add', '--', ...candidates], { cwd: rootDir, reject: false });
+        // Nothing staged (e.g. a no-op update) → no empty commit.
+        const staged = await execa('git', ['diff', '--cached', '--quiet'], {
+            cwd: rootDir,
+            reject: false,
+        });
+        if (staged.exitCode === 0)
+            return;
+        const res = await execa('git', ['commit', '-m', `chore: factory update v${version}`], {
+            cwd: rootDir,
+            reject: false,
+        });
+        if (res.exitCode === 0)
+            console.log(`✔ Cerebro commiteado (v${version}).`);
+        else
+            console.warn('Aviso: no se pudo commitear (¿falta identidad git o no es un repo?); el cerebro se instaló igual.');
+    }
+    catch {
+        console.warn('Aviso: no se pudo commitear; el cerebro se instaló igual.');
+    }
+}
 /**
  * `--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) {
+async function runResume(rootDir, flags) {
     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`.');
@@ -168,9 +228,9 @@ function runResume(rootDir) {
     applyPlan(rootDir, state.stagedDir, state.plan, state.backupDir);
     writeLockfile(rootDir, newLock);
     clearUpdateState(rootDir);
-    const pkgPath = path.join(rootDir, 'package.json');
-    if (existsSync(pkgPath))
-        maintainDerivedPkg(pkgPath, newLock.version);
+    // Maintain dotfiles BEFORE removing the staged dir (the .gitattributes source).
+    maintainDerivedDotfiles(rootDir, state.stagedDir, newLock.version);
+    await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes], flags);
     rmSync(state.stagedDir, { recursive: true, force: true });
     console.log('✔ `update` retomado y completado.');
 }
@@ -191,15 +251,31 @@ function warnOnScriptConflict(action, _pkgPath) {
     }
 }
 /**
- * After a sync, maintain the derived project's package.json: ensure the
- * `factory:update` script (warn on a divergent value) and set `agentKitVersion`
- * to the just-installed brain version, mirroring the lockfile's `version`. Run on
- * every update, so the field tracks each `factory:update` (and a derivative whose
- * field was missing or stale gets reconciled — same shape as the Factory's own
+ * After a sync, maintain the derived project's co-owned dotfiles — `package.json`
+ * AND `.gitattributes` — in one place. Centralized (not scattered per command) so
+ * all THREE update paths (main, legacy auto-register, resume) are covered by
+ * construction: a per-command call already regressed once (legacy + resume were
+ * missed). `stagedDir` is the freshly-unpacked tarball, the source of the
+ * `.gitattributes` managed block.
+ */
+function maintainDerivedDotfiles(rootDir, stagedDir, agentKitVersion) {
+    maintainDerivedPkg(rootDir, agentKitVersion);
+    syncDerivedGitattributes(rootDir, stagedDir);
+}
+/**
+ * Maintain the derived project's package.json: ensure the `factory:*` scripts
+ * (warn on a divergent `factory:update`) and set `agentKitVersion` to the
+ * just-installed brain version, mirroring the lockfile's `version`. Run on every
+ * update, so the field tracks each `factory:update` (and a derivative whose field
+ * was missing or stale gets reconciled — same shape as the Factory's own
  * package.json). `factoryVersion` (the frozen birth stamp) and `version` (the app
- * semver) are untouched.
+ * semver) are untouched. No-op (not an error) when the repo has no package.json
+ * (a non-Node derivative).
  */
-function maintainDerivedPkg(pkgPath, agentKitVersion) {
+function maintainDerivedPkg(rootDir, agentKitVersion) {
+    const pkgPath = path.join(rootDir, 'package.json');
+    if (!existsSync(pkgPath))
+        return;
     // Tolerant (mirrors `add`): a malformed package.json must NOT throw AFTER the
     // brain was already applied + the lockfile written — the install succeeded; the
     // script/version mirror is best-effort. Warn and move on.
@@ -212,6 +288,35 @@ function maintainDerivedPkg(pkgPath, agentKitVersion) {
             'Corrige package.json y vuelve a correr `factory update` para sincronizar agentKitVersion.');
     }
 }
+/**
+ * Sync the Factory's managed `.gitattributes` block (the EOL/binary rules that
+ * keep the kit's committed binaries from being corrupted by CRLF→LF normalization)
+ * into the derived repo, preserving the dev's own rules. The canonical block is
+ * READ from the staged tarball (single SSOT), so the rules are never duplicated in
+ * the CLI. Runs even without package.json (a non-Node derivative needs the rules
+ * too). Best-effort like the package.json mirror: a tarball that predates the
+ * managed block (no markers → no block) is a silent no-op, and a write failure
+ * never fails an already-applied update.
+ */
+function syncDerivedGitattributes(rootDir, stagedDir) {
+    try {
+        const srcPath = path.join(stagedDir, GITATTRIBUTES_FILE);
+        if (!existsSync(srcPath))
+            return;
+        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
+        if (!block)
+            return;
+        const { action } = syncManagedBlock(rootDir, block);
+        if (action === 'unchanged')
+            return;
+        console.log(action === 'created'
+            ? '✔ `.gitattributes` creado con las reglas de normalización del kit.'
+            : '✔ `.gitattributes`: bloque de reglas del kit sincronizado.');
+    }
+    catch {
+        console.warn('Aviso: no se pudo sincronizar `.gitattributes`; el cerebro se instaló igual.');
+    }
+}
 /** Print the deletes + kept-retired (design §7.6 — visible) + a one-line summary. */
 function reportSummary(diff, manifest) {
     if (diff.deleteSilent.length > 0) {
@@ -257,7 +362,7 @@ export async function runUpdate(flags, deps = {}) {
         if (!hasUpdateState(rootDir)) {
             throw new CLIError('No hay un `update` pendiente para retomar.');
         }
-        runResume(rootDir);
+        await runResume(rootDir, flags);
         return;
     }
     // Preflight (gh) before any download — reused, not reimplemented.
@@ -335,9 +440,8 @@ export async function runUpdate(flags, deps = {}) {
         // (agentKitVersion advances; factoryVersion stays frozen).
         writeLockfile(rootDir, stampBirth(oldLock, manifest));
         clearUpdateState(rootDir);
-        const pkgPath = path.join(rootDir, 'package.json');
-        if (existsSync(pkgPath))
-            maintainDerivedPkg(pkgPath, manifest.version);
+        maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+        await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes], flags);
         reportSummary(diff, manifest);
     }
     finally {
@@ -394,9 +498,7 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     // 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))
-        maintainDerivedPkg(pkgPath, manifest.version);
+    maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
     if (claudeMdExists) {
         console.log('\nConservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
             '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');

package/dist/lib/commit-decision.js

@@ -0,0 +1,7 @@
+export function decideCommit({ commit, noCommit, isTTY }) {
+    if (noCommit)
+        return 'skip';
+    if (commit)
+        return 'commit';
+    return isTTY ? 'prompt' : 'commit';
+}

package/dist/lib/constants.js

@@ -30,6 +30,23 @@ export const LOCKFILE_FILE = 'lockfile.json';
  * exists on disk (path-match path). See `diffLockfiles` + the install commands.
  */
 export const CLAUDE_MD_FILE = 'CLAUDE.md';
+/**
+ * Repo-root `.gitattributes`. NOT a tracked manifest file (absent from `track`),
+ * so it never flows through the diff/lockfile engine — a derived repo's own rules
+ * would otherwise read as "locally edited" and conflict on every update. Instead a
+ * delimited managed block (markers below) is synced surgically post-apply, like
+ * `package.json` scripts: the block is replaced verbatim, everything outside it is
+ * preserved byte-for-byte. See `syncManagedBlock` in `lib/gitattributes.ts`.
+ */
+export const GITATTRIBUTES_FILE = '.gitattributes';
+/**
+ * Managed-block sentinels. These are PREFIXES (the live source lines carry extra
+ * descriptive text + trailing `>>>`/`<<<`), matched with `startsWith` so detection
+ * survives edits to the comment copy. Do not change without a migration: a derived
+ * repo's existing block is located by these prefixes.
+ */
+export const MANAGED_BLOCK_START = '# >>> timekast-factory managed';
+export const MANAGED_BLOCK_END = '# <<< timekast-factory managed';
 /** The scripts 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

package/dist/lib/gitattributes.js

@@ -0,0 +1,101 @@
+/**
+ * Surgical sync of the Factory's managed `.gitattributes` block into a derived
+ * project, mirroring the `package.json` script-insertion pattern (`package-json.ts`):
+ * the delimited block is replaced verbatim, everything outside it is preserved.
+ *
+ * Why not the lockfile/`track` engine: `.gitattributes` is dual-owned at the
+ * intra-file level (the Factory block + the dev's own rules share one file). The
+ * lockfile hashes whole files, so tracking it would read the dev's rules as a
+ * local edit and conflict on every update. Instead the block is synced as an
+ * idempotent post-apply step, outside `diffLockfiles`/`applyPlan`.
+ *
+ * The canonical block is the single SSOT: it is READ from the `.gitattributes`
+ * that ships in the staged tarball (see `extractManagedBlock`), never duplicated
+ * as a CLI constant. A derived repo's existing block is located by the
+ * `MANAGED_BLOCK_START` / `_END` sentinels (prefix match), so the descriptive
+ * comment copy can evolve without breaking detection.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { GITATTRIBUTES_FILE, MANAGED_BLOCK_END, MANAGED_BLOCK_START } from './constants.js';
+const isStart = (line) => line.trimStart().startsWith(MANAGED_BLOCK_START);
+const isEnd = (line) => line.trimStart().startsWith(MANAGED_BLOCK_END);
+/** Drop trailing all-whitespace lines (so appends don't pile up blank lines). */
+function stripTrailingEmpty(lines) {
+    const out = [...lines];
+    while (out.length > 0 && out[out.length - 1].trim() === '')
+        out.pop();
+    return out;
+}
+/**
+ * Extract the managed block (markers inclusive) from a `.gitattributes` content,
+ * or `null` if no start marker is present. Used on the well-formed staged source
+ * to obtain the canonical block to sync. If a start marker is found with no end
+ * marker, returns from start to EOF (defensive — the source is well-formed).
+ */
+export function extractManagedBlock(content) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const start = lines.findIndex(isStart);
+    if (start === -1)
+        return null;
+    let end = -1;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (isEnd(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    const slice = end === -1 ? lines.slice(start) : lines.slice(start, end + 1);
+    return slice.join('\n');
+}
+/**
+ * Sync `sourceBlock` (markers inclusive) into `<rootDir>/.gitattributes`,
+ * preserving every rule outside the managed block. The whole file is normalized
+ * to LF (it lives at repo root, outside `.claude/** text eol=lf`, so a source
+ * packed with CRLF on an autocrlf machine is normalized here). Idempotent:
+ * writes only when the bytes actually change.
+ *
+ *   - no file / empty file      → `created` (block only)
+ *   - file without a start marker → `inserted` (block appended after a blank line)
+ *   - start + end markers        → `updated` (content between markers replaced)
+ *   - start without end (dev clobbered half a line) → `updated`, regenerated
+ *     cleanly from start to EOF (NOT appended — avoids a dangling start marker)
+ */
+export function syncManagedBlock(rootDir, sourceBlock) {
+    const filePath = path.join(rootDir, GITATTRIBUTES_FILE);
+    const raw = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
+    const block = sourceBlock.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+    let result;
+    let action;
+    if (raw.trim() === '') {
+        result = `${block}\n`;
+        action = 'created';
+    }
+    else {
+        const lines = raw.replace(/\r\n/g, '\n').split('\n');
+        const start = lines.findIndex(isStart);
+        if (start === -1) {
+            const before = stripTrailingEmpty(lines);
+            result = `${before.join('\n')}\n\n${block}\n`;
+            action = 'inserted';
+        }
+        else {
+            // Replace from start to the end marker, or to EOF when the end marker is
+            // missing (malformed block → regenerate clean rather than append).
+            let end = lines.length - 1;
+            for (let i = start + 1; i < lines.length; i++) {
+                if (isEnd(lines[i])) {
+                    end = i;
+                    break;
+                }
+            }
+            const merged = [...lines.slice(0, start), ...block.split('\n'), ...lines.slice(end + 1)];
+            result = `${stripTrailingEmpty(merged).join('\n')}\n`;
+            action = 'updated';
+        }
+    }
+    if (result === raw)
+        return { action: 'unchanged' };
+    writeFileSync(filePath, result, 'utf8');
+    return { action };
+}

package/dist/lib/readme.js

@@ -0,0 +1,60 @@
+/**
+ * Render a README scoped to a freshly-bootstrapped derived project.
+ *
+ * Why: the `full` tarball ships the Factory's own README (it documents the
+ * distribution CLI — `factory new` etc.), which is wrong inside a derived app.
+ * `factory new` overwrites it with this one, scoped to the project: how to run
+ * it (full) and how to keep the `.claude/` brain current. Pure + deterministic
+ * so it unit-tests without mocks (mirrors `publish-core.ts`).
+ */
+const FACTORY_URL = 'https://github.com/TimeKast/TimeKast-Factory';
+/** The `factory *` invocation prefix: a Node project gets the `pnpm` scripts; otherwise `npx`. */
+function factoryCmd(sub, hasPackageJson) {
+    return hasPackageJson ? `pnpm factory:${sub}` : `npx @timekast/factory ${sub}`;
+}
+/**
+ * Build the derived project's README markdown.
+ *
+ * @param name           The project name (already validated/slugged by the caller).
+ * @param profile        `full` ships the Next.js boilerplate; `core` is brain-only.
+ * @param hasPackageJson Whether the project carries a `package.json` (drives `pnpm` vs `npx`).
+ */
+export function renderDerivedReadme(name, profile, hasPackageJson) {
+    const isFull = profile === 'full';
+    const dev = isFull
+        ? `## Desarrollo
+
+\`\`\`bash
+pnpm install
+cp .env.example .env.local   # edita DATABASE_URL + AUTH_SECRET
+pnpm dev
+\`\`\`
+
+Abre [http://localhost:3000](http://localhost:3000).
+
+`
+        : '';
+    const stack = isFull
+        ? `Boilerplate Next.js 16 + TypeScript + Drizzle ORM + Tailwind + NextAuth, más el cerebro AI-first \`.claude/\` (Claude Code).`
+        : `Este repo usa el cerebro AI-first \`.claude/\` de TimeKast Factory (reglas + skills + workflows para Claude Code), sin el boilerplate Next.js.`;
+    return `# ${name}
+
+> Proyecto creado con [TimeKast Factory](${FACTORY_URL}).
+
+${stack}
+
+${dev}## Mantener el cerebro al día
+
+El cerebro \`.claude/\` se actualiza sin pisar tu trabajo local:
+
+\`\`\`bash
+${factoryCmd('update', hasPackageJson)}   # actualizar a la última versión
+${factoryCmd('status', hasPackageJson)}   # versión instalada vs. disponible
+${factoryCmd('doctor', hasPackageJson)}   # diagnóstico (huérfanos, conflictos, seguridad)
+\`\`\`
+
+---
+
+_Bootstrapped from TimeKast Factory._
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timekast/factory",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",