heyspex 0.1.0

package/dist/cli/hs-claim.mjs

@@ -0,0 +1,541 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-claim.ts
+import { readFileSync as readFileSync4 } from "node:fs";
+import process2 from "node:process";
+
+// spex-console/src/lib/work-stages.ts
+var WORK_STAGES = [
+  "Grounding",
+  "Breaking down",
+  "Drafting",
+  "Validating",
+  "Testing",
+  "Reviewing"
+];
+function isWorkStage(value) {
+  return typeof value === "string" && WORK_STAGES.includes(value);
+}
+
+// spex-console/src/lib/cli/agent-identity.ts
+function resolveAgentIdentity(argAgent, argSession) {
+  const trimmedAgent = typeof argAgent === "string" ? argAgent.trim() : "";
+  const trimmedSession = typeof argSession === "string" ? argSession.trim() : "";
+  if (trimmedAgent && trimmedSession) {
+    return { agent: trimmedAgent, sessionId: trimmedSession };
+  }
+  const claudeSession = (process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || "").trim();
+  if (claudeSession) {
+    return {
+      agent: trimmedAgent || "Claude Code",
+      sessionId: trimmedSession || claudeSession
+    };
+  }
+  const cursorSession = (process.env.CURSOR_TRACE_ID || process.env.CURSOR_SESSION_ID || process.env.COMPOSER_SESSION_ID || "").trim();
+  if (cursorSession) {
+    return {
+      agent: trimmedAgent || "Cursor",
+      sessionId: trimmedSession || cursorSession
+    };
+  }
+  return {
+    agent: trimmedAgent || process.env.HEYSPEX_AGENT?.trim() || "External agent",
+    sessionId: trimmedSession || process.env.HEYSPEX_SESSION_ID?.trim() || process.env.HEYSPEX_AGENT_SESSION?.trim() || "local"
+  };
+}
+
+// spex-console/src/lib/cli/control-shared.ts
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var EXIT = {
+  /** Success. */
+  OK: 0,
+  /** Usage error — unknown subcommand/flag, or a missing required argument. */
+  USAGE: 1,
+  /** Claim race lost — the spec is already claimed by another agent (409). */
+  CONFLICT: 9,
+  /** Target not found — release of an unheld claim, etc. (404). */
+  NOT_FOUND: 10,
+  /** Invalid argument — bad `--ttl`, unknown `--kind`, unparseable date. */
+  INVALID_ARG: 11,
+  /** SpexConsole unreachable (network error reaching the dev server). */
+  CONSOLE_UNREACHABLE: 12,
+  /** Server failure — a non-OK response that isn't 400/402/404/409. */
+  WRITE_FAILED: 13,
+  /** Neon control plane absent — the endpoint returned 402 (upgrade required). */
+  NEON_REQUIRED: 14,
+  /**
+   * A cross-account `--account <id>` override was refused — the caller is
+   * not a builder/admin (`resolveScopedAccountId`'s `forbidden_account_override`,
+   * [[HS-X3GB-EKLJ-TASK-hs-cli-account-flag-for-cross-account]]). Distinct
+   * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
+   * malformed command.
+   */
+  FORBIDDEN: 15
+};
+function readPairedToken() {
+  try {
+    const raw = readFileSync(join(homedir(), ".heyspex", "credentials.yaml"), "utf-8");
+    const match = raw.match(/\b(hsmcp_[A-Za-z0-9_-]+|hscmp_[A-Za-z0-9_-]+)\b/);
+    return match?.[1];
+  } catch {
+    return void 0;
+  }
+}
+function bearerHeaderFor(consoleUrl) {
+  try {
+    const host = new URL(consoleUrl).hostname;
+    if (host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "::1") {
+      return {};
+    }
+    const token = readPairedToken();
+    return token ? { authorization: `Bearer ${token}` } : {};
+  } catch {
+    return {};
+  }
+}
+async function controlRequest(deps, req) {
+  const url = `${deps.consoleUrl}${req.path}`;
+  let res;
+  try {
+    res = await deps.fetchImpl(url, {
+      method: req.method,
+      headers: {
+        "content-type": "application/json",
+        // A remote console (cloud vault write mode, [[HS-PH7O-ILNC-DIAG-hs-check-report-cannot-authenticate]])
+        // authenticates every control call; loopback never asked, so the header
+        // is attached only when the target is non-loopback and a paired token
+        // exists. Same `hsmcp_` bearer the MCP server presents.
+        ...bearerHeaderFor(deps.consoleUrl)
+      },
+      ...req.body !== void 0 ? { body: JSON.stringify(req.body) } : {}
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: {
+        code: EXIT.CONSOLE_UNREACHABLE,
+        message: `could not reach console at ${deps.consoleUrl}: ${message}
+  Start the dev server or set HEYSPEX_CONSOLE_URL.`,
+        payload: {
+          ok: false,
+          error: "console_unreachable",
+          url: deps.consoleUrl,
+          message
+        },
+        isError: true
+      }
+    };
+  }
+  let parsed = null;
+  try {
+    parsed = await res.json();
+  } catch {
+  }
+  if (res.status === 402) {
+    return {
+      ok: false,
+      error: {
+        code: EXIT.NEON_REQUIRED,
+        message: "this command requires the Neon control plane, which is not configured (console returned 402).",
+        payload: {
+          ok: false,
+          error: "neon_required",
+          status: 402,
+          console_response: parsed
+        },
+        isError: true
+      }
+    };
+  }
+  return { ok: true, status: res.status, body: parsed };
+}
+function envelopeMessage(body) {
+  if (body && typeof body === "object" && "message" in body) {
+    const m = body.message;
+    if (typeof m === "string") return m;
+  }
+  return "";
+}
+function writeFailed(status, body) {
+  const detail = envelopeMessage(body);
+  return {
+    code: EXIT.WRITE_FAILED,
+    message: `console returned ${status}${detail ? `: ${detail}` : ""}`,
+    payload: { ok: false, error: "write_failed", status, console_response: body },
+    isError: true
+  };
+}
+function parseTtl(token) {
+  const trimmed = token.trim().toLowerCase();
+  if (trimmed === "none" || trimmed === "null") return { value: null };
+  const n = Number(trimmed);
+  if (!Number.isFinite(n) || n < 0) {
+    return { error: `--ttl must be a non-negative number of ms, or "none"` };
+  }
+  return { value: n };
+}
+
+// spex-console/src/lib/cli/claim.ts
+function parseClaimArgs(argv) {
+  const subRaw = argv[0];
+  if (subRaw === "--help" || subRaw === "-h" || subRaw === void 0) {
+    return { help: true };
+  }
+  if (subRaw !== "acquire" && subRaw !== "release" && subRaw !== "list" && subRaw !== "progress") {
+    return {
+      error: { code: EXIT.USAGE, message: `unknown subcommand: ${subRaw}` }
+    };
+  }
+  const sub = subRaw;
+  const takesSpecId = sub === "acquire" || sub === "release" || sub === "progress";
+  let specId;
+  let agent;
+  let session;
+  let agentProfile;
+  let ttlMs;
+  let stage;
+  let acProgress;
+  let json = false;
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--agent" || arg.startsWith("--agent=")) {
+      const v = arg === "--agent" ? argv[++i] : arg.slice("--agent=".length);
+      if (v === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--agent requires a value" } };
+      }
+      agent = v;
+    } else if (arg === "--session" || arg.startsWith("--session=")) {
+      const v = arg === "--session" ? argv[++i] : arg.slice("--session=".length);
+      if (v === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--session requires a value" } };
+      }
+      session = v;
+    } else if (arg === "--agent-profile" || arg.startsWith("--agent-profile=")) {
+      const v = arg === "--agent-profile" ? argv[++i] : arg.slice("--agent-profile=".length);
+      if (v === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--agent-profile requires a value" } };
+      }
+      agentProfile = v;
+    } else if (arg === "--ttl" || arg.startsWith("--ttl=")) {
+      const token = arg === "--ttl" ? argv[++i] : arg.slice("--ttl=".length);
+      if (token === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--ttl requires a value" } };
+      }
+      const res = parseTtl(token);
+      if ("error" in res) {
+        return { error: { code: EXIT.INVALID_ARG, message: res.error } };
+      }
+      ttlMs = res.value;
+    } else if (arg === "--stage" || arg.startsWith("--stage=")) {
+      const v = arg === "--stage" ? argv[++i] : arg.slice("--stage=".length);
+      if (v === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--stage requires a value" } };
+      }
+      stage = v;
+    } else if (arg === "--ac" || arg.startsWith("--ac=")) {
+      const v = arg === "--ac" ? argv[++i] : arg.slice("--ac=".length);
+      if (v === void 0) {
+        return { error: { code: EXIT.INVALID_ARG, message: "--ac requires a value" } };
+      }
+      const n = Number(v);
+      if (!Number.isInteger(n) || n < 0) {
+        return {
+          error: { code: EXIT.INVALID_ARG, message: "--ac must be a non-negative integer" }
+        };
+      }
+      acProgress = n;
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else if (takesSpecId && specId === void 0) {
+      specId = arg;
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  if (takesSpecId && !specId) {
+    return { error: { code: EXIT.USAGE, message: `claim ${sub} requires a spec id` } };
+  }
+  if (sub === "progress") {
+    if (!stage) {
+      return { error: { code: EXIT.USAGE, message: "claim progress requires --stage <verb>" } };
+    }
+    if (!isWorkStage(stage)) {
+      return {
+        error: {
+          code: EXIT.INVALID_ARG,
+          message: `--stage must be one of: ${WORK_STAGES.join(", ")}`
+        }
+      };
+    }
+  }
+  return { args: { sub, specId, agent, session, agentProfile, ttlMs, stage, acProgress, json } };
+}
+function describeClaim(c) {
+  if (!c) return "(unknown claim)";
+  return `${c.agentId ?? "?"}${c.sessionId ? ` \xB7 ${c.sessionId}` : ""}`;
+}
+async function runClaim(args, deps) {
+  if (args.sub === "list") {
+    const res2 = await controlRequest(deps, { method: "GET", path: "/api/control/active-claims" });
+    if (!res2.ok) return res2.error;
+    if (res2.status !== 200) return writeFailed(res2.status, res2.body);
+    const claims = res2.body?.claims ?? [];
+    const lines = claims.length ? claims.map((c) => `  ${c.specId ?? "?"} \u2014 ${describeClaim(c)}`).join("\n") : "  (no active claims)";
+    return {
+      code: EXIT.OK,
+      message: `${claims.length} active claim(s):
+${lines}`,
+      payload: { ok: true, claims },
+      isError: false
+    };
+  }
+  if (args.sub === "progress") {
+    const res2 = await controlRequest(deps, {
+      method: "PATCH",
+      path: `/api/specs/${encodeURIComponent(args.specId)}/claim/status`,
+      body: {
+        status: "working",
+        currentStage: args.stage,
+        ...args.acProgress !== void 0 ? { acProgress: args.acProgress } : {}
+      }
+    });
+    if (!res2.ok) return res2.error;
+    if (res2.status === 200) {
+      const acSuffix = args.acProgress !== void 0 ? ` (criterion ${args.acProgress})` : "";
+      return {
+        code: EXIT.OK,
+        message: `${args.specId}: ${args.stage}${acSuffix}`,
+        payload: {
+          ok: true,
+          spec_id: args.specId,
+          current_stage: args.stage,
+          ac_progress: args.acProgress
+        },
+        isError: false
+      };
+    }
+    if (res2.status === 404) {
+      return {
+        code: EXIT.NOT_FOUND,
+        message: `no active claim for ${args.specId} \u2014 claim it first (hs claim acquire ${args.specId})`,
+        payload: { ok: false, error: "not_found" },
+        isError: true
+      };
+    }
+    if (res2.status === 400) {
+      const detail = envelopeMessage(res2.body);
+      return {
+        code: EXIT.INVALID_ARG,
+        message: `console rejected the request${detail ? `: ${detail}` : ""}`,
+        payload: { ok: false, error: "invalid_request", message: detail },
+        isError: true
+      };
+    }
+    return writeFailed(res2.status, res2.body);
+  }
+  if (args.sub === "acquire") {
+    const id = resolveAgentIdentity(args.agent, args.session);
+    const res2 = await controlRequest(deps, {
+      method: "POST",
+      path: "/api/control/active-claims/acquire",
+      body: {
+        spec_id: args.specId,
+        agent: id.agent,
+        session_id: id.sessionId,
+        ...args.agentProfile ? { agent_profile: args.agentProfile } : {},
+        ...args.ttlMs !== void 0 ? { ttl_ms: args.ttlMs } : {}
+      }
+    });
+    if (!res2.ok) return res2.error;
+    if (res2.status === 200) {
+      const claim = res2.body?.claim;
+      return {
+        code: EXIT.OK,
+        message: `Claimed ${args.specId} as ${id.agent}`,
+        payload: { ok: true, acquired: true, claim },
+        isError: false
+      };
+    }
+    if (res2.status === 409) {
+      const existing = res2.body?.existing;
+      return {
+        code: EXIT.CONFLICT,
+        message: `${args.specId} is already claimed by ${describeClaim(existing)}`,
+        payload: { ok: false, acquired: false, error: "already_claimed", existing },
+        isError: true
+      };
+    }
+    if (res2.status === 400) {
+      const detail = envelopeMessage(res2.body);
+      return {
+        code: EXIT.INVALID_ARG,
+        message: `console rejected the request${detail ? `: ${detail}` : ""}`,
+        payload: { ok: false, error: "invalid_request", message: detail },
+        isError: true
+      };
+    }
+    return writeFailed(res2.status, res2.body);
+  }
+  const releaser = resolveAgentIdentity(args.agent, args.session).agent;
+  const path2 = `/api/control/active-claims/${encodeURIComponent(args.specId)}?agent=${encodeURIComponent(releaser)}`;
+  const res = await controlRequest(deps, { method: "DELETE", path: path2 });
+  if (!res.ok) return res.error;
+  if (res.status === 200) {
+    return {
+      code: EXIT.OK,
+      message: `Released ${args.specId}`,
+      payload: { ok: true, released: true },
+      isError: false
+    };
+  }
+  if (res.status === 404) {
+    return {
+      code: EXIT.NOT_FOUND,
+      message: `no active claim for ${args.specId}`,
+      payload: { ok: false, released: false, error: "not_found" },
+      isError: true
+    };
+  }
+  if (res.status === 400) {
+    const detail = envelopeMessage(res.body);
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `console rejected the request${detail ? `: ${detail}` : ""}`,
+      payload: { ok: false, error: "invalid_request", message: detail },
+      isError: true
+    };
+  }
+  return writeFailed(res.status, res.body);
+}
+var HELP = [
+  "Usage:",
+  "  hs claim acquire <spec-id> [flags]   Atomically claim a spec",
+  "  hs claim release <spec-id> [flags]   Release a claim",
+  "  hs claim list [--json]               List all active claims",
+  "  hs claim progress <spec-id> --stage <verb> [--ac <n>]",
+  "                                       Report the current work-stage of a claim",
+  "",
+  "Wraps the /api/control/active-claims endpoints (Neon control plane). Acquire",
+  "is atomic: two concurrent acquires for one spec yield exactly one success and",
+  "one `already_claimed` conflict (exit 9). `progress` PATCHes the claim status",
+  "route so the live verb shows on the What's Next surface.",
+  "",
+  "Flags:",
+  "  --agent <name>          Claiming agent (default: detected identity).",
+  "  --session <id>          Session id (default: detected identity).",
+  "  --agent-profile <slug>  Bind the claim to an agent identity (acquire only).",
+  "  --ttl <ms|none>         Claim fuse in ms; `none` = no fuse (acquire only).",
+  "  --stage <verb>          Work-stage verb for `progress` (Grounding, Breaking",
+  "                          down, Drafting, Validating, Testing, Reviewing).",
+  "  --ac <n>                0-based acceptance-criterion index for `progress`.",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 9 already-claimed \xB7 10 not-found \xB7 11 bad-arg \xB7",
+  "            12 console-unreachable \xB7 13 server-error \xB7 14 neon-required"
+].join("\n");
+
+// spex-console/src/lib/cli/defer.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// scripts/lib/console-url-resolver.mjs
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+var DEFAULT_CONSOLE_URL = "https://app.heyspex.com";
+
+// spex-console/src/lib/cli/defer.ts
+function resolveSpexConsoleUrl(vaultRoot, readDiscovery2, opts = {}) {
+  const env = opts.env ?? process.env;
+  const raw = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
+  if (raw && raw.length > 0) return raw.replace(/\/+$/, "");
+  try {
+    const homeDir = opts.homeDir ?? os.homedir();
+    const readFile = opts.readFile ?? ((p) => readFileSync3(p, "utf-8"));
+    const credentials = readFile(path.join(homeDir, ".heyspex", "credentials.yaml"));
+    const match = credentials.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    if (value && value.length > 0) return value.replace(/\/+$/, "");
+  } catch {
+  }
+  for (const name of ["console-url", "cockpit-url"]) {
+    try {
+      const discovery = readDiscovery2(`${vaultRoot}/.heyspex/${name}`);
+      if (discovery && discovery.trim().length > 0) {
+        return discovery.trim().replace(/\/+$/, "");
+      }
+    } catch {
+    }
+  }
+  return DEFAULT_CONSOLE_URL;
+}
+var HELP2 = [
+  "Usage:",
+  "  hs defer <spec-id> [--until <when>] [--json] [--no-daemon]",
+  "  hs undefer <spec-id> [--json] [--no-daemon]",
+  "",
+  "Time-shift a spec via its `defer_until` frontmatter field. A deferred spec is",
+  "scheduler-invisible until the date passes, then auto-revives.",
+  "",
+  "Arguments:",
+  "  <spec-id>        The spec to defer/undefer (e.g. HS-TASK-EWL5).",
+  "",
+  "Flags:",
+  "  --until <when>   ISO date, or relative offset +Nd / +Nw / +Nm / +Ny.",
+  "                   Defaults to +1y (matches the console Defer button).",
+  "                   Ignored by `undefer` (which always clears the field).",
+  "  --json           Emit a machine-readable JSON result.",
+  "  --no-daemon      Write straight to the vault (no console needed; CI path).",
+  "  --help, -h       Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 10 not-found \xB7 11 bad-arg \xB7 12 console-unreachable \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/bin/hs-claim.ts
+function readDiscovery(p) {
+  try {
+    return readFileSync4(p, "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function main() {
+  const vaultRoot = process2.env.HS_VAULT_ROOT;
+  if (!vaultRoot) {
+    process2.stderr.write(
+      "hs claim: HS_VAULT_ROOT is not set (the dispatcher must resolve and pass it).\n"
+    );
+    process2.exit(EXIT.USAGE);
+  }
+  const parsed = parseClaimArgs(process2.argv.slice(3));
+  if (parsed.help) {
+    process2.stdout.write(`${HELP}
+`);
+    process2.exit(EXIT.OK);
+  }
+  if (parsed.error) {
+    process2.stderr.write(`hs claim: ${parsed.error.message}
+`);
+    process2.exit(parsed.error.code);
+  }
+  const consoleUrl = resolveSpexConsoleUrl(vaultRoot, readDiscovery);
+  const result = await runClaim(parsed.args, { fetchImpl: fetch, consoleUrl });
+  const sink = result.isError ? process2.stderr : process2.stdout;
+  sink.write(`${parsed.args.json ? JSON.stringify(result.payload) : result.message}
+`);
+  process2.exit(result.code);
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process2.stderr.write(`hs claim: unhandled: ${message}
+`);
+  process2.exit(EXIT.WRITE_FAILED);
+});