heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/regen-tasks.mjs

@@ -21,7 +21,24 @@
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, isAbsolute, resolve, sep } from 'node:path';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+// Cloud-mode vault WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+// Regen has no create-first/link-second reorder — nothing it writes links to a
+// basename another write in the same batch mints — but the same rule applies:
+// a `writeFileSync` under `specs/` in cloud mode is a split brain.
+import {
+  createSpecViaConsole,
+  updateSpecViaConsole,
+  stripServerMintedFields,
+} from './cloud-vault-writes.mjs';
+import {
+  resolveWriteModeFromDeps,
+  splitRawSpecForConsole,
+  cloudWriteFailureResult,
+  cloudModeUnsupportedWrite,
+} from './promotion-helpers.mjs';
+
 
 const TERMINAL_STATUSES = new Set([
   'closed',
@@ -49,6 +66,11 @@ export function softDeleteToTrash(vaultRoot, relPath, bucket = 'misc') {
   if (!existsSync(abs)) return { ok: false, error: 'not_found', source: relPath };
   const basename = relPath.split(/[\\/]/).pop() || `${timestamp()}-spec.md`;
   const trashDir = join(vaultRoot, 'specs', '.trash', bucket);
+  try {
+    assertPathUnderRoot(vaultRoot, trashDir, 'regen-tasks write');
+  } catch (err) {
+    return { ok: false, error: 'BAD_VAULT_ROOT', source: relPath, message: err.message };
+  }
   mkdirSync(trashDir, { recursive: true });
   const dest = join(trashDir, `${timestamp()}-${basename}`);
   renameSync(abs, dest);
@@ -136,7 +158,77 @@ function epicSlugFromRel(relPath) {
  *
  * Both modes return `{ ok, mode, task, epic, brief?, commit_result? }`.
  */
-export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body, retire_reason, loadTask }) {
+/**
+ * The cloud twin of the `.trash/` soft-delete — EXPLICIT DEGRADE.
+ *
+ * `softDeleteToTrash` renames a file into `specs/.trash/<bucket>/`, which is
+ * not a spec of any type the console models (no TYPE_TO_FOLDER entry, no id,
+ * no frontmatter contract), so there is no POST/PUT route that could carry it.
+ * In cloud mode the replacement still happens — `PUT /api/specs/:id` overwrites
+ * the body and the console keeps its own version history — but the local
+ * `.trash/` copy the [[destructive-action-checklist]] recovery procedure names
+ * does not exist. That is REPORTED on every affected entry rather than
+ * silently skipped, so the caller knows which recovery path applies.
+ */
+function cloudTrashDegrade(relPath) {
+  return cloudModeUnsupportedWrite(
+    `specs/.trash/… (soft-delete of ${relPath})`,
+    'a trash copy is not a spec of any type the console models, so there is no route to write it; the replacement itself still landed through PUT /api/specs/:id and the console keeps its own version history',
+    { recovery: 'Restore the previous body from the console\'s spec history rather than from a local .trash/ file.' },
+  );
+}
+
+/**
+ * Replace one existing spec's body through the console.
+ * `new_body` is the agent-authored full markdown (frontmatter + body), the
+ * same string the disk path writes verbatim.
+ */
+async function putBodyViaConsole(specId, newBody, cloudDeps) {
+  const { frontmatter, body } = splitRawSpecForConsole(newBody);
+  return updateSpecViaConsole({ ...cloudDeps, specId, frontmatter, body });
+}
+
+/**
+ * Cloud-mode `executeRegenTask` commit. Same result shape as the disk path
+ * plus `write_mode: 'cloud'` and the `.trash/` degrade note.
+ */
+async function regenTaskCommitViaConsole({ taskSummary, epicSummary, new_body, retire_reason, cloudDeps }) {
+  let res;
+  try {
+    res = await putBodyViaConsole(taskSummary.id, new_body, cloudDeps);
+  } catch (err) {
+    return {
+      ok: false,
+      ...cloudWriteFailureResult(err, {
+        step: { kind: 'update', type: 'task', spec_id: taskSummary.id },
+        completed: [],
+      }),
+    };
+  }
+  return {
+    ok: true,
+    mode: 'commit',
+    write_mode: 'cloud',
+    task: { id: res.specId ?? taskSummary.id, rel_path: res.relPath ?? taskSummary.rel_path },
+    retired_to: null,
+    retire_reason: retire_reason || null,
+    epic: epicSummary ? { id: epicSummary.id } : null,
+    cloud_mode_unsupported_writes: [cloudTrashDegrade(taskSummary.rel_path ?? taskSummary.id)],
+    message:
+      `Replaced the body of ${taskSummary.id} through the console (cloud write mode — nothing was written to local disk). ` +
+      'No local .trash/ copy was made; recover the previous body from the console\'s spec history.',
+  };
+}
+
+export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body, retire_reason, loadTask, writeMode, consoleFetch, consoleUrl }) {
+  // Vault WRITE mode ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]),
+  // resolved ONCE by the caller and defaulting to `local`. This function stays
+  // SYNCHRONOUS on the local path on purpose — `spec-edit-tools.mjs` consumes
+  // its return value synchronously — and returns a Promise only in cloud mode,
+  // which a cloud-aware caller awaits (awaiting the plain object the local
+  // path returns is a no-op, so one call site serves both).
+  const cloudWriteMode = resolveWriteModeFromDeps({ writeMode });
+  const cloudDeps = { consoleFetch, consoleUrl };
   if (!task_id) {
     return { ok: false, error: 'MISSING_TASK_ID', message: 'task_id is required' };
   }
@@ -159,6 +251,15 @@ export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body,
         message: 'commit: true requires non-empty new_body',
       };
     }
