@timekast/factory 1.19.0 → 1.20.0

package/dist/lib/backlog-parse.js

@@ -0,0 +1,208 @@
+/**
+ * Parser for the backlog issue/epic markdown blockquote header — the shared
+ * reader `push` (BSYNC-005) and `sync` (BSYNC-006) use instead of each re-deriving
+ * how to pull `Issue ID` / `Status` / `Priority` / `Story Points` / `Epic` /
+ * `Skills` / `Depends on` / `Board` (+ the BSYNC-007 `Backlog UUID` / `MoSCoW`) out
+ * of a `> **Label:** value` blockquote.
+ *
+ * The regex shape is CALQUED from `scripts/tools/update-board.ts` (`parseStatus` /
+ * `parseStoryPoints` / `parseEpic` / `parseTitle`) — same `[>-] \*\*(Label):\*\*`
+ * anchor — so the two parsers can never drift on the tooling-critical fields. It is
+ * NOT a re-implementation of a new format: it extends the same one.
+ *
+ * DEFENSIVE TOLERANCE (issue §8): the BSYNC-007 lines (`Backlog UUID` / `MoSCoW` /
+ * `Board`) do not exist in legacy issues. Every field parser degrades to a default
+ * (`Board` → `story`, `MoSCoW` → `undefined`, `Backlog UUID` → the deterministic v5
+ * fallback) when its line is absent, and the presence of the new lines never breaks
+ * the existing fields. This module is PURE (operates on a `content: string`), so the
+ * parser itself needs no FS seam; the one disk touch (credential resolution) lives in
+ * `backlog-mapping.ts` behind an injectable reader.
+ */
+import { createHash } from 'node:crypto';
+import { mapMoscow } from './backlog-mapping.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Field-level regex helpers (calqued from update-board.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Escape a label for safe interpolation into a `RegExp` (labels are literal text). */
+function escapeLabel(label) {
+    return label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Capture the value of a LINE-START blockquote field: `> **Label:** value`. Mirrors
+ * `update-board.ts`'s `[>-] \*\*Label:\*\*` anchor (accepts `>` or `-` bullet). Returns
+ * the trimmed rest of the line, or `undefined` if the field is absent.
+ *
+ * NOTE: fields that share a line with another via a `·` separator (e.g. `Depends on`
+ * sits beside `Parallelizable`) capture the whole tail here; the field-specific parser
+ * splits on `·`. `Story Points` is the one MID-LINE field (`**Effort:** M · **Story
+ * Points:** 5`) and uses its own loose regex below, exactly as `update-board.ts` does.
+ */
+export function matchBlockquoteField(content, label) {
+    const match = content.match(new RegExp(`[>-] \\*\\*${escapeLabel(label)}:\\*\\* ([^\\n]*)`, 'i'));
+    return match ? match[1].trim() : undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Individual field parsers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Bucket the `> **Status:**` line to a {@link LocalStatus} — calqued VERBATIM from
+ * `update-board.ts` `parseStatus()` (including the Spanish synonyms + `Deferred`/
+ * `Postponed` both bucketing to `postponed`). Default `todo`.
+ */
+export function parseStatus(content) {
+    if (content.match(/[>-] \*\*(Status|Estado):\*\*.*(✅|Completed|Completado|Done)/i))
+        return 'done';
+    if (content.match(/[>-] \*\*(Status|Estado):\*\*.*(In Progress|En Progreso|🚧|Working)/i))
+        return 'in-progress';
+    if (content.match(/[>-] \*\*(Status|Estado):\*\*.*(Won't Do|Wont Do|Cancelled|Cancelado|❌|No se hará)/i))
+        return 'wont-do';
+    if (content.match(/[>-] \*\*(Status|Estado):\*\*.*(Postponed|Pospuesto|Deferred|Diferido|⏸️|Post-MVP)/i))
+        return 'postponed';
+    if (content.match(/[>-] \*\*(Status|Estado):\*\*.*(Blocked|Bloqueado|🚫)/i))
+        return 'blocked';
+    return 'todo';
+}
+/** Parse Story Points (mid-line field). Calqued from `update-board.ts`. 0 if missing/invalid. */
+export function parseStoryPoints(content) {
+    const match = content.match(/\*\*(Story Points|SP):\*\* (\d+)/i);
+    if (!match)
+        return 0;
+    const value = parseInt(match[2], 10);
+    return Number.isNaN(value) ? 0 : value;
+}
+/** Parse the raw `> **Priority:**` value (e.g. `P1`). `undefined` if absent. */
+export function parsePriority(content) {
+    return matchBlockquoteField(content, 'Priority') ?? matchBlockquoteField(content, 'Prioridad');
+}
+/** Parse the raw `> **Epic:**` value (the markdown link/text). `undefined` if absent. */
+export function parseEpic(content) {
+    return matchBlockquoteField(content, 'Epic');
+}
+/**
+ * Parse the `Issue ID` — the meta field (`> **Issue ID:** ID`) preferred, falling back
+ * to the H1 prefix (`# ID: title`) like `update-board.ts` does (handles post-rename
+ * mismatch). `undefined` only for a malformed file with neither.
+ */
+export function parseIssueId(content) {
+    const meta = content.match(/[>-] \*\*Issue ID:\*\* ([\w-]+)/i);
+    if (meta)
+        return meta[1];
+    const h1 = content.match(/^# ([\w-]+): /m);
+    return h1 ? h1[1] : undefined;
+}
+/** Parse the bare title text from the H1 (`# ID: title` → `title`). `undefined` if absent. */
+export function parseTitle(content) {
+    const match = content.match(/^# [\w-]+: (.*)$/m);
+    return match ? match[1].trim() : undefined;
+}
+/** Parse `> **Skills:**` into its backtick-quoted tokens (`` `sk-api`, `kb-api` `` → [...]). */
+export function parseSkills(content) {
+    const line = matchBlockquoteField(content, 'Skills');
+    if (!line)
+        return [];
+    return Array.from(line.matchAll(/`([^`]+)`/g), (m) => m[1]);
+}
+/**
+ * Parse `> **Depends on:**` into single-token issue IDs. The field shares a line with
+ * `Parallelizable` (`BSYNC-001 · **Parallelizable:** no`), so we take the segment before
+ * the `·`, then split on comma/space. A `—` (no deps) yields `[]`.
+ */
+export function parseDependsOn(content) {
+    const line = matchBlockquoteField(content, 'Depends on');
+    if (!line)
+        return [];
+    const head = line.split('·')[0];
+    return head
+        .split(/[\s,]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0 && token !== '—' && token !== '-');
+}
+/** The element boards an ISSUE can declare (`> **Board:**`) — epics/features are separate. */
+const ISSUE_BOARD_VALUES = ['story', 'task', 'bug'];
+/**
+ * Parse `> **Board:**` to an element type. Defaults to `story` (the BSYNC-007 template
+ * default) when the line is absent (legacy issue) or carries an unknown value.
+ */
+export function parseBoard(content) {
+    const raw = matchBlockquoteField(content, 'Board')?.toLowerCase();
+    return raw && ISSUE_BOARD_VALUES.includes(raw)
+        ? raw
+        : 'story';
+}
+/** Parse `> **MoSCoW:**` to the remote enum (`must`/`should`/`could`); `undefined` if `—`/absent. */
+export function parseMoscow(content) {
+    return mapMoscow(matchBlockquoteField(content, 'MoSCoW'));
+}
+/** UUID string shape (any version) — used to validate a stamped `Backlog UUID`. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Parse a stamped `> **Backlog UUID:**` value. Returns the UUID only when it is a real
+ * UUID — a `{{uuid}}` placeholder, a `—`, or an absent line (legacy issue) → `undefined`
+ * (the caller then falls back to {@link deterministicElementUuid}).
+ */
+export function parseBacklogUuid(content) {
+    const raw = matchBlockquoteField(content, 'Backlog UUID');
+    return raw && UUID_RE.test(raw) ? raw.toLowerCase() : undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Deterministic UUID v5 fallback (no new dependency — uses node:crypto SHA-1)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * The FIXED namespace for the Factory backlog's deterministic UUIDs. 🔴 NEVER change
+ * this value — it seeds every legacy issue's fallback id; changing it would re-map
+ * every un-stamped element to a NEW remote element on the next push (duplication).
+ * A named constant (not a magic literal): CODING.md §5.
+ */
+export const BACKLOG_UUID_NAMESPACE = '9e3f8b7a-2c4d-4e5f-8a1b-6c7d8e9f0a1b';
+/** 16 raw bytes of a UUID string. */
+function uuidToBytes(uuid) {
+    return Buffer.from(uuid.replace(/-/g, ''), 'hex');
+}
+/** 16 raw bytes → canonical UUID string. */
+function bytesToUuid(bytes) {
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+/**
+ * Compute a DETERMINISTIC RFC-4122 v5 (SHA-1) UUID from a stable `name` under
+ * {@link BACKLOG_UUID_NAMESPACE}. Same input → same UUID on every run (issue §4/§8):
+ * this is what lets `push` re-run without duplicating a legacy (un-stamped) element —
+ * the collision would otherwise surface as a `500` (smoke Hallazgo 3), indistinguishable
+ * from a transient error, so determinism (not the server) is what guarantees idempotency.
+ * Implemented on `node:crypto` (SHA-1) — no `uuid` dependency added.
+ */
+export function deterministicElementUuid(name) {
+    const hash = createHash('sha1')
+        .update(Buffer.concat([uuidToBytes(BACKLOG_UUID_NAMESPACE), Buffer.from(name, 'utf8')]))
+        .digest();
+    const bytes = hash.subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC-4122 variant
+    return bytesToUuid(bytes);
+}
+/**
+ * Parse one issue's markdown into a normalized {@link ParsedIssue}. Tolerant of legacy
+ * issues (BSYNC-007 fields absent → defaults) and of the new lines being present
+ * (they never break the existing fields). The effective `uuid` is the stamped
+ * `Backlog UUID` or the deterministic fallback keyed on the Issue ID.
+ */
+export function parseIssue(content) {
+    const issueId = parseIssueId(content);
+    const title = parseTitle(content);
+    const backlogUuid = parseBacklogUuid(content);
+    const uuid = backlogUuid ?? deterministicElementUuid(issueId ?? title ?? content.trim());
+    return {
+        issueId,
+        title,
+        status: parseStatus(content),
+        priority: parsePriority(content),
+        storyPoints: parseStoryPoints(content),
+        epic: parseEpic(content),
+        skills: parseSkills(content),
+        dependsOn: parseDependsOn(content),
+        board: parseBoard(content),
+        moscow: parseMoscow(content),
+        backlogUuid,
+        uuid,
+    };
+}

package/dist/lib/constants.js

@@ -168,6 +168,29 @@ export const GENERATOR_SCRIPTS = [
 export const GENERATE_REFERENCE_NAME = 'generate:reference';
 export const GENERATE_REFERENCE_CMD = 'tsx scripts/tools/generate-inventory.ts && tsx scripts/tools/generate-codebase.ts && tsx scripts/tools/generate-hooks.ts && tsx scripts/tools/generate-schema.ts && tsx scripts/tools/generate-api.ts';
 export const GENERATE_REFERENCE_GATE_FILE = 'scripts/tools/generate-schema.ts';
+/**
+ * The `ports` block of a derivative's `package.json`, and the one key inside it the CLI
+ * maintains.
+ *
+ * `SHIPPED_E2E_PORT` is the value the kit's boilerplate USED to carry (`"e2e": 3006`). It is
+ * the ONLY value `emptyShippedE2EPort` is allowed to overwrite — the same discipline as
+ * `OBSOLETE_SCRIPT_CMDS` above: heal a known-obsolete kit value, never touch one the dev
+ * chose. Since `package.json` is frozen at bootstrap in a derivative (BR-FACTORY-006) and is
+ * not part of the tracked file set, the CLI is the only thing that can retire it.
+ *
+ * `PORTS_E2E_COMMENT_KEY` is how a comment is spelled in a file format that has none: a
+ * SIBLING key (the `"//"` convention npm itself documents), so the emptied value carries its
+ * own explanation instead of looking like a mistake. The text deliberately names no port
+ * range — the range lives in the runner, which ships on a different track (`scripts/**` via
+ * `factory update`) than this CLI (npm), so a number repeated here would drift.
+ */
+export const SHIPPED_E2E_PORT = 3006;
+export const PORTS_KEY = 'ports';
+export const PORTS_E2E_KEY = 'e2e';
+export const PORTS_E2E_COMMENT_KEY = '//e2e';
+export const PORTS_E2E_COMMENT = "Empty on purpose: the e2e runner derives a port from this checkout's absolute path, so " +
+    'two checkouts can run their suites at the same time. Put a number here to pin one, or ' +
+    'export E2E_PORT for a single run.';
 /**
  * Update-time healing registry: for each kit-owned script, the prior command(s)
  * the kit used to ship. When the kit changes HOW a script is invoked (e.g. the

package/dist/lib/env-file.js

@@ -39,6 +39,12 @@ export const PROVISION_OWNED = new Set([
     // Secrets; they must NEVER reach Vercel (a day-2 push would leak the Neon key).
     'NEON_API_KEY',
     'NEON_PROJECT_ID',
+    // LOCAL-ONLY backlog-central credentials (BSYNC-003): the derivative's `backlog
+    // push`/`sync` read them from `.env.local`. The `read_write` key is scoped to the
+    // project and must NEVER reach Vercel (a day-2 push would leak it). `env:push` skips
+    // both; provision writes them per-derivative to the gitignored `.env.local`.
+    'BACKLOG_API_KEY',
+    'BACKLOG_PROJECT_ID',
 ]);
 /**
  * Replace the value of `KEY=...` in an env-file body, preserving every other line.
@@ -140,3 +146,39 @@ export function writeEmailLocalCreds(rootDir, resendKey, emailFrom) {
     chmodSync(localPath, 0o600); // holds RESEND_API_KEY → owner-only.
     return true;
 }
+/**
+ * Write the backlog-central credentials into `.env.local` (BSYNC-003): the minted
+ * per-project `read_write` key (`BACKLOG_API_KEY`) + the project id
+ * (`BACKLOG_PROJECT_ID`), so the derivative's `backlog push`/`sync` can talk to
+ * backlog.timekast.mx. Both are PROVISION_OWNED → LOCAL-ONLY, never pushed to Vercel.
+ *
+ * DIVERGENCE from {@link writeE2eLocalCreds}/{@link writeEmailLocalCreds} (which
+ * no-op when `.env.local` is absent, relying on {@link writeEnvLocal} to create it in
+ * the Vercel step): `backlog` can be provisioned STANDALONE (`--services=backlog`),
+ * with no Neon/Vercel step to seed `.env.local` first — so this CREATES `.env.local`
+ * (from `.env.example` when present, else a bare file) if it does not exist, then
+ * fills the two keys. Safe on an existing file: `setEnvLine` only touches these two
+ * keys, preserving the rest. Returns false only when the key/project id is missing —
+ * the key VALUE is never logged (no-echo; the caller prints only key NAMES).
+ */
+export function writeBacklogLocalCreds(rootDir, projectId, apiKey) {
+    if (!apiKey || !projectId)
+        return false;
+    const localPath = join(rootDir, '.env.local');
+    let body = '';
+    if (existsSync(localPath)) {
+        body = readFileSync(localPath, 'utf8');
+    }
+    else {
+        const examplePath = join(rootDir, '.env.example');
+        if (existsSync(examplePath))
+            body = readFileSync(examplePath, 'utf8');
+    }
+    body = setEnvLine(body, 'BACKLOG_PROJECT_ID', projectId);
+    body = setEnvLine(body, 'BACKLOG_API_KEY', apiKey);
+    // `mode: 0o600` on create closes the world-readable window; chmod covers the
+    // overwrite path too. `.env.local` holds BACKLOG_API_KEY → owner-only.
+    writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
+    chmodSync(localPath, 0o600);
+    return true;
+}

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, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, UPDATE_SCRIPT_NAME, } from './constants.js';
+import { FACTORY_SCRIPTS, GENERATE_REFERENCE_CMD, GENERATE_REFERENCE_GATE_FILE, GENERATE_REFERENCE_NAME, GENERATOR_SCRIPTS, INVITE_ADMIN_SCRIPT_CMD, INVITE_ADMIN_SCRIPT_FILE, INVITE_ADMIN_SCRIPT_NAME, OBSOLETE_SCRIPT_CMDS, PORTS_E2E_COMMENT, PORTS_E2E_COMMENT_KEY, PORTS_E2E_KEY, PORTS_KEY, PREFLIGHT_SCRIPT_CMD, PREFLIGHT_SCRIPT_FILE, PREFLIGHT_SCRIPT_NAME, PROFILES, SHIPPED_E2E_PORT, 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
@@ -197,6 +197,64 @@ export function insertFactoryUpdateScript(pkgPath) {
     }
     return primary;
 }
+/**
+ * Retire the E2E port the kit used to ship in a derivative's `package.json`: KEEP the key,
+ * EMPTY the value (`"e2e": null`), and add the `//e2e` sibling that explains why.
+ *
+ * WHY EMPTY RATHER THAN DELETE. `null` is a signal the e2e runner reads: with the key
+ * present and empty it derives a port from the checkout's absolute path, so two worktrees of
+ * one repo can run their suites at the same time. Deleting the key would say something
+ * different — "this project never had one" — which is the state that keeps a project on the
+ * runner's hardcoded fallback. So the key is the contract; only the value retires.
+ *
+ * WHY ONLY EXACTLY `3006`. Same discipline as `ensureFactoryScripts`: a KNOWN-OBSOLETE kit
+ * value is healed, a divergent one is never touched. A dev who pinned `4100` on purpose
+ * keeps `4100` through every future `factory update`; anything that is not the shipped
+ * number — including a `null` already written by an earlier update — is left alone, which is
+ * also what makes this idempotent (a second run writes nothing and cannot duplicate the
+ * comment).
+ *
+ * Surgical like the rest of this module: reads, mutates only inside `ports`, re-serializes
+ * with the original indentation + trailing newline, and writes ONLY on a real change. Key
+ * order inside `ports` is preserved and the comment is inserted immediately BEFORE `e2e`, so
+ * what a derivative sees in `git diff` is two lines: the emptied value and its explanation.
+ *
+ * @param pkgPath Absolute path to the derived project's `package.json`.
+ */
+export function emptyShippedE2EPort(pkgPath) {
+    const raw = readFileSync(pkgPath, 'utf8');
+    const indent = detectIndent(raw);
+    const pkg = parsePackageJson(raw);
+    const ports = pkg[PORTS_KEY];
+    if (typeof ports !== 'object' || ports === null || Array.isArray(ports))
+        return 'absent';
+    const block = ports;
+    const current = block[PORTS_E2E_KEY];
+    if (current === undefined)
+        return 'absent';
+    if (current === null)
+        return 'already-empty';
+    if (current !== SHIPPED_E2E_PORT)
+        return 'preserved';
+    // Rebuilt rather than assigned in place: an object literal's key order is its insertion
+    // order, so this is what puts the comment immediately before the key it describes while
+    // leaving every sibling (`dev`, whatever else the project keeps here) where it was. An
+    // existing `//e2e` is dropped on the way through and re-inserted once, never twice.
+    const rebuilt = {};
+    for (const [key, value] of Object.entries(block)) {
+        if (key === PORTS_E2E_COMMENT_KEY)
+            continue;
+        if (key === PORTS_E2E_KEY) {
+            rebuilt[PORTS_E2E_COMMENT_KEY] = PORTS_E2E_COMMENT;
+            rebuilt[PORTS_E2E_KEY] = null;
+            continue;
+        }
+        rebuilt[key] = value;
+    }
+    pkg[PORTS_KEY] = rebuilt;
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, 'utf8');
+    return 'emptied';
+}
 /**
  * Surgically set the derived project's `package.json.agentKitVersion` to the
  * installed brain version, mirroring the lockfile's `version`. The Factory's own

package/dist/lib/provision-preflight.js

@@ -45,6 +45,14 @@ const SERVICE_TOKENS = {
     // at the scaffold stage.
     github: 'VERCEL_TOKEN',
     dns: 'CLOUDFLARE_API_TOKEN',
+    // `backlog` (BSYNC-003) registers the project in backlog.timekast.mx with the org
+    // `admin` token. NOTE: unlike the other gate tokens (fail-closed here), a missing
+    // `BACKLOG_ADMIN_TOKEN` degrades GRACEFULLY at the command layer — WARN + skip when
+    // backlog is one of several services (`resolveBacklogService` in provision.ts strips
+    // it BEFORE this preflight runs), a hard error only when it is the sole service. So
+    // by the time the preflight sees `backlog` in `services`, the token is present; this
+    // entry is the defense-in-depth double-check.
+    backlog: 'BACKLOG_ADMIN_TOKEN',
 };
 /** True when the thrown error is execa's "command not found" (ENOENT). */
 function isCommandNotFound(error) {

package/dist/lib/provision-state.js

@@ -247,6 +247,12 @@ export function isServiceComplete(state, service) {
             return state.github?.done === true;
         case 'dns':
             return state.dns !== undefined;
+        case 'backlog':
+            // Complete only when the per-project key was minted AND written — NOT on the
+            // mere presence of state.backlog (its `projectId` is recorded before the mint,
+            // so a run that created the project but failed to mint would be wrongly skipped
+            // on resume, and the show-once key would never reach `.env.local`).
+            return state.backlog?.keyMinted === true;
         default:
             return false;
     }
@@ -348,6 +354,9 @@ export function readDestroyTarget(rootDir) {
             neonBranchDevId: realId(adopted.neonBranchDevId),
             vercelProjectId: realId(adopted.vercelProjectId),
             githubRepo: realRepo(adopted.githubRepo),
+            // The adopt backfill (PROV-007) does not reconstruct backlog central — nothing
+            // to tear down from an adopted stack; a normal provision state carries it.
+            backlogProjectId: null,
             domains,
         };
     }
@@ -380,6 +389,7 @@ export function readDestroyTarget(rootDir) {
         neonBranchDevId: realId(step.neon?.developBranchId),
         vercelProjectId: realId(step.vercel?.projectId),
         githubRepo: realRepo(step.github?.repo),
+        backlogProjectId: realId(step.backlog?.projectId),
         domains,
     };
 }

package/package.json

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