@timekast/factory 1.18.0 → 1.20.0

package/dist/lib/backlog-mapping.js

@@ -0,0 +1,175 @@
+/**
+ * Mapping tables + credential resolution for the Factory ↔ backlog.timekast.mx
+ * integration — the shared translation layer between the LOCAL backlog vocabulary
+ * (the emoji+word `Status:`, `P0..P3` priority, integer Story Points, `must/should/
+ * could` MoSCoW that live in issue/epic markdown) and the REMOTE enums the API
+ * accepts (`backlog-api.ts`). Both `push` (BSYNC-005) and `sync` (BSYNC-006)
+ * consume this ONE module so neither hand-rolls the translation.
+ *
+ * Two design rules the issue (§4) pins down:
+ *   - Every axis (status/priority/points/moscow) is a DATA TABLE, never scattered
+ *     if/else — a reviewer reads the bijection at a glance.
+ *   - Status is a strict 6↔6 BIJECTION: each of the 6 local buckets has exactly one
+ *     remote destination and vice-versa (asserted by the unit tests).
+ *
+ * Local status buckets mirror `scripts/tools/update-board.ts` `parseStatus()` (SSOT
+ * vocabulary: `.claude/skills/tk-backlog/methodology/issue-shape.md`). `Deferred`
+ * and `Postponed` are synonyms that both bucket to `postponed` locally → `deferred`
+ * remotely, keeping the 6↔6 bijection intact.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * LOCAL bucket → REMOTE `WorkStatus`. Half of the bijection; {@link STATUS_REMOTE_TO_LOCAL}
+ * is its exact inverse. The 6 remote states were live-verified (smoke Hallazgo 3).
+ */
+export const STATUS_LOCAL_TO_REMOTE = {
+    todo: 'todo',
+    'in-progress': 'in_progress',
+    done: 'done',
+    'wont-do': 'wont_do',
+    postponed: 'deferred',
+    blocked: 'blocked',
+};
+/** REMOTE `WorkStatus` → LOCAL bucket. Exact inverse of {@link STATUS_LOCAL_TO_REMOTE}. */
+export const STATUS_REMOTE_TO_LOCAL = {
+    todo: 'todo',
+    in_progress: 'in-progress',
+    done: 'done',
+    wont_do: 'wont-do',
+    deferred: 'postponed',
+    blocked: 'blocked',
+};
+/** Translate a local status bucket to the remote `WorkStatus` the API PATCH accepts. */
+export function mapStatusToRemote(local) {
+    return STATUS_LOCAL_TO_REMOTE[local];
+}
+/** Translate a remote `WorkStatus` (from `sync-state`) back to the local bucket for the diff. */
+export function mapStatusToLocal(remote) {
+    return STATUS_REMOTE_TO_LOCAL[remote];
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Priority — P0..P3 → p0..p3 (data table)
+// ─────────────────────────────────────────────────────────────────────────────
+/** LOCAL `P0..P3` → REMOTE `p0..p3` (FCT-005 — an axis independent of MoSCoW). */
+export const PRIORITY_LOCAL_TO_REMOTE = {
+    P0: 'p0',
+    P1: 'p1',
+    P2: 'p2',
+    P3: 'p3',
+};
+/**
+ * Map a raw `Priority:` value (`P1`, `P0 (Crítico)`, …) to the remote enum. Extracts
+ * the `P0..P3` token defensively; anything without one → `undefined` (the push then
+ * omits `priority` rather than sending a bogus value).
+ */
+export function mapPriority(raw) {
+    if (!raw)
+        return undefined;
+    const match = raw.toUpperCase().match(/P[0-3]/);
+    return match ? PRIORITY_LOCAL_TO_REMOTE[match[0]] : undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// MoSCoW — must/should/could (data table)
+// ─────────────────────────────────────────────────────────────────────────────
+/** The three MoSCoW commitments that ever reach the backlog (`won't` never pushes). */
+export const MOSCOW_VALUES = ['must', 'should', 'could'];
+/**
+ * Normalize a raw `MoSCoW:` value to the remote enum. A `—` / empty / unknown value
+ * (a legacy issue without the BSYNC-007 field, or a placeholder) → `undefined`, so
+ * the push omits `moscow` instead of guessing.
+ */
+export function mapMoscow(raw) {
+    if (!raw)
+        return undefined;
+    const value = raw.trim().toLowerCase();
+    return MOSCOW_VALUES.includes(value)
+        ? value
+        : undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Story points — canonical scale (data table)
+// ─────────────────────────────────────────────────────────────────────────────
+/** The canonical Fibonacci-ish Story Points scale (DoR: 1/2/3/5/8/13). */
+export const STORY_POINTS_SCALE = [1, 2, 3, 5, 8, 13];
+/** Whether a value sits on the canonical {@link STORY_POINTS_SCALE}. */
+export function isCanonicalStoryPoints(sp) {
+    return STORY_POINTS_SCALE.includes(sp);
+}
+/**
+ * Map local Story Points to the remote `points` field. A positive integer passes
+ * through unchanged (fidelity — we never re-bucket the team's estimate); `0`/missing
+ * → `null`, which the API treats as "no points" (epics/features carry `null` too,
+ * smoke Hallazgo 4). Non-canonical positive values (e.g. `4`) pass through as-is;
+ * {@link isCanonicalStoryPoints} lets the caller warn without dropping the value.
+ */
+export function mapStoryPoints(sp) {
+    return Number.isInteger(sp) && sp > 0 ? sp : null;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Credential resolution — fail-closed, NEVER throws (issue §4)
+// ─────────────────────────────────────────────────────────────────────────────
+/** The env keys the derivative's `.env.local` carries for the backlog integration. */
+export const BACKLOG_API_KEY_VAR = 'BACKLOG_API_KEY';
+export const BACKLOG_PROJECT_ID_VAR = 'BACKLOG_PROJECT_ID';
+/** Default FS reader — reads `.env.local` if present, swallowing any error to `null`. */
+function defaultReadFile(filePath) {
+    try {
+        return existsSync(filePath) ? readFileSync(filePath, 'utf8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read one `KEY=value` from an env-file body, stripping a matching quote pair. */
+function readEnvValue(body, key) {
+    const match = body.match(new RegExp(`^${key}=(.*)$`, 'm'));
+    if (!match)
+        return undefined;
+    let value = match[1].trim();
+    if (value.length >= 2 &&
+        ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'")))) {
+        value = value.slice(1, -1);
+    }
+    return value.length > 0 ? value : undefined;
+}
+/**
+ * Resolve the per-project backlog credentials from `{rootDir}/.env.local`. FAIL-CLOSED
+ * (issue §4): a missing file, an unreadable file, or a missing/empty `BACKLOG_API_KEY`
+ * / `BACKLOG_PROJECT_ID` all return the distinctive `not-configured` result — this
+ * function NEVER throws, so a derivative that never provisioned the backlog service
+ * does not crash `push`/`sync`; they just skip. The `readFile` seam is injectable so
+ * tests drive every branch without disk.
+ */
+export function resolveBacklogCredentials(rootDir, deps = {}) {
+    const read = deps.readFile ?? defaultReadFile;
+    let body;
+    try {
+        body = read(`${rootDir.replace(/\/+$/, '')}/.env.local`);
+    }
+    catch {
+        // A throwing injected reader must still fail closed, never propagate.
+        body = null;
+    }
+    if (body === null) {
+        return {
+            status: 'not-configured',
+            reason: 'No se encontró `.env.local`; el backlog central no está configurado.',
+        };
+    }
+    const apiKey = readEnvValue(body, BACKLOG_API_KEY_VAR);
+    const projectId = readEnvValue(body, BACKLOG_PROJECT_ID_VAR);
+    if (!apiKey || !projectId) {
+        const missing = [
+            !apiKey ? BACKLOG_API_KEY_VAR : null,
+            !projectId ? BACKLOG_PROJECT_ID_VAR : null,
+        ]
+            .filter(Boolean)
+            .join(' + ');
+        return {
+            status: 'not-configured',
+            reason: `Falta ${missing} en \`.env.local\`; el backlog central no está configurado.`,
+        };
+    }
+    return { status: 'configured', apiKey, projectId };
+}

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/cloudflare-api.js

@@ -16,8 +16,12 @@
  * actionable `CLIError` (issue §8 Gherkin) — it NEVER deletes a record to recover.
  *
  * What this module does NOT do:
- *   - Delete a DNS record. The idempotent path is create-or-PATCH; an existing
- *     record is never removed without explicit human confirmation (issue §8).
+ *   - Delete a DNS record to RECOVER from an error. The idempotent provisioning
+ *     path is create-or-PATCH; a record is never removed to "fix" a failed call
+ *     (issue §8). The ONE deletion shipped here ({@link deleteDnsRecord},
+ *     BOOT-007) is DELIBERATE cleanup inside a flow a human already confirmed
+ *     (retiring the interim domain after the client domain went live) — it is
+ *     never an automatic recovery move.
  *   - Read or log a token value. The token arrives as an argument and is handed
  *     straight to the `Authorization` header; it never reaches stdout.
  *
@@ -241,3 +245,109 @@ export async function ensureCnameRecord(zoneId, name, token, deps = {}) {
     }
     return 'unchanged';
 }
+/**
+ * Delete a DNS record by id — `DELETE /zones/{id}/dns_records/{recordId}`
+ * (BOOT-007). The ONE deletion in this module, and it is DELIBERATE: it runs only
+ * inside a flow the human already confirmed (retiring the interim domain after the
+ * client domain verified — the orphaned interim CNAME would otherwise resolve to
+ * {@link CNAME_VERCEL_TARGET} and serve a 404 forever). It is NEVER used to
+ * recover from a failed call — the module-header contract stands.
+ *
+ * Mirrors `removeVercelDomain`'s 404 tolerance: a record already gone (deleted by
+ * hand or by a previous run) is `absent`, not an error — the cleanup is idempotent.
+ *
+ * @throws {CloudflareApiError} on any non-2xx other than 404 / `success: false`.
+ */
+export async function deleteDnsRecord(zoneId, recordId, token, deps = {}) {
+    try {
+        await cloudflareApi('DELETE', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(recordId)}`, token, deps);
+        return 'removed';
+    }
+    catch (error) {
+        if (error instanceof CloudflareApiError && error.status === 404)
+            return 'absent';
+        throw error;
+    }
+}
+/**
+ * Normalize a record content for comparison (issue §8 idempotency). Cloudflare
+ * returns TXT content wrapped in double quotes (`"v=spf1 …"`) while Resend hands
+ * it bare — a byte-compare would false-positive a "different content" and PATCH
+ * on every re-run. Stripping ONE layer of surrounding quotes + trimming makes the
+ * re-run comparison stable without touching the value actually stored.
+ */
+function normalizeRecordContent(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/**
+ * Find an existing record of `spec.type` for `name` in the zone (issue §8
+ * idempotency) — same lookup shape as {@link findCnameRecord}, parameterized on
+ * the type. Returns the record (so the caller can compare content and PATCH a
+ * rotated value) or `null` when absent.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function findDnsRecord(zoneId, type, name, token, deps = {}) {
+    const data = (await cloudflareApi('GET', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, undefined, { type, name }));
+    return (data.result ?? []).find((r) => r.name === name && r.type === type) ?? null;
+}
+/**
+ * Create a TXT/MX record — `POST /zones/{id}/dns_records` (BOOT-003 §4), same
+ * call shape as {@link createCnameRecord} (`ttl: 1` = auto). TXT/MX cannot be
+ * proxied, so no `proxied` flag is sent. `priority` rides along for MX only.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function createDnsRecord(zoneId, spec, token, deps = {}) {
+    await cloudflareApi('POST', `/zones/${encodeURIComponent(zoneId)}/dns_records`, token, deps, {
+        type: spec.type,
+        name: spec.name,
+        content: spec.content,
+        ttl: 1,
+        ...(spec.priority !== undefined ? { priority: spec.priority } : {}),
+    });
+}
+/**
+ * PATCH an existing record to the content/priority the spec demands — `PATCH
+ * /zones/{id}/dns_records/{recordId}` (issue §8: a DKIM rotation leaves a record
+ * with STALE content; we repoint it in place). Same principle as
+ * {@link unproxyCnameRecord}: we NEVER delete a record to "fix" it.
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false`.
+ */
+export async function patchDnsRecord(zoneId, recordId, spec, token, deps = {}) {
+    await cloudflareApi('PATCH', `/zones/${encodeURIComponent(zoneId)}/dns_records/${encodeURIComponent(recordId)}`, token, deps, {
+        type: spec.type,
+        name: spec.name,
+        content: spec.content,
+        ...(spec.priority !== undefined ? { priority: spec.priority } : {}),
+    });
+}
+/**
+ * Idempotently ensure a TXT/MX record matching `spec` exists in the zone
+ * (BOOT-003 §4 + §8) — the TXT/MX sibling of {@link ensureCnameRecord}. Returns
+ * the outcome so the caller can narrate it:
+ *   - `created`   — no record existed → POSTed a fresh one
+ *   - `updated`   — a record existed with DIFFERENT content/priority (e.g. a DKIM
+ *                   rotation) → PATCHed it in place (never deleted — §8)
+ *   - `unchanged` — a record with the same content already existed → nothing to do
+ *
+ * @throws {CloudflareApiError} on any non-2xx / `success: false` (caller maps it).
+ */
+export async function ensureDnsRecord(zoneId, spec, token, deps = {}) {
+    const existing = await findDnsRecord(zoneId, spec.type, spec.name, token, deps);
+    if (!existing) {
+        await createDnsRecord(zoneId, spec, token, deps);
+        return 'created';
+    }
+    const sameContent = normalizeRecordContent(existing.content) === normalizeRecordContent(spec.content);
+    const samePriority = spec.priority === undefined || existing.priority === spec.priority;
+    if (sameContent && samePriority)
+        return 'unchanged';
+    await patchDnsRecord(zoneId, existing.id, spec, token, deps);
+    return 'updated';
+}

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.
@@ -78,10 +84,13 @@ export function writeEnvLocal(rootDir, neon, opts = {}) {
     body = setEnvLine(body, 'DATABASE_URL', neon.developDirect);
     body = setEnvLine(body, 'DATABASE_URL_MAIN', neon.mainDirect);
     body = setEnvLine(body, 'AUTH_SECRET', generateAuthSecret());
-    writeFileSync(localPath, body, 'utf8');
-    // `.env.local` holds DB strings + AUTH_SECRET → owner-only (0600). Same
-    // discipline the secrets rail uses; matters on the headless multi-tenant
-    // Agent Server where the default umask would leave it world-readable.
+    // `.env.local` holds DB strings + AUTH_SECRET → owner-only (0600) from birth.
+    // The `mode: 0o600` makes the file created 0600 with no world-readable window
+    // between create and chmod — critical on the headless multi-tenant Agent Server
+    // where the default umask would otherwise leave one tenant's secrets briefly
+    // readable by others. `mode` only applies when the file is CREATED, so the
+    // chmod below still covers the `--force` overwrite path (file already exists).
+    writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
     chmodSync(localPath, 0o600);
     return 'written';
 }
@@ -104,7 +113,7 @@ export function writeE2eLocalCreds(rootDir, projectId, apiKey) {
     let body = readFileSync(localPath, 'utf8');
     body = setEnvLine(body, 'NEON_PROJECT_ID', projectId);
     body = setEnvLine(body, 'NEON_API_KEY', apiKey);
-    writeFileSync(localPath, body, 'utf8');
+    writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
     chmodSync(localPath, 0o600); // holds NEON_API_KEY → owner-only.
     return true;
 }
@@ -133,7 +142,43 @@ export function writeEmailLocalCreds(rootDir, resendKey, emailFrom) {
     body = setEnvLine(body, 'EMAIL_PROVIDER', 'resend');
     body = setEnvLine(body, 'RESEND_API_KEY', resendKey);
     body = setEnvLine(body, 'EMAIL_FROM', emailFrom);
-    writeFileSync(localPath, body, 'utf8');
+    writeFileSync(localPath, body, { encoding: 'utf8', mode: 0o600 });
     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;
+}