@timekast/factory 1.4.0 → 1.6.0

package/dist/commands/new.js

@@ -18,7 +18,7 @@ import prompts from 'prompts';
 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 { applyPackageJsonEdits, kitLocalScripts } 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';
@@ -103,7 +103,7 @@ export async function runNew(name) {
         const pkgPath = path.join(destDir, 'package.json');
         const hasPackageJson = existsSync(pkgPath);
         if (hasPackageJson) {
-            const { content, scriptAlreadyPresent } = applyPackageJsonEdits(readFileSync(pkgPath, 'utf8'), validName);
+            const { content, scriptAlreadyPresent } = applyPackageJsonEdits(readFileSync(pkgPath, 'utf8'), validName, kitLocalScripts(destDir));
             writeFileSync(pkgPath, content, 'utf8');
             if (scriptAlreadyPresent) {
                 console.warn('Aviso: `factory:update` ya existía en package.json con otro valor; no se sobrescribió.');

package/dist/commands/update.js

@@ -41,7 +41,7 @@ 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, LOCKFILE_FILE, PROFILES, TIMEKAST_DIR, } 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';
@@ -186,6 +186,7 @@ async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
         `${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 });
@@ -251,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
@@ -317,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) {

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
@@ -74,3 +83,14 @@ export const FACTORY_SCRIPTS = {
     [PUBLISH_SCRIPT_NAME]: PUBLISH_SCRIPT_CMD,
     [UNPUBLISH_SCRIPT_NAME]: UNPUBLISH_SCRIPT_CMD,
 };
+/**
+ * Kit-local convenience script: the readiness sweep (`pnpm preflight`, consumed
+ * by the /deploy gate and /preflight). Unlike the npx-based `factory:*` scripts
+ * it shells a file that ships with the FULL brain, so the installer ensures it
+ * only when that file exists in the repo (file-gated — a core/non-Factory repo
+ * never gets a broken entry). Insert-if-missing like the rest: a dev's own
+ * `preflight` script is never overwritten.
+ */
+export const PREFLIGHT_SCRIPT_NAME = 'preflight';
+export const PREFLIGHT_SCRIPT_CMD = 'tsx scripts/tools/preflight.ts';
+export const PREFLIGHT_SCRIPT_FILE = 'scripts/tools/preflight.ts';

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/package-json.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { FACTORY_SCRIPTS, PROFILES, UPDATE_SCRIPT_NAME } from './constants.js';
+import { FACTORY_SCRIPTS, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, UPDATE_SCRIPT_NAME, } from './constants.js';
 /**
  * Auto-detect the profile to install into an existing repo from its
  * `package.json`: a `factoryVersion` field means the repo was born from the
@@ -66,12 +66,12 @@ export function parsePackageJson(raw) {
  * only on a real edit) + the result for the primary `factory:update` script
  * (which drives the install messaging).
  */
-function ensureFactoryScripts(pkg) {
+function ensureFactoryScripts(pkg, extraScripts = {}) {
     const scripts = pkg.scripts ?? {};
     pkg.scripts = scripts;
     let changed = false;
     let primary = { action: 'already-correct' };
-    for (const [name, cmd] of Object.entries(FACTORY_SCRIPTS)) {
+    for (const [name, cmd] of Object.entries({ ...FACTORY_SCRIPTS, ...extraScripts })) {
         const existing = scripts[name];
         let result;
         if (existing === undefined) {
@@ -91,27 +91,41 @@ function ensureFactoryScripts(pkg) {
     return { changed, primary };
 }
 /**
- * Rename `package.json.name` and ensure the `factory:*` scripts exist,
- * preserving everything else. Returns the serialized document (with the
- * original indentation + trailing newline).
+ * The kit-local scripts to ensure for THIS repo: `preflight` only when its
+ * backing file ships here (full brain). File-gated so a core/non-Factory repo
+ * never gets an entry that shells a file it does not have — and it self-heals:
+ * the entry appears on the first install/update after the file lands.
+ */
+export function kitLocalScripts(rootDir) {
+    return existsSync(path.join(rootDir, PREFLIGHT_SCRIPT_FILE))
+        ? { [PREFLIGHT_SCRIPT_NAME]: PREFLIGHT_SCRIPT_CMD }
+        : {};
+}
+/**
+ * Rename `package.json.name` and ensure the `factory:*` scripts (+ the
+ * file-gated kit-local `extraScripts`, see `kitLocalScripts`) exist, 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) {
+export function applyPackageJsonEdits(raw, name, extraScripts = {}) {
     const indent = detectIndent(raw);
     const pkg = parsePackageJson(raw);
     pkg.name = name;
-    const { primary } = ensureFactoryScripts(pkg);
+    const { primary } = ensureFactoryScripts(pkg, extraScripts);
     const content = `${JSON.stringify(pkg, null, indent)}\n`;
     return { content, scriptAlreadyPresent: primary.action === 'conflict' };
 }
 /**
  * Surgically ensure the `factory:*` scripts (`update` / `doctor` / `status`)
- * exist in the `package.json` at `pkgPath` (design §7.4). Reads, mutates only
- * those keys, and re-serializes with the original indentation + trailing
- * newline. NEVER overwrites a divergent value and NEVER touches `name`, deps,
- * or any other script.
+ * plus the file-gated kit-local scripts (`preflight` when its file ships —
+ * `kitLocalScripts` on the package.json's own directory) exist in the
+ * `package.json` at `pkgPath` (design §7.4). Reads, mutates only those keys,
+ * 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 at least one script was added; if all are already
  * present (correct or divergent) the file is left byte-identical.
@@ -123,7 +137,7 @@ export function insertFactoryUpdateScript(pkgPath) {
     const raw = readFileSync(pkgPath, 'utf8');
     const indent = detectIndent(raw);
     const pkg = parsePackageJson(raw);
-    const { changed, primary } = ensureFactoryScripts(pkg);
+    const { changed, primary } = ensureFactoryScripts(pkg, kitLocalScripts(path.dirname(pkgPath)));
     if (changed) {
         writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
     }

package/package.json

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