heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/verify-reproduction.mjs

@@ -19,6 +19,15 @@
  * `status:` — the status API owns coercion, rollup, and spec events ([[HS-DIAG-DOSH]]),
  * and the reproduction gate lives inside it, so a clean record is what unlocks the
  * close rather than this module deciding on its own.
+ *
+ * Cloud contract ([[HS-7UJZ-O86I-DIAG]]): a diagnose filed through the console in
+ * cloud mode exists ONLY as a Neon row — there is no `specs/diagnoses/*.md` for the
+ * disk scan to find. When the session's console reliance is `cloud` the diagnose is
+ * resolved and the verdict recorded THROUGH the console (`GET` + `PUT
+ * /api/specs/:id`, the same frontmatter fields + change-log row the disk path
+ * writes); in local reliance the disk scan runs first, exactly as before, and the
+ * console is consulted only when the scan finds nothing. The close still goes
+ * through the status PATCH either way.
  */
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
@@ -78,15 +87,7 @@ export const SPAWNED_WORK_FIELDS = ['spawned_epics', 'spawned_tasks'];
  * ([[HS-B1ZT-QCP2-DIAG-heyspex-promote-research-cannot-resolve]]).
  */
 export function resolveDiagnoseRef(vaultRoot, rawRef) {
-  const ref =
-    typeof rawRef === 'string'
-      ? rawRef
-          .trim()
-          .replace(/^\[\[|\]\]$/g, '')
-          .replace(/^['"]|['"]$/g, '')
-          .replace(/\.md$/i, '')
-          .trim()
-      : '';
+  const ref = normalizeDiagnoseRef(rawRef);
   if (!ref) return { error: 'INVALID_ARGS', message: 'spec_id is required' };
 
   const dir = join(vaultRoot, 'specs', 'diagnoses');
@@ -99,6 +100,7 @@ export function resolveDiagnoseRef(vaultRoot, rawRef) {
   const load = (file) => {
     const absPath = join(dir, file);
     return {
+      source: 'disk',
       basename: file.replace(/\.md$/i, ''),
       absPath,
       relPath: join('specs', 'diagnoses', file),
@@ -146,6 +148,138 @@ export function resolveDiagnoseRef(vaultRoot, rawRef) {
   return notFound;
 }
 
+/** Strip a spec reference to the bare basename / id: `[[x]]`, quotes, `.md`. */
+function normalizeDiagnoseRef(rawRef) {
+  return typeof rawRef === 'string'
+    ? rawRef
+        .trim()
+        .replace(/^\[\[|\]\]$/g, '')
+        .replace(/^['"]|['"]$/g, '')
+        .replace(/\.md$/i, '')
+        .trim()
+    : '';
+}
+
+/**
+ * Resolve a diagnose reference through the console — `GET /api/specs/:id`, the
+ * same read `heyspex_submit_for_review` makes ([[HS-7UJZ-O86I-DIAG]]).
+ *
+ * The route accepts the frontmatter id, the basename, and (GET-only) a unique
+ * id prefix, and answers `404 ambiguous_id` with candidates when a prefix names
+ * more than one spec — mapped here onto the same error codes the disk resolver
+ * returns so a caller reads one contract. A transport failure or a non-404
+ * refusal is NOT "not found": it is reported as `CONSOLE_UNREACHABLE` so the
+ * caller can tell "no such diagnose" from "could not ask".
+ */
+export async function resolveDiagnoseViaConsole(consoleFetch, rawRef) {
+  const ref = normalizeDiagnoseRef(rawRef);
+  if (!ref) return { error: 'INVALID_ARGS', message: 'spec_id is required' };
+  const route = `GET /api/specs/${ref}`;
+  if (typeof consoleFetch !== 'function') {
+    return { error: 'CONSOLE_UNREACHABLE', message: `${route}: no console transport available` };
+  }
+  let res;
+  try {
+    res = await consoleFetch(`/api/specs/${encodeURIComponent(ref)}`);
+  } catch (err) {
+    return { error: 'CONSOLE_UNREACHABLE', message: `${route} failed: ${err?.message ?? err}` };
+  }
+  const notFound = {
+    error: 'DIAGNOSE_NOT_FOUND',
+    message: `diagnose ${rawRef} is not in the console's index either (${route} → 404)`,
+    status: 404,
+  };
+  if (!res?.ok) {
+    if (res?.status === 404) {
+      if (res.body?.error === 'ambiguous_id' && Array.isArray(res.body?.candidates)) {
+        return {
+          error: 'DIAGNOSE_ID_AMBIGUOUS',
+          message: `spec_id ${rawRef} is a prefix of ${res.body.candidates.length} specs in the console's index — pass the full basename instead`,
+          candidates: res.body.candidates,
+        };
+      }
+      return notFound;
+    }
+    return {
+      error: 'CONSOLE_UNREACHABLE',
+      message: `${route} returned ${res?.status ?? 0}${res?.error ? `: ${res.error}` : ''}`,
+      status: res?.status ?? 0,
+      console_response: res?.body ?? null,
+    };
+  }
+  const spec = res.body?.spec;
+  if (!spec || typeof spec !== 'object') return notFound;
+  const frontmatter =
+    spec.frontmatter && typeof spec.frontmatter === 'object' ? { ...spec.frontmatter } : {};
+  const relPath = typeof spec.relPath === 'string' ? spec.relPath : null;
+  const basename =
+    (typeof spec.basename === 'string' && spec.basename) ||
+    (relPath ? relPath.split('/').pop().replace(/\.md$/i, '') : null) ||
+    String(spec.id ?? frontmatter.id ?? ref);
+  return {
+    record: {
+      source: 'console',
+      basename,
+      specId: String(frontmatter.id ?? spec.id ?? basename),
+      relPath,
+      type: String(frontmatter.type ?? spec.type ?? ''),
+      status: String(frontmatter.status ?? spec.status ?? ''),
+      frontmatter,
+      body: typeof spec.body === 'string' ? spec.body : '',
+    },
+  };
+}
+
+/**
+ * Pick the record to write the verdict on — disk or console ([[HS-7UJZ-O86I-DIAG]]).
+ *
+ * `cloud` reliance asks the console FIRST: that is where a cloud-filed diagnose
+ * lives, and the close gate in the status API reads the same index, so a disk
+ * write there would be a split brain the gate never sees. Only a console 404
+ * falls back to the local scan (an unpushed file in a vault clone). Any other
+ * reliance keeps the disk scan first — byte-identical to the pre-cloud path —
+ * and only asks the console when the scan finds nothing; a console that cannot
+ * be reached then leaves the disk answer (`DIAGNOSE_NOT_FOUND`) standing, with
+ * the console's answer attached.
+ */
+export async function resolveDiagnoseRecord({ vaultRoot, consoleFetch, rawRef, reliance = null }) {
+  if (reliance === 'cloud') {
+    const viaConsole = await resolveDiagnoseViaConsole(consoleFetch, rawRef);
+    if (viaConsole.error !== 'DIAGNOSE_NOT_FOUND') return viaConsole;
+    const local = resolveDiagnoseRef(vaultRoot, rawRef);
+    if (!local.error) return local;
+    return { ...viaConsole, message: `${viaConsole.message}; ${local.message}` };
+  }
+  const local = resolveDiagnoseRef(vaultRoot, rawRef);
+  if (local.error !== 'DIAGNOSE_NOT_FOUND') return local;
+  const viaConsole = await resolveDiagnoseViaConsole(consoleFetch, rawRef);
+  if (viaConsole.error === 'DIAGNOSE_NOT_FOUND' || viaConsole.error === 'CONSOLE_UNREACHABLE') {
+    return {
+      ...local,
+      message: `${local.message}; ${viaConsole.message}`,
+      console: { error: viaConsole.error, status: viaConsole.status ?? null },
+    };
+  }
+  return viaConsole;
+}
+
+/** One frontmatter link value (string or list) as bare basenames. */
+function refListFromFrontmatter(value) {
+  const entries = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+  const out = [];
+  for (const entry of entries) {
+    const ref = normalizeDiagnoseRef(typeof entry === 'string' ? entry : '');
+    if (ref) out.push(ref);
+  }
+  return out;
+}
+
+/** {@link spawnedWorkRefs} for parsed frontmatter (the console's `spec.frontmatter`). */
+export function spawnedWorkRefsFromFrontmatter(frontmatter) {
+  if (!frontmatter || typeof frontmatter !== 'object') return [];
+  return SPAWNED_WORK_FIELDS.flatMap((field) => refListFromFrontmatter(frontmatter[field]));
+}
+
 /** Every spec this diagnose spawned — the link fields, never a parent edge. */
 export function spawnedWorkRefs(block) {
   const out = [];
@@ -181,6 +315,33 @@ export function buildVerifiedContent(raw, { result, evidence, by, now, today })
   return `${fm.open}${block}${fm.close}${body}`;
 }
 
+function changeLogMessage(result, evidence) {
+  const verdict =
+    result === 'no_longer_reproduces'
+      ? 'Reproduction re-run: NO LONGER REPRODUCES.'
+      : 'Reproduction re-run: STILL REPRODUCES.';
+  return `${verdict} ${evidence}`;
+}
+
+/**
+ * The console twin of {@link buildVerifiedContent}: the `{ frontmatter, body }`
+ * pair `PUT /api/specs/:id` takes, carrying the same four verdict fields and the
+ * same change-log row. The fields REPLACE any prior verdict (object spread), as
+ * `setScalarField` does on disk. `updated:` is left to the console — `updateSpec`
+ * stamps it on every write.
+ */
+export function buildVerifiedConsoleWrite(record, { result, evidence, by, now, today }) {
+  const frontmatter = {
+    ...record.frontmatter,
+    [REPRODUCTION_RERUN_FIELDS.at]: now,
+    [REPRODUCTION_RERUN_FIELDS.by]: by,
+    [REPRODUCTION_RERUN_FIELDS.result]: result,
+    [REPRODUCTION_RERUN_FIELDS.evidence]: evidence,
+  };
+  const body = appendChangeLogRow(record.body ?? '', today, by, changeLogMessage(result, evidence));
+  return { frontmatter, body };
+}
+
 /**
  * @param {{
  *   vaultRoot: string,
@@ -188,7 +349,12 @@ export function buildVerifiedContent(raw, { result, evidence, by, now, today })
  *   args?: Record<string, unknown>,
  *   clock?: () => string,
  *   agent?: string,
+ *   getReliance?: () => Promise<string|null>,
  * }} ctx
+ *
+ * `getReliance` resolves the session's console reliance (`cloud` | `local` |
+ * null). It defaults to "unknown", which keeps the disk-first order — the
+ * handler injects the real dev-mode resolver.
  */
 export async function executeVerifyReproduction({
   vaultRoot,
@@ -196,6 +362,7 @@ export async function executeVerifyReproduction({
   args = {},
   clock = isoNow,
   agent = 'agent',
+  getReliance = async () => null,
 }) {
   const result = typeof args.result === 'string' ? args.result.trim().toLowerCase() : '';
   if (!REPRODUCTION_VERDICTS.includes(result)) {
@@ -214,18 +381,45 @@ export async function executeVerifyReproduction({
     };
   }
 
-  const resolved = resolveDiagnoseRef(vaultRoot, args.spec_id);
+  let reliance = null;
+  try {
+    reliance = await getReliance();
+  } catch {
+    reliance = null;
+  }
+  const resolved = await resolveDiagnoseRecord({
+    vaultRoot,
+    consoleFetch,
+    rawRef: args.spec_id,
+    reliance,
+  });
   if (resolved.error) return resolved;
   const diagnose = resolved.record;
+  const viaConsole = diagnose.source === 'console';
 
-  const fm = getFrontmatterBlock(diagnose.raw);
-  if (!fm) {
-    return {
-      error: 'DIAGNOSE_FRONTMATTER_MISSING',
-      message: `${diagnose.basename} has no frontmatter — cannot record a reproduction re-run`,
-    };
+  let fm = null;
+  let type;
+  let specId;
+  let statusBefore;
+  let spawned;
+  if (viaConsole) {
+    type = diagnose.type.trim().toLowerCase();
+    specId = diagnose.specId;
+    statusBefore = (diagnose.status || 'open').trim().toLowerCase();
+    spawned = spawnedWorkRefsFromFrontmatter(diagnose.frontmatter);
+  } else {
+    fm = getFrontmatterBlock(diagnose.raw);
+    if (!fm) {
+      return {
+        error: 'DIAGNOSE_FRONTMATTER_MISSING',
+        message: `${diagnose.basename} has no frontmatter — cannot record a reproduction re-run`,
+      };
+    }
+    type = (getScalarField(fm.block, 'type') ?? '').trim().toLowerCase();
+    specId = getScalarField(fm.block, 'id') ?? diagnose.basename;
+    statusBefore = (getScalarField(fm.block, 'status') ?? 'open').trim().toLowerCase();
+    spawned = spawnedWorkRefs(fm.block);
   }
-  const type = (getScalarField(fm.block, 'type') ?? '').trim().toLowerCase();
   if (type && type !== 'diagnose') {
     return {
       error: 'NOT_A_DIAGNOSE',
@@ -234,27 +428,47 @@ export async function executeVerifyReproduction({
     };
   }
 
-  const specId = getScalarField(fm.block, 'id') ?? diagnose.basename;
-  const statusBefore = (getScalarField(fm.block, 'status') ?? 'open').trim().toLowerCase();
-  const spawned = spawnedWorkRefs(fm.block);
-
   const now = clock();
   const today = todayDate();
   const by = typeof args.by === 'string' && args.by.trim() ? args.by.trim() : agent;
 
-  const content = buildVerifiedContent(diagnose.raw, { result, evidence, by, now, today });
-  const commit = commitWrites([{ kind: 'update', absPath: diagnose.absPath, content }]);
-  if (!commit.ok) {
-    return {
-      error: 'WRITE_FAILED',
-      message: commit.error?.message ?? 'unknown write failure',
-    };
+  if (viaConsole) {
+    // Neon-only diagnose ([[HS-7UJZ-O86I-DIAG]]): the verdict lands through the
+    // console's own spec write, `PUT /api/specs/:id` — the route every cloud-mode
+    // edit already goes through (cloud-vault-writes.mjs) — so the status API's
+    // close gate reads the verdict from the same index this call just wrote.
+    const write = buildVerifiedConsoleWrite(diagnose, { result, evidence, by, now, today });
+    const put = await consoleFetch(`/api/specs/${encodeURIComponent(specId)}`, {
+      method: 'PUT',
+      body: write,
+    });
+    if (!put?.ok) {
+      return {
+        error: 'WRITE_FAILED',
+        message:
+          `PUT /api/specs/${specId} returned ${put?.status ?? 0}` +
+          (put?.error ? `: ${put.error}` : '') +
+          ' — the verdict was NOT recorded.',
+        status: put?.status ?? 0,
+        console_response: put?.body ?? null,
+      };
+    }
+  } else {
+    const content = buildVerifiedContent(diagnose.raw, { result, evidence, by, now, today });
+    const commit = commitWrites([{ kind: 'update', absPath: diagnose.absPath, content }]);
+    if (!commit.ok) {
+      return {
+        error: 'WRITE_FAILED',
+        message: commit.error?.message ?? 'unknown write failure',
+      };
+    }
   }
 
   const recorded = {
     spec_id: specId,
     basename: diagnose.basename,
-    path: diagnose.relPath,
+    path: diagnose.relPath ?? null,
+    recorded_via: viaConsole ? 'console' : 'disk',
     result,
     evidence,
     by,
@@ -262,6 +476,7 @@ export async function executeVerifyReproduction({
     spawned_work: spawned,
     status_before: statusBefore,
   };
+  const where = viaConsole ? "in the console's index" : 'on disk';
 
   // A run that still reproduces records and closes nothing — the diagnose is left
   // exactly as it was, and its Resolution row stays open.
@@ -293,6 +508,31 @@ export async function executeVerifyReproduction({
     body: { status: 'closed', close_reason: `Reproduction re-run ${now}: no longer reproduces.` },
   });
   if (!res?.ok) {
+    const refusalReason = typeof res?.body?.error === 'string' ? res.body.error : null;
+    // `REPRODUCTION_NOT_REVERIFIED` is the ONE refusal this call cannot honestly
+    // report as a soft "verdict recorded, could not close". The gate refuses on a
+    // missing/unclean verdict — and the clean verdict was written to disk a few
+    // lines above, by this very call. So the gate did not see the file it is
+    // gating on, and nothing the caller does next clears the reason it was given.
+    // Reported softly, an agent read it literally and handed off a finished bug as
+    // unfinished ([[HS-SC2Q-E7TN-DIAG-closing-a-diagnose-takes-two-calls-the]]).
+    // Surfaced as an error, so it reads as the console-side fault it is.
+    if (refusalReason === 'REPRODUCTION_NOT_REVERIFIED') {
+      return {
+        ...recorded,
+        error: 'CLOSE_GATE_STALE_VERDICT',
+        closed: false,
+        status: res?.status,
+        console_response: res?.body,
+        message:
+          `The clean verdict IS ${where} in \`${diagnose.basename}\`, but the console's close gate ` +
+          'refused with `REPRODUCTION_NOT_REVERIFIED` — it read a copy of the frontmatter from before ' +
+          'this write. This is a console-side staleness fault, not unfinished work: do NOT report the ' +
+          'diagnose as un-closed. Verify the console build carries the read-your-own-write heal in ' +
+          '`apply-status-transition.ts`; re-running this call closes the spec once the console has ' +
+          'caught up.',
+      };
+    }
     return {
       ...recorded,
       closed: false,
@@ -300,7 +540,7 @@ export async function executeVerifyReproduction({
       status: res?.status,
       console_response: res?.body,
       message:
-        'Verdict recorded on disk, but the status API did not close the spec. The record stands — ' +
+        `Verdict recorded ${where}, but the status API did not close the spec. The record stands — ` +
         're-run the close once the reason in `console_response` is cleared.',
     };
   }

package/vendor/heyspex-mcp/whoami.mjs

@@ -0,0 +1,92 @@
+// whoami.mjs — "which account does this machine's credential belong to?"
+//
+// ONE probe shared by `hs whoami` (cli-verbs.mjs `runWhoamiCli`) and the
+// install/connect identity gate (spex-console/src/lib/cli/install-identity.ts),
+// so the account a human is shown is exactly the account a later write would
+// bind to ([[HS-HAQI-KODY-DIAG-hs-install-and-hs-connect-bind-a-new]]).
+//
+// Plain Node ESM, zero dependencies (spex-console imports it straight from
+// TypeScript, same as folder-trust-store.mjs). Never prints, logs or returns
+// token material: callers only ever see an identity verdict.
+
+import { heyspexHome } from '../../scripts/lib/heyspex-home.mjs';
+import { homedir } from 'node:os';
+
+import { readBearer } from './credentials.mjs';
+
+/** Console route that resolves an `hsmcp_` / `hscmp_` bearer to its account. */
+export const SESSION_PATH = '/api/mcp/session';
+
+/**
+ * The bearer `hs whoami`, `hs connect` / `hs join` and the MCP server all send:
+ * `HEYSPEX_MCP_TOKEN` env first, then the top-level `mcp_token:` key of
+ * `~/.heyspex/credentials.yaml` — resolved by the ONE shared reader
+ * (`./credentials.mjs`, [[HS-HL0D-WW9R-TASK-share-one-bearer-reader-and-one-console]]),
+ * the same module `readPairedToken()` in spex-console/src/lib/cli/control-shared.ts
+ * delegates to. Never a first `hsmcp_`/`hscmp_` match anywhere in the file: a
+ * Companion token under `clerk:` is not this machine's MCP bearer, and probing
+ * it would show the human one account and bind another.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv | Record<string, string | undefined>, homeDir?: string, readFile?: (p: string) => string }} [opts]
+ * @returns {string | null}
+ */
+export function readStoredBearer({ env = process.env, homeDir = heyspexHome(), readFile } = {}) {
+  return readBearer({ env, homeDir, readFile }).token;
+}
+
+/**
+ * Ask `consoleUrl` who `token` belongs to.
+ *
+ * Returns one of:
+ *   { kind: 'no_credential' }
+ *   { kind: 'identified', accountId, email, displayName, consoleUrl }
+ *   { kind: 'rejected', status }          — 401/403: token unknown or revoked
+ *   { kind: 'unsupported', status }       — 404/405: console predates this route
+ *   { kind: 'unreachable', message }      — network error / non-JSON / 5xx
+ *
+ * @param {{ consoleUrl?: string, token?: string | null, fetchImpl?: (url: string, init?: object) => Promise<any> }} [opts]
+ */
+export async function probeCredentialIdentity({ consoleUrl, token, fetchImpl = fetch } = {}) {
+  if (!token) return { kind: 'no_credential' };
+  const base = String(consoleUrl ?? '').trim().replace(/\/+$/, '');
+  let res;
+  try {
+    res = await fetchImpl(`${base}${SESSION_PATH}`, {
+      method: 'GET',
+      headers: { authorization: `Bearer ${token}` },
+      cache: 'no-store',
+    });
+  } catch (err) {
+    return { kind: 'unreachable', message: err?.message ?? String(err) };
+  }
+  if (res.status === 401 || res.status === 403) return { kind: 'rejected', status: res.status };
+  if (res.status === 404 || res.status === 405) return { kind: 'unsupported', status: res.status };
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  if (!res.ok || !body || typeof body.userId !== 'string' || !body.userId.trim()) {
+    return { kind: 'unreachable', message: `console returned ${res.status}` };
+  }
+  return {
+    kind: 'identified',
+    accountId: body.userId.trim(),
+    email: typeof body.email === 'string' && body.email.trim() ? body.email.trim() : null,
+    displayName:
+      typeof body.displayName === 'string' && body.displayName.trim() ? body.displayName.trim() : null,
+    // How the console authenticated this caller (the route's `mode`, e.g. a
+    // bearer); the `hs login` receipt shows it ([[HS-CRNE-WW9R-TASK-give-hs-install-and-hs-login-the]]).
+    mode: typeof body.mode === 'string' && body.mode.trim() ? body.mode.trim() : null,
+    consoleUrl: base,
+  };
+}
+
+/**
+ * `email (account id)`, or just the account id when the console has no email for it.
+ * @param {{ email?: string | null, accountId: string }} identity
+ */
+export function formatIdentity({ email, accountId }) {
+  return email ? `${email} (${accountId})` : accountId;
+}