heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/research-focus.mjs

@@ -11,10 +11,27 @@ import {
   rmSync,
   readdirSync,
 } from 'node:fs';
-import { join } from 'node:path';
+import { join, isAbsolute, resolve, sep } from 'node:path';
 import { parseSimpleFocusYaml } from './capture-focus.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
-import { familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { ownerFrontmatterEntry, resolveSessionOwner } from './session-owner.mjs';
+import { collectOccupiedKeysEitherKind, familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+// Cloud-mode vault WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+// `heyspex_complete_research` is a promotion in the same shape as the others:
+// it CREATES a research doc and then LINKS the source idea/capture to it via
+// `promoted_to:` — a basename the console only mints when the POST answers.
+import {
+  createSpecViaConsole,
+  updateSpecViaConsole,
+} from './cloud-vault-writes.mjs';
+import {
+  fetchSpecRecordViaConsole,
+  resolveWriteModeFromDeps,
+  splitRawSpecForConsole,
+  cloudWriteFailureResult,
+} from './promotion-helpers.mjs';
+
 
 export function researchFocusPath(vaultRoot) {
   return join(vaultRoot, '.heyspex', 'research-focus.yaml');
@@ -42,6 +59,11 @@ export function writeResearchFocus(vaultRoot, { specPath, sourceIdeaId, scope, r
     return { error: 'INVALID_SCOPE', message: `scope must be one of ${[...VALID_SCOPES].join('|')}` };
   }
   const dir = join(vaultRoot, '.heyspex');
+  try {
+    assertPathUnderRoot(vaultRoot, dir, 'research-focus write');
+  } catch (err) {
+    return { error: 'BAD_VAULT_ROOT', message: err.message };
+  }
   mkdirSync(dir, { recursive: true });
   const lines = [
     '# HeySpex research-on-deck — MCP /hs-res ([[idea-capture-guardrails]])',
@@ -189,6 +211,161 @@ function collectOccupiedResearchIds(vaultRoot) {
   return occupied;
 }
 
+/**
+ * Cloud write mode ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]):
+ * the same two-step promotion the disk path performs, reordered CREATE FIRST /
+ * LINK SECOND because the console mints the research doc's id, family and
+ * filename — so the `promoted_to:` wikilink the source idea gets can only be
+ * built after `POST /api/specs` returns.
+ *
+ * Nothing is minted locally: `mintFileKey` / `mintFamilyKey` /
+ * `allocateRandomVaultId` all draw against a vault scan, which in a file-less
+ * vault is empty and can therefore collide with a key the cloud vault already
+ * holds. An INHERITED family (read off the source idea, never minted) is still
+ * passed through, matching the disk path's precedence.
+ *
+ * The research-focus PIN stays on local disk: it is per-workstation machine
+ * state under the local dot-directory, not vault content, and nothing indexes
+ * it (same call HS-KR16 made for the promote-research review-gate markers).
+ */
+async function completeResearchViaConsole(vaultRoot, args, deps, { sourceIdeaId, scope }) {
+  const cloudDeps = { consoleFetch: deps?.consoleFetch, consoleUrl: deps?.consoleUrl };
+  const completed = [];
+
+  // 1. The source idea/capture, through the console — there is no local file.
+  let ideaRecord;
+  try {
+    ideaRecord = await fetchSpecRecordViaConsole(deps?.consoleFetch, sourceIdeaId);
+  } catch (err) {
+    return cloudWriteFailureResult(err, {
+      step: { kind: 'read', type: 'source_idea', spec_id: sourceIdeaId },
+      completed,
+    });
+  }
+  if (!ideaRecord) {
+    return {
+      error: 'IDEA_NOT_FOUND',
+      message: `Source idea ${sourceIdeaId} was not found through the console (cloud write mode — no local vault is consulted).`,
+    };
+  }
+
+  const ideaFmId =
+    ideaRecord.raw.match(/^id:\s*(\S+)/m)?.[1]?.replace(/^['"]|['"]$/g, '') ?? null;
+  const ideaFamilyValue =
+    ideaRecord.raw.match(/^family:\s*(\S+)/m)?.[1]?.replace(/^['"]|['"]$/g, '') ?? null;
+  const familyKey = familyOf({
+    id: ideaFmId ?? sourceIdeaId,
+    basename: ideaRecord.basename,
+    frontmatter: { family: ideaFamilyValue },
+  });
+
+  const today = new Date().toISOString().slice(0, 10);
+  const tags = Array.isArray(args.tags) ? args.tags : ['research'];
+  const related = Array.isArray(args.related) ? [...args.related] : [];
+  const sourceLink = `[[${ideaRecord.basename}]]`;
+  if (!related.some((r) => String(r).includes(sourceIdeaId))) {
+    related.unshift(sourceLink);
+  }
+
+  // 2. CREATE FIRST. `id`/`file_id`/`created`/`updated` are all server-minted
+  //    and therefore absent from the request by construction — and so is
+  //    `status` ([[HS-ISZP]]): the console seeds `open` and refuses an
+  //    out-of-band status on create.
+  const frontmatter = {
+    ...(familyKey ? { family: familyKey } : {}),
+    // An explicit `args.owner` wins; else the paired session account; else the
+    // key is OMITTED ([[HS-WE87-WW9R-TASK-thread-the-gated-caller-through-every]]).
+    ...ownerFrontmatterEntry({
+      explicit: args.owner,
+      resolve: deps?.resolveSessionOwner ?? resolveSessionOwner,
+    }),
+    tags,
+    related,
+    source_idea: sourceLink,
+    scope,
+  };
+  let created;
+  try {
+    created = await createSpecViaConsole({
+      ...cloudDeps,
+      type: 'research',
+      name: args.title,
+      summary: args.executive_summary?.trim() || args.summary?.trim() || null,
+      frontmatter,
+      body: buildResearchBody(args, { sourceIdeaId, scope }),
+      actingAgent: deps?.actingAgent ?? null,
+    });
+  } catch (err) {
+    return cloudWriteFailureResult(err, {
+      step: { kind: 'create', type: 'research', name: args.title },
+      completed,
+    });
+  }
+  completed.push({
+    kind: 'create',
+    type: 'research',
+    spec_id: created.specId,
+    basename: created.basename,
+    rel_path: created.relPath,
+  });
+
+  // 3. …LINK SECOND: the idea's `promoted_to:` names the basename the POST
+  //    returned, so this could not have been built any earlier.
+  const ideaSplit = splitRawSpecForConsole(ideaRecord.raw);
+  const ideaFrontmatter = {
+    ...ideaSplit.frontmatter,
+    promoted_to: `[[${created.basename}]]`,
+    updated: today,
+  };
+  try {
+    const res = await updateSpecViaConsole({
+      ...cloudDeps,
+      specId: ideaFmId ?? sourceIdeaId,
+      frontmatter: ideaFrontmatter,
+      body: ideaSplit.body,
+    });
+    completed.push({
+      kind: 'update',
+      type: 'source_idea',
+      spec_id: res.specId,
+      basename: res.basename ?? ideaRecord.basename,
+      rel_path: res.relPath,
+    });
+  } catch (err) {
+    return {
+      error: 'IDEA_UPDATE_FAILED',
+      message:
+        `Research ${created.specId} was created through the console at ${created.relPath}, but linking ` +
+        `${sourceIdeaId} back to it failed: ${String(err?.message ?? err)}`,
+      research_id: created.specId,
+      research_path: created.relPath,
+      write_mode: 'cloud',
+      completed_steps: completed,
+      partial: true,
+    };
+  }
+
+  const pinResult = clearResearchFocus(vaultRoot);
+
+  return {
+    success: true,
+    write_mode: 'cloud',
+    research_id: created.specId,
+    research_path: created.relPath,
+    research_basename: created.basename,
+    source_idea_id: sourceIdeaId,
+    source_idea_path: ideaRecord.relPath,
+    scope,
+    pin_cleared: pinResult.existed,
+    writes: completed.map((w) => ({ kind: w.kind, path: w.rel_path ?? null, spec_id: w.spec_id })),
+    next_steps: [
+      `Open ${created.specId} in console to review the draft research`,
+      'Add wikilinks back to related specs',
+      'Add `enhances:` to bind this research to a milestone, or `bound_epic:` when an epic is filed from it',
+    ],
+  };
+}
+
 /**
  * Atomically write the research file, update the source idea's `promoted_to`,
  * and clear the research-focus pin. Returns the new research id + path.
@@ -237,6 +414,20 @@ export function executeCompleteResearch(vaultRoot, args = {}, deps = {}) {
       };
     }
   }
+  // ── Vault WRITE mode ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]) ──
+  //
+  // Resolved ONCE here from `deps.writeMode` (the caller's single
+  // `resolveVaultWriteMode()` call) and defaulting to `local`, so every
+  // pre-existing caller keeps the SYNCHRONOUS disk path below — this function
+  // is deliberately NOT declared `async`: `handleCompleteResearch` consumes
+  // its return value synchronously, and making it async would turn that into
+  // an unawaited Promise. The cloud branch returns a Promise instead, which a
+  // cloud-aware caller awaits (and `await` on the plain object the disk branch
+  // returns is a no-op, so one call site can serve both).
+  if (resolveWriteModeFromDeps(deps) === 'cloud') {
+    return completeResearchViaConsole(vaultRoot, args, deps, { sourceIdeaId, scope });
+  }
+
   if (!deps.allocateRandomVaultId) {
     return { error: 'MISSING_DEPS', message: 'allocateRandomVaultId is required' };
   }
@@ -284,11 +475,19 @@ export function executeCompleteResearch(vaultRoot, args = {}, deps = {}) {
     mintFamilyKey(vaultRoot);
   // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
   // and (V3) the anchor for `id:` itself.
-  const fileKey = mintFileKey(vaultRoot);
+  // Disk occupancy ([[HS-FJWL]]): this writer commits through the disk-only
+  // `commitWrites`, and the caller resolves `deps.writeMode` before reaching
+  // it, so the vault walk is complete on every path that gets here.
+  const fileKey = mintFileKey(collectOccupiedKeysEitherKind(vaultRoot));
   const newId = `HS-${fileKey}`;
   const slug = slugify(args.title);
   const filename = `${newId}-${familyKey}-RES-${slug}.md`;
   const researchDir = join(vaultRoot, 'specs', 'research');
+  try {
+    assertPathUnderRoot(vaultRoot, researchDir, 'research-focus write');
+  } catch (err) {
+    return { error: 'BAD_VAULT_ROOT', message: err.message };
+  }
   mkdirSync(researchDir, { recursive: true });
   const absResearchPath = join(researchDir, filename);
 
@@ -307,7 +506,11 @@ export function executeCompleteResearch(vaultRoot, args = {}, deps = {}) {
     name: args.title,
     type: 'research',
     status: 'open',
-    owner: args.owner || 'pwher',
+    // Same owner rule as the cloud twin above.
+    ...ownerFrontmatterEntry({
+      explicit: args.owner,
+      resolve: deps?.resolveSessionOwner ?? resolveSessionOwner,
+    }),
     created: today,
     updated: today,
     tags,