heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/close-branch-report.mjs

@@ -0,0 +1,102 @@
+/**
+ * Session-close branch report
+ * ([[HS-PPX7-CWPX-TASK-session-close-names-the-branch-each]], epic
+ * [[HS-B8CY-CWPX-EPIC-one-session-one-reviewable-change]] AC5).
+ *
+ * At close-out, names the branch each half of the session landed on — the
+ * CODE half (the checked-out git branch of the session's code repo) and the
+ * SPEC half (branches the cloud drain committed this session's specs to, read
+ * from `GET /api/source/session-branch`) — and says plainly whether they are
+ * the same branch. Pure core (`buildCloseBranchReport`) + a thin gatherer
+ * (`gatherCloseBranchReport`) with injected `consoleFetch` / `runGit`.
+ *
+ * Honesty rule: a half that could not be read is reported UNKNOWN, and an
+ * unknown half never yields a "same branch" claim.
+ */
+import { spawnSync } from 'node:child_process';
+
+/**
+ * The written rule for a drain commit that landed on a different branch than
+ * the code (mid-session drain while the working tree is on another branch).
+ * Mirrored verbatim into the live-proof runbook.
+ */
+export const MID_SESSION_DRAIN_RULE =
+  'The cloud drain commits spec files on its own branch without touching your working tree. ' +
+  'To join the halves: `git fetch origin <spec-branch>`, then on your code branch run ' +
+  '`git merge --no-ff origin/<spec-branch>` (or `git cherry-pick <commit>` for one commit). ' +
+  'Never rebase-merge; a dirty working tree is fine because the merge only adds spec files. ' +
+  'Next time run `hs source branch declare` before cloud writes so both halves land on one branch.';
+
+/**
+ * @param {{ codeBranch: string | null, specBranches: string[] | null, declared?: string | null }} input
+ *   codeBranch / specBranches are null when that half could not be read.
+ * @returns {{ status: 'same'|'differ'|'none'|'unknown', matches: boolean, lines: string[] }}
+ */
+export function buildCloseBranchReport({ codeBranch, specBranches, declared = null }) {
+  const lines = [];
+  lines.push(`Code branch: ${codeBranch ?? 'unknown (no checked-out branch / git unavailable)'}`);
+  if (specBranches === null) {
+    lines.push('Spec branch(es): unknown (console unreachable)');
+  } else if (specBranches.length === 0) {
+    lines.push('Spec branch(es): none — no cloud spec commits this session');
+  } else {
+    lines.push(`Spec branch(es): ${specBranches.join(', ')}`);
+  }
+  if (declared) lines.push(`Declared session branch: ${declared}`);
+
+  if (codeBranch === null || specBranches === null) {
+    const which = [codeBranch === null ? 'code' : null, specBranches === null ? 'spec' : null]
+      .filter(Boolean)
+      .join(' and ');
+    lines.push(`Match: unknown — the ${which} half could not be read.`);
+    return { status: 'unknown', matches: false, lines };
+  }
+  if (specBranches.length === 0) {
+    lines.push('Match: nothing to compare — the cloud drain made no spec commits for this session.');
+    return { status: 'none', matches: false, lines };
+  }
+  const differing = specBranches.filter((b) => b !== codeBranch);
+  if (differing.length === 0) {
+    lines.push('Match: yes — same branch, the code and the spec files can be reviewed together.');
+    return { status: 'same', matches: true, lines };
+  }
+  lines.push(`Match: NO — spec commits are on ${differing.join(', ')}, code is on ${codeBranch}.`);
+  lines.push(MID_SESSION_DRAIN_RULE);
+  return { status: 'differ', matches: false, lines };
+}
+
+function defaultRunGit(args, cwd) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+/** Current checked-out branch of `cwd`, or null. */
+export function readCodeBranch({ cwd = process.cwd(), runGit = defaultRunGit } = {}) {
+  try {
+    const r = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+    const out = String(r?.stdout ?? '').trim();
+    if (r?.status !== 0 || !out || out === 'HEAD') return null;
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gather both halves and build the report. Never throws.
+ * `consoleFetch(path)` is the MCP's console client (`{ ok, body }`).
+ */
+export async function gatherCloseBranchReport({ consoleFetch, cwd = process.cwd(), runGit } = {}) {
+  const codeBranch = readCodeBranch({ cwd, runGit });
+  let specBranches = null;
+  let declared = null;
+  try {
+    const res = await consoleFetch('/api/source/session-branch');
+    if (res?.ok && Array.isArray(res.body?.drainCommits)) {
+      specBranches = [...new Set(res.body.drainCommits.map((c) => c.branch).filter(Boolean))];
+      declared = res.body.declaration?.branch ?? null;
+    }
+  } catch {
+    specBranches = null;
+  }
+  return buildCloseBranchReport({ codeBranch, specBranches, declared });
+}

package/vendor/heyspex-mcp/cloud-tool-surface.mjs

@@ -0,0 +1,128 @@
+/**
+ * cloud-tool-surface.mjs — the tools the REMOTE MCP endpoint serves.
+ *
+ * `POST /api/mcp` on the console runs `dispatchHeySpexTool` in-process on a
+ * shared serverless runtime with NO vault checkout: `vaultRoot` points at a
+ * directory that does not exist, there is no git, and `~/.heyspex/*` is the
+ * lambda's own (empty) home. Only handlers that do their work through the
+ * console HTTP API in the neon read tier are correct there. This module is
+ * the explicit allowlist; `tools/list` on the remote endpoint returns exactly
+ * these, and `tools/call` on anything else answers "needs the local server".
+ *
+ * Every entry was verified by reading its handler (audit 2026-09-14, WP6):
+ *
+ *   PURE console-API handlers (no vault disk, no git, no home):
+ *     recall_memories (memory-tools.mjs neon branch), list_procedures
+ *     (procedure-handlers.mjs loadCatalogViaTier), handoff_record/load
+ *     (session-tools.mjs), claim_spec / release_spec / report_progress /
+ *     record_wip / defer_spec / claim_list / claim_acquire / claim_release
+ *     (claim-tools.mjs, all postClaimEndpoint/consoleFetch), pin_get / pin_set
+ *     / get_focus_areas / set_focus_areas (focus-tools.mjs), milestone_show /
+ *     events_show (events-tools.mjs), list_known_tags (spec-edit-tools.mjs).
+ *
+ *   Console-API handlers whose optional disk touches are read-only or fail
+ *   open (result still correct, some enrichment degrades):
+ *     get_procedure (marker write try/catch'd), preflight (marker write →
+ *     `marker_warning`; recipes readdir guarded → []), submit_for_review
+ *     (`.heyspex/config.yaml` review grain → default), file_spec (POST
+ *     /api/specs; landing probe defaults expectTier=cloud in neon),
+ *     next_on_deck (scheduler cohort + direct spec are tier-split to the
+ *     console; the synchronous enrichers — plans, amendments, WIP fallback,
+ *     memory scoring — are existsSync-guarded and silently empty),
+ *     active_capture (DB-first via the console; disk fallbacks guarded).
+ *
+ * Deliberately EXCLUDED (disk/git-bound or process-global in a shared runtime):
+ *   heyspex_update_capture      – stashes to `<vaultRoot>/.heyspex/capture-outbox`
+ *                                 on transport failure with no try/catch
+ *                                 (capture-outbox.mjs) — a lambda outbox is a
+ *                                 false "your words will sync" promise.
+ *   heyspex_validate_linkage    – full readdir walk of `<vaultRoot>/specs` (validate-linkage.mjs).
+ *   heyspex_next_review         – `git status`/`git show` via execSync + disk-only queue (next-review.mjs).
+ *   heyspex_dev_mode            – `set` writes `~/.heyspex/dev-mode.json` + credentials.yaml;
+ *                                 `get` would report the LAMBDA's mode, not the caller's.
+ *   heyspex_load_tools          – mutates the process-global `loadedToolNames`
+ *                                 (tool-catalog.mjs) shared by every tenant in the
+ *                                 container; the remote surface is fixed anyway.
+ *   heyspex_settings_list/get   – read `<vaultRoot>/.heyspex/config.yaml` → misleading defaults.
+ *   heyspex_design_*            – read `<vaultRoot>/spex-console/public/design-system/*` and DESIGN.md.
+ *   heyspex_list_recipes        – readdir `<vaultRoot>/specs/recipes`.
+ *   save_research, push_plan, backfill_epic, promote_*, register_spec,
+ *   edit_file, record_alignment (git shelling), regen_*, ground_plan,
+ *   plan_review/plan_qc, canvas_inbox, session_end/hooks_*, dev_server_status,
+ *   fleet_queue_*, firecrawl/research-plan, import_agent, start_recipe,
+ *   verify_reproduction, split_research, active/complete_research, pin_capture,
+ *   suggest_pillar, validate_user_skills, next_resolution, resolve_*,
+ *   claim_file/release_file_claim, evidence_show/export_events, propose_metadata
+ *                               – vault-disk, git, or local-process bound per
+ *                                 the cloud-first audit; not re-verified here.
+ */
+import { TOOLS } from './tool-catalog.mjs';
+
+/** Ordered allowlist — order is the order `tools/list` advertises them. */
+export const CLOUD_TOOL_NAMES = Object.freeze([
+  // session + procedure discovery
+  'heyspex_recall_memories',
+  'heyspex_list_procedures',
+  'heyspex_get_procedure',
+  'heyspex_preflight',
+  'heyspex_handoff_load',
+  'heyspex_handoff_record',
+  // the claim contract
+  'heyspex_next_on_deck',
+  'heyspex_claim_spec',
+  'heyspex_release_spec',
+  'heyspex_report_progress',
+  'heyspex_submit_for_review',
+  'heyspex_record_wip',
+  // author_summary_then_claim completion ([[HS-T41O-NZ8S-DIAG]]): in cloud
+  // write mode the handler is GET + PUT /api/specs/:id only — no disk. The
+  // lambda's own home resolves to prod/cloud, so the local branch never runs.
+  'heyspex_author_summary',
+  'heyspex_defer_spec',
+  'heyspex_claim_list',
+  'heyspex_claim_acquire',
+  'heyspex_claim_release',
+  // filing + read-side context
+  'heyspex_file_spec',
+  'heyspex_active_capture',
+  'heyspex_milestone_show',
+  'heyspex_events_show',
+  // [[HS-YFLS]] fix 2: the duplicate check before filing. `handleSearchSpecs`
+  // is PURE consoleFetch (GET /api/search only) — no vault disk, no git, no
+  // home — so it is correct on the shared runtime, and it is exactly the tool a
+  // remote agent needs before POST /api/specs.
+  'heyspex_search_specs',
+  'heyspex_list_known_tags',
+  // focus / pin control plane
+  'heyspex_pin_get',
+  'heyspex_pin_set',
+  'heyspex_get_focus_areas',
+  'heyspex_set_focus_areas',
+]);
+
+const CLOUD_TOOL_NAME_SET = new Set(CLOUD_TOOL_NAMES);
+const CATALOG_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+
+/** True when `name` is served by the remote endpoint. */
+export function isCloudSafeTool(name) {
+  return CLOUD_TOOL_NAME_SET.has(name);
+}
+
+/** True when `name` exists in the full catalog (local server surface). */
+export function isCatalogTool(name) {
+  return CATALOG_BY_NAME.has(name);
+}
+
+/**
+ * The catalog entries for the remote surface, in allowlist order. A name the
+ * catalog no longer carries is dropped (never a hole in `tools/list`); the
+ * unit test asserts the two stay in sync so a drift fails CI, not a client.
+ */
+export function cloudToolSurface() {
+  return CLOUD_TOOL_NAMES.map((name) => CATALOG_BY_NAME.get(name)).filter(Boolean);
+}
+
+/** Allowlisted names missing from the catalog — expected empty; surfaced for the test + doctor. */
+export function cloudSurfaceDrift() {
+  return CLOUD_TOOL_NAMES.filter((name) => !CATALOG_BY_NAME.has(name));
+}