+    if (cloudWriteMode === 'cloud') {
+      return regenTaskCommitViaConsole({
+        taskSummary,
+        epicSummary,
+        new_body,
+        retire_reason,
+        cloudDeps,
+      });
+    }
     if (!taskSummary.rel_path) {
       return { ok: false, error: 'NO_REL_PATH', task_id };
     }
@@ -172,6 +273,11 @@ export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body,
     // it — that's an agent error and surfaces as a malformed spec at the
     // next /hs-next.
     const destAbs = join(vaultRoot, taskSummary.rel_path);
+    try {
+      assertPathUnderRoot(vaultRoot, dirname(destAbs), 'regen-tasks write');
+    } catch (err) {
+      return { ok: false, error: 'BAD_VAULT_ROOT', task_id, message: err.message };
+    }
     mkdirSync(dirname(destAbs), { recursive: true });
     writeFileSync(destAbs, new_body, 'utf8');
     return {
@@ -222,7 +328,93 @@ export function executeRegenTask(vaultRoot, { task_id, commit = false, new_body,
  * The tool is deliberately deterministic — the LLM thinking happens between
  * brief mode and commit mode in the calling agent.
  */
-export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, task_specs, loadTask }) {
+/**
+ * Cloud-mode `executeRegenTasksForEpic` commit — the same two entry shapes the
+ * disk path takes, routed through the console:
+ *
+ *   `{ id, new_body, retire_reason }` → `PUT /api/specs/:id` (replace in place;
+ *      no local `.trash/` copy — reported, see {@link cloudTrashDegrade}).
+ *   `{ new_id, body, rel_path }`      → `POST /api/specs` (the caller-supplied
+ *      `new_id`/`rel_path` are IGNORED: the console mints the id, the family
+ *      and the filename, so nothing is hand-picked — HS-BYU4 AC3. The minted
+ *      id is reported back in `wrote[]`.)
+ */
+async function regenTasksForEpicCommitViaConsole({ epicSummary, task_specs, loadTask, cloudDeps }) {
+  const retired = [];
+  const wrote = [];
+  const errors = [];
+  const unsupported = [];
+  for (const entry of task_specs) {
+    if (entry && typeof entry === 'object' && entry.id && typeof entry.new_body === 'string') {
+      const target = loadSpecRecord(loadTask, entry.id);
+      const specId = target?.id || target?.frontmatter?.id || entry.id;
+      try {
+        const res = await putBodyViaConsole(specId, entry.new_body, cloudDeps);
+        retired.push({ id: entry.id, trash_path: null, retire_reason: entry.retire_reason || null });
+        unsupported.push(cloudTrashDegrade(target?.relPath || target?.rel_path || entry.id));
+        wrote.push({ id: res.specId ?? specId, rel_path: res.relPath ?? null });
+      } catch (err) {
+        errors.push({
+          id: entry.id,
+          ...cloudWriteFailureResult(err, {
+            step: { kind: 'update', type: 'task', spec_id: specId },
+            completed: wrote,
+          }),
+        });
+      }
+    } else if (entry && typeof entry === 'object' && entry.new_id && typeof entry.body === 'string') {
+      const { frontmatter, body } = splitRawSpecForConsole(entry.body);
+      const cleaned = stripServerMintedFields(frontmatter);
+      try {
+        const created = await createSpecViaConsole({
+          ...cloudDeps,
+          type: cleaned.type ?? frontmatter.type ?? 'task',
+          name: cleaned.name ?? frontmatter.name ?? String(entry.new_id),
+          summary: cleaned.summary ?? null,
+          frontmatter: cleaned,
+          body,
+        });
+        wrote.push({
+          id: created.specId,
+          rel_path: created.relPath,
+          requested_id: entry.new_id,
+          note:
+            'The console minted this id/filename server-side; the caller-supplied `new_id`/`rel_path` were not used (file keys are never hand-picked).',
+        });
+      } catch (err) {
+        errors.push({
+          new_id: entry.new_id,
+          ...cloudWriteFailureResult(err, {
+            step: { kind: 'create', type: 'task', name: entry.new_id },
+            completed: wrote,
+          }),
+        });
+      }
+    } else {
+      errors.push({ entry, error: 'INVALID_SHAPE' });
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    mode: 'commit',
+    write_mode: 'cloud',
+    epic: { id: epicSummary.id },
+    retired,
+    wrote,
+    errors,
+    bucket: null,
+    ...(unsupported.length > 0 ? { cloud_mode_unsupported_writes: unsupported } : {}),
+    message:
+      `Stage-1-2-3 commit for ${epicSummary.id} through the console: replaced ${retired.length}, wrote ${wrote.length}, errors ${errors.length}. ` +
+      'Cloud write mode — nothing was written to local disk and no .trash/ copies were made; recover previous bodies from the console\'s spec history.',
+  };
+}
+
+export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, task_specs, loadTask, writeMode, consoleFetch, consoleUrl }) {
+  // Same once-per-call resolution + sync-unless-cloud contract as
+  // {@link executeRegenTask} above.
+  const cloudWriteMode = resolveWriteModeFromDeps({ writeMode });
+  const cloudDeps = { consoleFetch, consoleUrl };
   if (!epic_id) {
     return { ok: false, error: 'MISSING_EPIC_ID', message: 'epic_id is required' };
   }
@@ -255,6 +447,9 @@ export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, t
         message: 'commit: true requires task_specs: [{ id, new_body, retire_reason } | { new_id, body, rel_path }]',
       };
     }
