@timekast/factory 1.2.0 → 1.3.0

package/dist/commands/update.js

@@ -40,7 +40,8 @@ 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, PROFILES, } from '../lib/constants.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';
@@ -168,9 +169,8 @@ 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);
     rmSync(state.stagedDir, { recursive: true, force: true });
     console.log('✔ `update` retomado y completado.');
 }
@@ -191,15 +191,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 +228,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) {
@@ -335,9 +380,7 @@ 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);
         reportSummary(diff, manifest);
     }
     finally {
@@ -394,9 +437,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/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/package.json

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