heyspex 0.1.0 → 0.2.0

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

@@ -0,0 +1,325 @@
+// Small cross-cutting helpers for tool handlers: spec-id guards, the design
+// result wrapper, and the disk-landing measurement. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { statSync } from 'node:fs';
+import { relative } from 'node:path';
+import {
+  collectOccupiedFamilyKeysFromVault,
+  fileKeyFromBasename,
+  requireResolvableSpecId,
+} from './spec-id-lib.mjs';
+import { resolveSpecFileByFileKey } from './vault-io.mjs';
+import { getConfig } from './mcp-config.mjs';
+
+// Ambiguity guard for mutating ops ([[HS-EPIC-6SNQ-dual-read-resolver-grace-period-for-pipe]]
+// AC#3). A bare family token (`HS-P2TR`) names a whole shared-suffix family, so a
+// mutating op given one would act on an arbitrary family member.
+//
+// Era-3 escape ([[HS-0QVQ-RHIB-TASK]]): under era 3 a spec's `id:` IS a bare
+// `HS-<fileKey>` token, which the shape check alone cannot tell apart from a
+// family token. Before rejecting, try resolving the token as a FILE KEY — a
+// unique hit that is NOT also an occupied family key names exactly one spec
+// and is safe to act on. A token that matches BOTH namespaces (the
+// [[HS-SJOT-AEP1-DIAG]] cross-namespace collision) fails closed, naming both
+// interpretations — never silently pick one.
+//
+// Cloud reliance ([[HS-05ZW-XHR4-DIAG-the-capture-dropped-it-warning-blamed]]):
+// that file-key escape is a LOCAL `readdirSync` scan, and a cloud-filed spec has
+// no `.md` on this machine at all (`landed.onDisk: false`). So the scan could not
+// tell "genuinely ambiguous" apart from "this machine has no copy", and every
+// cloud-filed spec's own freshly minted id was refused by the very next tool
+// called on it. `classifyBareSpecId` now separates those two verdicts, and the
+// async `resolveSpecIdForMutation` asks the console before rejecting a token
+// that is merely unresolvable FROM HERE.
+
+/** How long the console disambiguation lookup may take before it is abandoned. */
+export const SPEC_ID_CONSOLE_LOOKUP_TIMEOUT_MS = 8000;
+
+/**
+ * Local-only verdict on a bare `HS-XXXX` spec id. One implementation shared by
+ * the synchronous guard and the async, console-aware resolver — never forked.
+ *
+ * @returns {{ kind: 'unambiguous' }
+ *          | { kind: 'local_file_key', path: string }
+ *          | { kind: 'collision', error: { error: string, message: string } }
+ *          | { kind: 'local_family', error: { error: string, message: string } }
+ *          | { kind: 'unresolved_locally', error: { error: string, message: string } }}
+ */
+export function classifyBareSpecId(vaultRoot, specId) {
+  const shapeError = requireResolvableSpecId(specId);
+  if (!shapeError) return { kind: 'unambiguous' };
+
+  const token = String(specId).trim().replace(/\.md$/i, '').replace(/^HS-/i, '').toUpperCase();
+  let byKey = null;
+  try {
+    byKey = resolveSpecFileByFileKey(vaultRoot, specId);
+  } catch {
+    byKey = null; // unreadable vault — the local scan could not answer
+  }
+  let isFamily = false;
+  try {
+    isFamily = collectOccupiedFamilyKeysFromVault(vaultRoot).has(token);
+  } catch {
+    isFamily = false;
+  }
+
+  if (byKey && isFamily) {
+    return {
+      kind: 'collision',
+      error: {
+        error: 'AMBIGUOUS_SPEC_ID',
+        message:
+          `"${specId}" matches BOTH the unique file key of ${byKey} AND the family key of other ` +
+          `specs (cross-namespace collision) — refusing to guess. Pass the full basename of the ` +
+          `spec you mean.`,
+      },
+    };
+  }
+  if (byKey) return { kind: 'local_file_key', path: byKey }; // clean era-3 file-key hit
+  if (isFamily) {
+    // PROVEN a family key against this vault, so the strong wording is earned.
+    return {
+      kind: 'local_family',
+      error: requireResolvableSpecId(specId, { confirmedFamily: true }),
+    };
+  }
+  // Neither namespace matched anything on disk. That is NOT proof of ambiguity —
+  // in cloud reliance it is the expected shape of a spec that lives only in Neon.
+  return { kind: 'unresolved_locally', error: shapeError };
+}
+
+/**
+ * Synchronous, local-only guard. Returns an error object to short-circuit on,
+ * or null when the id is safe to act on. Kept for callers (and tests) holding a
+ * vault root and no console; a tool handler should prefer
+ * {@link resolveSpecIdForMutation}, which additionally clears cloud-only ids.
+ */
+export function bareTokenSpecIdGuard(vaultRoot, specId) {
+  const verdict = classifyBareSpecId(vaultRoot, specId);
+  return verdict.error ?? null;
+}
+
+function errorResponse(payload) {
+  return { isError: true, content: [{ type: 'text', text: JSON.stringify(payload) }] };
+}
+
+/** Local mirror of spec-id-lib's (unexported) id normalizer. */
+function normalizeId(input) {
+  return String(input ?? '')
+    .trim()
+    .replace(/\.md$/i, '')
+    .toUpperCase();
+}
+
+/** `{ error, message }` for a token nothing could verify, naming WHY not. */
+function unverifiedResponse(specId, detail) {
+  return requireResolvableSpecId(specId, { detail });
+}
+
+/** Lazily-bound console transport; injectable for tests, never imported eagerly. */
+async function defaultConsoleFetch() {
+  const mod = await import('./console-transport.mjs');
+  return mod.consoleFetch;
+}
+
+/**
+ * Ask the console to resolve a bare token this machine cannot.
+ * `GET /api/specs/:id` resolves an era-3 file key server-side and answers with
+ * the full spec (including `basename`), or `404 { error: "ambiguous_id",
+ * candidates }` when the token really does name more than one spec.
+ *
+ * Never throws and never hangs: the transport carries an explicit timeout and
+ * every failure degrades to a rejection saying the id could not be VERIFIED
+ * from here. Silence is never upgraded into a claim about family keys.
+ */
+async function resolveBareSpecIdViaConsole(specId, deps = {}) {
+  let fetcher = deps.consoleFetch;
+  if (!fetcher) {
+    try {
+      fetcher = await defaultConsoleFetch();
+    } catch {
+      return {
+        error: unverifiedResponse(
+          specId,
+          'The console transport is unavailable in this process, so nothing was checked against the vault of record.',
+        ),
+      };
+    }
+  }
+
+  let res;
+  try {
+    res = await fetcher(`/api/specs/${encodeURIComponent(specId)}`, {
+      timeout: deps.timeoutMs ?? SPEC_ID_CONSOLE_LOOKUP_TIMEOUT_MS,
+    });
+  } catch (err) {
+    const why = err?.message ? String(err.message) : String(err);
+    return {
+      error: unverifiedResponse(
+        specId,
+        `The console lookup that would have resolved it failed (${why}).`,
+      ),
+    };
+  }
+
+  const body = res?.body ?? null;
+
+  if (res?.ok) {
+    const spec = body?.spec ?? null;
+    const basename =
+      typeof spec?.basename === 'string' && spec.basename.trim() ? spec.basename.trim() : null;
+    if (!basename) {
+      return {
+        error: unverifiedResponse(
+          specId,
+          'The console answered without a basename, so the id could not be pinned to one spec.',
+        ),
+      };
+    }
+    // Do NOT trust a resolution that does not carry the token asked about. A
+    // live `heyspex_register_spec` dry run once resolved one spec's basename to
+    // an UNRELATED spec ([[HS-J6IE]]); this gate is why a server-side fuzzy
+    // match can never do that here.
+    const resolvedKey = fileKeyFromBasename(basename);
+    const token = String(specId).trim().replace(/^HS-/i, '').toUpperCase();
+    const idMatches = normalizeId(spec?.id ?? '') === normalizeId(specId);
+    if (resolvedKey?.toUpperCase() !== token && !idMatches) {
+      return {
+        error: {
+          error: 'AMBIGUOUS_SPEC_ID',
+          message:
+            `"${specId}" was answered by the console with "${basename}", whose file key does not ` +
+            `match the token asked about — refusing to act on a resolution that changed the id. ` +
+            `Pass the full basename of the spec you mean.`,
+        },
+      };
+    }
+    return { basename };
+  }
+
+  if (body?.error === 'ambiguous_id') {
+    const candidates = Array.isArray(body.candidates) ? body.candidates : [];
+    return {
+      error: {
+        error: 'AMBIGUOUS_SPEC_ID',
+        message:
+          `"${specId}" names ${candidates.length || 'more than one'} specs in the vault of record` +
+          (candidates.length ? ` (${candidates.join(', ')})` : '') +
+          ` — refusing to guess. Pass the full basename of the spec you mean.`,
+      },
+    };
+  }
+
+  if (res?.status === 404) {
+    return {
+      error: unverifiedResponse(
+        specId,
+        'The vault of record has no spec under that id either (console answered 404).',
+      ),
+    };
+  }
+
+  const status =
+    res?.authProblem
+    || (res?.status === 0 || res?.status == null ? 'unreachable' : `HTTP ${res.status}`);
+  return {
+    error: unverifiedResponse(
+      specId,
+      `The console could not be asked (${status}), so nothing about this id was actually verified.`,
+    ),
+  };
+}
+
+/**
+ * THE shared entry point for every mutating tool handler that takes a
+ * `spec_id`. Resolves the id to something unambiguous, or returns the MCP error
+ * response to short-circuit on.
+ *
+ *  - full basename / already-unambiguous id → passes straight through
+ *  - bare token the LOCAL vault resolves to one file → passes through
+ *  - bare token only the CONSOLE can resolve → cleared, and rewritten to the
+ *    full basename so the caller acts on an unambiguous id
+ *  - genuinely ambiguous (either namespace, locally or server-side) → refused
+ *  - console unreachable / not signed in / 404 → refused, saying plainly that
+ *    the id could not be verified from this machine and why
+ *
+ * The console is consulted ONLY when the local scan came back empty, so the
+ * happy path costs exactly what it did before.
+ *
+ * `deps` is the test seam and nothing else: `{ vaultRoot }` overrides the
+ * resolved config, `{ consoleFetch }` replaces the transport (so no suite ever
+ * touches the live network), `{ timeoutMs }` shortens the lookup budget.
+ *
+ * @returns {Promise<{ specId: string, resolvedVia?: 'console' } | { response: object }>}
+ */
+export async function resolveSpecIdForMutation(specId, deps = {}) {
+  let verdict;
+  try {
+    verdict = classifyBareSpecId(deps.vaultRoot ?? getConfig().vaultRoot, specId);
+  } catch {
+    // Config unavailable — no local scan is possible, which is exactly the
+    // "could not answer from here" case, not proof of ambiguity.
+    const shapeError = requireResolvableSpecId(specId);
+    verdict = shapeError
+      ? { kind: 'unresolved_locally', error: shapeError }
+      : { kind: 'unambiguous' };
+  }
+
+  if (verdict.kind === 'unambiguous' || verdict.kind === 'local_file_key') {
+    return { specId: typeof specId === 'string' ? specId.trim() : specId };
+  }
+  if (verdict.kind !== 'unresolved_locally') return { response: errorResponse(verdict.error) };
+
+  const viaConsole = await resolveBareSpecIdViaConsole(specId, deps);
+  if (viaConsole.basename) return { specId: viaConsole.basename, resolvedVia: 'console' };
+  return { response: errorResponse(viaConsole.error ?? verdict.error) };
+}
+
+/**
+ * Back-compat face of {@link resolveSpecIdForMutation} for handlers that need
+ * only the veto and not the resolved id. Same single implementation.
+ */
+export async function ambiguousSpecIdResponse(specId, deps = {}) {
+  const resolved = await resolveSpecIdForMutation(specId, deps);
+  return resolved.response ?? null;
+}
+
+/**
+ * Measure a direct-to-disk vault write ([[HS-IOJW-5YDH-DIAG]] sweep). Tools that
+ * call writeFileSync themselves cannot land in the cloud, but they still
+ * reported on the request rather than the result — this stats the file so the
+ * `landed` block means the bytes are really there. Never throws.
+ */
+export function measureDiskLanding(vaultRoot, absPath) {
+  let onDisk = false;
+  let bytes = null;
+  try {
+    const st = statSync(absPath);
+    onDisk = st.isFile();
+    bytes = onDisk ? st.size : null;
+  } catch {
+    onDisk = false;
+    bytes = null;
+  }
+  return {
+    tier: 'disk',
+    reported_by: 'measured',
+    abs_path: absPath,
+    rel_path: vaultRoot ? relative(vaultRoot, absPath) : null,
+    on_disk: onDisk,
+    bytes,
+  };
+}
+
+export function wrapDesignResult(result) {
+  if (result && result.error) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+  };
+}