+    if (cloudWriteMode === 'cloud') {
+      return regenTasksForEpicCommitViaConsole({ epicSummary, task_specs, loadTask, cloudDeps });
+    }
     const bucket = epicSlugFromRel(epicSummary.rel_path);
     const retired = [];
     const wrote = [];
@@ -273,6 +468,12 @@ export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, t
           continue;
         }
         const abs = join(vaultRoot, rel);
+        try {
+          assertPathUnderRoot(vaultRoot, dirname(abs), 'regen-tasks write');
+        } catch (err) {
+          errors.push({ id: entry.id, error: 'BAD_VAULT_ROOT', message: err.message });
+          continue;
+        }
         mkdirSync(dirname(abs), { recursive: true });
         writeFileSync(abs, entry.new_body, 'utf8');
         retired.push({ id: entry.id, trash_path: del.trash_path, retire_reason: entry.retire_reason || null });
@@ -283,6 +484,12 @@ export function executeRegenTasksForEpic(vaultRoot, { epic_id, commit = false, t
           errors.push({ new_id: entry.new_id, error: 'CONFLICT', rel_path: entry.rel_path });
           continue;
         }
+        try {
+          assertPathUnderRoot(vaultRoot, dirname(abs), 'regen-tasks write');
+        } catch (err) {
+          errors.push({ new_id: entry.new_id, error: 'BAD_VAULT_ROOT', message: err.message });
+          continue;
+        }
         mkdirSync(dirname(abs), { recursive: true });
         writeFileSync(abs, entry.body, 'utf8');
         wrote.push({ id: entry.new_id, rel_path: entry.rel_path });