heyspex 0.2.6 → 0.2.7

package/vendor/heyspex-mcp/config-seed.yaml

@@ -1,15 +1,15 @@
-# .heyspex/config.yaml — HeySpex workflow settings for this vault.
-# Seeded by `hs init` (ADR-0009 §1: the file lives at the VAULT root and is git-tracked).
-# Field reference: specs/protocols/agent-settings-protocol.md. Change values with
-# `hs settings set <key> <value>` or heyspex_settings_set — never by hand.
-
-mvp_mode:
-  enabled: true
-  review_grain: epic
-  review_backlog_never_blocks: true
-
-pricing_tier:
-  tier: free
-
-agent_behaviors:
-  ask_forgiveness_not_permission: true
+# .heyspex/config.yaml — HeySpex workflow settings for this vault.
+# Seeded by `hs init` (ADR-0009 §1: the file lives at the VAULT root and is git-tracked).
+# Field reference: specs/protocols/agent-settings-protocol.md. Change values with
+# `hs settings set <key> <value>` or heyspex_settings_set — never by hand.
+
+mvp_mode:
+  enabled: true
+  review_grain: epic
+  review_backlog_never_blocks: true
+
+pricing_tier:
+  tier: free
+
+agent_behaviors:
+  ask_forgiveness_not_permission: true

