heyspex 0.1.0

package/scripts/gateway-skills-lib.mjs

@@ -0,0 +1,421 @@
+// gateway-skills-lib.mjs — shared core for user-authored gateway skills
+// (HS-WEC3, design: specs/research/HS-P861-G9JR-RES-user-customizable-mcp-servers-and.md).
+//
+// One core module, three faces (capability-three-faces rule):
+//   - `hs gateway validate`            (scripts/hs-gateway.mjs)
+//   - heyspex_validate_user_skills     (vendor/heyspex-mcp/cli.mjs)
+//   - hs doctor --check-gateway        (scripts/heyspex-doctor.mjs)
+//
+// Invocation-guardrail invariants this module owns:
+//   - Scope resolution is a deterministic exact-tag set operation. Never a
+//     semantic / similarity / top-K match: a wrong "no match" is safe (tool
+//     stays hidden, user can override); a wrong "close enough" silently
+//     exposes something out of scope.
+//   - Malformed scope declarations FAIL CLOSED: a skill whose tool_scope /
+//     requires_servers cannot be parsed is invalid and inert — it never falls
+//     back to "all tools". A skill with NO tool_scope key at all falls back to
+//     the documented HS-A4BY default (no declared scope = all tools available)
+//     and is flagged as such, not invented differently here.
+//   - This module never rewrites user content. Validation is read-only;
+//     callers (doctor included) report and suggest, they do not "fix" a
+//     user's declarations by guessing intent.
+//
+// Zero runtime dependencies on purpose: the doctor is the fallback tool that
+// must run on a fresh clone before `npm install` has succeeded, so this file
+// parses the small documented frontmatter subset itself instead of borrowing
+// js-yaml from the spex-console workspace.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Path of the user-skill root, relative to the vault root. */
+export const USER_SKILLS_REL = path.join('.heyspex', 'skills', 'user');
+
+/** Frontmatter fields the Skill File Format defines (research doc §Skill File Format). */
+export const SKILL_KNOWN_FIELDS = new Set([
+  'name',
+  'description',
+  'tool_scope',
+  'origin',
+  'version',
+  'requires_servers',
+]);
+
+export const SKILL_REQUIRED_FIELDS = ['name', 'description'];
+export const SKILL_ORIGINS = new Set(['user', 'heyspex']);
+
+// ---------------------------------------------------------------------------
+// Strict frontmatter parsing (documented subset only)
+// ---------------------------------------------------------------------------
+
+/** Split a SKILL.md into its frontmatter block and body. Returns null when no block. */
+export function extractFrontmatterBlock(raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+  if (!match) return null;
+  return { yamlBlock: match[1], body: raw.slice(match[0].length) };
+}
+
+function stripInlineComment(value) {
+  // Only for unquoted values: everything from the first ` #` is a comment.
+  const idx = value.search(/\s#/);
+  return idx === -1 ? value : value.slice(0, idx);
+}
+
+function parseScalar(rawValue, errors, lineNo) {
+  let v = rawValue.trim();
+  if (v.startsWith('"') || v.startsWith("'")) {
+    const quote = v[0];
+    const end = v.indexOf(quote, 1);
+    if (end === -1) {
+      errors.push({ code: 'yaml_unterminated_quote', message: `line ${lineNo}: unterminated ${quote}quoted${quote} string` });
+      return null;
+    }
+    return v.slice(1, end);
+  }
+  v = stripInlineComment(v).trim();
+  if (v === '') return '';
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (/^-?\d+$/.test(v)) return Number.parseInt(v, 10);
+  if (/^-?\d+\.\d+$/.test(v)) return Number.parseFloat(v);
+  return v;
+}
+
+function parseInlineArray(inner, errors, lineNo) {
+  const trimmed = inner.trim();
+  if (trimmed === '') return [];
+  return trimmed.split(',').map((part) => parseScalar(part, errors, lineNo));
+}
+
+/**
+ * Parse the strict frontmatter subset the Skill File Format documents:
+ * top-level `key: scalar`, `key: [a, b]`, `key:` + `- item` lists, and
+ * `|` / `>` block scalars. Anything else is an error — deliberately, so a
+ * malformed declaration surfaces instead of silently parsing to something
+ * broader than the user wrote (fail closed).
+ */
+export function parseSkillFrontmatter(yamlBlock) {
+  const data = {};
+  const errors = [];
+  const lines = yamlBlock.split(/\r?\n/);
+  let pendingListKey = null;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    const listItem = /^\s+-\s*(.*)$/.exec(line) ?? /^-\s+(.*)$/.exec(line);
+    if (listItem) {
+      if (!pendingListKey) {
+        errors.push({ code: 'yaml_stray_list_item', message: `line ${lineNo}: list item without a preceding key` });
+        continue;
+      }
+      if (data[pendingListKey] === null) data[pendingListKey] = [];
+      data[pendingListKey].push(parseScalar(listItem[1], errors, lineNo));
+      continue;
+    }
+
+    if (/^\s/.test(line)) {
+      errors.push({ code: 'yaml_nested_unsupported', message: `line ${lineNo}: nested mappings are not part of the skill frontmatter format` });
+      pendingListKey = null;
+      continue;
+    }
+
+    const kv = /^([A-Za-z0-9_][A-Za-z0-9_-]*):(.*)$/.exec(line);
+    if (!kv) {
+      errors.push({ code: 'yaml_unparseable_line', message: `line ${lineNo}: cannot parse "${line.trim()}"` });
+      pendingListKey = null;
+      continue;
+    }
+
+    const key = kv[1];
+    if (Object.prototype.hasOwnProperty.call(data, key)) {
+      errors.push({ code: 'yaml_duplicate_key', message: `line ${lineNo}: duplicate key "${key}"` });
+    }
+    const rest = kv[2].trim();
+    pendingListKey = null;
+
+    if (rest === '' ) {
+      data[key] = null; // either an empty value or a dash-list follows
+      pendingListKey = key;
+      continue;
+    }
+    if (rest === '|' || rest === '>') {
+      const collected = [];
+      while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || lines[i + 1].trim() === '')) {
+        collected.push(lines[i + 1].trim());
+        i += 1;
+      }
+      while (collected.length && collected[collected.length - 1] === '') collected.pop();
+      data[key] = collected.join(rest === '|' ? '\n' : ' ');
+      continue;
+    }
+    const inline = /^\[(.*)\]$/.exec(stripInlineComment(rest).trim());
+    if (inline) {
+      data[key] = parseInlineArray(inline[1], errors, lineNo);
+      continue;
+    }
+    data[key] = parseScalar(rest, errors, lineNo);
+  }
+
+  return { data, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Validation (read-only; never mutates user content)
+// ---------------------------------------------------------------------------
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.trim().length > 0;
+}
+
+function validateTagArray(value, field, errors, warnings) {
+  if (!Array.isArray(value)) {
+    errors.push({
+      code: `skill_${field}_malformed`,
+      field,
+      message: `${field} must be a list of tag strings (e.g. ${field}: ["internal-crm"]) — the skill stays inert until this parses`,
+    });
+    return [];
+  }
+  const tags = [];
+  for (const entry of value) {
+    if (!isNonEmptyString(entry)) {
+      errors.push({
+        code: `skill_${field}_malformed`,
+        field,
+        message: `${field} contains a non-string or empty entry — the skill stays inert until this parses`,
+      });
+      return [];
+    }
+    const tag = entry.trim();
+    if (tag !== entry || /[A-Z\s]/.test(tag)) {
+      warnings.push({
+        code: `skill_${field}_tag_style`,
+        field,
+        message: `${field} tag "${entry}" has whitespace or uppercase — scope matching is exact, so this only matches a server registered with the identical tag`,
+      });
+    }
+    if (tags.includes(tag)) {
+      warnings.push({ code: `skill_${field}_duplicate_tag`, field, message: `${field} lists "${tag}" more than once` });
+      continue;
+    }
+    tags.push(tag);
+  }
+  return tags;
+}
+
+/**
+ * Validate one skill document. Pure: takes raw file text, returns a report.
+ * errors  → the skill is invalid and must be treated as inert (fail closed).
+ * warnings → advisory only; the skill still works.
+ */
+export function validateSkillDocument(raw, { slug = null, relPath = null } = {}) {
+  const errors = [];
+  const warnings = [];
+  let frontmatter = {};
+  let scope = { declared: false, tool_scope: [], requires_servers: [] };
+
+  const block = extractFrontmatterBlock(raw);
+  if (!block) {
+    errors.push({ code: 'skill_missing_frontmatter', message: 'no frontmatter block (--- ... ---) at the top of the file' });
+  } else {
+    const parsed = parseSkillFrontmatter(block.yamlBlock);
+    frontmatter = parsed.data;
+    errors.push(...parsed.errors);
+
+    for (const field of SKILL_REQUIRED_FIELDS) {
+      if (!isNonEmptyString(frontmatter[field])) {
+        errors.push({ code: `skill_${field}_missing`, field, message: `required field "${field}" is missing or empty` });
+      }
+    }
+
+    if (slug && isNonEmptyString(frontmatter.name) && frontmatter.name.trim() !== slug) {
+      warnings.push({
+        code: 'skill_name_slug_mismatch',
+        field: 'name',
+        message: `name "${frontmatter.name.trim()}" does not match the directory slug "${slug}"`,
+      });
+    }
+
+    if (Object.prototype.hasOwnProperty.call(frontmatter, 'tool_scope')) {
+      if (frontmatter.tool_scope === null) {
+        errors.push({ code: 'skill_tool_scope_malformed', field: 'tool_scope', message: 'tool_scope has no value — the skill stays inert until this parses' });
+      } else {
+        scope = { ...scope, declared: true, tool_scope: validateTagArray(frontmatter.tool_scope, 'tool_scope', errors, warnings) };
+      }
+    } else {
+      // Documented HS-A4BY default: no declared scope means all tools
+      // available. Flagged so callers can surface it — but NOT an error, and
+      // NOT a different default invented for user content.
+      warnings.push({
+        code: 'skill_no_scope_declared',
+        field: 'tool_scope',
+        message: 'no tool_scope declared — per the spec-scoped-tool-access default this skill does not narrow the tool surface',
+      });
+    }
+
+    if (Object.prototype.hasOwnProperty.call(frontmatter, 'requires_servers') && frontmatter.requires_servers !== null) {
+      scope = { ...scope, requires_servers: validateTagArray(frontmatter.requires_servers, 'requires_servers', errors, warnings) };
+    }
+
+    if (Object.prototype.hasOwnProperty.call(frontmatter, 'origin')) {
+      if (!SKILL_ORIGINS.has(frontmatter.origin)) {
+        errors.push({ code: 'skill_origin_invalid', field: 'origin', message: `origin must be "user" or "heyspex", got "${frontmatter.origin}"` });
+      } else if (frontmatter.origin === 'heyspex') {
+        warnings.push({ code: 'skill_origin_heyspex_in_user_dir', field: 'origin', message: 'origin is "heyspex" but the file lives under skills/user/ — if you authored this skill, set origin: user' });
+      }
+    } else {
+      warnings.push({ code: 'skill_origin_missing', field: 'origin', message: 'add origin: user so the doctor can tell user skills from shipped ones' });
+    }
+
+    if (Object.prototype.hasOwnProperty.call(frontmatter, 'version')) {
+      if (!Number.isInteger(frontmatter.version) || frontmatter.version < 1) {
+        warnings.push({ code: 'skill_version_malformed', field: 'version', message: 'version should be a positive integer (bump it on intentional edits)' });
+      }
+    } else {
+      warnings.push({ code: 'skill_version_missing', field: 'version', message: 'add version: 1 — it lets the doctor tell intentional edits from drift' });
+    }
+
+    for (const key of Object.keys(frontmatter)) {
+      if (!SKILL_KNOWN_FIELDS.has(key)) {
+        warnings.push({ code: 'skill_unknown_field', field: key, message: `unknown frontmatter field "${key}" (known: ${[...SKILL_KNOWN_FIELDS].join(', ')})` });
+      }
+    }
+
+    if (!block.body.trim()) {
+      warnings.push({ code: 'skill_body_empty', message: 'skill body is empty — the intent classifier has nothing to match against' });
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    slug,
+    relPath,
+    frontmatter,
+    scope,
+    errors,
+    warnings,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Discovery + aggregate validation
+// ---------------------------------------------------------------------------
+
+/** Files allowed at the top of skills/user/ without being flagged as misplaced. */
+const TOP_LEVEL_ALLOWED = new Set(['README.md', '.gitkeep']);
+
+export function discoverUserSkills(vaultRoot) {
+  const root = path.join(vaultRoot, USER_SKILLS_REL);
+  if (!fs.existsSync(root)) return { root, exists: false, entries: [], misplaced: [] };
+
+  const entries = [];
+  const misplaced = [];
+  for (const dirent of fs.readdirSync(root, { withFileTypes: true })) {
+    if (dirent.isDirectory()) {
+      const skillPath = path.join(root, dirent.name, 'SKILL.md');
+      if (fs.existsSync(skillPath)) {
+        entries.push({ slug: dirent.name, absPath: skillPath, relPath: path.join(USER_SKILLS_REL, dirent.name, 'SKILL.md') });
+      } else {
+        misplaced.push({ name: dirent.name, reason: `directory has no SKILL.md — expected ${path.join(USER_SKILLS_REL, dirent.name, 'SKILL.md')}` });
+      }
+    } else if (!TOP_LEVEL_ALLOWED.has(dirent.name)) {
+      misplaced.push({ name: dirent.name, reason: `loose file — skills live at ${path.join(USER_SKILLS_REL, '<slug>', 'SKILL.md')}` });
+    }
+  }
+  return { root, exists: true, entries, misplaced };
+}
+
+/** Validate every user skill under `<vaultRoot>/.heyspex/skills/user/`. Read-only. */
+export function validateUserSkills(vaultRoot) {
+  const discovery = discoverUserSkills(vaultRoot);
+  const skills = discovery.entries.map((entry) => {
+    let raw;
+    try {
+      raw = fs.readFileSync(entry.absPath, 'utf8');
+    } catch (err) {
+      return {
+        ok: false,
+        slug: entry.slug,
+        relPath: entry.relPath,
+        frontmatter: {},
+        scope: { declared: false, tool_scope: [], requires_servers: [] },
+        errors: [{ code: 'skill_unreadable', message: `cannot read file: ${err.message}` }],
+        warnings: [],
+      };
+    }
+    return validateSkillDocument(raw, { slug: entry.slug, relPath: entry.relPath });
+  });
+
+  return {
+    root: discovery.root,
+    exists: discovery.exists,
+    misplaced: discovery.misplaced,
+    skills,
+    counts: {
+      total: skills.length,
+      valid: skills.filter((s) => s.ok).length,
+      invalid: skills.filter((s) => !s.ok).length,
+      with_warnings: skills.filter((s) => s.warnings.length > 0).length,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Server registry (HS-DCCP) + orphan resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * The gateway server registry is HS-DCCP-EPIC's to build (a Neon table per
+ * vault: { server_id, url, auth_type, encrypted_credentials, scope_tags },
+ * plus the `origin` column this epic adds). Until that lands there is nothing
+ * to read, so this returns available: false and callers must say so plainly
+ * rather than pretending an empty registry was probed.
+ */
+export function getServerRegistry() {
+  return {
+    available: false,
+    reason: 'server registry not yet built (HS-DCCP-EPIC-thin-project-scoped-mcp-connector is open) — server registration and the live connectivity probe land with it',
+    servers: [],
+    scopeTags: [],
+  };
+}
+
+/**
+ * Which valid skills declare a scope no registered server provides?
+ * Deterministic exact-tag set difference — by design never a similarity
+ * match. Orphaned skills are inert until fixed (fail closed), so this is a
+ * warning-grade signal: report + suggest, never rewrite the declaration.
+ */
+export function computeOrphanReport(aggregate, registry = getServerRegistry()) {
+  const provided = new Set([
+    ...registry.scopeTags,
+    ...registry.servers.map((s) => s.server_id).filter(Boolean),
+  ]);
+
+  const orphans = [];
+  for (const skill of aggregate.skills) {
+    if (!skill.ok) continue; // invalid skills are already inert via gateway-skills
+    const declared = [...new Set([...skill.scope.tool_scope, ...skill.scope.requires_servers])];
+    if (declared.length === 0) continue;
+    if (!registry.available) {
+      orphans.push({ slug: skill.slug, relPath: skill.relPath, declared, missing: declared, reason: 'registry_unavailable' });
+      continue;
+    }
+    const missing = declared.filter((tag) => !provided.has(tag));
+    if (missing.length > 0) {
+      orphans.push({ slug: skill.slug, relPath: skill.relPath, declared, missing, reason: 'unmatched_tags' });
+    }
+  }
+  return { registry_available: registry.available, registry_reason: registry.available ? null : registry.reason, orphans };
+}
+
+/** One-call report used by all three faces. */
+export function buildGatewayReport(vaultRoot) {
+  const skills = validateUserSkills(vaultRoot);
+  const registry = getServerRegistry(vaultRoot);
+  const orphanReport = computeOrphanReport(skills, registry);
+  return { skills, registry: { available: registry.available, reason: registry.available ? null : registry.reason }, orphans: orphanReport };
+}

package/scripts/lib/console-url-resolver.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * console-url-resolver.mjs — the ONE shared console-URL resolver
+ * ([[HS-GD45-MCPC-TASK-mcp-cloud-auth-shared-console-resolver]] of
+ * [[HS-UP6L-DZFX-RES-cloud-first-dogfooding-migration-what-s]]).
+ *
+ * Before this file, the SAME localhost-fallback chain was hand-duplicated in
+ * five places (`vendor/heyspex-mcp/cli.mjs`, `scripts/claude-hooks/
+ * claim-liveness-shared.mjs`, `scripts/claude-hooks/session-end.mjs`,
+ * `dev-factory/lib/breakdown-to-filing.mjs`, `dev-factory/lib/
+ * fleet-queue-neon.mjs`) — a config change (e.g. "point at the cloud
+ * console") had to be applied five times, and [[HS-G59F-DIAG-OQ34-console-url-silently-defaults-to]]
+ * documented the drift that causes. This module is the ONE implementation;
+ * all five now import/delegate to it.
+ *
+ * Precedence (cloud-first — an explicit override always wins over ambient
+ * discovery, and a paired cloud console outranks a stale local dev-server
+ * discovery file):
+ *   1. `HEYSPEX_CONSOLE_URL` env (legacy-cockpit: `HEYSPEX_COCKPIT_URL`)
+ *   2. `console_url:` in `~/.heyspex/credentials.yaml` — written by
+ *      `hs mcp pair <code>` when a machine pairs with a deployed console,
+ *      and by `hs dev local` (owner-only) when the owner's OWN machine
+ *      overrides to `http://localhost:3000` — that write is rung 2, so it
+ *      wins over the rung-4 default below without needing rung 1
+ *   3. `.heyspex/console-url` discovery file in the repo (legacy-cockpit `cockpit-url`)
+ *      — written by the local dev-server launcher
+ *      (`spex-console/scripts/ensure-next-dev.mjs`), ephemeral per session
+ *   4. `https://app.heyspex.com` (the cloud console — [[HS-3UZS-EKLJ-DIAG-a-brand-new-team-member-s-one-command]]
+ *      Gap 1: a fresh clone with none of the above set has no way to
+ *      discover the production console, and used to silently guess
+ *      localhost instead, which for anyone but the owner is unreachable and
+ *      degrades every registration to registry.json-only. The owner's own
+ *      daily local tooling is unaffected — rung 2 above always wins for them.)
+ *
+ * Plain Node ESM, zero deps beyond `node:fs`/`node:os`/`node:path` — every
+ * consumer (vendor MCP server, Claude-hook scripts, dev-factory dispatchers)
+ * can import this directly with no build step and no risk of pulling in a
+ * dependency that isn't installed in their execution context.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * The rung-4 fallback when nothing else resolves — the cloud console, so a
+ * fresh clone reaches production instead of guessing localhost. Literal
+ * mirror of `CLOUD_CONSOLE_URL` (`spex-console/src/lib/dev-mode.ts`): this
+ * file stays dependency-free plain Node (see module doc), so it cannot
+ * import that TS module — keep the two literals in sync by hand.
+ */
+export const DEFAULT_CONSOLE_URL = 'https://app.heyspex.com';
+
+function trimTrailingSlash(url) {
+  return url.replace(/\/+$/, '');
+}
+
+/**
+ * Read `console_url:` out of `~/.heyspex/credentials.yaml` with a targeted
+ * regex rather than a full YAML parse — mirrors the same
+ * no-hard-yaml-dependency extraction `dev-factory/fleet/manager.mjs`
+ * already uses for `companion_token`, so every one of this resolver's five
+ * consumers (some of which run standalone, outside the npm workspace's
+ * hoisted `node_modules`) can call it with zero new dependencies.
+ */
+export function readCredentialsConsoleUrl({ homeDir = homedir() } = {}) {
+  try {
+    const raw = readFileSync(join(homeDir, '.heyspex', 'credentials.yaml'), 'utf8');
+    const match = raw.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    return value && value.length > 0 ? trimTrailingSlash(value) : null;
+  } catch {
+    // Missing file, missing key, or unreadable — no credentials-file override.
+    return null;
+  }
+}
+
+/** Read the repo's `.heyspex/console-url` (or legacy-cockpit `cockpit-url`) discovery file. */
+export function readDiscoveryFileConsoleUrl(repoRoot) {
+  if (!repoRoot) return null;
+  for (const name of ['console-url', 'cockpit-url' /* legacy-cockpit */]) {
+    // legacy-cockpit: pre-rename launchers only wrote cockpit-url — keep resolving it.
+    try {
+      const discovery = readFileSync(join(repoRoot, '.heyspex', name), 'utf8').trim();
+      if (discovery.length > 0) return trimTrailingSlash(discovery);
+    } catch {
+      // Missing or unreadable — try the next candidate.
+    }
+  }
+  return null;
+}
+
+/**
+ * Thrown by {@link resolveConsoleUrl} in `strict` mode when nothing in the
+ * precedence chain (env → credentials file → discovery file) resolves —
+ * i.e. the caller is about to guess `DEFAULT_CONSOLE_URL` instead of knowing
+ * the real console URL ([[HS-OQ34-G59F-DIAG-console-url-silently-defaults-to]]:
+ * "not knowing the port produces a guess, not an error").
+ */
+export class ConsoleUrlUnresolvedError extends Error {
+  constructor() {
+    super(
+      'resolveConsoleUrl: no HEYSPEX_CONSOLE_URL/HEYSPEX_COCKPIT_URL env, no console_url: in ' + // legacy-cockpit env name
+        '~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file — refusing to ' +
+        `silently fall back to the ${DEFAULT_CONSOLE_URL} default in strict mode.`,
+    );
+    this.name = 'ConsoleUrlUnresolvedError';
+  }
+}
+
+/**
+ * Resolve the console base URL (no trailing slash) per the precedence above.
+ * Every input is injectable so callers/tests can run hermetically:
+ *   - `repoRoot` — needed only for step 3 (discovery file); omit if the
+ *     caller has no vault root to check (env/credentials-only resolution).
+ *   - `env` — defaults to `process.env`.
+ *   - `homeDir` — defaults to `os.homedir()`.
+ *   - `strict` — when `true`, throw {@link ConsoleUrlUnresolvedError} instead
+ *     of returning `DEFAULT_CONSOLE_URL` when nothing resolves. Opt-in only —
+ *     default `false` preserves every existing caller's fail-open behavior.
+ *
+ * Non-strict (default): never throws — every read is wrapped and falls
+ * through to the next step, so a caller in a fail-open context (a
+ * Claude-hook script) stays fail-open by construction. Strict callers should
+ * catch {@link ConsoleUrlUnresolvedError} and surface/log the failure loudly
+ * instead of posting to a guessed URL.
+ *
+ * @param {object} [options]
+ * @param {string} [options.repoRoot] - needed only for step 3 (discovery file); omit if the
+ *   caller has no vault root to check (env/credentials-only resolution).
+ * @param {NodeJS.ProcessEnv} [options.env] - defaults to `process.env`.
+ * @param {string} [options.homeDir] - defaults to `os.homedir()`.
+ * @param {boolean} [options.strict] - throw {@link ConsoleUrlUnresolvedError} instead of
+ *   returning `DEFAULT_CONSOLE_URL` when nothing resolves. Default `false`.
+ */
+export function resolveConsoleUrl({
+  repoRoot,
+  env = process.env,
+  homeDir = homedir(),
+  strict = false,
+} = {}) {
+  const envUrl = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim(); // legacy-cockpit env
+  if (envUrl) return trimTrailingSlash(envUrl);
+
+  const credentialsUrl = readCredentialsConsoleUrl({ homeDir });
+  if (credentialsUrl) return credentialsUrl;
+
+  const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot);
+  if (discoveryUrl) return discoveryUrl;
+
+  if (strict) throw new ConsoleUrlUnresolvedError();
+  return DEFAULT_CONSOLE_URL;
+}