arcane-cli 0.14.0 → 0.15.1

package/dist/index.js

@@ -802,6 +802,167 @@ async function applyNamingStrategy(strategy, roleIds) {
 import { readFile as readFile2, readdir as readdir2, access as access2 } from "fs/promises";
 import { join } from "path";
 import { parse } from "yaml";
+
+// src/modules/agent-schema.ts
+var CURRENT_ROSTER_SCHEMA_VERSION = 2;
+var POWER_LEVELS = /* @__PURE__ */ new Set([
+  "Spectator",
+  "Apprentice",
+  "Wizard",
+  "Sorcerer",
+  "Magus",
+  "Archmage"
+]);
+var AGENT_CATEGORIES = /* @__PURE__ */ new Set([
+  "engineering",
+  "operations",
+  "quality",
+  "research"
+]);
+var NAMING_STRATEGIES = /* @__PURE__ */ new Set(["arcanos", "generic", "random", "custom"]);
+var AGENT_PROFILES = /* @__PURE__ */ new Set(["base", "full", "custom"]);
+var AgentConfigValidationError = class extends Error {
+  constructor(source, issues) {
+    super(`Invalid agent configuration in ${source}:
+- ${issues.join("\n- ")}`);
+    this.name = "AgentConfigValidationError";
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(value, path4, issues) {
+  if (!isRecord(value)) {
+    issues.push(`${path4} must be an object`);
+    return void 0;
+  }
+  return value;
+}
+function requireString(value, path4, issues) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    issues.push(`${path4} must be a non-empty string`);
+  }
+}
+function requireBoolean(value, path4, issues) {
+  if (typeof value !== "boolean") issues.push(`${path4} must be a boolean`);
+}
+function requireStringArray(value, path4, issues) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    issues.push(`${path4} must be an array of strings`);
+  }
+}
+function requireEnum(value, allowed, path4, issues) {
+  if (typeof value !== "string" || !allowed.has(value)) {
+    issues.push(`${path4} must be one of: ${[...allowed].join(", ")}`);
+  }
+}
+function validateOptionalClient(clients, key, property, expected, issues) {
+  if (clients[key] === void 0) return;
+  const client = requireRecord(clients[key], `clients.${key}`, issues);
+  if (!client) return;
+  if (expected === "string") {
+    requireString(client[property], `clients.${key}.${property}`, issues);
+  } else {
+    requireBoolean(client[property], `clients.${key}.${property}`, issues);
+  }
+}
+function validateAgentDefinition(value, source) {
+  const issues = [];
+  const definition = requireRecord(value, "definition", issues);
+  if (!definition) throw new AgentConfigValidationError(source, issues);
+  requireString(definition.id, "id", issues);
+  requireString(definition.role, "role", issues);
+  requireEnum(definition.category, AGENT_CATEGORIES, "category", issues);
+  const persona = requireRecord(definition.persona, "persona", issues);
+  if (persona) {
+    requireString(persona.description, "persona.description", issues);
+    requireStringArray(persona.behavioral_rules, "persona.behavioral_rules", issues);
+    for (const key of ["personality", "voice", "visual_description"]) {
+      if (persona[key] !== void 0) requireString(persona[key], `persona.${key}`, issues);
+    }
+    if (persona.catchphrases !== void 0) {
+      requireStringArray(persona.catchphrases, "persona.catchphrases", issues);
+    }
+  }
+  const model = requireRecord(definition.model, "model", issues);
+  if (model) {
+    requireString(model.primary, "model.primary", issues);
+    requireStringArray(model.fallback, "model.fallback", issues);
+  }
+  const tools = requireRecord(definition.tools, "tools", issues);
+  if (tools) {
+    requireStringArray(tools.allowed, "tools.allowed", issues);
+    requireStringArray(tools.denied, "tools.denied", issues);
+  }
+  const autonomy = requireRecord(definition.autonomy, "autonomy", issues);
+  if (autonomy) {
+    requireEnum(
+      autonomy.default_power_level,
+      POWER_LEVELS,
+      "autonomy.default_power_level",
+      issues
+    );
+    requireBoolean(autonomy.exec_allowed, "autonomy.exec_allowed", issues);
+  }
+  const spawn = requireRecord(definition.spawn, "spawn", issues);
+  if (spawn) {
+    requireBoolean(spawn.can_spawn, "spawn.can_spawn", issues);
+    requireStringArray(spawn.spawnable_by, "spawn.spawnable_by", issues);
+  }
+  const clients = requireRecord(definition.clients, "clients", issues);
+  if (clients) {
+    validateOptionalClient(clients, "openclaw", "workspace_prefix", "string", issues);
+    validateOptionalClient(clients, "copilot", "agent_file", "boolean", issues);
+    validateOptionalClient(clients, "claude", "include_in_instructions", "boolean", issues);
+    validateOptionalClient(clients, "codex", "include_in_agents_md", "boolean", issues);
+  }
+  if (issues.length > 0) throw new AgentConfigValidationError(source, issues);
+  return definition;
+}
+function validateAgentRoster(value, source) {
+  const issues = [];
+  const parsed = requireRecord(value, "roster", issues);
+  if (!parsed) throw new AgentConfigValidationError(source, issues);
+  const version = parsed.schema_version;
+  if (!Number.isInteger(version)) {
+    throw new AgentConfigValidationError(source, [
+      'schema_version must be an integer; run "spell agents init" with a compatible Arcane CLI'
+    ]);
+  }
+  if (version > CURRENT_ROSTER_SCHEMA_VERSION) {
+    throw new AgentConfigValidationError(source, [
+      `schema_version ${version} is newer than supported version ${CURRENT_ROSTER_SCHEMA_VERSION}; upgrade Arcane before reading this roster`
+    ]);
+  }
+  if (version < 1) {
+    throw new AgentConfigValidationError(source, [
+      `schema_version ${version} is unsupported; supported versions are 1 and ${CURRENT_ROSTER_SCHEMA_VERSION}`
+    ]);
+  }
+  const roster = version === 1 ? { ...parsed, schema_version: CURRENT_ROSTER_SCHEMA_VERSION } : parsed;
+  requireEnum(roster.naming_strategy, NAMING_STRATEGIES, "naming_strategy", issues);
+  requireEnum(roster.agent_profile, AGENT_PROFILES, "agent_profile", issues);
+  const openclaw = requireRecord(roster.openclaw, "openclaw", issues);
+  if (openclaw) {
+    requireBoolean(openclaw.enabled, "openclaw.enabled", issues);
+    requireString(openclaw.workspace_root, "openclaw.workspace_root", issues);
+  }
+  if (!Array.isArray(roster.roster)) {
+    issues.push("roster must be an array");
+  } else {
+    roster.roster.forEach((entry, index) => {
+      const item = requireRecord(entry, `roster[${index}]`, issues);
+      if (!item) return;
+      requireString(item.definition, `roster[${index}].definition`, issues);
+      if (item.name !== null) requireString(item.name, `roster[${index}].name`, issues);
+      requireString(item.id, `roster[${index}].id`, issues);
+    });
+  }
+  if (issues.length > 0) throw new AgentConfigValidationError(source, issues);
+  return roster;
+}
+
+// src/modules/agent-loader.ts
 var AgentDefinitionNotFoundError = class extends Error {
   constructor(id, searchDir) {
     super(
@@ -818,6 +979,14 @@ var AgentRosterNotFoundError = class extends Error {
     this.name = "AgentRosterNotFoundError";
   }
 };
+function parseYaml(content, source) {
+  try {
+    return parse(content);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : "unknown YAML parse error";
+    throw new AgentConfigValidationError(source, [`malformed YAML: ${detail}`]);
+  }
+}
 async function loadAgentDefinition(agentsDir, id) {
   const filePath = join(agentsDir, `${id}.yaml`);
   let content;
@@ -826,7 +995,7 @@ async function loadAgentDefinition(agentsDir, id) {
   } catch {
     throw new AgentDefinitionNotFoundError(id, agentsDir);
   }
-  return parse(content);
+  return validateAgentDefinition(parseYaml(content, filePath), filePath);
 }
 async function loadRoster(targetDir) {
   const rosterPath = join(targetDir, ".arcane", "agents.yaml");
@@ -836,7 +1005,7 @@ async function loadRoster(targetDir) {
   } catch {
     throw new AgentRosterNotFoundError();
   }
-  return parse(content);
+  return validateAgentRoster(parseYaml(content, rosterPath), rosterPath);
 }
 async function rosterExists(targetDir) {
   try {
@@ -1332,9 +1501,10 @@ async function runAgentsSync(options, targetDir, assetsDir) {
   try {
     roster = await loadRoster(targetDir);
   } catch (err) {
-    if (err instanceof AgentRosterNotFoundError) {
+    if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
       console.error(err.message);
       process.exit(1);
+      return;
     }
     throw err;
   }
@@ -1373,9 +1543,10 @@ async function runAgentsList(targetDir) {
   try {
     roster = await loadRoster(targetDir);
   } catch (err) {
-    if (err instanceof AgentRosterNotFoundError) {
+    if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
       console.error(err.message);
       process.exit(1);
+      return;
     }
     throw err;
   }
@@ -1415,6 +1586,35 @@ async function runAgentsList(targetDir) {
 import { execFile } from "child_process";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
+async function inspectGitRepository(cwd) {
+  try {
+    const { stdout: stdout2 } = await execFileAsync(
+      "git",
+      ["rev-parse", "--is-inside-work-tree"],
+      { cwd }
+    );
+    if (stdout2.trim() !== "true") {
+      return { status: "not-repository" };
+    }
+  } catch {
+    return { status: "not-repository" };
+  }
+  try {
+    await execFileAsync("git", ["rev-parse", "--verify", "HEAD"], { cwd });
+  } catch {
+    return { status: "no-commits" };
+  }
+  const { stdout } = await execFileAsync(
+    "git",
+    ["status", "--porcelain", "-uall"],
+    { cwd }
+  );
+  const lines = stdout.trim();
+  return {
+    status: "ready",
+    uncommittedChanges: lines.length === 0 ? 0 : lines.split("\n").length
+  };
+}
 async function countUncommittedChanges(cwd) {
   try {
     const { stdout } = await execFileAsync("git", ["status", "--porcelain", "-uall"], { cwd });
@@ -1752,6 +1952,34 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     }
     throw err;
   }
+  console.warn(
+    `WARNING: Arcane v${packageVersion} update safety notice: commit your work before updating.`
+  );
+  console.warn(
+    "Updates can replace managed files. A clean committed baseline is required for recovery."
+  );
+  const gitState = await inspectGitRepository(targetDir);
+  if (gitState.status === "not-repository") {
+    console.error(
+      "Update refused: this directory is not a Git repository or Git is unavailable."
+    );
+    process.exit(1);
+    return;
+  }
+  if (gitState.status === "no-commits") {
+    console.error(
+      "Update refused: this repository has no commits. Commit the current baseline before updating."
+    );
+    process.exit(1);
+    return;
+  }
+  if (gitState.uncommittedChanges > 0) {
+    console.error(
+      `Update refused: this repository has ${gitState.uncommittedChanges} uncommitted change${gitState.uncommittedChanges === 1 ? "" : "s"}. Commit or otherwise clean the working tree before updating.`
+    );
+    process.exit(1);
+    return;
+  }
   if (manifest.version === packageVersion && manifest.components.length > 0) {
     console.log("Already up to date.");
     return;
@@ -1777,13 +2005,17 @@ async function runUpdate(options, targetDir, assetsDir, packageVersion) {
     const updatedFiles = [];
     for (const file of component.files) {
       const srcPath = join6(assetsDir, file);
-      if (options.dryRun) {
+      const preserveExisting = component.skipExisting && await fileExists(join6(targetDir, file));
+      if (preserveExisting) {
+        console.log(`  ${options.dryRun ? "[dry-run] Would preserve" : "Preserved"}: ${file}`);
+      } else if (options.dryRun) {
         console.log(`  [dry-run] Would update: ${file}`);
+        fileCount++;
       } else {
         await copyFile(srcPath, targetDir, file, { force: true });
+        fileCount++;
       }
       updatedFiles.push(file);
-      fileCount++;
     }
     for (const dir of component.directories ?? []) {
       const srcDirPath = join6(assetsDir, dir);
@@ -2040,6 +2272,73 @@ import { access as access3, readFile as readFile5, mkdir as mkdir5, copyFile as
 import { join as join9, dirname as dirname2 } from "path";
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
+
+// src/config/incidents.ts
+var INCIDENT_QUEUE = [
+  { id: "EF-05", severity: "medium", impact: "other", confidence: "confirmed", state: "open", detectedOn: "2026-07-31" },
+  { id: "EF-08", severity: "medium", impact: "other", confidence: "confirmed", state: "open", detectedOn: "2026-07-31" },
+  { id: "EF-16", severity: "high", impact: "other", confidence: "confirmed", state: "open", detectedOn: "2026-07-31" },
+  { id: "EF-17", severity: "high", impact: "other", confidence: "confirmed", state: "open", detectedOn: "2026-07-31" },
+  { id: "EF-20", severity: "high", impact: "other", confidence: "research", state: "open", detectedOn: "2026-07-31" },
+  { id: "EF-21", severity: "high", impact: "other", confidence: "confirmed", state: "open", detectedOn: "2026-07-31" },
+  { id: "EF-23", severity: "medium", impact: "other", confidence: "confirmed", state: "open", detectedOn: "2026-07-31" },
+  { id: "EF-25", severity: "high", impact: "data-integrity", confidence: "confirmed", state: "resolved", detectedOn: "2026-07-14", resolution: "PRs 13 and 14" },
+  { id: "EF-26", severity: "high", impact: "security", confidence: "confirmed", state: "resolved", detectedOn: "2026-07-31", resolution: "PR 15" },
+  { id: "EF-27", severity: "high", impact: "security", confidence: "confirmed", state: "resolved", detectedOn: "2026-07-31", resolution: "PR 16" },
+  { id: "EF-28", severity: "high", impact: "security", confidence: "confirmed", state: "resolved", detectedOn: "2026-07-31", resolution: "PR 17" },
+  { id: "EF-29", severity: "medium", impact: "other", confidence: "confirmed", state: "resolved", detectedOn: "2026-07-31", resolution: "PR 18" }
+];
+
+// src/modules/incident-gate.ts
+var DEFERRAL_PATTERN = /^Deferred \d{4}-\d{2}-\d{2} — known open, accepting the risk\.$/;
+var BLOCKING_SEVERITIES = /* @__PURE__ */ new Set(["critical", "high"]);
+var PROTECTED_IMPACTS = /* @__PURE__ */ new Set(["data-integrity", "security"]);
+function evaluateIncidentGate(records) {
+  const blockers = [];
+  const acceptedRisks = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const record of records) {
+    if (seen.has(record.id)) {
+      blockers.push(`${record.id}: duplicate incident record`);
+      continue;
+    }
+    seen.add(record.id);
+    if (record.confidence === "research") continue;
+    if (!PROTECTED_IMPACTS.has(record.impact)) continue;
+    if (!record.severity) {
+      blockers.push(`${record.id}: confirmed ${record.impact} incident is missing severity`);
+      continue;
+    }
+    if (!BLOCKING_SEVERITIES.has(record.severity)) continue;
+    if (record.state === "resolved") {
+      if (!record.resolution?.trim()) {
+        blockers.push(`${record.id}: resolved incident is missing resolution evidence`);
+      }
+      continue;
+    }
+    if (record.state === "deferred") {
+      if (!record.deferral || !DEFERRAL_PATTERN.test(record.deferral)) {
+        blockers.push(
+          `${record.id}: deferral must be exactly "Deferred <date> \u2014 known open, accepting the risk."`
+        );
+      } else {
+        acceptedRisks.push(`${record.id}: ${record.deferral}`);
+      }
+      continue;
+    }
+    blockers.push(
+      `${record.id}: unresolved ${record.severity} ${record.impact} incident blocks release`
+    );
+  }
+  return {
+    blocked: blockers.length > 0,
+    blockers,
+    acceptedRisks,
+    checked: records.length
+  };
+}
+
+// src/commands/doctor.ts
 var execFileAsync2 = promisify2(execFile2);
 async function checkNodeVersion() {
   const name = "Node.js version";
@@ -2096,6 +2395,28 @@ async function checkArcaneManifest(targetDir) {
   const manifestPath2 = join9(targetDir, ".arcane.json");
   try {
     await access3(manifestPath2);
+  } catch {
+    const selfHostedManifestPath = join9(targetDir, "src", "assets", ".arcane.json");
+    try {
+      const raw = await readFile5(selfHostedManifestPath, "utf8");
+      const manifest = JSON.parse(raw);
+      if (manifest.selfHosted === true && manifest.tracking_mode === "internal") {
+        return {
+          name,
+          passed: true,
+          message: "self-hosted source tree \u2014 committed source manifest is authoritative"
+        };
+      }
+    } catch {
+    }
+    return {
+      name,
+      passed: false,
+      message: "No .arcane.json found. Run `spell init` to initialize Arcane in this project.",
+      blocking: false
+    };
+  }
+  try {
     const raw = await readFile5(manifestPath2, "utf8");
     const manifest = JSON.parse(raw);
     if (!manifest.version || !Array.isArray(manifest.components)) {
@@ -2114,10 +2435,25 @@ async function checkArcaneManifest(targetDir) {
     return {
       name,
       passed: false,
-      message: "No .arcane.json found. Run `spell init` to initialize Arcane in this project.",
-      blocking: false
+      message: ".arcane.json is present but contains invalid JSON. Re-run `spell init`."
+    };
+  }
+}
+function checkIncidentReleaseGate() {
+  const result = evaluateIncidentGate(INCIDENT_QUEUE);
+  if (result.blocked) {
+    return {
+      name: "Incident release gate (ARC-024)",
+      passed: false,
+      message: result.blockers.join("; ")
     };
   }
+  const accepted = result.acceptedRisks.length > 0 ? `; ${result.acceptedRisks.length} explicitly deferred` : "";
+  return {
+    name: "Incident release gate (ARC-024)",
+    passed: true,
+    message: `${result.checked} incidents classified${accepted}`
+  };
 }
 var SESSION_CONTINUITY_FILES = [
   "TODO.md",
@@ -2164,7 +2500,8 @@ async function runDoctor(targetDir, options = {}, assetsDir) {
   const results = await Promise.all([
     checkNodeVersion(),
     checkVSCodeExtension("GitHub.copilot-chat", "GitHub Copilot (Chat)"),
-    checkArcaneManifest(targetDir)
+    checkArcaneManifest(targetDir),
+    Promise.resolve(checkIncidentReleaseGate())
   ]);
   const sessionResults = await checkSessionContinuity(targetDir);
   results.push(...sessionResults);