package/vendor/heyspex-mcp/dev-factory-overlay.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// dev-factory-overlay.mjs — the ONE gate that decides whether the owner's personal
+// dev-factory overlay may load ([[HS-R475-C86Z-TASK-load-the-owner-dev-factory-overlay-only]],
+// epic [[HS-9JMD-C86Z-EPIC-owner-dev-factory-isolation]], research
+// [[HS-RXJO-C86Z-RES-spexfleet-per-user-seat-assignment-with]] §Owner dev-factory isolation).
+//
+// The overlay is the owner's own fleet configuration under `<repo>/dev-factory/`:
+// routing-table.json (which model fills which purpose), seats.json (the seat roster and
+// each seat's fill), budget-config.json (per-company spend caps). It must never be read,
+// inherited or overwritten by another HeySpex developer. It loads only when ALL hold:
+//
+//   1. switch      — `HEYSPEX_DEV_FACTORY` is not "0" (the owner's off switch);
+//   2. checkout    — the root is a heyspex-app SOURCE checkout: package.json name "heyspex",
+//                    a `.git` entry (dir, or file for a worktree), a `dev-factory/` dir, and
+//                    not under `node_modules/` (an installed package is never a checkout);
+//   3. account     — when the overlay declares its owners (`dev-factory/overlay-owner.json`
+//                    `{ "account_ids": [...] }`), the signed-in account (HS_ACCOUNT_ID, else
+//                    the credentials store's current account) is one of them. Signed out is
+//                    allowed (not another user; the owner's offline fleet machines keep
+//                    running). No declaration = no account check (back-compat).
+//
+// An explicit `HS_DEV_FACTORY_ROOT` naming this root's dev-factory dir is the caller's own
+// opt-in (test fixtures, the owner's coordinator) and skips check 2 — it never skips 1 or 3.
+// The console's builder gate (`guardOwnerFactoryRead`) is the account check for HTTP callers.
+//
+// Plain Node ESM, builtins + ./credentials.mjs only, never throws. Packaged (vendor glob) so
+// every packaged reader can call it; a packaged install always resolves "closed" at check 2.
+//
+//   node vendor/heyspex-mcp/dev-factory-overlay.mjs                # prints the verdict JSON
+//   node vendor/heyspex-mcp/dev-factory-overlay.mjs --assert-open  # exit 1 unless open, and
+//                                                                   # proves the files still load
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { readCurrentAccountId } from './credentials.mjs';
+
+export const DEV_FACTORY_SWITCH_ENV = 'HEYSPEX_DEV_FACTORY';
+export const OVERLAY_OWNER_FILE = 'overlay-owner.json';
+/** The overlay files this gate guards, relative to `<root>/dev-factory/`. */
+export const OVERLAY_FILES = Object.freeze(['routing-table.json', 'seats.json', 'budget-config.json']);
+
+const norm = (p) => path.resolve(String(p)).replaceAll('\\', '/').replace(/\/+$/, '').toLowerCase();
+
+function readJsonOrNull(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** True when `root` is a heyspex-app source checkout (see header check 2). Never throws. */
+export function isHeyspexSourceCheckout(root) {
+  try {
+    if (!root) return false;
+    const abs = path.resolve(String(root));
+    if (/[\\/]node_modules([\\/]|$)/i.test(abs)) return false;
+    if (!existsSync(path.join(abs, '.git'))) return false;
+    if (!existsSync(path.join(abs, 'dev-factory'))) return false;
+    const pkg = readJsonOrNull(path.join(abs, 'package.json'));
+    return pkg?.name === 'heyspex';
+  } catch {
+    return false;
+  }
+}
+
+/** The account ids `dev-factory/overlay-owner.json` declares as the overlay's owners ([] = undeclared). */
+export function declaredOverlayOwners(root) {
+  const doc = root ? readJsonOrNull(path.join(String(root), 'dev-factory', OVERLAY_OWNER_FILE)) : null;
+  const ids = Array.isArray(doc?.account_ids) ? doc.account_ids : [];
+  return ids.filter((id) => typeof id === 'string' && id.trim()).map((id) => id.trim());
+}
+
+/**
+ * The full verdict. `root` is the REPO root (the directory that holds `dev-factory/`).
+ * @param {{ root: string, env?: Record<string, string|undefined>, accountId?: string|null }} opts
+ *   `accountId` — injected signed-in account (tests); read from env/credentials otherwise.
+ * @returns {{ open: boolean, reason: string, root: string|null, accountId: string|null, owners: string[] }}
+ */
+export function devFactoryOverlayVerdict({ root, env = process.env, accountId } = {}) {
+  const out = (open, reason, extra = {}) => ({ open, reason, root: root ? path.resolve(String(root)) : null, accountId: null, owners: [], ...extra });
+  try {
+    if (!root) return out(false, 'no-root');
+    if (String(env?.[DEV_FACTORY_SWITCH_ENV] ?? '').trim() === '0') return out(false, 'disabled');
+
+    const override = env?.HS_DEV_FACTORY_ROOT;
+    const optedIn = Boolean(override) && norm(override) === norm(path.join(String(root), 'dev-factory'));
+    if (!optedIn && !isHeyspexSourceCheckout(root)) return out(false, 'not-source-checkout');
+
+    const owners = declaredOverlayOwners(root);
+    const who =
+      accountId !== undefined
+        ? accountId
+        : (env?.HS_ACCOUNT_ID && String(env.HS_ACCOUNT_ID).trim()) || safeCurrentAccountId();
+    if (owners.length > 0 && who && !owners.includes(who)) {
+      return out(false, 'not-owner-account', { accountId: who, owners });
+    }
+    const reason = optedIn ? 'override' : owners.length === 0 ? 'owner-undeclared' : who ? 'owner' : 'signed-out';
+    return out(true, reason, { accountId: who ?? null, owners });
+  } catch {
+    return out(false, 'error');
+  }
+}
+
+function safeCurrentAccountId() {
+  try {
+    return readCurrentAccountId() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Boolean form of {@link devFactoryOverlayVerdict}. */
+export function isDevFactoryOverlayOpen(root, opts = {}) {
+  return devFactoryOverlayVerdict({ ...opts, root }).open;
+}
+
+/**
+ * Same verdict, keyed by the dev-factory DIRECTORY (what the console's
+ * `resolveDevFactoryRoot()` returns) instead of the repo root.
+ */
+export function isDevFactoryDirOverlayOpen(devFactoryDir, opts = {}) {
+  if (!devFactoryDir) return false;
+  return isDevFactoryOverlayOpen(path.dirname(path.resolve(String(devFactoryDir))), opts);
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+const self = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === self) {
+  const root = path.resolve(path.dirname(self), '..', '..');
+  const verdict = devFactoryOverlayVerdict({ root });
+  const loads = Object.fromEntries(
+    OVERLAY_FILES.map((f) => [f, readJsonOrNull(path.join(root, 'dev-factory', f)) !== null]),
+  );
+  console.log(JSON.stringify({ ...verdict, loads }, null, 2));
+  if (process.argv.includes('--assert-open')) {
+    const ok = verdict.open && loads['routing-table.json'] && loads['seats.json'];
+    process.exit(ok ? 0 : 1);
+  }
+}