@timekast/factory 1.9.0 → 1.10.0

package/dist/commands/secrets.js

@@ -0,0 +1,67 @@
+/**
+ * `factory secrets <file>` — distribute methodology secrets safely (SEC-001).
+ *
+ * Reads a master `KEY=value` file and merges it idempotently into the
+ * per-user secrets rail `~/.claude/.env`, creating it with `chmod 600` if it
+ * does not exist. Two hard guarantees:
+ *
+ *   1. Fail-closed gate — `runPreflight()` (gh installed + authed + org member)
+ *      runs FIRST, before any I/O on the target. A non-member, an expired
+ *      session, or `gh` missing from PATH aborts with a non-zero exit and the
+ *      target is never created or modified. In headless mode with no resolvable
+ *      auth, preflight throws too → the command is a no-op fail-closed.
+ *   2. No-echo — stdout lists only the KEY NAMES processed (added / updated /
+ *      skipped), never their values. A secret value never reaches the terminal.
+ *
+ * The org gate is `runPreflight()` from `lib/preflight.ts` — the public API.
+ * `preflight()` / `assertOrgMembership` are NOT public and are not called here.
+ */
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { mergeEnvFile } from '../lib/env-merge.js';
+import { runPreflight } from '../lib/preflight.js';
+/** Absolute path to the per-user secrets rail (`~/.claude/.env`). */
+export function defaultSecretsTarget() {
+    return path.join(homedir(), '.claude', '.env');
+}
+/** Render the merge outcome to stdout — KEY NAMES only, never values (no-echo). */
+function reportMerge(result, targetPath) {
+    // Surface ignored lines first (P2-2): only the candidate name (left of `=`) is
+    // shown — the value of an invalid line is never echoed.
+    if (result.invalid.length > 0) {
+        console.warn(`⚠ Ignoré ${result.invalid.length} línea(s) con nombre de clave inválido: ` +
+            `${result.invalid.join(', ')} (solo se permite [A-Za-z_][A-Za-z0-9_]*).`);
+    }
+    const total = result.added.length + result.updated.length + result.skipped.length;
+    if (total === 0) {
+        console.log('No había claves que procesar en el archivo fuente.');
+        return;
+    }
+    console.log(`✔ Secretos sincronizados en \`${targetPath}\` (permisos 600).`);
+    if (result.added.length > 0) {
+        console.log(`  Agregadas:    ${result.added.join(', ')}`);
+    }
+    if (result.updated.length > 0) {
+        console.log(`  Actualizadas: ${result.updated.join(', ')}`);
+    }
+    if (result.skipped.length > 0) {
+        console.log(`  Sin cambios:  ${result.skipped.join(', ')}`);
+    }
+    // Reaffirm the no-echo guarantee so the operator knows values were never shown.
+    console.log('ℹ Solo se muestran NOMBRES de clave; los valores nunca se imprimen.');
+}
+/**
+ * Run `factory secrets <file>`. Order is deliberate and security-relevant:
+ * preflight gate first (fail-closed — no target I/O on failure), then the merge.
+ */
+export async function secretsCommand(file, deps = {}) {
+    const preflight = deps.preflight ?? runPreflight;
+    const targetPath = deps.targetPath ?? defaultSecretsTarget();
+    // 1. Fail-closed gate. Throws BEFORE any read/write of the source or target —
+    //    a non-member / unauthenticated / headless-no-token run touches nothing.
+    await preflight();
+    // 2. Merge the source into the rail (creates it 0600 if absent, idempotent).
+    const result = await mergeEnvFile(file, targetPath);
+    // 3. Report — KEY NAMES only.
+    reportMerge(result, targetPath);
+}

package/dist/index.js

@@ -14,6 +14,7 @@ import { parseAddFlags, runAdd } from './commands/add.js';
 import { runDoctor } from './commands/doctor.js';
 import { parseNewFlags, runNew } from './commands/new.js';
 import { parsePublishArgs, runPublish } from './commands/publish.js';
+import { secretsCommand } from './commands/secrets.js';
 import { runStatus } from './commands/status.js';
 import { parseUnpublishTargets, runUnpublish } from './commands/unpublish.js';
 import { parseUpdateFlags, runUpdate } from './commands/update.js';
@@ -32,6 +33,7 @@ Comandos:
   doctor           Detecta huérfanos, conflictos y rules sin importar + aviso de seguridad
   publish <qué>    Publica el entregable (proposal|mockup|both) a proposals.timekast.mx
   unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
+  secrets <file>   Mergea un archivo KEY=value de secretos de metodología a ~/.claude/.env (chmod 600)
 
 Sobre \`new\`:
   Pregunta el perfil de forma interactiva. Los flags \`--full\` / \`--core\` lo
@@ -136,6 +138,15 @@ async function main(argv) {
             await runUnpublish(parseUnpublishTargets(rest));
             return;
         }
+        case 'secrets': {
+            const file = rest.find((arg) => !arg.startsWith('-'));
+            if (!file) {
+                throw new CLIError('Falta el archivo de secretos. Uso: `factory secrets <file>` ' +
+                    '(un archivo `KEY=value`, p.ej. el master `secrets.env`).');
+            }
+            await secretsCommand(file);
+            return;
+        }
         default:
             throw new CLIError(`Comando desconocido: \`${command}\`.\nEjecuta \`factory --help\` para ver los comandos disponibles.`);
     }

