heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/promotion-helpers.mjs

@@ -19,6 +19,8 @@ import {
   mkdirSync,
   unlinkSync,
 } from 'node:fs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { splitRawSpec } from './cloud-vault-writes.mjs';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Date / string utilities
@@ -278,3 +280,252 @@ export function commitWrites(writes) {
     return { ok: false, error: err };
   }
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cloud-tier (neon) read support — [[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]]
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The disk-tier loaders throughout promote-capture.mjs / promote-research.mjs
+// (`find*ByIdLocal`, `find*ByBasename`, etc.) all return the same shape:
+// `{ basename, absPath, relPath, raw }` — `raw` being the FULL file text
+// (frontmatter fence + body), which every downstream consumer parses with the
+// regex-based `getFrontmatterBlock`/`getScalarField`/`parseListFieldBasenames`
+// helpers above. The console's `GET /api/specs/[id]` route (the same by-id
+// route `loadSpecByIdViaTier` in vault-io.mjs uses) instead returns ALREADY
+// PARSED `frontmatter` (an object) + a fenced-out `body` — so a neon-tier read
+// reconstructs an equivalent `raw` string via {@link synthesizeRawFromSpec}
+// rather than requiring every regex consumer to grow a second, object-shaped
+// code path. `absPath` is always `null` on a neon read (no local file backs
+// it) — safe because nothing reads `absPath` before the write phase, which
+// stays disk-only and is out of this task's scope.
+
+/**
+ * Reconstruct a byte-plausible "raw" markdown file (frontmatter fence + body)
+ * from a console-returned `{ frontmatter, body }` pair. Round-trip fidelity
+ * only needs to satisfy the regex readers above, not survive a re-write —
+ * every neon-tier document in this flow is a READ-ONLY input.
+ */
+export function synthesizeRawFromSpec(frontmatter, body) {
+  const lines = [];
+  for (const [key, value] of Object.entries(frontmatter ?? {})) {
+    if (value === undefined) continue;
+    if (value === null) {
+      lines.push(`${key}: null`);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+        continue;
+      }
+      lines.push(`${key}:`);
+      for (const item of value) {
+        if (typeof item === 'string' && /^\[\[[^\]]+\]\]$/.test(item)) {
+          // Already wikilink-wrapped (the shape every cross-ref list field
+          // stores) — quote it verbatim so parseListFieldBasenames's
+          // `- "[[basename]]"` pattern matches.
+          lines.push(`  - "${item}"`);
+        } else {
+          lines.push(`  - ${yamlScalar(item)}`);
+        }
+      }
+      continue;
+    }
+    if (typeof value === 'object') {
+      // Rare in this flow (frontmatter here is scalars + wikilink lists) —
+      // best-effort JSON scalar rather than a second nested-YAML writer.
+      lines.push(`${key}: ${JSON.stringify(value)}`);
+      continue;
+    }
+    lines.push(`${key}: ${yamlScalar(value)}`);
+  }
+  return `---\n${lines.join('\n')}\n---\n${body ?? ''}`;
+}
+
+/**
+ * Fetch one spec by id/basename from the console via an INJECTED
+ * `consoleFetch` and reshape it into the `{ basename, absPath, relPath, raw }`
+ * contract every disk-tier loader above already returns. Mirrors the
+ * `GET /api/specs/[id]` contract `loadSpecByIdViaTier` (vault-io.mjs) uses —
+ * same route, same "404 is a real not-found answer" rule — but goes through
+ * the CALLER's own injected `consoleFetch` instead of that module's hardwired
+ * transport, matching promote-capture.mjs / promote-research.mjs's existing
+ * deps-injection convention (`defaultProposeStubs`) so callers/tests never
+ * need a real socket. A non-404 failure throws; the caller wraps this with
+ * `readViaSelector` (read-path.mjs) so it surfaces as
+ * `CONSOLE_UNREACHABLE_CLOUD_MODE` naming the route.
+ */
+export async function fetchSpecRecordViaConsole(consoleFetchFn, specId) {
+  if (typeof consoleFetchFn !== 'function') {
+    throw new Error('fetchSpecRecordViaConsole: a consoleFetch dependency is required in the neon tier');
+  }
+  const res = await consoleFetchFn(`/api/specs/${encodeURIComponent(specId)}`);
+  if (res.ok) {
+    const spec = res.body?.spec;
+    if (!spec) return null;
+    const relPath = spec.relPath ?? spec.path ?? null;
+    const basename = relPath
+      ? String(relPath).split(/[\\/]/).pop().replace(/\.md$/i, '')
+      : String(spec.frontmatter?.id ?? specId);
+    return {
+      basename,
+      absPath: null,
+      relPath,
+      raw: synthesizeRawFromSpec(spec.frontmatter || {}, spec.body || ''),
+    };
+  }
+  if (res.status === 404) return null; // not_found / ambiguous_id — a real answer, not a failure.
+  throw new Error(
+    `GET /api/specs/${specId} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`,
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cloud-mode WRITE support — [[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The READ half above (HS-KR16) taught the promotion flows to FIND their input
+// documents through the console. This half teaches them to SAVE the result
+// there too. The machinery itself lives in `cloud-vault-writes.mjs` (the
+// write-side twin of read-path.mjs); what belongs HERE is only the small bit of
+// shared vocabulary every promotion module must agree on:
+//
+//   - how the mode is read off `deps` (resolved ONCE per handler call by the
+//     caller, never re-derived inside a helper — the same rule `deps.tier`
+//     follows), and
+//   - how a write that has NO cloud equivalent at all reports itself.
+//
+// On the second point: `POST /api/specs` can only create documents whose
+// `type` the console's TYPE_TO_FOLDER knows (task, epic, milestone, diagnose,
+// capture, planning-flow, memory-*, protocol, workflow-recipe, research,
+// review, pillar, agent, golden-case, adr, draft, daily). A roadmap manifest
+// append, a soft-delete into a trash folder, a local pin file — none of those
+// is a spec of a known kind, and inventing a type for them would file a
+// document into a folder the console does not model. Those degrade EXPLICITLY
+// instead, carrying {@link CLOUD_MODE_UNSUPPORTED_WRITE} and naming both the
+// file and the reason, so the caller reports a real gap rather than silently
+// skipping a write.
+//
+// NOTE on the local dot-directory state (`review-focus.yaml`,
+// `research-focus.yaml`, the promote-research review-gate markers): those are
+// LOCAL MACHINE STATE, not vault content — they do not live under `specs/`,
+// nothing indexes them, and they are per-workstation by design (HS-KR16 §Scope
+// made exactly this call for the marker cache). They keep writing to disk in
+// cloud mode and are deliberately NOT routed through the console.
+
+/** Error code for a write with no console equivalent. */
+export const CLOUD_MODE_UNSUPPORTED_WRITE = 'CLOUD_MODE_UNSUPPORTED_WRITE';
+
+/**
+ * Repair the ONE lossy case in the markdown → object round-trip these flows
+ * depend on.
+ *
+ * Every cloud write starts from markdown one of the shared content builders
+ * produced, and `splitRawSpec` (cloud-vault-writes.mjs) parses it with
+ * `parseFrontmatter`/`parseSimpleYaml` from vault-io.mjs — the vault's own YAML
+ * dialect, deliberately reused so there is no second parser to drift. That
+ * parser renders an INLINE EMPTY LIST (`depends_on: []`, `tags: []`,
+ * `children: []`, `epics: []`, `related: []` — every stub template writes
+ * several) as `['']`: a one-element list holding an empty string.
+ *
+ * On disk that never mattered, because the disk path writes the markdown
+ * verbatim and never round-trips it. Through the console it very much does: a
+ * `depends_on: ['']` would be stored as a real one-entry list whose entry is a
+ * dangling empty wikilink. Normalizing here — at the single seam where parsed
+ * frontmatter becomes a request body — fixes every caller at once, and is
+ * deliberately narrow: ONLY the exact `['']` shape collapses, so a genuine
+ * list that merely contains a blank alongside real entries is left alone for
+ * the console to reject on its own terms.
+ */
+export function normalizeParsedFrontmatter(frontmatter) {
+  const out = {};
+  for (const [key, value] of Object.entries(frontmatter ?? {})) {
+    out[key] =
+      Array.isArray(value) && value.length === 1 && value[0] === '' ? [] : value;
+  }
+  return out;
+}
+
+/**
+ * `splitRawSpec` + {@link normalizeParsedFrontmatter} — the single call every
+ * cloud write in these modules uses to turn built markdown into the
+ * `{ frontmatter, body }` pair the console's POST/PUT routes take.
+ */
+export function splitRawSpecForConsole(raw) {
+  const { frontmatter, body } = splitRawSpec(raw);
+  return { frontmatter: normalizeParsedFrontmatter(frontmatter), body };
+}
+
+/**
+ * The vault write mode for this call: `deps.writeMode` when the caller
+ * resolved one (`resolveVaultWriteMode()` from read-path.mjs), else `local`.
+ *
+ * Defaulting to `local` — NOT to the resolver's own prod-default `cloud` — is
+ * what keeps every pre-existing caller and test byte-identical: a caller that
+ * never heard of this task passes no `writeMode` and takes the disk path it
+ * always took.
+ */
+export function resolveWriteModeFromDeps(deps) {
+  return deps?.writeMode === 'cloud' ? 'cloud' : 'local';
+}
+
+/**
+ * Build the canonical "this write cannot exist in cloud mode" result — the
+ * same `{ error, message }` shape every promotion handler already returns, so
+ * a caller renders it with no new branch.
+ */
+export function cloudModeUnsupportedWrite(file, why, details = {}) {
+  return {
+    error: CLOUD_MODE_UNSUPPORTED_WRITE,
+    message:
+      `CLOUD_MODE_UNSUPPORTED_WRITE: "${file}" cannot be written through the console — ${why}. ` +
+      'Nothing was written for this step; re-run in local (disk) write mode if this document is required.',
+    file,
+    reason: why,
+    ...details,
+  };
+}
+
+/**
+ * Render a failed cloud write as the `{ error, message }` result shape every
+ * promotion handler already returns.
+ *
+ * There is deliberately NO rollback claim: `commitWrites`'s disk transaction
+ * can restore a snapshot, the console cannot un-create. So the result names
+ * the step that failed AND lists the steps that already landed, and says so in
+ * words — a caller must never read this as "nothing happened"
+ * ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]] AC5).
+ *
+ * `message` is passed through verbatim from `cloud-vault-writes.mjs`, so it
+ * always STARTS WITH `CONSOLE_UNREACHABLE_CLOUD_MODE` and names the route and
+ * the console.
+ */
+export function cloudWriteFailureResult(err, { step = null, completed = [] } = {}) {
+  const message = String(err?.message ?? err);
+  return {
+    error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+    message,
+    route: err?.route ?? null,
+    console_url: err?.console_url ?? null,
+    write_mode: 'cloud',
+    failed_step: step,
+    completed_steps: completed,
+    partial: completed.length > 0,
+    rollback:
+      completed.length > 0
+        ? 'none — the console has no un-create, so every step listed in completed_steps DID land; reconcile from there rather than retrying blind'
+        : 'nothing landed — the first console write failed',
+  };
+}
+
+/**
+ * Throwable twin of {@link cloudModeUnsupportedWrite}, for the code paths that
+ * signal by exception rather than by return value.
+ */
+export function cloudModeUnsupportedWriteError(file, why, details = {}) {
+  const payload = cloudModeUnsupportedWrite(file, why, details);
+  const err = new Error(payload.message);
+  err.name = CLOUD_MODE_UNSUPPORTED_WRITE;
+  Object.assign(err, payload);
+  return err;
+}