@timekast/factory 1.0.0 → 1.1.0

package/dist/commands/doctor.js

@@ -16,8 +16,9 @@
  * No lockfile (pre-CLI repo) → delegate to the "run factory:update" advice, exit
  * 0, never abort (same pattern as `status` / the §8 edge case).
  */
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
+import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLAUDE_MD_FILE } from '../lib/constants.js';
 import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
 import { detectRepo } from '../lib/repo-detection.js';
@@ -42,29 +43,6 @@ export const A1_WARNING = 'Aviso de seguridad (A1): el boilerplate `src/` y sus
     'dependencia) NO llega por este canal. El canal de parches de `src/` es EPIC 2 ' +
     '(update agentico con merge inteligente), aún no disponible. Mantén `src/` y tus ' +
     'dependencias al día por tu cuenta mientras tanto.';
-/**
- * Recursively collect repo-relative POSIX paths of files under `.claude/`. Only
- * descends into `.claude/`; `src/` and everything else is invisible (design
- * §7.2). Mirrors the `update` engine's `collectClaudePaths`.
- */
-function collectClaudePaths(rootDir) {
-    const out = [];
-    const walk = (rel) => {
-        const abs = path.join(rootDir, rel);
-        if (!existsSync(abs))
-            return;
-        if (statSync(abs).isDirectory()) {
-            for (const entry of readdirSync(abs)) {
-                walk(path.posix.join(rel, entry));
-            }
-        }
-        else {
-            out.push(rel);
-        }
-    };
-    walk('.claude');
-    return out;
-}
 /**
  * Concatenate the body of the reserved "on-demand reference" section of CLAUDE.md
  * — the lines under a heading matching `ON_DEMAND_HEADING_RE`, until the next

package/dist/commands/update.js

@@ -33,11 +33,12 @@
  * `update` NEVER touches `src/` — files outside the lockfile/manifest are
  * invisible (design §9 out-of-scope).
  */
