@massa-ai/opencode-plugin 1.55.0 → 1.56.0

package/dist/config-cli.js

@@ -601,15 +601,18 @@ var init_massa_ai_config = __esm(() => {
     security: {
       corsOrigins: []
     },
-    scheduler: DEFAULT_SCHEDULER_CONFIG
+    scheduler: DEFAULT_SCHEDULER_CONFIG,
+    bootstrap: { rules: {} }
   };
 });
 
 // ../../packages/shared/dist/config/config-loader.js
 var exports_config_loader = {};
 __export(exports_config_loader, {
+  writeRawConfig: () => writeRawConfig,
   writeFileAtomically: () => writeFileAtomically,
   saveConfig: () => saveConfig,
+  readRawConfigStrict: () => readRawConfigStrict,
   migrateDataDirOnce: () => migrateDataDirOnce,
   mergeSchedulerSection: () => mergeSchedulerSection,
   loadRawUserConfig: () => loadRawUserConfig,
@@ -620,12 +623,23 @@ __export(exports_config_loader, {
   getConfigForEnv: () => getConfigForEnv,
   getConfigDir: () => getConfigDir,
   configExists: () => configExists,
-  __resetMigrationForTests: () => __resetMigrationForTests
+  __resetMigrationForTests: () => __resetMigrationForTests,
+  ConfigWriteConflictError: () => ConfigWriteConflictError,
+  ConfigParseError: () => ConfigParseError
 });
 import fs from "fs";
 import path3 from "path";
 import os2 from "os";
 import crypto from "crypto";
+function readConfigFileOrEmpty() {
+  try {
+    return fs.readFileSync(CONFIG_FILE, "utf-8");
+  } catch (error) {
+    if (error?.code === "ENOENT")
+      return "";
+    throw error;
+  }
+}
 function getConfigDir() {
   return CONFIG_DIR;
 }
@@ -692,6 +706,21 @@ function loadRawUserConfig() {
     return {};
   }
 }
+function readRawConfigStrict() {
+  const raw = readConfigFileOrEmpty();
+  if (raw === "")
+    return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ConfigParseError(CONFIG_FILE, error);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ConfigParseError(CONFIG_FILE, new Error("parsed value is not a JSON object"));
+  }
+  return parsed;
+}
 function loadConfigSafe() {
   try {
     return loadConfig();
@@ -746,6 +775,43 @@ function writeFileAtomically(targetPath, content) {
 function saveConfig(config) {
   writeFileAtomically(CONFIG_FILE, JSON.stringify(config, null, 2));
 }
+function writeRawConfig(doc, opts) {
+  const onDiskAtStart = readConfigFileOrEmpty();
+  if (onDiskAtStart === opts.expectedBytes) {
+    writeFileAtomically(CONFIG_FILE, JSON.stringify(doc, null, 2));
+    return;
+  }
+  let original;
+  let current;
+  try {
+    original = opts.expectedBytes === "" ? {} : JSON.parse(opts.expectedBytes);
+  } catch (error) {
+    throw new ConfigParseError(`${CONFIG_FILE} (caller-supplied expectedBytes)`, error);
+  }
+  try {
+    current = onDiskAtStart === "" ? {} : JSON.parse(onDiskAtStart);
+  } catch (error) {
+    throw new ConfigParseError(CONFIG_FILE, error);
+  }
+  const reapplied = { ...current };
+  const touchedKeys = new Set([...Object.keys(original), ...Object.keys(doc)]);
+  for (const key of touchedKeys) {
+    const before = JSON.stringify(original[key]);
+    const after = JSON.stringify(doc[key]);
+    if (before === after)
+      continue;
+    if (Object.prototype.hasOwnProperty.call(doc, key)) {
+      reapplied[key] = doc[key];
+    } else {
+      delete reapplied[key];
+    }
+  }
+  const onDiskImmediatelyBeforeWrite = readConfigFileOrEmpty();
+  if (onDiskImmediatelyBeforeWrite !== onDiskAtStart) {
+    throw new ConfigWriteConflictError(CONFIG_FILE);
+  }
+  writeFileAtomically(CONFIG_FILE, JSON.stringify(reapplied, null, 2));
+}
 function initConfig() {
   if (!fs.existsSync(CONFIG_FILE)) {
     saveConfig(defaultMassaAiConfig);
@@ -772,12 +838,25 @@ function getConfigForEnv() {
   env.ENABLE_METRICS = String(config.logging.enableMetrics);
   return env;
 }
-var CONFIG_DIR, CONFIG_FILE, migrationAttempted = false, tempFileCounter = 0;
+var CONFIG_DIR, CONFIG_FILE, ConfigParseError, ConfigWriteConflictError, migrationAttempted = false, tempFileCounter = 0;
 var init_config_loader = __esm(() => {
   init_massa_ai_config();
   init_xdg();
   CONFIG_DIR = configDir("massa-ai");
   CONFIG_FILE = path3.join(CONFIG_DIR, "config.json");
+  ConfigParseError = class ConfigParseError extends Error {
+    constructor(filePath, cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      super(`Failed to parse ${filePath}: ${reason}`);
+      this.name = "ConfigParseError";
+    }
+  };
+  ConfigWriteConflictError = class ConfigWriteConflictError extends Error {
+    constructor(filePath) {
+      super(`${filePath} changed on disk twice while writing \u2014 refusing to overwrite a ` + `concurrent update. Re-read the file and retry.`);
+      this.name = "ConfigWriteConflictError";
+    }
+  };
 });
 
 // ../../packages/shared/dist/env.js
@@ -2622,12 +2701,585 @@ function findRepoRootWithMarker(startDir, marker, maxLevels) {
   }
   return null;
 }
-// src/config-cli.ts
-import { promises as fs9 } from "fs";
+// ../../packages/shared/dist/bootstrap/rules.js
+var BOOTSTRAP_RULE_IDS = [
+  "caveman",
+  "massa-ai-router",
+  "persona-router",
+  "dedupe-guardrails",
+  "plan-challenge",
+  "conversation-feedback",
+  "indexing-hygiene",
+  "english-code",
+  "code-comments"
+];
+function isBootstrapRuleId(value) {
+  return typeof value === "string" && BOOTSTRAP_RULE_IDS.includes(value);
+}
+var BOOTSTRAP_RULES = [
+  {
+    id: "caveman",
+    defaultEnabled: true,
+    description: "Keep communication compressed while preserving technical accuracy."
+  },
+  {
+    id: "massa-ai-router",
+    defaultEnabled: true,
+    description: "Load the massa-ai skill as the workflow router before substantive work."
+  },
+  {
+    id: "persona-router",
+    defaultEnabled: true,
+    description: "Select one cataloged specialist persona after massa-ai context is available."
+  },
+  {
+    id: "dedupe-guardrails",
+    defaultEnabled: true,
+    description: "Reuse already-loaded massa-ai context instead of bulk-loading workflows or references."
+  },
+  {
+    id: "plan-challenge",
+    defaultEnabled: true,
+    description: "Run The Fool as a post-plan challenge gate per the configured policy."
+  },
+  {
+    id: "conversation-feedback",
+    defaultEnabled: true,
+    description: "Emit chat-visible status updates for massa-ai workflow progress."
+  },
+  {
+    id: "indexing-hygiene",
+    defaultEnabled: true,
+    description: "Ignore build output, dependency, and secret paths during indexing and context loading."
+  },
+  {
+    id: "english-code",
+    defaultEnabled: true,
+    description: "Write generated code, identifiers, comments, and commit-facing artifacts in English regardless of conversational language."
+  },
+  {
+    id: "code-comments",
+    defaultEnabled: false,
+    description: "Require API doc blocks and rationale comments on generated code, per code-annotation.md \xA71/\xA72."
+  }
+];
+var RULES_BY_ID = new Map(BOOTSTRAP_RULES.map((rule) => [rule.id, rule]));
+function bootstrapRuleDefaults() {
+  const defaults = {};
+  for (const rule of BOOTSTRAP_RULES)
+    defaults[rule.id] = rule.defaultEnabled;
+  return defaults;
+}
+
+class BootstrapRuleError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BootstrapRuleError";
+  }
+}
+function namedError4(name, message) {
+  const err = new BootstrapRuleError(message);
+  err.name = name;
+  return err;
+}
+var UnknownRuleError = (id, known = BOOTSTRAP_RULE_IDS) => namedError4("UnknownRuleError", `unknown bootstrap rule "${id}" \u2014 valid ids: ${known.join(", ")}`);
+function assertKnownRuleId(id) {
+  if (!isBootstrapRuleId(id))
+    throw UnknownRuleError(id, BOOTSTRAP_RULE_IDS);
+}
+// ../../packages/shared/dist/bootstrap/state.js
+init_config_loader();
+import fs9 from "fs";
+var BOOTSTRAP_STATE_KEY = "bootstrap";
+var BOOTSTRAP_RULES_KEY = "rules";
+var BOOTSTRAP_STATE_PATH = `${BOOTSTRAP_STATE_KEY}.${BOOTSTRAP_RULES_KEY}`;
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveBootstrapState(doc) {
+  const document = doc ?? readRawConfigStrict();
+  const state = bootstrapRuleDefaults();
+  const ignored = [];
+  const bootstrap = document[BOOTSTRAP_STATE_KEY];
+  if (bootstrap === undefined)
+    return { state, ignoredStateKeys: [] };
+  if (!isPlainObject2(bootstrap)) {
+    return { state, ignoredStateKeys: [BOOTSTRAP_STATE_KEY] };
+  }
+  const rules = bootstrap[BOOTSTRAP_RULES_KEY];
+  if (rules === undefined)
+    return { state, ignoredStateKeys: [] };
+  if (!isPlainObject2(rules)) {
+    return { state, ignoredStateKeys: [BOOTSTRAP_STATE_PATH] };
+  }
+  for (const [key, value] of Object.entries(rules)) {
+    if (!isBootstrapRuleId(key) || typeof value !== "boolean") {
+      ignored.push(key);
+      continue;
+    }
+    state[key] = value;
+  }
+  return { state, ignoredStateKeys: ignored.sort() };
+}
+function readConfigBytes() {
+  try {
+    return fs9.readFileSync(getConfigPath(), "utf-8");
+  } catch (error) {
+    if (error?.code === "ENOENT")
+      return "";
+    throw error;
+  }
+}
+function setBootstrapRuleEnabled(id, enabled) {
+  assertKnownRuleId(id);
+  const expectedBytes = readConfigBytes();
+  let document;
+  if (expectedBytes === "") {
+    document = {};
+  } else {
+    let parsed;
+    try {
+      parsed = JSON.parse(expectedBytes);
+    } catch (error) {
+      throw new ConfigParseError(getConfigPath(), error);
+    }
+    if (!isPlainObject2(parsed)) {
+      throw new ConfigParseError(getConfigPath(), new Error("parsed value is not a JSON object"));
+    }
+    document = parsed;
+  }
+  const before = resolveBootstrapState(document);
+  const bootstrap = document[BOOTSTRAP_STATE_KEY];
+  const bootstrapSubtree = isPlainObject2(bootstrap) ? bootstrap : {};
+  const rules = bootstrapSubtree[BOOTSTRAP_RULES_KEY];
+  const rulesSubtree = isPlainObject2(rules) ? rules : {};
+  const next = {
+    ...document,
+    [BOOTSTRAP_STATE_KEY]: {
+      ...bootstrapSubtree,
+      [BOOTSTRAP_RULES_KEY]: { ...rulesSubtree, [id]: enabled }
+    }
+  };
+  writeRawConfig(next, { expectedBytes });
+  const after = resolveBootstrapState(next);
+  return {
+    id,
+    enabled,
+    changed: before.state[id] !== enabled,
+    state: after.state,
+    ignoredStateKeys: after.ignoredStateKeys
+  };
+}
+// ../../packages/shared/dist/bootstrap/render.js
 import path13 from "path";
+var BOOTSTRAP_BLOCK_START = "<!-- massa-ai:bootstrap:start -->";
+var BOOTSTRAP_BLOCK_END = "<!-- massa-ai:bootstrap:end -->";
+var CONTRACT_FILENAME = "MASSA-AI.md";
+function wrapBootstrapBlock(body) {
+  return `${BOOTSTRAP_BLOCK_START}
+${body.replace(/\n+$/, "")}
+${BOOTSTRAP_BLOCK_END}
+`;
+}
+function ruleMarker(id, suffix) {
+  return `<!-- massa-ai:rule:${id}:${suffix} -->`;
+}
+var ANY_MASSA_AI_MARKER = /<!--\s*massa-ai:(?:rule|bootstrap):[^>]*-->/;
+
+class BootstrapRenderError extends Error {
+  details;
+  constructor(name, message, details = []) {
+    super(message);
+    this.name = name;
+    this.details = details;
+  }
+}
+var HOST_CONFIG_DIR = {
+  claude: [".claude"],
+  codex: [".codex"],
+  cursor: [".cursor"],
+  opencode: [".config", "opencode"]
+};
+function resolveHostRoot(host, targetHome, hostRoot) {
+  requireAbsoluteTargetHome(targetHome);
+  if (hostRoot === undefined)
+    return path13.join(targetHome, ...HOST_CONFIG_DIR[host]);
+  const relative = path13.relative(targetHome, hostRoot);
+  if (!path13.isAbsolute(hostRoot) || relative === "" || relative.startsWith("..") || path13.isAbsolute(relative)) {
+    throw new BootstrapRenderError("HostRootOutsideTargetHomeError", `hostRoot must be an absolute directory inside targetHome, got "${hostRoot}" for targetHome "${targetHome}"`, [hostRoot, targetHome]);
+  }
+  return hostRoot;
+}
+function bootstrapContractPath(host, targetHome, hostRoot) {
+  return path13.join(resolveHostRoot(host, targetHome, hostRoot), CONTRACT_FILENAME);
+}
+function bootstrapStateFilePath(targetHome) {
+  requireAbsoluteTargetHome(targetHome);
+  return path13.join(targetHome, ".config", "massa-ai", "config.json");
+}
+function renderBootstrap(options) {
+  const { source, state, host, targetHome, hostRoot } = options;
+  requireAbsoluteTargetHome(targetHome);
+  requireTotalState(state);
+  const body = applyRuleState(extractBootstrapBlock(source), state);
+  const contract = `${renderHeader(state, targetHome)}
+
+${body}`;
+  const pointer = renderPointer(host, targetHome, hostRoot);
+  const emitted = [
+    ...contract.split(`
+`).filter((line) => ANY_MASSA_AI_MARKER.test(line)),
+    ...pointer.split(`
+`).filter((line) => ANY_MASSA_AI_MARKER.test(line))
+  ].map((line) => line.trim());
+  if (emitted.length > 0) {
+    throw new BootstrapRenderError("MarkerInInterpolatedPathError", `rendered output carries a massa-ai marker, which can only have come from an interpolated path: ${emitted.join(", ")}`, emitted);
+  }
+  return { contract, pointer };
+}
+function requireAbsoluteTargetHome(targetHome) {
+  if (!path13.isAbsolute(targetHome)) {
+    throw new BootstrapRenderError("TargetHomeNotAbsoluteError", `targetHome must be an absolute path, got "${targetHome}"`, [targetHome]);
+  }
+}
+function requireTotalState(state) {
+  const missing = BOOTSTRAP_RULES.filter((rule) => typeof state[rule.id] !== "boolean").map((rule) => rule.id);
+  if (missing.length > 0) {
+    throw new BootstrapRenderError("IncompleteBootstrapStateError", `bootstrap state is missing a boolean for: ${missing.join(", ")} \u2014 pass a state resolved by resolveBootstrapState`, missing);
+  }
+}
+function extractBootstrapBlock(source) {
+  const startCount = countOccurrences(source, BOOTSTRAP_BLOCK_START);
+  const endCount = countOccurrences(source, BOOTSTRAP_BLOCK_END);
+  const startIndex = source.indexOf(BOOTSTRAP_BLOCK_START);
+  const endIndex = source.indexOf(BOOTSTRAP_BLOCK_END);
+  if (startCount !== 1 || endCount !== 1 || startIndex > endIndex) {
+    throw new BootstrapRenderError("BootstrapSourceError", `source must contain exactly one well-formed bootstrap block \u2014 found ${startCount} start and ${endCount} end marker(s)`, [`start=${startCount}`, `end=${endCount}`]);
+  }
+  return source.slice(startIndex + BOOTSTRAP_BLOCK_START.length, endIndex);
+}
+function findMarker(lines, marker) {
+  let index = -1;
+  let count = 0;
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i]?.trim() === marker) {
+      if (count === 0)
+        index = i;
+      count++;
+    }
+  }
+  return { index, count };
+}
+function countOccurrences(haystack, needle) {
+  let count = 0;
+  let from = 0;
+  for (;; ) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1)
+      return count;
+    count++;
+    from = at + needle.length;
+  }
+}
+function splitOffSpan(inner, id) {
+  const offStart = findMarker(inner, ruleMarker(id, "off"));
+  const offEnd = findMarker(inner, ruleMarker(id, "off-end"));
+  if (offStart.count === 0 && offEnd.count === 0)
+    return { on: inner, off: [] };
+  if (offStart.count !== 1 || offEnd.count !== 1 || offStart.index > offEnd.index) {
+    throw new BootstrapRenderError("MalformedOffSpanError", `rule "${id}" has a malformed off-text span \u2014 found ${offStart.count} ":off" and ${offEnd.count} ":off-end" marker(s)`, [id]);
+  }
+  return {
+    on: [...inner.slice(0, offStart.index), ...inner.slice(offEnd.index + 1)],
+    off: inner.slice(offStart.index + 1, offEnd.index)
+  };
+}
+function applyRuleState(block, state) {
+  const lines = block.split(`
+`);
+  const missingSpans = [];
+  for (const rule of BOOTSTRAP_RULES) {
+    const start = findMarker(lines, ruleMarker(rule.id, "start"));
+    const end = findMarker(lines, ruleMarker(rule.id, "end"));
+    if (start.count !== 1 || end.count !== 1 || start.index > end.index) {
+      missingSpans.push(rule.id);
+      continue;
+    }
+    const span = splitOffSpan(lines.slice(start.index + 1, end.index), rule.id);
+    const replacement = state[rule.id] ? span.on : span.off;
+    lines.splice(start.index, end.index - start.index + 1, ...replacement);
+  }
+  if (missingSpans.length > 0) {
+    throw new BootstrapRenderError("MissingRuleSpanError", `source has no well-formed span for rule(s): ${missingSpans.join(", ")}`, missingSpans);
+  }
+  const leftovers = lines.filter((line) => ANY_MASSA_AI_MARKER.test(line)).map((line) => line.trim());
+  if (leftovers.length > 0) {
+    throw new BootstrapRenderError("UnknownRuleMarkerError", `source carries marker(s) no registry rule consumed: ${leftovers.join(", ")}`, leftovers);
+  }
+  return normalizeBlankLines(lines);
+}
+function normalizeBlankLines(lines) {
+  const out = [];
+  let inFence = false;
+  for (const line of lines) {
+    if (line.trimStart().startsWith("```")) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+    if (inFence) {
+      out.push(line);
+      continue;
+    }
+    const previous = out[out.length - 1];
+    const isBlank = line.trim() === "";
+    if (isBlank && (previous === undefined || previous.trim() === ""))
+      continue;
+    if (/^#{1,6} /.test(line) && previous !== undefined && previous.trim() !== "")
+      out.push("");
+    out.push(line);
+  }
+  return `${out.join(`
+`).trimEnd()}
+`;
+}
+function renderHeader(state, targetHome) {
+  const lines = [
+    "> Generated by massa-ai from `skills/AGENTS.md`. Edits made here are lost on",
+    "> the next `scripts/install-skills.sh --apply` or",
+    "> `massa-ai-config bootstrap enable|disable <rule-id>` run.",
+    ">",
+    `> Rule state lives in \`${bootstrapStateFilePath(targetHome)}\` under the`,
+    `> \`${BOOTSTRAP_STATE_PATH}\` key. List every rule and its state with`,
+    "> `massa-ai-config bootstrap list`; switch one back on with",
+    "> `massa-ai-config bootstrap enable <rule-id>`. That command is a binary and",
+    "> not a rule, so it keeps working with every rule below disabled \u2014",
+    "> `massa-ai-config bootstrap enable massa-ai-router` is the way back when the",
+    "> router rule itself is off."
+  ];
+  if (BOOTSTRAP_RULES.every((rule) => !state[rule.id])) {
+    lines.push("", "**Every massa-ai bootstrap rule is disabled.** The contract below carries no", "rule to activate, and nothing in this file changes agent behavior until at", "least one rule is enabled again.");
+  }
+  return lines.join(`
+`);
+}
+function renderPointer(host, targetHome, hostRoot) {
+  return [
+    "## massa-ai Startup Contract",
+    "",
+    "Before substantive work in this session, read",
+    `\`${bootstrapContractPath(host, targetHome, hostRoot)}\``,
+    "with your Read tool and follow it. This block is a pointer only: it states no",
+    "rule of its own, and massa-ai overwrites it on the next install.",
+    ""
+  ].join(`
+`);
+}
+// ../../packages/shared/dist/bootstrap/report.js
+var CLEAN_STATUSES = new Set(["written", "skipped"]);
+function bootstrapReportSucceeded(report) {
+  return report.rows.every((row) => CLEAN_STATUSES.has(row.status));
+}
+function buildBootstrapReport(input) {
+  const restartRequired = !input.dryRun && input.rows.some((row) => row.status === "written");
+  return {
+    rows: input.rows,
+    restartRequired,
+    dryRun: input.dryRun,
+    ignoredStateKeys: input.ignoredStateKeys
+  };
+}
+// ../../packages/shared/dist/bootstrap/engine.js
+init_config_loader();
+import fs10 from "fs";
+import path14 from "path";
+var INSTALL_STATE_FILENAME = "install-state.json";
+var WIRING_REMEDY = "scripts/install-skills.sh --apply";
+
+class BootstrapEngineError extends Error {
+  details;
+  constructor(name, message, details = []) {
+    super(message);
+    this.name = name;
+    this.details = details;
+  }
+}
+function applyBootstrapState(options) {
+  const { targetHome } = options;
+  const dryRun = options.dryRun ?? false;
+  const warn = options.onWarning ?? ((message) => console.warn(message));
+  const configPath = bootstrapStateFilePath(targetHome);
+  const installStatePath = path14.join(path14.dirname(configPath), INSTALL_STATE_FILENAME);
+  const { platforms } = readInstallState(installStatePath);
+  const installed = HOSTS.filter((host) => platforms[host] !== undefined);
+  if (installed.length === 0) {
+    return buildBootstrapReport({ rows: [], dryRun, ignoredStateKeys: [] });
+  }
+  const resolved = resolveRuleState(configPath, warn);
+  const source = readSource(options);
+  const rows = installed.map((host) => applyHost({
+    host,
+    source,
+    state: resolved.state,
+    targetHome,
+    hostRoot: recordedHostRoot(platforms[host]),
+    dryRun
+  }));
+  return buildBootstrapReport({
+    rows,
+    dryRun,
+    ignoredStateKeys: resolved.ignoredStateKeys
+  });
+}
+function recordedHostRoot(record) {
+  const root = record?.root;
+  return typeof root === "string" && root.length > 0 ? root : undefined;
+}
+function resolveRuleState(configPath, warn) {
+  const raw = readFileOrNull(configPath);
+  if (raw === null)
+    return resolveBootstrapState({});
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    warn(degradeWarning(configPath, error));
+    return resolveBootstrapState({});
+  }
+  if (!isPlainObject3(parsed)) {
+    warn(degradeWarning(configPath, new Error("parsed value is not a JSON object")));
+    return resolveBootstrapState({});
+  }
+  return resolveBootstrapState(parsed);
+}
+function degradeWarning(configPath, cause) {
+  const error = new ConfigParseError(configPath, cause);
+  return `${error.name}: ${error.message} \u2014 rendering the registry bootstrap defaults; ${configPath} was not written`;
+}
+function readSource(options) {
+  if (options.source !== undefined)
+    return options.source;
+  if (options.sourcePath !== undefined) {
+    const text = readFileOrNull(options.sourcePath);
+    if (text === null) {
+      throw new BootstrapEngineError("BootstrapSourceUnreadableError", `could not read the bootstrap source at ${options.sourcePath}`, [options.sourcePath]);
+    }
+    return text;
+  }
+  throw new BootstrapEngineError("BootstrapSourceUnavailableError", "no bootstrap source given \u2014 pass `source` (the skills/AGENTS.md text) or `sourcePath`", ["source", "sourcePath"]);
+}
+function applyHost(input) {
+  const { host, source, state, targetHome, hostRoot, dryRun } = input;
+  let contractPath;
+  let document;
+  try {
+    contractPath = bootstrapContractPath(host, targetHome, hostRoot);
+    document = wrapBootstrapBlock(renderBootstrap({ source, state, host, targetHome, hostRoot }).contract);
+  } catch (error) {
+    return { host, status: "failed", reason: error.message };
+  }
+  const wired = isWired(host, targetHome, hostRoot);
+  const notWired = () => ({
+    host,
+    status: "written-not-wired",
+    reason: notWiredReason(host, targetHome, hostRoot)
+  });
+  if (readFileOrNull(contractPath) === document) {
+    return wired ? { host, status: "skipped", reason: `${contractPath} is already up to date` } : notWired();
+  }
+  if (!dryRun) {
+    try {
+      writeFileAtomically(contractPath, document);
+    } catch (error) {
+      return {
+        host,
+        status: "failed",
+        reason: `could not write ${contractPath}: ${error.message}`
+      };
+    }
+  }
+  return wired ? { host, status: "written" } : notWired();
+}
+function wiringArtifact(host, targetHome, hostRoot) {
+  const root = resolveHostRoot(host, targetHome, hostRoot);
+  const contractPath = path14.join(root, CONTRACT_FILENAME);
+  switch (host) {
+    case "claude":
+      return { file: path14.join(root, "CLAUDE.md"), token: `@${CONTRACT_FILENAME}` };
+    case "codex":
+    case "cursor":
+      return { file: path14.join(root, "AGENTS.md"), token: contractPath };
+    case "opencode":
+      return { file: openCodeConfigPath(root), token: `"${contractPath}"` };
+  }
+}
+function openCodeConfigPath(root) {
+  const json = path14.join(root, "opencode.json");
+  if (fs10.existsSync(json))
+    return json;
+  return path14.join(root, "opencode.jsonc");
+}
+function isWired(host, targetHome, hostRoot) {
+  const artifact = wiringArtifact(host, targetHome, hostRoot);
+  const text = readFileOrNull(artifact.file);
+  return text !== null && text.includes(artifact.token);
+}
+function notWiredReason(host, targetHome, hostRoot) {
+  const artifact = wiringArtifact(host, targetHome, hostRoot);
+  return `contract written, but ${host} has no artifact that loads it \u2014 expected ${artifact.token} in ${artifact.file}; run ${WIRING_REMEDY} to add the wiring`;
+}
+function readFileOrNull(filePath) {
+  try {
+    return fs10.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function isPlainObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// ../../packages/shared/dist/bootstrap/format.js
+function enabledWord(enabled) {
+  return enabled ? "enabled" : "disabled";
+}
+function formatBootstrapInventory(state) {
+  return BOOTSTRAP_RULES.map((rule) => {
+    const current = enabledWord(state[rule.id]);
+    const fallback = enabledWord(rule.defaultEnabled);
+    return `  ${rule.id}: ${current} (default: ${fallback}) \u2014 ${rule.description}`;
+  }).join(`
+`);
+}
+function formatBootstrapReport(report) {
+  const dryRunSuffix = report.dryRun ? " (dry run \u2014 no files changed)" : "";
+  const lines = [];
+  if (report.rows.length === 0) {
+    lines.push(`bootstrap: no host installed${dryRunSuffix}`);
+  } else {
+    lines.push(`bootstrap: ${report.rows.length} host(s)${dryRunSuffix}`);
+    for (const row of report.rows) {
+      const detail = row.reason ? `: ${row.reason}` : "";
+      lines.push(`  ${row.host}: ${row.status}${detail}`);
+    }
+  }
+  if (report.ignoredStateKeys.length > 0) {
+    lines.push("", `Ignored persisted rule state: ${report.ignoredStateKeys.join(", ")} \u2014 not a known rule id with a boolean value.`);
+  }
+  if (report.restartRequired) {
+    lines.push("", "A host session restart is required for the change to take effect.");
+  }
+  return lines.join(`
+`);
+}
+
+// ../../packages/shared/dist/bootstrap/index.js
+init_config_loader();
+// src/config-cli.ts
+import { promises as fs11 } from "fs";
+import path15 from "path";
 import os8 from "os";
 import { fileURLToPath } from "url";
-var __dirname2 = path13.dirname(fileURLToPath(import.meta.url));
+var __dirname2 = path15.dirname(fileURLToPath(import.meta.url));
 var GENERATOR_MARKER = "scripts/generate-subagent-artifacts.ts";
 var GENERATOR_MARKER_MAX_LEVELS = 6;
 function formatVariantSync(results) {
@@ -2667,6 +3319,13 @@ Commands:
   profile set <name> [--host <h>] [--dry-run]
                     Switch installed agents to a profile (restart required after)
 
+  bootstrap list    List every startup-contract rule: state, default, description
+  bootstrap show    Same as 'bootstrap list'
+  bootstrap enable <rule-id> [--target <dir> --yes] [--dry-run]
+  bootstrap disable <rule-id> [--target <dir> --yes] [--dry-run]
+                    Toggle one rule and re-render MASSA-AI.md for every
+                    recorded host (restart required after)
+
 Examples:
   massa-ai-config init
   massa-ai-config init --mistral your-api-key
@@ -2675,6 +3334,8 @@ Examples:
   massa-ai-config set embedding.dimensions 1024
   massa-ai-config agents install --user
   massa-ai-config profile set work --dry-run
+  massa-ai-config bootstrap list
+  massa-ai-config bootstrap disable caveman
 `);
 }
 function parseOptions(args) {
@@ -2838,18 +3499,18 @@ Using defaults:`);
         return 1;
       }
       const scope = typeof options.project === "boolean" ? "project" : "user";
-      const agentsDir = scope === "project" ? path13.join(process.cwd(), ".opencode/agents") : path13.join(process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim() || path13.join(os8.homedir(), ".config"), "opencode", "agents");
-      const sourceAgentsDir = path13.resolve(__dirname2, "..", "agents");
+      const agentsDir = scope === "project" ? path15.join(process.cwd(), ".opencode/agents") : path15.join(process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim() || path15.join(os8.homedir(), ".config"), "opencode", "agents");
+      const sourceAgentsDir = path15.resolve(__dirname2, "..", "agents");
       if (subcommand === "install") {
-        await fs9.mkdir(agentsDir, { recursive: true });
+        await fs11.mkdir(agentsDir, { recursive: true });
         let count = 0;
-        const entries = await fs9.readdir(sourceAgentsDir);
+        const entries = await fs11.readdir(sourceAgentsDir);
         for (const entry of entries) {
           if (!entry.startsWith("massa-ai-") || !entry.endsWith(".md"))
             continue;
-          const src = path13.join(sourceAgentsDir, entry);
-          const dest = path13.join(agentsDir, entry);
-          await fs9.copyFile(src, dest);
+          const src = path15.join(sourceAgentsDir, entry);
+          const dest = path15.join(agentsDir, entry);
+          await fs11.copyFile(src, dest);
           count++;
         }
         console.log(`+ ${count} subagent specialists (generated from skills/agents/*/SKILL.md)`);
@@ -2857,14 +3518,14 @@ Using defaults:`);
       } else {
         let removed = 0;
         try {
-          const entries = await fs9.readdir(agentsDir);
+          const entries = await fs11.readdir(agentsDir);
           for (const entry of entries) {
             if (!entry.startsWith("massa-ai-") || !entry.endsWith(".md"))
               continue;
-            const filePath = path13.join(agentsDir, entry);
-            const content = await fs9.readFile(filePath, "utf8");
+            const filePath = path15.join(agentsDir, entry);
+            const content = await fs11.readFile(filePath, "utf8");
             if (content.includes("massa-ai-owned: true")) {
-              await fs9.unlink(filePath);
+              await fs11.unlink(filePath);
               removed++;
             }
           }
@@ -2917,6 +3578,62 @@ Using defaults:`);
       console.error("Usage: massa-ai-config profile <list|show|set> ...");
       return 1;
     }
