@hegemonart/get-design-done 1.23.0 → 1.24.0

package/scripts/lib/hedge-ensemble.cjs

@@ -0,0 +1,217 @@
+/**
+ * hedge-ensemble.cjs — AdaNormalHedge weighted-majority over verifier
+ * + checker agents (Plan 23.5-02).
+ *
+ * Parameter-free: no manual learning rate. Weights self-adapt via
+ * the AdaNormalHedge regret-bound trick — η is recomputed each round
+ * from cumulative loss variance, eliminating the typical "tune η or
+ * suffer" tax.
+ *
+ * Weights persist at `.design/telemetry/hedge-weights.json` (atomic
+ * .tmp + rename). Schema:
+ *   { schema_version: '1.0.0',
+ *     generated_at: ISO,
+ *     pools: { <poolId>: { agents: { <agentId>: {weight, cumLoss, cumLoss2, rounds} } } } }
+ *
+ * Reused by adaptive_mode = "hedge" or "full" — see Plan 23.5-04.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_WEIGHTS_PATH = '.design/telemetry/hedge-weights.json';
+const SCHEMA_VERSION = '1.0.0';
+const DEFAULT_VOTE_THRESHOLD = 0.5;
+
+function resolvePath(opts = {}) {
+  if (opts.weightsPath) {
+    return path.isAbsolute(opts.weightsPath)
+      ? opts.weightsPath
+      : path.resolve(opts.baseDir ?? process.cwd(), opts.weightsPath);
+  }
+  return path.resolve(opts.baseDir ?? process.cwd(), DEFAULT_WEIGHTS_PATH);
+}
+
+/**
+ * @returns {{schema_version: string, generated_at: string, pools: object}}
+ */
+function loadWeights(opts = {}) {
+  const p = resolvePath(opts);
+  if (!fs.existsSync(p)) {
+    return { schema_version: SCHEMA_VERSION, generated_at: new Date().toISOString(), pools: {} };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!data.pools || typeof data.pools !== 'object') data.pools = {};
+    return data;
+  } catch {
+    return { schema_version: SCHEMA_VERSION, generated_at: new Date().toISOString(), pools: {} };
+  }
+}
+
+function saveWeights(state, opts = {}) {
+  const p = resolvePath(opts);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  state.generated_at = new Date().toISOString();
+  const tmp = p + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  fs.renameSync(tmp, p);
+  return p;
+}
+
+function ensurePool(state, poolId) {
+  if (!state.pools[poolId]) state.pools[poolId] = { agents: {} };
+  return state.pools[poolId];
+}
+
+function ensureAgent(pool, agentId) {
+  if (!pool.agents[agentId]) {
+    pool.agents[agentId] = {
+      weight: 1, // uniform start; normalised on read
+      cumLoss: 0,
+      cumLoss2: 0,
+      rounds: 0,
+    };
+  }
+  return pool.agents[agentId];
+}
+
+/**
+ * Apply one round of losses to a pool. losses: Record<agentId, lossInZeroOne>.
+ *
+ * AdaNormalHedge update (parameter-free):
+ *   For each agent i:
+ *     R_i        = sum of (mean_loss - loss_i) over rounds  (instantaneous regret)
+ *     C_i        = sum of (loss_i - mean_loss)^2            (cumulative loss variance)
+ *   Set η_i = sqrt(ln(N) / max(1, C_i))  per-agent learning rate.
+ *   weight_i ∝ Phi(R_i, C_i) where Phi is a positive-only potential.
+ *
+ * Simplification used here: w_i *= exp(-η * loss_i) with η derived
+ * from cumulative variance — gives the same regret bound as full
+ * AdaNormalHedge for the binary-loss case we care about (verifier
+ * pass/fail). Trade off: slightly less tight bound vs the full
+ * potential, but no need to plumb regret tracking everywhere.
+ *
+ * @param {{poolId: string, losses: Record<string, number>, baseDir?: string, weightsPath?: string, eta?: number}} input
+ * @returns {{weights: Record<string, number>, weightsPath: string}}
+ */
+function loss(input) {
+  if (!input || typeof input.poolId !== 'string' || input.poolId.length === 0) {
+    throw new TypeError('hedge-ensemble.loss: poolId (string) required');
+  }
+  if (!input.losses || typeof input.losses !== 'object') {
+    throw new TypeError('hedge-ensemble.loss: losses (Record<string, number>) required');
+  }
+  const state = loadWeights(input);
+  const pool = ensurePool(state, input.poolId);
+  // First, ensure every losing agent exists.
+  for (const [agentId, lossVal] of Object.entries(input.losses)) {
+    if (typeof lossVal !== 'number' || Number.isNaN(lossVal)) {
+      throw new TypeError(`hedge-ensemble.loss: losses.${agentId} must be a number`);
+    }
+  }
+  for (const agentId of Object.keys(input.losses)) {
+    ensureAgent(pool, agentId);
+  }
+  const N = Object.keys(pool.agents).length;
+  // Compute mean loss this round (over agents that received a value).
+  const lossList = Object.values(input.losses);
+  const meanLoss = lossList.length > 0 ? lossList.reduce((a, b) => a + b, 0) / lossList.length : 0;
+  // Update each agent's cumulative variance + regret-like signal, then
+  // recompute its weight via exp(-η_i * loss_i).
+  for (const [agentId, rawLoss] of Object.entries(input.losses)) {
+    const lossVal = Math.min(1, Math.max(0, rawLoss));
+    const a = pool.agents[agentId];
+    const dev = lossVal - meanLoss;
+    a.cumLoss += lossVal;
+    a.cumLoss2 += dev * dev;
+    a.rounds += 1;
+    const eta =
+      typeof input.eta === 'number'
+        ? input.eta
+        : Math.sqrt(Math.log(Math.max(2, N)) / Math.max(1, a.cumLoss2));
+    a.weight *= Math.exp(-eta * lossVal);
+    if (!Number.isFinite(a.weight) || a.weight <= 0) a.weight = 1e-9;
+  }
+  // Renormalize.
+  const total = Object.values(pool.agents).reduce((s, x) => s + x.weight, 0) || 1;
+  /** @type {Record<string, number>} */
+  const out = {};
+  for (const agentId of Object.keys(pool.agents)) {
+    pool.agents[agentId].weight /= total;
+    out[agentId] = pool.agents[agentId].weight;
+  }
+  const writtenPath = saveWeights(state, input);
+  return { weights: out, weightsPath: writtenPath };
+}
+
+/**
+ * Compute the weighted-majority verdict for a pool given each agent's
+ * binary vote (pass=1, fail=0). Vote passes when the weighted sum
+ * exceeds threshold (default 0.5).
+ *
+ * @param {{poolId: string, votes: Record<string, 0|1|boolean>, threshold?: number, baseDir?: string, weightsPath?: string}} input
+ * @returns {{passes: boolean, weighted: number, threshold: number, perAgent: Record<string, {weight: number, vote: number}>}}
+ */
+function vote(input) {
+  if (!input || typeof input.poolId !== 'string') {
+    throw new TypeError('hedge-ensemble.vote: poolId required');
+  }
+  if (!input.votes || typeof input.votes !== 'object') {
+    throw new TypeError('hedge-ensemble.vote: votes required');
+  }
+  const state = loadWeights(input);
+  const pool = ensurePool(state, input.poolId);
+  const threshold = typeof input.threshold === 'number' ? input.threshold : DEFAULT_VOTE_THRESHOLD;
+  let total = 0;
+  /** @type {Record<string, {weight: number, vote: number}>} */
+  const perAgent = {};
+  let weightSum = 0;
+  for (const [agentId, raw] of Object.entries(input.votes)) {
+    const v = raw === true || raw === 1 ? 1 : 0;
+    const a = ensureAgent(pool, agentId);
+    perAgent[agentId] = { weight: a.weight, vote: v };
+    total += a.weight * v;
+    weightSum += a.weight;
+  }
+  // Normalise the weighted sum against the SUM of voting agents'
+  // weights — agents in the pool that didn't vote this round don't
+  // dilute the result.
+  const weighted = weightSum > 0 ? total / weightSum : 0;
+  return { passes: weighted >= threshold, weighted, threshold, perAgent };
+}
+
+/**
+ * Read current weights for a pool, normalised over the pool's agents.
+ *
+ * @param {{poolId: string, baseDir?: string, weightsPath?: string}} input
+ * @returns {Record<string, number>}
+ */
+function weights(input) {
+  if (!input || typeof input.poolId !== 'string') {
+    throw new TypeError('hedge-ensemble.weights: poolId required');
+  }
+  const state = loadWeights(input);
+  const pool = state.pools[input.poolId];
+  if (!pool) return {};
+  const total = Object.values(pool.agents).reduce((s, x) => s + x.weight, 0);
+  /** @type {Record<string, number>} */
+  const out = {};
+  for (const [k, v] of Object.entries(pool.agents)) {
+    out[k] = total > 0 ? v.weight / total : 0;
+  }
+  return out;
+}
+
+module.exports = {
+  loss,
+  vote,
+  weights,
+  loadWeights,
+  saveWeights,
+  DEFAULT_VOTE_THRESHOLD,
+  DEFAULT_WEIGHTS_PATH,
+  SCHEMA_VERSION,
+};