-import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 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 { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
@@ -64,30 +65,6 @@ async function acquireFromRelease(profile) {
     const manifest = validateStagedManifest(stagedDir, manifestRaw);
     return { stagedDir, manifest, tmpRoot };
 }
-/**
- * Recursively collect repo-relative paths of files under `.claude/` plus any
- * tracked root files the manifest references at the top level. Used both for
- * disk hashing and auto-register path-match. Only descends into `.claude/`;
- * `src/` and everything else is invisible (design §7.2).
- */
-function collectClaudePaths(rootDir) {
-    const out = [];
-    const walk = (rel) => {
-        const abs = path.join(rootDir, rel);
-        if (!existsSync(abs))
-            return;
-        if (statSync(abs).isDirectory()) {
-            for (const entry of readdirSync(abs)) {
-                walk(path.posix.join(rel, entry));
-            }
-        }
-        else {
-            out.push(rel);
-        }
-    };
-    walk('.claude');
-    return out;
-}
 /**
  * Hash the disk content (normalized) of every path in `paths` that exists.
  * A missing file is simply absent from the returned map.

package/dist/lib/claude-paths.js

@@ -0,0 +1,68 @@
+/**
+ * Collect the repo-relative POSIX paths of files under `.claude/`, EXCLUDING
+ * gitignored ones. Shared by `update` (legacy auto-register ambiguous report)
+ * and `doctor` (orphan report) so neither flags a dev-local, gitignored file
+ * (`settings.local.json`, `transitions/`, `.DS_Store`) as "ambiguous"/"orphan" —
+ * those are never kit-managed, so surfacing them is pure noise.
+ *
+ * Only descends into `.claude/`; `src/` and everything else is invisible
+ * (design §7.2).
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+/**
+ * Fallback ignore set, used only when `git check-ignore` is unavailable (no git
+ * binary, or the dir is not a git repo). Mirrors the kit's own `.gitignore`
+ * entries for `.claude/`. The git path is authoritative when present.
+ */
+const IGNORE_FALLBACK_RE = /(^|\/)(\.DS_Store|settings\.local\.json)$|(^|\/)transitions\//;
+/** Recursively gather repo-relative POSIX paths of files under `.claude/`. */
+function walkClaude(rootDir) {
+    const out = [];
+    const walk = (rel) => {
+        const abs = path.join(rootDir, rel);
+        if (!existsSync(abs))
+            return;
+        if (statSync(abs).isDirectory()) {
+            for (const entry of readdirSync(abs))
+                walk(path.posix.join(rel, entry));
+        }
+        else {
+            out.push(rel);
+        }
+    };
+    walk('.claude');
+    return out;
+}
+/**
+ * Drop the gitignored paths from `paths`. Uses `git check-ignore --stdin` (the
+ * authoritative source — respects nested `.gitignore`, negations, etc.); falls
+ * back to `IGNORE_FALLBACK_RE` when git is missing or the dir is not a repo.
+ *
+ * `git check-ignore` exit codes: 0 = some paths matched (printed), 1 = none
+ * matched (empty output), 128 = error / not a repo. `spawnSync` does not throw,
+ * so 0 and 1 both yield usable stdout; >1 or a spawn error → fallback.
+ */
+function dropGitignored(rootDir, paths) {
+    if (paths.length === 0)
+        return paths;
+    const res = spawnSync('git', ['-C', rootDir, 'check-ignore', '--stdin'], {
+        input: paths.join('\n'),
+        encoding: 'utf8',
+    });
+    if (res.error || res.status === null || res.status > 1) {
+        return paths.filter((p) => !IGNORE_FALLBACK_RE.test(p));
+    }
+    const ignored = new Set((res.stdout || '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean));
+    return paths.filter((p) => !ignored.has(p));
+}
+/**
+ * Repo-relative POSIX paths of NON-gitignored files under `.claude/`.
+ */
+export function collectClaudePaths(rootDir) {
+    return dropGitignored(rootDir, walkClaude(rootDir));
+}

package/dist/lib/constants.js

@@ -26,9 +26,24 @@ export const LOCKFILE_FILE = 'lockfile.json';
  * exists on disk (path-match path). See `diffLockfiles` + the install commands.
  */
 export const CLAUDE_MD_FILE = 'CLAUDE.md';
-/** The script the CLI injects into a derived project's package.json. */
+/** 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
 // is NOT a dependency (B3): a bare `@timekast/factory update` would be
 // "command not found". npx resolves the published package on demand.
 export const UPDATE_SCRIPT_CMD = 'npx @timekast/factory update';
+export const DOCTOR_SCRIPT_NAME = 'factory:doctor';
+export const DOCTOR_SCRIPT_CMD = 'npx @timekast/factory doctor';
+export const STATUS_SCRIPT_NAME = 'factory:status';
+export const STATUS_SCRIPT_CMD = 'npx @timekast/factory status';
+/**
+ * All convenience scripts the installer ensures in a Node derivative's
+ * package.json (each: add if missing, never overwrite a divergent value). Keyed
+ * by script name → command. `factory:update` is the primary (drives the install
+ * messaging); `doctor`/`status` are read-only diagnostics with no other alias.
+ */
+export const FACTORY_SCRIPTS = {
+    [UPDATE_SCRIPT_NAME]: UPDATE_SCRIPT_CMD,
+    [DOCTOR_SCRIPT_NAME]: DOCTOR_SCRIPT_CMD,
+    [STATUS_SCRIPT_NAME]: STATUS_SCRIPT_CMD,
+};

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 { PROFILES, UPDATE_SCRIPT_CMD, UPDATE_SCRIPT_NAME } from './constants.js';
+import { FACTORY_SCRIPTS, 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
@@ -58,26 +58,40 @@ export function parsePackageJson(raw) {
     }
 }
 /**
- * Pure core of the script insertion: mutate `pkg.scripts` in place to ensure
- * `factory:update` exists, never overwriting a divergent value. Shared by
+ * Pure core of the script insertion: mutate `pkg.scripts` in place to ensure ALL
+ * `factory:*` convenience scripts exist (`update` / `doctor` / `status`), adding
+ * each if missing and NEVER overwriting a divergent value (§7.4). Shared by
  * `applyPackageJsonEdits` (the `new` flow) and `insertFactoryUpdateScript`
- * (the `update` flow) so both follow the same §7.4 rule.
+ * (the `update` flow). Returns whether anything changed (so the caller writes
+ * only on a real edit) + the result for the primary `factory:update` script
+ * (which drives the install messaging).
  */
-function ensureUpdateScript(pkg) {
+function ensureFactoryScripts(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' };
+    let changed = false;
+    let primary = { action: 'already-correct' };
+    for (const [name, cmd] of Object.entries(FACTORY_SCRIPTS)) {
+        const existing = scripts[name];
+        let result;
+        if (existing === undefined) {
+            scripts[name] = cmd;
+            changed = true;
+            result = { action: 'added' };
+        }
+        else if (existing === cmd) {
+            result = { action: 'already-correct' };
+        }
+        else {
+            result = { action: 'conflict', existingValue: existing };
+        }
+        if (name === UPDATE_SCRIPT_NAME)
+            primary = result;
     }
-    return { action: 'conflict', existingValue: existing };
+    return { changed, primary };
 }
 /**
- * Rename `package.json.name` and ensure the `factory:update` script exists,
+ * Rename `package.json.name` and ensure the `factory:*` scripts exist,
  * preserving everything else. Returns the serialized document (with the
  * original indentation + trailing newline).
  *
@@ -88,31 +102,32 @@ export function applyPackageJsonEdits(raw, name) {
     const indent = detectIndent(raw);
     const pkg = parsePackageJson(raw);
     pkg.name = name;
-    const result = ensureUpdateScript(pkg);
+    const { primary } = ensureFactoryScripts(pkg);
     const content = `${JSON.stringify(pkg, null, indent)}\n`;
-    return { content, scriptAlreadyPresent: result.action === 'conflict' };
+    return { content, scriptAlreadyPresent: primary.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.
+ * 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.
  *
- * Writes the file only when something actually changed (`added`); for
- * `already-correct` and `conflict` the file is left byte-identical.
+ * 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.
  *
  * @param pkgPath Absolute path to the derived project's `package.json`.
- * @returns What happened, plus the existing value when it conflicts.
+ * @returns The result for the primary `factory:update` script (+ existing value on conflict).
  */
 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') {
+    const { changed, primary } = ensureFactoryScripts(pkg);
+    if (changed) {
         writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
     }
-    return result;
+    return primary;
 }
 /**
  * Surgically set the derived project's `package.json.agentKitVersion` to the

package/package.json

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