package/dist/lib/env-merge.js

@@ -0,0 +1,201 @@
+/**
+ * Non-naive `.env` parser + merger for the `factory secrets` rail (SEC-001).
+ *
+ * Merges a SOURCE `.env`-style file into a TARGET (`~/.claude/.env` in
+ * production), idempotently and additively:
+ *   - keys in source that are absent in target → ADDED
+ *   - keys in source that already exist with a different value → UPDATED
+ *   - keys in source whose value already matches target → SKIPPED (no churn)
+ *   - keys in target NOT mentioned in source → preserved verbatim
+ *   - comment lines (`# ...`) + blank lines in target → preserved verbatim
+ *   - the target's trailing newline → preserved
+ *   - target absent → created with `chmod 600` BEFORE the first write
+ *
+ * "Non-naive" parsing rules (the sharp cases the tests pin):
+ *   - split a `KEY=value` line on the FIRST `=` only — a value may contain `=`
+ *     (`KEY=a=b=c` → value `a=b=c`).
+ *   - a value wrapped in single or double quotes keeps its quotes literally
+ *     (`KEY="val"` and `KEY='val'` round-trip byte-for-byte).
+ *   - a `#` INSIDE a quoted value is literal, NOT a comment start
+ *     (`KEY="val#hash"` keeps `#hash`). A `#` at column 0 (after optional
+ *     whitespace) is a comment line and is never parsed as a key.
+ *
+ * The merge is line-oriented and surgical: an updated key is rewritten in place
+ * (its original line position is kept), so re-running with the same source is a
+ * no-op on disk (idempotent — every key SKIPs the second time).
+ *
+ * Known limitation (documented, not blocked — SEC-001 §8): concurrent writers
+ * on the same target may corrupt it (no file lock). The command is manual.
+ */
+import { chmodSync, existsSync, lstatSync, readFileSync, writeFileSync } from 'node:fs';
+/**
+ * True when a line is a comment or blank — never parsed as a key. A comment is
+ * a `#` at the first non-whitespace column; a blank line is empty/whitespace.
+ */
+function isCommentOrBlank(line) {
+    const trimmed = line.trimStart();
+    return trimmed === '' || trimmed.startsWith('#');
+}
+/**
+ * A valid env-var name: a letter or underscore, then letters/digits/underscores
+ * (POSIX shell name shape). The source file is the one fully-untrusted input the
+ * tool otherwise trusts, so a line whose key fails this shape (`export FOO`,
+ * `; rm -rf`, `FOO BAR`) is NOT written to the rail — it's reported as invalid
+ * (P2-2 hardening). Inert as `.env` data, but we refuse to write surprising keys.
+ */
+function isValidKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+/**
+ * Parse a single `KEY=value` line, splitting on the FIRST `=` only. Returns null
+ * for comment/blank lines, lines with no `=`, and lines whose key is not a valid
+ * env-var name (all preserved as-is by the target rewrite, never treated as a
+ * key). The key is trimmed; the value keeps its quotes and inner characters
+ * literally (only trailing whitespace, which a real `.env` loader ignores, is
+ * stripped so re-runs stay idempotent).
+ */
+function parseLine(line) {
+    if (isCommentOrBlank(line))
+        return null;
+    const eq = line.indexOf('=');
+    if (eq === -1)
+        return null;
+    const key = line.slice(0, eq).trim();
+    if (key === '')
+        return null;
+    if (!isValidKey(key))
+        return null;
+    const value = line.slice(eq + 1).replace(/\s+$/, '');
+    return { key, value };
+}
+/**
+ * Build the canonical `KEY=value` line for a pair. Centralized so source parse
+ * and target rewrite emit identical text (the idempotency contract depends on
+ * byte-equality between a freshly written line and the one parsed back).
+ */
+function renderLine(pair) {
+    return `${pair.key}=${pair.value}`;
+}
+/**
+ * Read `.env` text, failing closed with a clear error on non-UTF-8 input (SEC-001
+ * §8 edge case). `readFileSync(..., 'utf8')` does not throw on invalid bytes — it
+ * substitutes U+FFFD — so we detect the replacement character and reject rather
+ * than silently corrupt a secret. An empty/missing target is the caller's
+ * concern; this only runs on files known to exist.
+ */
+function readEnvText(filePath) {
+    const text = readFileSync(filePath, 'utf8');
+    if (text.includes('�')) {
+        throw new Error(`El archivo \`${filePath}\` no es UTF-8 válido (bytes no decodificables). ` +
+            'Revisa su codificación; no se modificó nada.');
+    }
+    return text;
+}
+/**
+ * Parse the SOURCE file's key/value pairs, last-write-wins on duplicate keys (a
+ * source listing a key twice resolves to its final value — mirrors how a real
+ * loader reads top-to-bottom). Order of first appearance is preserved for the
+ * keys that get appended to the target. Lines whose key fails `isValidKey` are
+ * NOT merged — their candidate name (value-free) is collected in `invalid` so
+ * the command can warn the operator (P2-2).
+ */
+function parseSource(text) {
+    const byKey = new Map();
+    const order = [];
+    const invalid = [];
+    for (const line of text.split('\n')) {
+        if (isCommentOrBlank(line))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue; // no '=' — not a key assignment; ignored in a source file
+        const key = line.slice(0, eq).trim();
+        if (key === '')
+            continue;
+        if (!isValidKey(key)) {
+            if (!invalid.includes(key))
+                invalid.push(key); // candidate only — never the value
+            continue;
+        }
+        const value = line.slice(eq + 1).replace(/\s+$/, '');
+        if (!byKey.has(key))
+            order.push(key);
+        byKey.set(key, value);
+    }
+    return { pairs: order.map((key) => ({ key, value: byKey.get(key) })), invalid };
+}
+/**
+ * Merge `sourcePath` into `targetPath`. See the module docstring for the full
+ * contract. Async to match the CLI's command surface (`mergeEnvFile(...)` is
+ * awaited), though the FS ops are synchronous under the hood — the cost is a
+ * couple of small reads/writes, and sync keeps the chmod-before-write ordering
+ * race-free.
+ *
+ * @throws when the source is missing/unreadable, or either file is not UTF-8.
+ */
+export async function mergeEnvFile(sourcePath, targetPath) {
+    // Source must exist and be readable — fail closed with a clear message (the
+    // command never half-writes a target off a missing/garbled source).
+    if (!existsSync(sourcePath)) {
+        throw new Error(`No encontré el archivo fuente \`${sourcePath}\`.`);
+    }
+    const { pairs: sourcePairs, invalid } = parseSource(readEnvText(sourcePath));
+    // Reject a symlink target explicitly (SEC-001 §8): writing through a symlink
+    // could redirect secrets outside `~/.claude/`. We refuse rather than follow.
+    if (existsSync(targetPath) && lstatSync(targetPath).isSymbolicLink()) {
+        throw new Error(`El destino \`${targetPath}\` es un symlink. Por seguridad no escribo a través de symlinks; ` +
+            'apunta a un archivo regular.');
+    }
+    // Target absent → create empty with 0600 BEFORE writing any secret, so the
+    // file is never world-readable even for the instant between create and chmod.
+    const targetExists = existsSync(targetPath);
+    if (!targetExists) {
+        writeFileSync(targetPath, '', { mode: 0o600 });
+    }
+    const targetText = targetExists ? readEnvText(targetPath) : '';
+    // Preserve the trailing-newline shape of the original target: an empty file and
+    // a file ending in `\n` both round-trip; a file without a final newline gets one
+    // (a well-formed `.env` ends in a newline — POSIX text-file convention).
+    const hadTrailingNewline = targetText.endsWith('\n');
+    const lines = targetText.length === 0 ? [] : targetText.replace(/\n$/, '').split('\n');
+    const sourceByKey = new Map(sourcePairs.map((p) => [p.key, p.value]));
+    const seenInTarget = new Set();
+    const added = [];
+    const updated = [];
+    const skipped = [];
+    // Rewrite existing target lines in place: a key present in source is updated
+    // (or skipped if unchanged); comments, blanks, and untouched keys pass through.
+    const rewritten = lines.map((line) => {
+        const pair = parseLine(line);
+        if (!pair)
+            return line; // comment / blank / malformed — preserve verbatim
+        seenInTarget.add(pair.key);
+        if (!sourceByKey.has(pair.key))
+            return line; // key not in source — preserve
+        const nextValue = sourceByKey.get(pair.key);
+        if (nextValue === pair.value) {
+            skipped.push(pair.key);
+            return line;
+        }
+        updated.push(pair.key);
+        return renderLine({ key: pair.key, value: nextValue });
+    });
+    // Append source keys that were not already in the target, in source order.
+    for (const pair of sourcePairs) {
+        if (seenInTarget.has(pair.key))
+            continue;
+        added.push(pair.key);
+        rewritten.push(renderLine(pair));
+    }
+    // Reassemble. Restore the trailing newline when the original had one (or when
+    // we created/append-grew the file — a `.env` should end in `\n`).
+    const body = rewritten.join('\n');
+    const shouldEndWithNewline = hadTrailingNewline || !targetExists || rewritten.length > lines.length;
+    const finalText = shouldEndWithNewline && rewritten.length > 0 ? `${body}\n` : body;
+    writeFileSync(targetPath, finalText, { mode: 0o600 });
+    // Re-assert 0600 even when the file already existed (it may have been created
+    // with looser perms before this rail existed — SEC-001 §8). `writeFileSync`'s
+    // `mode` is ignored for an existing file, so chmod explicitly.
+    chmodSync(targetPath, 0o600);
+    return { added, updated, skipped, invalid };
+}

package/package.json

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