package/scripts/lib/install/config-dir.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+// Config-dir lookup chain for the get-design-done multi-runtime installer.
+//
+// Order of precedence (Phase 24 D-03):
+//   1. Explicit override (--config-dir <dir> from caller).
+//   2. Per-runtime env var (CLAUDE_CONFIG_DIR, OPENCODE_CONFIG_DIR, ...).
+//   3. POSIX/Windows fallback at $HOME / $USERPROFILE + the runtime's
+//      configDirFallback (e.g. ~/.claude, ~/.gemini, ~/.config/opencode).
+//
+// resolveConfigDir returns the absolute path the installer should target.
+// It does NOT verify the directory exists — that is the caller's job.
+
+const path = require('node:path');
+const os = require('node:os');
+
+const { getRuntime, listRuntimes } = require('./runtimes.cjs');
+
+function homeDir() {
+  return os.homedir();
+}
+
+function resolveConfigDir(runtimeId, opts) {
+  const runtime = getRuntime(runtimeId);
+  const overrides = (opts && opts.env) || process.env;
+  const explicit = opts && opts.configDir;
+
+  if (explicit && String(explicit).trim()) {
+    return path.resolve(String(explicit).trim());
+  }
+
+  const envValue = overrides[runtime.configDirEnv];
+  if (envValue && String(envValue).trim()) {
+    return path.resolve(String(envValue).trim());
+  }
+
+  const home = (opts && opts.home) || homeDir();
+  // configDirFallback may use POSIX separators (e.g. ".config/opencode") for
+  // cross-runtime portability — path.join + path.resolve normalises to the
+  // host platform's separator on output.
+  return path.resolve(path.join(home, ...runtime.configDirFallback.split('/')));
+}
+
+function resolveAllConfigDirs(opts) {
+  const out = {};
+  for (const runtime of listRuntimes()) {
+    out[runtime.id] = resolveConfigDir(runtime.id, opts);
+  }
+  return out;
+}
+
+module.exports = {
+  resolveConfigDir,
+  resolveAllConfigDirs,
+};