+    case "bootstrap": {
+      const subcommand = args[1];
+      if (subcommand === "list" || subcommand === "show") {
+        try {
+          console.log(formatBootstrapInventory(resolveBootstrapState().state));
+        } catch (e) {
+          console.error(`Error: ${e.message}`);
+          return 1;
+        }
+        return 0;
+      }
+      if (subcommand === "enable" || subcommand === "disable") {
+        const ruleId = args[2];
+        if (!ruleId) {
+          console.error("Usage: massa-ai-config bootstrap <enable|disable> <rule-id> [--target <dir> --yes] [--dry-run]");
+          return 1;
+        }
+        try {
+          assertKnownRuleId(ruleId);
+        } catch (e) {
+          console.error(`Error: ${e.message}`);
+          return 1;
+        }
+        const targetOpt = typeof options.target === "string" ? options.target : undefined;
+        const targetHome = targetOpt === undefined ? os8.homedir() : path15.resolve(targetOpt);
+        if (targetHome !== os8.homedir() && options.yes !== true) {
+          console.error(`Error: --target ${targetHome} is not your home (${os8.homedir()}) \u2014 pass --yes to confirm writing there`);
+          return 1;
+        }
+        const dryRun = options["dry-run"] === true;
+        try {
+          if (dryRun) {
+            console.log(`bootstrap ${subcommand} ${ruleId}: dry run \u2014 ${getConfigPath()} was not written`);
+          } else {
+            setBootstrapRuleEnabled(ruleId, subcommand === "enable");
+          }
+          const stateFile = bootstrapStateFilePath(targetHome);
+          if (stateFile !== getConfigPath()) {
+            console.error(`Warning: the rule state is persisted to ${getConfigPath()}, but --target renders from ${stateFile} \u2014 set XDG_CONFIG_HOME to move the persisted state`);
+          }
+          const repoRoot = findRepoRootWithMarker(__dirname2, GENERATOR_MARKER, GENERATOR_MARKER_MAX_LEVELS);
+          const report = applyBootstrapState({
+            targetHome,
+            dryRun,
+            sourcePath: repoRoot === null ? undefined : path15.join(repoRoot, "skills", "AGENTS.md")
+          });
+          console.log(formatBootstrapReport(report));
+          return bootstrapReportSucceeded(report) ? 0 : 1;
+        } catch (e) {
+          console.error(`Error: ${e.message}`);
+          return 1;
+        }
+      }
+      console.error("Usage: massa-ai-config bootstrap <list|show|enable|disable> ...");
+      return 1;
+    }
     default:
       console.error(`Unknown command: ${command}`);
       help();

