@timekast/factory 1.3.0 → 1.5.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,13 @@
 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, GITATTRIBUTES_FILE, PROFILES, } from '../lib/constants.js';
+import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, LOCKFILE_FILE, PRETTIERIGNORE_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';
@@ -56,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. */
@@ -150,11 +154,67 @@ 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] : []),
+        ...(existsSync(path.join(rootDir, PRETTIERIGNORE_FILE)) ? [PRETTIERIGNORE_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`.');
@@ -171,6 +231,7 @@ function runResume(rootDir) {
     clearUpdateState(rootDir);
     // 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,16 +252,18 @@ function warnOnScriptConflict(action, _pkgPath) {
     }
 }
 /**
- * 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.
+ * After a sync, maintain the derived project's co-owned dotfiles — `package.json`,
+ * `.gitattributes` AND `.prettierignore` — 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 managed blocks. Runs BEFORE any brain commit, so the blocks land before a
+ * pre-commit hook could reformat the freshly-installed kit files.
  */
 function maintainDerivedDotfiles(rootDir, stagedDir, agentKitVersion) {
     maintainDerivedPkg(rootDir, agentKitVersion);
     syncDerivedGitattributes(rootDir, stagedDir);
+    syncDerivedPrettierignore(rootDir, stagedDir);
 }
 /**
  * Maintain the derived project's package.json: ensure the `factory:*` scripts
@@ -257,6 +320,34 @@ function syncDerivedGitattributes(rootDir, stagedDir) {
         console.warn('Aviso: no se pudo sincronizar `.gitattributes`; el cerebro se instaló igual.');
     }
 }
+/**
+ * Sync the Factory's managed `.prettierignore` block (keeps the derived repo's
+ * formatter away from `.claude/**` — a pre-commit `prettier --write` over the kit
+ * files drifts disk from the lockfile hashes and turns every later update into
+ * false conflicts) into the derived repo, preserving the dev's own ignore rules.
+ * Same contract as `syncDerivedGitattributes`: canonical block READ from the
+ * staged tarball (single SSOT), best-effort, tarball without the file (pre-block
+ * releases) → silent no-op, a write failure never fails an applied update.
+ */
+function syncDerivedPrettierignore(rootDir, stagedDir) {
+    try {
+        const srcPath = path.join(stagedDir, PRETTIERIGNORE_FILE);
+        if (!existsSync(srcPath))
+            return;
+        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
+        if (!block)
+            return;
+        const { action } = syncManagedBlock(rootDir, block, PRETTIERIGNORE_FILE);
+        if (action === 'unchanged')
+            return;
+        console.log(action === 'created'
+            ? '✔ `.prettierignore` creado con el ignore del cerebro (`.claude/`) — evita falsos conflictos por formato en futuros updates.'
+            : '✔ `.prettierignore`: bloque del kit sincronizado (`.claude/` fuera del formatter).');
+    }
+    catch {
+        console.warn('Aviso: no se pudo sincronizar `.prettierignore`; 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) {
@@ -302,7 +393,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.
@@ -381,6 +472,7 @@ export async function runUpdate(flags, deps = {}) {
         writeLockfile(rootDir, stampBirth(oldLock, manifest));
         clearUpdateState(rootDir);
         maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+        await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes], flags);
         reportSummary(diff, manifest);
     }
     finally {

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

@@ -39,6 +39,15 @@ export const CLAUDE_MD_FILE = 'CLAUDE.md';
  * preserved byte-for-byte. See `syncManagedBlock` in `lib/gitattributes.ts`.
  */
 export const GITATTRIBUTES_FILE = '.gitattributes';
+/**
+ * Repo-root `.prettierignore`. Same dual-owned managed-block treatment as
+ * `.gitattributes` (NOT tracked in the manifest — the dev's own ignore rules
+ * would read as local edits): the kit's block keeps the derived project's
+ * formatter away from `.claude/**`, whose prettier rewrite on the brain commit
+ * (table alignment, emphasis style) drifts disk from the lockfile hashes and
+ * turns every later `factory:update` into false conflicts (A2).
+ */
+export const PRETTIERIGNORE_FILE = '.prettierignore';
 /**
  * Managed-block sentinels. These are PREFIXES (the live source lines carry extra
  * descriptive text + trailing `>>>`/`<<<`), matched with `startsWith` so detection

package/dist/lib/gitattributes.js

@@ -1,15 +1,16 @@
 /**
- * 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.
+ * Surgical sync of a Factory-managed block into a derived project's dual-owned
+ * dotfile (`.gitattributes`, `.prettierignore`), 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
+ * Why not the lockfile/`track` engine: these files are 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
+ * lockfile hashes whole files, so tracking them 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`
+ * The canonical block is the single SSOT: it is READ from the same-named file
  * 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
@@ -49,11 +50,11 @@ export function extractManagedBlock(content) {
     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.
+ * Sync `sourceBlock` (markers inclusive) into `<rootDir>/<fileName>` (default
+ * `.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)
@@ -61,8 +62,8 @@ export function extractManagedBlock(content) {
  *   - 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);
+export function syncManagedBlock(rootDir, sourceBlock, fileName = GITATTRIBUTES_FILE) {
+    const filePath = path.join(rootDir, fileName);
     const raw = existsSync(filePath) ? readFileSync(filePath, 'utf8') : '';
     const block = sourceBlock.replace(/\r\n/g, '\n').replace(/\n+$/, '');
     let result;

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.3.0",
+  "version": "1.5.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",