package/scripts/lib/install/installer.cjs

@@ -0,0 +1,244 @@
+'use strict';
+
+// Per-runtime install/uninstall orchestrator. Returns a structured Result
+// for every runtime touched so the caller can render a per-runtime summary.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { getRuntime } = require('./runtimes.cjs');
+const { resolveConfigDir } = require('./config-dir.cjs');
+const {
+  mergeClaudeSettings,
+  removeClaudeSettings,
+  buildAgentsFileContent,
+  isPluginOwned,
+} = require('./merge.cjs');
+
+function loadJsonOr(empty, filePath) {
+  if (!fs.existsSync(filePath)) return empty;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (!raw.trim()) return empty;
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    const friendly = new Error(
+      `get-design-done installer: cannot parse ${filePath} as JSON\n  ${err.message}\n  Fix the file manually or delete it, then re-run.`,
+    );
+    friendly.code = 'EINSTALLER_BAD_JSON';
+    friendly.path = filePath;
+    throw friendly;
+  }
+}
+
+function atomicWrite(target, contents) {
+  const tmp = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(tmp, target);
+}
+
+function ensureDir(dir, dryRun) {
+  if (fs.existsSync(dir)) return false;
+  if (!dryRun) fs.mkdirSync(dir, { recursive: true });
+  return true;
+}
+
+function installRuntime(runtimeId, opts) {
+  const runtime = getRuntime(runtimeId);
+  const dryRun = Boolean(opts && opts.dryRun);
+  const configDir = resolveConfigDir(runtimeId, opts);
+
+  if (runtime.kind === 'claude-marketplace') {
+    return installClaudeMarketplace(runtime, configDir, dryRun);
+  }
+  if (runtime.kind === 'agents-md') {
+    return installAgentsMd(runtime, configDir, dryRun);
+  }
+  throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
+}
+
+function uninstallRuntime(runtimeId, opts) {
+  const runtime = getRuntime(runtimeId);
+  const dryRun = Boolean(opts && opts.dryRun);
+  const configDir = resolveConfigDir(runtimeId, opts);
+
+  if (runtime.kind === 'claude-marketplace') {
+    return uninstallClaudeMarketplace(runtime, configDir, dryRun);
+  }
+  if (runtime.kind === 'agents-md') {
+    return uninstallAgentsMd(runtime, configDir, dryRun);
+  }
+  throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
+}
+
+function installClaudeMarketplace(runtime, configDir, dryRun) {
+  const settingsPath = path.join(configDir, 'settings.json');
+  ensureDir(configDir, dryRun);
+  const existing = loadJsonOr({}, settingsPath);
+  const { next, changed } = mergeClaudeSettings(
+    existing,
+    runtime.marketplaceEntry,
+  );
+  if (!changed) {
+    return {
+      runtime: runtime.id,
+      path: settingsPath,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const formatted = `${JSON.stringify(next, null, 2)}\n`;
+  if (!dryRun) atomicWrite(settingsPath, formatted);
+  return {
+    runtime: runtime.id,
+    path: settingsPath,
+    action: fs.existsSync(settingsPath) ? 'updated' : 'created',
+    dryRun,
+  };
+}
+
+function uninstallClaudeMarketplace(runtime, configDir, dryRun) {
+  const settingsPath = path.join(configDir, 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    return {
+      runtime: runtime.id,
+      path: settingsPath,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const existing = loadJsonOr({}, settingsPath);
+  const { next, changed } = removeClaudeSettings(
+    existing,
+    runtime.marketplaceEntry,
+  );
+  if (!changed) {
+    return {
+      runtime: runtime.id,
+      path: settingsPath,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const formatted = `${JSON.stringify(next, null, 2)}\n`;
+  if (!dryRun) atomicWrite(settingsPath, formatted);
+  return {
+    runtime: runtime.id,
+    path: settingsPath,
+    action: 'removed',
+    dryRun,
+  };
+}
+
+function installAgentsMd(runtime, configDir, dryRun) {
+  ensureDir(configDir, dryRun);
+  const fileName = (runtime.files && runtime.files[0]) || 'AGENTS.md';
+  const target = path.join(configDir, fileName);
+  const desired = buildAgentsFileContent(runtime);
+
+  if (fs.existsSync(target)) {
+    const current = fs.readFileSync(target, 'utf8');
+    if (current === desired) {
+      return {
+        runtime: runtime.id,
+        path: target,
+        action: 'unchanged',
+        dryRun,
+      };
+    }
+    if (!isPluginOwned(current)) {
+      // Don't clobber unrelated user-authored AGENTS.md / GEMINI.md.
+      return {
+        runtime: runtime.id,
+        path: target,
+        action: 'skipped-foreign',
+        dryRun,
+        reason: `Existing ${fileName} was not authored by this plugin; refusing to overwrite. Move it aside or pass --force (not yet supported) to replace.`,
+      };
+    }
+    if (!dryRun) atomicWrite(target, desired);
+    return {
+      runtime: runtime.id,
+      path: target,
+      action: 'updated',
+      dryRun,
+    };
+  }
+  if (!dryRun) atomicWrite(target, desired);
+  return {
+    runtime: runtime.id,
+    path: target,
+    action: 'created',
+    dryRun,
+  };
+}
+
+function uninstallAgentsMd(runtime, configDir, dryRun) {
+  const fileName = (runtime.files && runtime.files[0]) || 'AGENTS.md';
+  const target = path.join(configDir, fileName);
+  if (!fs.existsSync(target)) {
+    return {
+      runtime: runtime.id,
+      path: target,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const current = fs.readFileSync(target, 'utf8');
+  if (!isPluginOwned(current)) {
+    return {
+      runtime: runtime.id,
+      path: target,
+      action: 'skipped-foreign',
+      dryRun,
+      reason: `Existing ${fileName} was not authored by this plugin; not removing.`,
+    };
+  }
+  if (!dryRun) fs.unlinkSync(target);
+  return {
+    runtime: runtime.id,
+    path: target,
+    action: 'removed',
+    dryRun,
+  };
+}
+
+function detectInstalled(opts) {
+  const installed = [];
+  const { listRuntimes } = require('./runtimes.cjs');
+  for (const runtime of listRuntimes()) {
+    const configDir = resolveConfigDir(runtime.id, opts);
+    if (runtime.kind === 'claude-marketplace') {
+      const settingsPath = path.join(configDir, 'settings.json');
+      if (!fs.existsSync(settingsPath)) continue;
+      try {
+        const data = loadJsonOr({}, settingsPath);
+        const key = `${runtime.marketplaceEntry.pluginName}@${runtime.marketplaceEntry.name}`;
+        if (data.enabledPlugins && data.enabledPlugins[key] === true) {
+          installed.push(runtime.id);
+        }
+      } catch {
+        // ignore
+      }
+      continue;
+    }
+    if (runtime.kind === 'agents-md') {
+      const fileName = (runtime.files && runtime.files[0]) || 'AGENTS.md';
+      const target = path.join(configDir, fileName);
+      if (!fs.existsSync(target)) continue;
+      try {
+        const content = fs.readFileSync(target, 'utf8');
+        if (isPluginOwned(content)) installed.push(runtime.id);
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return installed;
+}
+
+module.exports = {
+  installRuntime,
+  uninstallRuntime,
+  detectInstalled,
+};

package/scripts/lib/install/interactive.cjs

@@ -0,0 +1,142 @@
+'use strict';
+
+// @clack/prompts wrapper for the multi-runtime installer.
+//
+// runInteractiveInstall walks the user through three steps:
+//   1. Multi-select runtimes (with [a] all shortcut).
+//   2. Radio: Global vs Local install.
+//   3. Confirmation summary.
+//
+// runInteractiveUninstall walks the user through:
+//   1. Multi-select detected-installed runtimes.
+//   2. Confirmation summary.
+//
+// Both return null when the user cancels at any step (ESC / ctrl-c). The
+// caller is responsible for translating null into a "cancelled" exit-0
+// message.
+
+const { listRuntimes, getRuntime } = require('./runtimes.cjs');
+const { detectInstalled } = require('./installer.cjs');
+
+let clackCache = null;
+function loadClack() {
+  if (clackCache) return clackCache;
+  try {
+    clackCache = require('@clack/prompts');
+  } catch (err) {
+    throw new Error(
+      [
+        'Interactive install requires @clack/prompts.',
+        'Install it (npm i @clack/prompts) or pass an explicit runtime flag',
+        '(e.g. --claude --global) to skip the interactive session.',
+        `Original error: ${err && err.message}`,
+      ].join('\n'),
+    );
+  }
+  return clackCache;
+}
+
+function isCancel(p, value) {
+  return typeof p.isCancel === 'function' ? p.isCancel(value) : false;
+}
+
+async function runInteractiveInstall() {
+  const p = loadClack();
+
+  p.intro('get-design-done — multi-runtime installer');
+
+  const runtimes = listRuntimes();
+  const options = runtimes.map((r) => ({
+    value: r.id,
+    label: r.displayName,
+    hint: r.kind === 'claude-marketplace' ? 'marketplace registration' : `drops ${r.files[0] || 'AGENTS.md'}`,
+  }));
+
+  const picked = await p.multiselect({
+    message: 'Pick the runtimes to install into (space to toggle, [a] all):',
+    options,
+    required: true,
+  });
+  if (isCancel(p, picked)) {
+    p.cancel('Install cancelled.');
+    return null;
+  }
+
+  const location = await p.select({
+    message: 'Install location:',
+    options: [
+      { value: 'global', label: 'Global ($HOME-level config dir)' },
+      { value: 'local', label: 'Local (current working directory)' },
+    ],
+    initialValue: 'global',
+  });
+  if (isCancel(p, location)) {
+    p.cancel('Install cancelled.');
+    return null;
+  }
+
+  const summary = picked
+    .map((id) => `  • ${getRuntime(id).displayName}`)
+    .join('\n');
+  const confirmed = await p.confirm({
+    message: `Install into:\n${summary}\nLocation: ${location}\n\nProceed?`,
+    initialValue: true,
+  });
+  if (isCancel(p, confirmed) || confirmed === false) {
+    p.cancel('Install cancelled.');
+    return null;
+  }
+
+  return { runtimes: picked, location };
+}
+
+async function runInteractiveUninstall(opts) {
+  const p = loadClack();
+
+  p.intro('get-design-done — uninstall');
+
+  const installed = detectInstalled(opts || {});
+  if (installed.length === 0) {
+    p.note(
+      'No runtimes appear to have the get-design-done plugin installed.',
+      'Nothing to do.',
+    );
+    p.outro('Done.');
+    return null;
+  }
+
+  const options = installed.map((id) => ({
+    value: id,
+    label: getRuntime(id).displayName,
+    hint: 'installed',
+  }));
+
+  const picked = await p.multiselect({
+    message: 'Pick the runtimes to uninstall from:',
+    options,
+    required: true,
+  });
+  if (isCancel(p, picked)) {
+    p.cancel('Uninstall cancelled.');
+    return null;
+  }
+
+  const summary = picked
+    .map((id) => `  • ${getRuntime(id).displayName}`)
+    .join('\n');
+  const confirmed = await p.confirm({
+    message: `Uninstall from:\n${summary}\n\nProceed?`,
+    initialValue: true,
+  });
+  if (isCancel(p, confirmed) || confirmed === false) {
+    p.cancel('Uninstall cancelled.');
+    return null;
+  }
+
+  return { runtimes: picked };
+}
+
+module.exports = {
+  runInteractiveInstall,
+  runInteractiveUninstall,
+};