heyspex 0.2.0 → 0.2.1

package/scripts/lib/hs-source-branch.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * hs-source-branch.mjs — `hs source branch declare|show`, plus
+ * `resolvePushBranch` used by `hs source push` when no branch is typed
+ * ([[HS-G01N-CWPX-TASK-hs-source-declares-the-session-branch]], epic
+ * [[HS-B8CY-CWPX-EPIC-one-session-one-reviewable-change]]).
+ *
+ * The branch DECISION stays on the server: `GET /api/source/session-branch`
+ * runs the one shared resolver (`resolveSessionTargetBranch`,
+ * spex-console/src/lib/git-export/branch-resolver.ts) — the same function the
+ * cloud-write drain calls. This module never re-implements ref validation or
+ * the dated-branch rule; it only declares, asks, and falls back to the local
+ * HEAD when the console cannot be reached (and says so).
+ *
+ * The HTTP client is injectable (`fetchImpl`) so tests never touch a network;
+ * console URL + bearer reuse the same idiom as `hs-source-log.mjs`.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveConsoleUrl } from './console-url-resolver.mjs';
+import { bearerHeaderFor } from './hs-source-log.mjs';
+import { hookVaultHeaders } from './hook-vault-header.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+const ENDPOINT = '/api/source/session-branch';
+
+/**
+ * Current checked-out branch, or null (detached HEAD / git unavailable).
+ * @param {{ cwd?: string, run?: (cmd: string, args: string[], opts: object) => { status: number|null, stdout?: string } }} [opts]
+ * @returns {string | null}
+ */
+export function currentGitBranch({ cwd = process.cwd(), run = spawnSync } = {}) {
+  try {
+    const r = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, encoding: 'utf8' });
+    const out = (r.stdout ?? '').toString().trim();
+    if (r.status !== 0 || !out || out === 'HEAD') return null;
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+async function callConsole({ method, body, fetchImpl, consoleUrl, repoRoot }) {
+  const base = consoleUrl ?? resolveConsoleUrl({ repoRoot });
+  const headers = { ...bearerHeaderFor(base), ...hookVaultHeaders() };
+  if (body !== undefined) headers['content-type'] = 'application/json';
+  const res = await fetchImpl(`${base}${ENDPOINT}`, {
+    method,
+    headers,
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  let json = null;
+  try {
+    json = await res.json();
+  } catch {
+    json = null;
+  }
+  return { ok: res.ok, status: res.status, json, base };
+}
+
+/**
+ * Ask the console which branch this session's work should target.
+ * Never throws. `via: 'console'` carries the resolver's `source`
+ * ('session' | 'dated'); `via: 'git-head'` is the explicit offline fallback.
+ * @returns {Promise<{ branch: string, via: 'console'|'git-head', source?: string, note?: string } | { branch: null, via: 'none', note: string }>}
+ */
+export async function resolvePushBranch({
+  fetchImpl = fetch,
+  cwd = process.cwd(),
+  consoleUrl,
+  repoRoot,
+  run,
+} = {}) {
+  try {
+    const r = await callConsole({ method: 'GET', fetchImpl, consoleUrl, repoRoot });
+    const branch = r.ok ? r.json?.target?.branch : null;
+    if (typeof branch === 'string' && branch) {
+      return { branch, via: 'console', source: r.json.target.source };
+    }
+  } catch {
+    // fall through to the local fallback
+  }
+  const head = currentGitBranch({ cwd, run });
+  if (head) {
+    return {
+      branch: head,
+      via: 'git-head',
+      note: `console unreachable — pushing the checked-out branch \`${head}\` instead of the resolver's target`,
+    };
+  }
+  return { branch: null, via: 'none', note: 'console unreachable and no checked-out branch to fall back to' };
+}
+
+/**
+ * Spec commits the cloud drain made for this session, from the same console
+ * endpoint ([[HS-OAD2-CWPX-TASK-hs-source-status-names-the-spec-commits]]).
+ * Never throws. `known: false` means the console could not answer — callers
+ * must NOT present that as "no commits".
+ * @returns {Promise<{ known: true, commits: Array<{repo:string,branch:string,commitSha:string,settledAt:string,specIds:string[]}>, basis?: string } | { known: false }>}
+ */
+export async function fetchDrainCommits({ fetchImpl = fetch, consoleUrl, repoRoot } = {}) {
+  try {
+    const r = await callConsole({ method: 'GET', fetchImpl, consoleUrl, repoRoot });
+    if (!r.ok || !Array.isArray(r.json?.drainCommits)) return { known: false };
+    return { known: true, commits: r.json.drainCommits, basis: r.json.window?.basis };
+  } catch {
+    return { known: false };
+  }
+}
+
+/**
+ * Pure formatter for the `hs source status` section.
+ * @param {Awaited<ReturnType<typeof fetchDrainCommits>>} result
+ * @returns {string[]}
+ */
+export function formatDrainCommits(result) {
+  const head = 'Cloud spec commits (this session):';
+  if (!result.known) return [head, '  unknown (console unreachable)'];
+  if (result.commits.length === 0) return [head, '  No cloud spec commits for this session.'];
+  const lines = [head];
+  for (const c of result.commits) {
+    lines.push(`  ${c.branch} @ ${String(c.commitSha).slice(0, 7)}  ${c.specIds.join(', ')}`);
+  }
+  if (result.basis === 'last_12h') lines.push('  (no branch declared — showing the last 12 hours)');
+  return lines;
+}
+
+/**
+ * `hs source branch declare [<branch>]` / `hs source branch show`.
+ * @param {string[]} argv args after the `branch` verb
+ * @returns {Promise<number>} exit code
+ */
+export async function runBranchCommand(
+  argv,
+  { fetchImpl = fetch, cwd = process.cwd(), consoleUrl, repoRoot, run, out = console.log, err = console.error } = {},
+) {
+  const sub = argv[0] ?? 'show';
+
+  if (sub === 'show') {
+    try {
+      const r = await callConsole({ method: 'GET', fetchImpl, consoleUrl, repoRoot });
+      if (!r.ok || !r.json?.target) {
+        err(`hs source branch show: console answered ${r.status} — no target available.`);
+        return 1;
+      }
+      const t = r.json.target;
+      out(`target branch: ${t.branch} (${t.source === 'session' ? 'declared by this session' : 'dated fallback — no session branch declared'})`);
+      if (t.reason) out(`note: declared branch was refused — ${t.reason}`);
+      if (r.json.declaration) out(`declared ${r.json.declaration.declaredAt}, expires ${r.json.declaration.expiresAt}`);
+      return 0;
+    } catch (e) {
+      err(`hs source branch show: console unreachable (${e instanceof Error ? e.message : String(e)}).`);
+      return 1;
+    }
+  }
+
+  if (sub === 'declare') {
+    const branch = argv[1] ?? currentGitBranch({ cwd, run });
+    if (!branch) {
+      err('hs source branch declare: no branch given and no checked-out branch (detached HEAD?).');
+      return 1;
+    }
+    try {
+      const r = await callConsole({ method: 'POST', body: { branch }, fetchImpl, consoleUrl, repoRoot });
+      if (!r.ok) {
+        err(`hs source branch declare: refused — ${r.json?.reason ?? r.json?.error ?? `HTTP ${r.status}`}`);
+        return 1;
+      }
+      out(`declared session branch: ${r.json.declaration.branch} (expires ${r.json.declaration.expiresAt})`);
+      return 0;
+    } catch (e) {
+      err(`hs source branch declare: console unreachable (${e instanceof Error ? e.message : String(e)}).`);
+      return 1;
+    }
+  }
+
+  err(`hs source branch: unknown subcommand \`${sub}\` — expected declare|show.`);
+  return 2;
+}
+
+function invokedDirectly() {
+  try {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  // argv: [node, script, "branch", ...args]
+  runBranchCommand(process.argv.slice(3)).then((code) => process.exit(code));
+}

package/scripts/lib/hs-source-log.mjs

@@ -30,6 +30,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { readBearerToken } from '../../vendor/heyspex-mcp/credentials.mjs';
+import { hookVaultHeaders } from './hook-vault-header.mjs';
 import { resolveConsoleUrl } from './console-url-resolver.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -131,7 +132,7 @@ export async function lookupConsoleSettlement({
 
   let res;
   try {
-    res = await fetchImpl(url, { headers: { ...bearerHeaderFor(resolvedUrl) } });
+    res = await fetchImpl(url, { headers: { ...bearerHeaderFor(resolvedUrl), ...hookVaultHeaders() } });
   } catch (err) {
     return {
       found: false,

package/scripts/lib/hs-source-preflight.mjs

@@ -361,12 +361,26 @@ export function formatPreflightReport(plan) {
 
 /**
  * CLI entry for `hs source status`. Returns a process exit code; always 0
- * (read-only report, never fails the invocation itself).
- * @param {{ cwd?: string }} [opts]
+ * (read-only report, never fails the invocation itself). Appends the "Cloud
+ * spec commits (this session)" section from the console
+ * ([[HS-OAD2-CWPX-TASK-hs-source-status-names-the-spec-commits]]); the
+ * console lookup is lazy-imported and injectable, and an unreachable console
+ * prints "unknown", never "none".
+ * @param {{ cwd?: string, fetchDrainCommitsFn?: () => Promise<any> }} [opts]
+ * @returns {Promise<number>}
  */
-export function runStatusCommand({ cwd = process.cwd() } = {}) {
+export async function runStatusCommand({ cwd = process.cwd(), fetchDrainCommitsFn } = {}) {
   const status = getTreeStatus({ cwd });
   console.log(formatStatusReport(status));
+  try {
+    const mod = await import('./hs-source-branch.mjs');
+    const result = await (fetchDrainCommitsFn ?? mod.fetchDrainCommits)();
+    console.log('');
+    console.log(mod.formatDrainCommits(result).join('\n'));
+  } catch {
+    console.log('');
+    console.log('Cloud spec commits (this session):\n  unknown (console lookup unavailable)');
+  }
   return 0;
 }
 
@@ -398,5 +412,5 @@ function invokedDirectly() {
 if (invokedDirectly()) {
   const verb = process.argv[2];
   if (verb === 'preflight') process.exit(runPreflightCommand());
-  else process.exit(runStatusCommand());
+  else runStatusCommand().then((code) => process.exit(code));
 }