package/dist/index.js

@@ -600,15 +600,18 @@ var init_massa_ai_config = __esm(() => {
     security: {
       corsOrigins: []
     },
-    scheduler: DEFAULT_SCHEDULER_CONFIG
+    scheduler: DEFAULT_SCHEDULER_CONFIG,
+    bootstrap: { rules: {} }
   };
 });
 
 // ../../packages/shared/dist/config/config-loader.js
 var exports_config_loader = {};
 __export(exports_config_loader, {
+  writeRawConfig: () => writeRawConfig,
   writeFileAtomically: () => writeFileAtomically,
   saveConfig: () => saveConfig,
+  readRawConfigStrict: () => readRawConfigStrict,
   migrateDataDirOnce: () => migrateDataDirOnce,
   mergeSchedulerSection: () => mergeSchedulerSection,
   loadRawUserConfig: () => loadRawUserConfig,
@@ -619,12 +622,23 @@ __export(exports_config_loader, {
   getConfigForEnv: () => getConfigForEnv,
   getConfigDir: () => getConfigDir,
   configExists: () => configExists,
-  __resetMigrationForTests: () => __resetMigrationForTests
+  __resetMigrationForTests: () => __resetMigrationForTests,
+  ConfigWriteConflictError: () => ConfigWriteConflictError,
+  ConfigParseError: () => ConfigParseError
 });
 import fs from "fs";
 import path3 from "path";
 import os2 from "os";
 import crypto from "crypto";
+function readConfigFileOrEmpty() {
+  try {
+    return fs.readFileSync(CONFIG_FILE, "utf-8");
+  } catch (error) {
+    if (error?.code === "ENOENT")
+      return "";
+    throw error;
+  }
+}
 function getConfigDir() {
   return CONFIG_DIR;
 }
@@ -691,6 +705,21 @@ function loadRawUserConfig() {
     return {};
   }
 }
+function readRawConfigStrict() {
+  const raw = readConfigFileOrEmpty();
+  if (raw === "")
+    return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ConfigParseError(CONFIG_FILE, error);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ConfigParseError(CONFIG_FILE, new Error("parsed value is not a JSON object"));
+  }
+  return parsed;
+}
 function loadConfigSafe() {
   try {
     return loadConfig();
@@ -745,6 +774,43 @@ function writeFileAtomically(targetPath, content) {
 function saveConfig(config) {
   writeFileAtomically(CONFIG_FILE, JSON.stringify(config, null, 2));
 }
+function writeRawConfig(doc, opts) {
+  const onDiskAtStart = readConfigFileOrEmpty();
+  if (onDiskAtStart === opts.expectedBytes) {
+    writeFileAtomically(CONFIG_FILE, JSON.stringify(doc, null, 2));
+    return;
+  }
+  let original;
+  let current;
+  try {
+    original = opts.expectedBytes === "" ? {} : JSON.parse(opts.expectedBytes);
+  } catch (error) {
+    throw new ConfigParseError(`${CONFIG_FILE} (caller-supplied expectedBytes)`, error);
+  }
+  try {
+    current = onDiskAtStart === "" ? {} : JSON.parse(onDiskAtStart);
+  } catch (error) {
+    throw new ConfigParseError(CONFIG_FILE, error);
+  }
+  const reapplied = { ...current };
+  const touchedKeys = new Set([...Object.keys(original), ...Object.keys(doc)]);
+  for (const key of touchedKeys) {
+    const before = JSON.stringify(original[key]);
+    const after = JSON.stringify(doc[key]);
+    if (before === after)
+      continue;
+    if (Object.prototype.hasOwnProperty.call(doc, key)) {
+      reapplied[key] = doc[key];
+    } else {
+      delete reapplied[key];
+    }
+  }
+  const onDiskImmediatelyBeforeWrite = readConfigFileOrEmpty();
+  if (onDiskImmediatelyBeforeWrite !== onDiskAtStart) {
+    throw new ConfigWriteConflictError(CONFIG_FILE);
+  }
+  writeFileAtomically(CONFIG_FILE, JSON.stringify(reapplied, null, 2));
+}
 function initConfig() {
   if (!fs.existsSync(CONFIG_FILE)) {
     saveConfig(defaultMassaAiConfig);
@@ -771,12 +837,25 @@ function getConfigForEnv() {
   env.ENABLE_METRICS = String(config.logging.enableMetrics);
   return env;
 }
-var CONFIG_DIR, CONFIG_FILE, migrationAttempted = false, tempFileCounter = 0;
+var CONFIG_DIR, CONFIG_FILE, ConfigParseError, ConfigWriteConflictError, migrationAttempted = false, tempFileCounter = 0;
 var init_config_loader = __esm(() => {
   init_massa_ai_config();
   init_xdg();
   CONFIG_DIR = configDir("massa-ai");
   CONFIG_FILE = path3.join(CONFIG_DIR, "config.json");
+  ConfigParseError = class ConfigParseError extends Error {
+    constructor(filePath, cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      super(`Failed to parse ${filePath}: ${reason}`);
+      this.name = "ConfigParseError";
+    }
+  };
+  ConfigWriteConflictError = class ConfigWriteConflictError extends Error {
+    constructor(filePath) {
+      super(`${filePath} changed on disk twice while writing \u2014 refusing to overwrite a ` + `concurrent update. Re-read the file and retry.`);
+      this.name = "ConfigWriteConflictError";
+    }
+  };
 });
 
 // ../../packages/shared/dist/env.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/opencode-plugin",
-  "version": "1.55.0",
+  "version": "1.56.0",
   "description": "massa-ai plugin for OpenCode - Semantic code search, memory, and context compression",
   "type": "module",
   "main": "dist/index.js",
@@ -24,8 +24,8 @@
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.15",
     "@opencode-ai/sdk": "^1.2.15",
-    "@massa-ai/core": "^1.55.0",
-    "@massa-ai/shared": "^1.55.0"
+    "@massa-ai/core": "^1.56.0",
+    "@massa-ai/shared": "^1.56.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",