@timekast/factory 2.3.0 → 2.4.0

package/dist/lib/prune-tiers.js

@@ -0,0 +1,253 @@
+/**
+ * The CLI's reader of `.claude/policy/prune-tiers.json` (`factory prune`) — which kit paths a
+ * pruned repo shares with its collaborators and which stay local to the members.
+ *
+ * TWIN of `scripts/tools/lib/prune-tiers.mjs`, which the pre-commit guard and skill-lint use:
+ * the published CLI cannot import repo code, so the rule lives twice and
+ * `cli/tests/unit/prune-tiers-parity.test.ts` runs one corpus through both. Change one, change
+ * the other.
+ *
+ * The rule: an entry is a path pattern; a trailing `/` names a directory (everything below
+ * it), otherwise one file; `*` matches within a single segment. The matching entry with the
+ * most segments decides (`restrict` | `share`); none → `unclassified`; a tie between the two
+ * kinds → `ambiguous`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { CLIError } from './cli-error.js';
+import { MANAGED_BLOCK_END, MANAGED_BLOCK_START, PRUNE_FILE, TIMEKAST_DIR } from './constants.js';
+/** Repo-relative path of the registry. */
+export const PRUNE_TIERS_PATH = '.claude/policy/prune-tiers.json';
+/** Repo-relative path of the switch. */
+export const PRUNE_MARKER_PATH = `${TIMEKAST_DIR}/${PRUNE_FILE}`;
+/** The tier `prepare` applies when none is named — the only one today. */
+export const DEFAULT_PRUNE_TIER = 'collab';
+/**
+ * Markers of the block CMLL's cut wrote by hand before this command existed. `syncManagedBlock`
+ * only knows the kit's markers, so it would add a second block beside this one; `prepare`
+ * removes it first.
+ */
+export const LEGACY_COLLAB_START = '# >>> timekast:collab';
+export const LEGACY_COLLAB_END = '# <<< timekast:collab';
+function segmentsOf(entry) {
+    return entry.replace(/\/$/, '').split('/');
+}
+function segmentMatches(pattern, segment) {
+    if (!pattern.includes('*'))
+        return pattern === segment;
+    const rx = new RegExp(`^${pattern
+        .split('*')
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('[^/]*')}$`);
+    return rx.test(segment);
+}
+/** Does `entry` match `relPath`? A directory entry matches anything strictly below it. */
+export function entryMatches(entry, relPath) {
+    const isDir = entry.endsWith('/');
+    const want = segmentsOf(entry);
+    const have = relPath.split('/');
+    if (isDir ? have.length <= want.length : have.length !== want.length)
+        return false;
+    return want.every((pattern, i) => segmentMatches(pattern, have[i]));
+}
+/** Classify one repo-relative POSIX path under a tier. */
+export function classifyPath(tier, relPath) {
+    let bestDepth = -1;
+    let kinds = new Set();
+    for (const kind of ['restrict', 'share']) {
+        for (const entry of tier[kind]) {
+            if (!entryMatches(entry, relPath))
+                continue;
+            const depth = segmentsOf(entry).length;
+            if (depth > bestDepth) {
+                bestDepth = depth;
+                kinds = new Set([kind]);
+            }
+            else if (depth === bestDepth) {
+                kinds.add(kind);
+            }
+        }
+    }
+    if (kinds.size === 0)
+        return 'unclassified';
+    if (kinds.size > 1)
+        return 'ambiguous';
+    return [...kinds][0];
+}
+export function isRestricted(tier, relPath) {
+    return classifyPath(tier, relPath) === 'restrict';
+}
+/** Form errors of a parsed registry (empty = valid). Mirror of the `.mjs` validator. */
+export function validatePruneTiers(data) {
+    const errors = [];
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        return ['(root) — must be an object'];
+    }
+    const tiers = data.tiers;
+    if (typeof tiers !== 'object' || tiers === null || Array.isArray(tiers)) {
+        return ['tiers — must be an object of named tiers'];
+    }
+    if (Object.keys(tiers).length === 0)
+        errors.push('tiers — must declare at least one tier');
+    for (const [name, raw] of Object.entries(tiers)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            errors.push(`tiers.${name} — the tier name must be kebab-case`);
+        }
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            errors.push(`tiers.${name} — must be an object`);
+            continue;
+        }
+        const tier = raw;
+        for (const key of Object.keys(tier)) {
+            if (!['description', 'restrict', 'share'].includes(key)) {
+                errors.push(`tiers.${name}.${key} — unknown key (allowed: description, restrict, share)`);
+            }
+        }
+        for (const kind of ['restrict', 'share']) {
+            const list = tier[kind];
+            if (!Array.isArray(list) || list.length === 0) {
+                errors.push(`tiers.${name}.${kind} — must be a non-empty array of path patterns`);
+                continue;
+            }
+            list.forEach((entry, i) => {
+                if (typeof entry !== 'string' || entry.trim() !== entry || entry === '') {
+                    errors.push(`tiers.${name}.${kind}[${i}] — must be a non-empty string without surrounding spaces`);
+                    return;
+                }
+                if (entry.startsWith('/') || entry.includes('\\') || entry.includes('//')) {
+                    errors.push(`tiers.${name}.${kind}[${i}] — "${entry}" must be repo-relative, POSIX`);
+                }
+                if (/[?[\]{}!]/.test(entry) || entry.includes('**')) {
+                    errors.push(`tiers.${name}.${kind}[${i}] — "${entry}" may only use \`*\` within one segment`);
+                }
+                if (segmentsOf(entry).some((seg) => seg === '' || seg === '.' || seg === '..')) {
+                    errors.push(`tiers.${name}.${kind}[${i}] — "${entry}" has an empty or relative segment`);
+                }
+            });
+        }
+        if (!Array.isArray(tier.restrict) || !Array.isArray(tier.share))
+            continue;
+        const restrict = tier.restrict;
+        const share = tier.share;
+        const all = [...restrict, ...share];
+        const dupes = all.filter((e, i) => all.indexOf(e) !== i);
+        for (const dupe of new Set(dupes)) {
+            errors.push(`tiers.${name} — "${dupe}" is listed more than once`);
+        }
+        for (const entry of share) {
+            for (const dir of restrict.filter((r) => r.endsWith('/'))) {
+                if (!entry.startsWith(dir))
+                    continue;
+                if (segmentsOf(entry).length !== segmentsOf(dir).length + 1) {
+                    errors.push(`tiers.${name}.share — "${entry}" sits more than one level below the restricted ` +
+                        `directory "${dir}"; a re-include only works for a direct child`);
+                }
+            }
+        }
+        for (const entry of restrict) {
+            for (const dir of restrict.filter((r) => r !== entry && r.endsWith('/'))) {
+                if (entry.startsWith(dir)) {
+                    errors.push(`tiers.${name}.restrict — "${entry}" is already covered by "${dir}"; drop one`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+/** The tier's `.gitignore` lines, without markers. Mirror of the `.mjs` `gitignoreLines`. */
+export function gitignoreLines(tier) {
+    const depth = (e) => segmentsOf(e).length;
+    const ordered = [...tier.restrict].sort((a, b) => depth(a) - depth(b) || a.localeCompare(b));
+    const lines = [];
+    for (const entry of ordered) {
+        const children = entry.endsWith('/')
+            ? tier.share.filter((s) => s.startsWith(entry)).sort()
+            : [];
+        if (children.length === 0) {
+            lines.push(`/${entry}`);
+            continue;
+        }
+        lines.push(`/${entry}*`);
+        for (const child of children)
+            lines.push(`!/${child}`);
+    }
+    return lines;
+}
+/** The managed `.gitignore` block (markers inclusive) of one tier. */
+export function renderGitignoreBlock(tierName, tier) {
+    return [
+        `${MANAGED_BLOCK_START} (prune tier \`${tierName}\` — regenerated by \`factory prune\` and \`factory update\`; do not edit) >>>`,
+        '# Kit paths kept LOCAL to the members of the org: they never enter this repository, so a',
+        '# collaborator never sees them. Generated from .claude/policy/prune-tiers.json; the switch',
+        '# is .timekast/prune.json. Anything not listed here is shared.',
+        ...gitignoreLines(tier),
+        `${MANAGED_BLOCK_END} <<<`,
+    ].join('\n');
+}
+/** Remove the hand-written `timekast:collab` block (markers inclusive), if present. */
+export function stripLegacyCollabBlock(content) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const start = lines.findIndex((l) => l.trimStart().startsWith(LEGACY_COLLAB_START));
+    if (start === -1)
+        return { content, removed: false };
+    let end = lines.length - 1;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (lines[i].trimStart().startsWith(LEGACY_COLLAB_END)) {
+            end = i;
+            break;
+        }
+    }
+    const kept = [...lines.slice(0, start), ...lines.slice(end + 1)];
+    while (kept.length > 0 && kept[kept.length - 1].trim() === '')
+        kept.pop();
+    return { content: kept.length > 0 ? `${kept.join('\n')}\n` : '', removed: true };
+}
+/** Read + validate the registry under `dir` (a repo root or a staged tarball). */
+export function readPruneTiers(dir) {
+    const file = path.join(dir, PRUNE_TIERS_PATH);
+    if (!existsSync(file)) {
+        throw new CLIError(`No existe \`${PRUNE_TIERS_PATH}\`. Corre \`factory update\` para traer la versión del kit que lo incluye.`);
+    }
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new CLIError(`\`${PRUNE_TIERS_PATH}\` no es JSON válido: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const errors = validatePruneTiers(data);
+    if (errors.length > 0) {
+        throw new CLIError(`\`${PRUNE_TIERS_PATH}\` tiene errores de forma:\n  • ${errors.join('\n  • ')}`);
+    }
+    return data;
+}
+/** Look up one tier, naming the valid ones when it does not exist. */
+export function getTier(tiers, name) {
+    const tier = tiers.tiers[name];
+    if (!tier) {
+        throw new CLIError(`El tier \`${name}\` no existe en \`${PRUNE_TIERS_PATH}\`. Tiers disponibles: ${Object.keys(tiers.tiers).join(', ')}.`);
+    }
+    return tier;
+}
+/** The switch, or `null` when this repo is not pruned. */
+export function readPruneMarker(rootDir) {
+    const file = path.join(rootDir, PRUNE_MARKER_PATH);
+    if (!existsSync(file))
+        return null;
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new CLIError(`\`${PRUNE_MARKER_PATH}\` no es JSON válido; corrígelo o vuelve a correr \`factory prune prepare\`.`);
+    }
+    const marker = data;
+    if (typeof marker?.tier !== 'string' || typeof marker.at !== 'string') {
+        throw new CLIError(`\`${PRUNE_MARKER_PATH}\` debe tener la forma { "tier": "<nombre>", "at": "<fecha ISO>" }.`);
+    }
+    return { tier: marker.tier, at: marker.at };
+}
+export function writePruneMarker(rootDir, marker) {
+    mkdirSync(path.join(rootDir, TIMEKAST_DIR), { recursive: true });
+    writeFileSync(path.join(rootDir, PRUNE_MARKER_PATH), `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+}

package/dist/lib/prune-update.js

@@ -0,0 +1,78 @@
+/**
+ * `factory update` in a pruned repo (`factory prune`): keep the tier's `.gitignore` block in
+ * step with the kit, and compute what the brain commit must untrack and publish.
+ *
+ * Everything here is gated on `.timekast/prune.json`. Without it `planPruneMaintenance`
+ * returns `null` and the update behaves exactly as in a repo that was never pruned.
+ *
+ * The registry is read from the STAGED tarball, not from the repo: the tier the release ships
+ * is the one the commit has to honor, including a path that moved from restricted to shared.
+ * Such a path is in the `unchanged` bucket when its content did not change, so the update
+ * would never write it — it sits on the member's disk, untracked, and would never be
+ * published unless this module names it.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { GITIGNORE_FILE, MANAGED_BLOCK_START } from './constants.js';
+import { syncManagedBlock } from './gitattributes.js';
+import { trackedFiles } from './prune-git.js';
+import { LEGACY_COLLAB_START, PRUNE_MARKER_PATH, PRUNE_TIERS_PATH, getTier, isRestricted, readPruneMarker, readPruneTiers, renderGitignoreBlock, stripLegacyCollabBlock, } from './prune-tiers.js';
+/** Does `.gitignore` carry a prune block (the kit's or CMLL's hand-written one)? */
+function hasPruneBlock(rootDir) {
+    const file = path.join(rootDir, GITIGNORE_FILE);
+    if (!existsSync(file))
+        return false;
+    const content = readFileSync(file, 'utf8');
+    return (content.includes(LEGACY_COLLAB_START) ||
+        content.split('\n').some((l) => l.startsWith(MANAGED_BLOCK_START) && l.includes('prune tier')));
+}
+/**
+ * Regenerate the block and plan the commit's untrack/publish sets. Best-effort like the other
+ * dotfile syncs: a problem is reported and the update (already applied) stands.
+ *
+ * @param manifestPaths every path of the NEW manifest (what the kit ships now).
+ */
+export async function planPruneMaintenance(rootDir, stagedDir, manifestPaths) {
+    let marker;
+    try {
+        marker = readPruneMarker(rootDir);
+    }
+    catch (err) {
+        console.warn(`Aviso: ${err instanceof Error ? err.message : String(err)} No mantuve el tier.`);
+        return null;
+    }
+    if (!marker) {
+        if (hasPruneBlock(rootDir)) {
+            console.warn(`Aviso: \`${GITIGNORE_FILE}\` tiene el bloque de un repo compartido pero falta ` +
+                `\`${PRUNE_MARKER_PATH}\`, así que el guard del pre-commit está apagado. ` +
+                'Si el repo se comparte con colaboradores, corre `factory prune prepare`.');
+        }
+        return null;
+    }
+    try {
+        const source = existsSync(path.join(stagedDir, PRUNE_TIERS_PATH)) ? stagedDir : rootDir;
+        const tier = getTier(readPruneTiers(source), marker.tier);
+        const gitignorePath = path.join(rootDir, GITIGNORE_FILE);
+        if (existsSync(gitignorePath)) {
+            const stripped = stripLegacyCollabBlock(readFileSync(gitignorePath, 'utf8'));
+            if (stripped.removed)
+                writeFileSync(gitignorePath, stripped.content, 'utf8');
+        }
+        const { action } = syncManagedBlock(rootDir, renderGitignoreBlock(marker.tier, tier), GITIGNORE_FILE);
+        if (action !== 'unchanged') {
+            console.log(`✔ \`${GITIGNORE_FILE}\`: bloque del tier \`${marker.tier}\` sincronizado.`);
+        }
+        const tracked = new Set(await trackedFiles(rootDir));
+        return {
+            tierName: marker.tier,
+            tier,
+            untrack: [...tracked].filter((p) => isRestricted(tier, p)),
+            publish: manifestPaths.filter((p) => !tracked.has(p) && !isRestricted(tier, p) && existsSync(path.join(rootDir, p))),
+        };
+    }
+    catch (err) {
+        console.warn(`Aviso: no se pudo mantener el tier \`${marker.tier}\` ` +
+            `(${err instanceof Error ? err.message : String(err)}); el cerebro se instaló igual.`);
+        return null;
+    }
+}

package/package.json

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