@agent-surface/cli 0.11.0 → 0.12.0

package/dist/chunk-Q5WOLWEW.js

@@ -0,0 +1,984 @@
+import {
+  UsageError,
+  createSurfaceRunner
+} from "./chunk-QIVOZAWX.js";
+
+// src/baseline.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join, resolve, sep } from "path";
+import { serializeSurfaceSnapshot } from "@agent-surface/testing";
+var DEFAULT_BASELINE_DIR = ".agent-surface";
+var SCENARIO_MANIFEST_FILE = "scenarios.json";
+function baselineDirFor(configPath, configured) {
+  return resolve(dirname(configPath), configured ?? DEFAULT_BASELINE_DIR);
+}
+function baselinePath(dir, scenario) {
+  const reserved = /* @__PURE__ */ new Set(["scenarios", "coverage-allow", "unresolved-allow"]);
+  if (scenario.length === 0 || scenario === "." || scenario === ".." || scenario.includes("/") || scenario.includes("\\") || scenario.includes("\0") || reserved.has(scenario)) {
+    throw new Error(`invalid scenario name ${JSON.stringify(scenario)} \u2014 use a filename-safe name`);
+  }
+  const root = resolve(dir);
+  const path = resolve(root, `${scenario}.json`);
+  if (!path.startsWith(`${root}${sep}`)) {
+    throw new Error(`scenario ${JSON.stringify(scenario)} escapes the baseline directory`);
+  }
+  return path;
+}
+function scenarioManifestPath(dir) {
+  return join(dir, SCENARIO_MANIFEST_FILE);
+}
+function normalize(snapshot) {
+  return serializeSurfaceSnapshot(snapshot);
+}
+function readBaseline(path) {
+  if (!existsSync(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `could not read baseline ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function writeBaseline(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function readScenarioManifest(dir) {
+  const path = scenarioManifestPath(dir);
+  const value = readBaseline(path);
+  if (value === void 0) return void 0;
+  if (typeof value !== "object" || value === null || !Array.isArray(value.scenarios) || !value.scenarios.every((name) => typeof name === "string")) {
+    throw new Error(`${path} must contain { "scenarios": string[] }`);
+  }
+  return [...value.scenarios].sort();
+}
+function writeScenarioManifest(dir, scenarios) {
+  writeBaseline(scenarioManifestPath(dir), { scenarios: [...scenarios].sort() });
+}
+var PATH_SEGMENT = /([^.[\]]+)|\[(\d+)\]/g;
+function subjectFor(document, path) {
+  let node = document;
+  let subject;
+  for (const match of path.matchAll(PATH_SEGMENT)) {
+    if (typeof node !== "object" || node === null) return subject;
+    const record = node;
+    const candidate = record["capabilityId"] ?? record["procedureId"];
+    if (typeof candidate === "string") subject = candidate;
+    const key = match[1] ?? match[2];
+    if (key === void 0) return subject;
+    node = record[key];
+  }
+  if (typeof node === "object" && node !== null) {
+    const record = node;
+    const candidate = record["capabilityId"] ?? record["procedureId"];
+    if (typeof candidate === "string") subject = candidate;
+  }
+  return subject;
+}
+function annotate(entries, after, before) {
+  return entries.map((entry) => {
+    const subject = subjectFor(after, entry.path) ?? subjectFor(before, entry.path);
+    return subject ? { ...entry, subject } : entry;
+  });
+}
+function diff(before, after, path = "") {
+  if (Object.is(before, after)) return [];
+  const bothArrays = Array.isArray(before) && Array.isArray(after);
+  const bothObjects = !bothArrays && typeof before === "object" && typeof after === "object" && before !== null && after !== null;
+  if (bothArrays) {
+    const entries = [];
+    const max = Math.max(before.length, after.length);
+    for (let i = 0; i < max; i++) {
+      const at = `${path}[${i}]`;
+      if (i >= before.length) entries.push({ path: at, kind: "added", after: after[i] });
+      else if (i >= after.length) entries.push({ path: at, kind: "removed", before: before[i] });
+      else entries.push(...diff(before[i], after[i], at));
+    }
+    return entries;
+  }
+  if (bothObjects) {
+    const entries = [];
+    const beforeRecord = before;
+    const afterRecord = after;
+    const keys = /* @__PURE__ */ new Set([...Object.keys(beforeRecord), ...Object.keys(afterRecord)]);
+    for (const key of [...keys].sort()) {
+      const at = path ? `${path}.${key}` : key;
+      if (!(key in beforeRecord)) {
+        entries.push({ path: at, kind: "added", after: afterRecord[key] });
+      } else if (!(key in afterRecord)) {
+        entries.push({ path: at, kind: "removed", before: beforeRecord[key] });
+      } else {
+        entries.push(...diff(beforeRecord[key], afterRecord[key], at));
+      }
+    }
+    return entries;
+  }
+  if (JSON.stringify(before) === JSON.stringify(after)) return [];
+  return [{ path: path || "<root>", kind: "changed", before, after }];
+}
+function formatValue(value) {
+  if (value === void 0) return "\u2014";
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  return text.length > 120 ? `${text.slice(0, 117)}\u2026` : text;
+}
+
+// src/coverage.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+var ALLOWLIST_FILE = "coverage-allow.json";
+var UNREAD_ALLOWLIST_FILE = "unresolved-allow.json";
+function allowlistPathFor(baselineDir) {
+  return join2(baselineDir, ALLOWLIST_FILE);
+}
+function unreadAllowlistPathFor(baselineDir) {
+  return join2(baselineDir, UNREAD_ALLOWLIST_FILE);
+}
+function readAllowlist(path, keyName = "capabilityId") {
+  if (!existsSync2(path)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
+  } catch (error) {
+    throw new Error(
+      `could not parse ${path}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path} must be a JSON object of { "${keyName}": "reason" }`);
+  }
+  const allowlist = {};
+  for (const [id, reason] of Object.entries(parsed)) {
+    if (typeof reason !== "string" || reason.trim() === "") {
+      throw new Error(`${path}: "${id}" needs a non-empty reason string`);
+    }
+    allowlist[id] = reason;
+  }
+  return allowlist;
+}
+function unreadKey(entry) {
+  return `${entry.origin.file}#${entry.reason ?? "unknown"}#${entry.origin.site}`;
+}
+function buildCoverageReport(input) {
+  const unreached = [];
+  const allowed = [];
+  for (const id of [...input.authored].sort()) {
+    if (input.reachedIds.has(id)) continue;
+    if (id in input.allowlist) {
+      allowed.push(id);
+      continue;
+    }
+    unreached.push({ capabilityId: id, origin: input.origins.get(id) ?? { file: "?", line: 0 } });
+  }
+  const staleAllowlist = Object.keys(input.allowlist).filter((id) => input.reachedIds.has(id) || !input.authored.has(id)).sort();
+  const unreadAllowlist = input.unreadAllowlist ?? {};
+  const unread = [];
+  const allowedUnread = /* @__PURE__ */ new Set();
+  for (const entry of input.unresolved) {
+    const key = unreadKey(entry);
+    if (key in unreadAllowlist) allowedUnread.add(key);
+    else unread.push(entry);
+  }
+  const stillUnread = new Set(input.unresolved.map(unreadKey));
+  const staleUnreadAllowlist = Object.keys(unreadAllowlist).filter((key) => !stillUnread.has(key)).sort();
+  const unaccounted = [...input.reachedIds].filter((id) => !input.authored.has(id)).sort();
+  const domainReached = [...input.reachedIds].filter((id) => id.startsWith("domain:")).sort();
+  const unmanifestedDomain = input.domainAuthoritative ? unaccounted.filter((id) => id.startsWith("domain:")) : [];
+  const undeclared = unaccounted.filter((id) => !id.startsWith("domain:"));
+  return {
+    authored: input.authored.size,
+    reached: [...input.authored].filter((id) => input.reachedIds.has(id)).length,
+    scenarios: input.scenarios,
+    ...input.scope ? { scope: input.scope } : {},
+    allowlistOutOfScope: input.allowlistOutOfScope ?? 0,
+    unreached,
+    undeclared,
+    domainReached,
+    unmanifestedDomain,
+    domainAuthoritative: input.domainAuthoritative === true,
+    unresolved: unread,
+    allowed,
+    staleAllowlist,
+    allowlistPath: input.allowlistPath,
+    allowedUnread: [...allowedUnread].sort(),
+    staleUnreadAllowlist,
+    unreadAllowlistPath: input.unreadAllowlistPath
+  };
+}
+function coverageExitCode(report, options = {}) {
+  if (report.unreached.length > 0) return 1;
+  if (report.unmanifestedDomain.length > 0) return 1;
+  if (report.unresolved.length > 0 && !options.allowUnresolved) return 1;
+  if (report.staleAllowlist.length > 0) return 1;
+  if (report.staleUnreadAllowlist.length > 0) return 1;
+  return 0;
+}
+
+// src/extract.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { dirname as dirname2, isAbsolute, join as join3, relative, resolve as resolve2 } from "path";
+import ts from "typescript";
+var UNRESOLVED_ID = "<unresolved>";
+function findTsconfig(from) {
+  return ts.findConfigFile(resolve2(from), ts.sys.fileExists, "tsconfig.json");
+}
+function readLiteralConfigScope(configPath) {
+  const source = ts.createSourceFile(
+    configPath,
+    readFileSync3(configPath, "utf8"),
+    ts.ScriptTarget.Latest,
+    true,
+    configPath.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+  let scope;
+  const visit = (node) => {
+    if (scope) return;
+    if (ts.isPropertyAssignment(node) && propertyName(node.name) === "scope" && ts.isArrayLiteralExpression(node.initializer)) {
+      const values = node.initializer.elements.map((entry) => literalText(entry));
+      if (values.every((value) => value !== void 0)) scope = values;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return scope;
+}
+function readProgramFiles(tsconfigPath) {
+  const read = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+  if (read.error) {
+    throw new Error(
+      `could not read ${tsconfigPath}: ${ts.flattenDiagnosticMessageText(read.error.messageText, " ")}`
+    );
+  }
+  const parsed = ts.parseJsonConfigFileContent(
+    read.config,
+    ts.sys,
+    dirname2(tsconfigPath)
+  );
+  if (parsed.errors.length > 0 && parsed.fileNames.length === 0) {
+    throw new Error(
+      `could not resolve any files from ${tsconfigPath}: ${parsed.errors.map((error) => ts.flattenDiagnosticMessageText(error.messageText, " ")).join("; ")}`
+    );
+  }
+  return { fileNames: parsed.fileNames, options: parsed.options };
+}
+var REGISTRATION_HOOKS = /* @__PURE__ */ new Set(["useAgentComponent", "useAgentAction", "useAgentObservation"]);
+function isRegistrationModule(specifier) {
+  return specifier.startsWith("@agent-surface/");
+}
+var NO_IMPORTS = { locals: /* @__PURE__ */ new Map(), namespaces: /* @__PURE__ */ new Set() };
+function importedRegistrations(source) {
+  const locals = /* @__PURE__ */ new Map();
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    if (!isRegistrationModule(statement.moduleSpecifier.text)) continue;
+    const clause = statement.importClause;
+    if (!clause || clause.isTypeOnly || !clause.namedBindings) continue;
+    if (ts.isNamespaceImport(clause.namedBindings)) {
+      namespaces.add(clause.namedBindings.name.text);
+      continue;
+    }
+    for (const element of clause.namedBindings.elements) {
+      if (element.isTypeOnly) continue;
+      const imported = (element.propertyName ?? element.name).text;
+      if (REGISTRATION_HOOKS.has(imported)) locals.set(element.name.text, imported);
+    }
+  }
+  return { locals, namespaces };
+}
+function renamedRegistrationExports(source, imports) {
+  const renamed = [];
+  for (const statement of source.statements) {
+    if (!ts.isExportDeclaration(statement) || statement.isTypeOnly) continue;
+    const clause = statement.exportClause;
+    if (!clause || !ts.isNamedExports(clause)) continue;
+    const from = statement.moduleSpecifier;
+    const fromOurs = from !== void 0 && ts.isStringLiteral(from) && isRegistrationModule(from.text);
+    if (from && !fromOurs) continue;
+    for (const element of clause.elements) {
+      if (element.isTypeOnly) continue;
+      const local = (element.propertyName ?? element.name).text;
+      const hook = fromOurs ? REGISTRATION_HOOKS.has(local) ? local : void 0 : imports.locals.get(local);
+      if (hook === void 0 || element.name.text === hook) continue;
+      renamed.push({ node: element, hook, exported: element.name.text });
+    }
+  }
+  return renamed;
+}
+function namespaceMember(object, member, imports) {
+  return ts.isIdentifier(object) && imports.namespaces.has(object.text) && REGISTRATION_HOOKS.has(member);
+}
+function calleeName(call, imports = NO_IMPORTS) {
+  const callee = call.expression;
+  if (ts.isIdentifier(callee)) return imports.locals.get(callee.text) ?? callee.text;
+  if (ts.isPropertyAccessExpression(callee)) {
+    if (namespaceMember(callee.expression, callee.name.text, imports)) return callee.name.text;
+    return callee.name.text;
+  }
+  if (ts.isElementAccessExpression(callee)) {
+    const member = literalText(callee.argumentExpression);
+    if (member !== void 0 && namespaceMember(callee.expression, member, imports)) return member;
+  }
+  return void 0;
+}
+function propertyName(name) {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return void 0;
+}
+function propertyOf(object, wanted) {
+  for (const property of object.properties) {
+    if (ts.isPropertyAssignment(property) && propertyName(property.name) === wanted) {
+      return property.initializer;
+    }
+    if (ts.isShorthandPropertyAssignment(property) && property.name.text === wanted) {
+      return property.name;
+    }
+  }
+  return void 0;
+}
+function hasSpread(object) {
+  return object.properties.some((property) => ts.isSpreadAssignment(property));
+}
+var CAPABILITY_GROUPS = ["observations", "actions"];
+function spreadKeys(expression, source, depth = 0) {
+  if (depth > 1) return void 0;
+  if (ts.isParenthesizedExpression(expression)) {
+    return spreadKeys(expression.expression, source, depth);
+  }
+  if (ts.isConditionalExpression(expression)) {
+    const whenTrue = spreadKeys(expression.whenTrue, source, depth);
+    const whenFalse = spreadKeys(expression.whenFalse, source, depth);
+    if (!whenTrue || !whenFalse) return void 0;
+    return [...whenTrue, ...whenFalse];
+  }
+  const resolved = objectLiteralFor(expression, source);
+  if (!resolved.object) return void 0;
+  const keys = [];
+  for (const property of resolved.object.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      const nested = spreadKeys(property.expression, source, depth + 1);
+      if (!nested) return void 0;
+      keys.push(...nested);
+      continue;
+    }
+    const name = ts.isPropertyAssignment(property) || ts.isMethodDeclaration(property) ? propertyName(property.name) : ts.isShorthandPropertyAssignment(property) ? property.name.text : void 0;
+    if (name === void 0) return void 0;
+    keys.push(name);
+  }
+  return keys;
+}
+function literalText(node) {
+  if (!node) return void 0;
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  if (ts.isParenthesizedExpression(node)) return literalText(node.expression);
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const left = literalText(node.left);
+    const right = literalText(node.right);
+    if (left !== void 0 && right !== void 0) return left + right;
+  }
+  return void 0;
+}
+function describeConstruct(node) {
+  if (ts.isCallExpression(node)) {
+    const callee = calleeName(node);
+    return callee ? `built by ${callee}()` : "built by a call expression";
+  }
+  if (ts.isIdentifier(node)) return `a variable (${node.text}) this extractor could not follow`;
+  if (ts.isConditionalExpression(node)) return "a conditional expression";
+  if (ts.isTemplateExpression(node)) return "a template with substitutions";
+  if (ts.isPropertyAccessExpression(node)) return "a property access";
+  return "a non-literal expression";
+}
+function objectLiteralFor(expression, source) {
+  if (ts.isObjectLiteralExpression(expression)) return { object: expression };
+  if (ts.isIdentifier(expression)) {
+    const target = expression.text;
+    let found;
+    const visit = (node) => {
+      if (found) return;
+      if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === target && node.initializer && ts.isObjectLiteralExpression(node.initializer)) {
+        found = node.initializer;
+        return;
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (found) return { object: found };
+    return {
+      note: `the config is \`${target}\`, which is not a same-module object literal \u2014 the extractor follows one hop only`
+    };
+  }
+  return { note: `the config is ${describeConstruct(expression)}` };
+}
+var GRANULAR_HOOKS = /* @__PURE__ */ new Set(["useAgentAction", "useAgentObservation"]);
+function capabilitiesFromGroup(group, kind, componentType, componentPartial, emit, source) {
+  if (!group) return;
+  const resolved = objectLiteralFor(group, source);
+  if (!resolved.object) {
+    emit.push({
+      capabilityId: `view:${componentType}.${UNRESOLVED_ID}`,
+      kind,
+      origin: emit.origin(group),
+      resolution: "unresolved",
+      reason: "dynamic-group",
+      note: `\`${kind}s\` on "${componentType}" is not an object literal: ${resolved.note}`
+    });
+    return;
+  }
+  for (const property of resolved.object.properties) {
+    if (ts.isSpreadAssignment(property)) {
+      emit.push({
+        capabilityId: `view:${componentType}.${UNRESOLVED_ID}`,
+        kind,
+        origin: emit.origin(property),
+        resolution: "unresolved",
+        reason: "spread-members",
+        note: `\`${kind}s\` on "${componentType}" spreads another object, which may contribute capabilities this inventory cannot name`
+      });
+      continue;
+    }
+    const name = ts.isPropertyAssignment(property) || ts.isMethodDeclaration(property) ? propertyName(property.name) : ts.isShorthandPropertyAssignment(property) ? property.name.text : void 0;
+    if (name === void 0) {
+      emit.push({
+        capabilityId: `view:${componentType}.${UNRESOLVED_ID}`,
+        kind,
+        origin: emit.origin(property),
+        resolution: "unresolved",
+        reason: "computed-name",
+        note: `a capability on "${componentType}" has a computed name`
+      });
+      continue;
+    }
+    const capability = {
+      capabilityId: `view:${componentType}.${name}`,
+      kind,
+      origin: emit.origin(property),
+      resolution: "static"
+    };
+    const notes = [];
+    if (componentPartial) notes.push(componentPartial);
+    const value = ts.isPropertyAssignment(property) ? property.initializer : void 0;
+    const definition = value && ts.isCallExpression(value) && value.arguments.length > 0 ? value.arguments[0] : value;
+    if (definition && ts.isObjectLiteralExpression(definition)) {
+      const description = literalText(propertyOf(definition, "description"));
+      if (description !== void 0) capability.description = description;
+      else notes.push("description is not a string literal");
+      if (kind === "action") {
+        const effect = literalText(propertyOf(definition, "effect"));
+        if (effect !== void 0) capability.effect = effect;
+        else notes.push("effect is not a string literal");
+      }
+      if (hasSpread(definition)) notes.push("the definition spreads another object");
+    } else {
+      notes.push(
+        value ? `the definition is ${describeConstruct(value)}` : "the definition is not an object literal"
+      );
+    }
+    if (notes.length > 0) {
+      capability.resolution = "partial";
+      capability.note = notes.join("; ");
+    }
+    emit.push(capability);
+  }
+}
+function visitCall(call, emit, source, imports, deferred, enclosing) {
+  const callee = calleeName(call, imports);
+  if (callee === void 0) {
+    const object = ts.isElementAccessExpression(call.expression) ? call.expression.expression : void 0;
+    if (object && ts.isIdentifier(object) && imports.namespaces.has(object.text)) {
+      emit.push({
+        capabilityId: UNRESOLVED_ID,
+        kind: "action",
+        origin: emit.origin(call),
+        resolution: "unresolved",
+        reason: "dynamic-callee",
+        note: `a call reads a computed member of \`${object.text}\`, a namespace of this library \u2014 which export it calls, and so whether it registers anything, cannot be read here`
+      });
+    }
+    return;
+  }
+  if (GRANULAR_HOOKS.has(callee)) {
+    emit.push({
+      capabilityId: UNRESOLVED_ID,
+      kind: callee === "useAgentAction" ? "action" : "observation",
+      origin: emit.origin(call),
+      resolution: "unresolved",
+      reason: "granular-hook",
+      note: `${callee}() registers against a render-scope link, so its component type is not at this call site`
+    });
+    return;
+  }
+  if (callee !== "useAgentComponent" && callee !== "register") return;
+  const argument = call.arguments[0];
+  if (!argument) return;
+  const resolved = objectLiteralFor(argument, source);
+  if (!resolved.object) {
+    emit.push({
+      capabilityId: UNRESOLVED_ID,
+      kind: "action",
+      origin: emit.origin(call),
+      resolution: "unresolved",
+      reason: "dynamic-config",
+      note: `${callee}() call site could not be read: ${resolved.note}`
+    });
+    return;
+  }
+  const config = resolved.object;
+  const typeNode = propertyOf(config, "type");
+  const type = literalText(typeNode);
+  if (type === void 0) {
+    if (callee === "register" && typeNode === void 0) return;
+    const slot = enclosing && typeNode && ts.isIdentifier(typeNode) ? parameterSlot(typeNode.text, enclosing.fn) : void 0;
+    if (slot && enclosing?.name) {
+      deferred.push({ config, source, emit, wrapperName: enclosing.name, slot, site: call });
+      return;
+    }
+    emit.push({
+      capabilityId: UNRESOLVED_ID,
+      kind: "action",
+      origin: emit.origin(call),
+      resolution: "unresolved",
+      reason: "dynamic-type",
+      note: `\`type\` is not a string literal, so no capability id on this component can be determined`
+    });
+    return;
+  }
+  const componentPartial = hasSpread(config) ? "the component config spreads another object, so some metadata here may be dynamic" : void 0;
+  for (const property of config.properties) {
+    if (!ts.isSpreadAssignment(property)) continue;
+    const keys = spreadKeys(property.expression, source);
+    if (keys && !keys.some((key) => CAPABILITY_GROUPS.includes(key))) {
+      continue;
+    }
+    emit.push({
+      capabilityId: `view:${type}.${UNRESOLVED_ID}`,
+      kind: "action",
+      origin: emit.origin(property),
+      resolution: "unresolved",
+      reason: "spread-members",
+      note: keys ? `"${type}" spreads ${describeConstruct(property.expression)}, which contributes \`${keys.filter((key) => CAPABILITY_GROUPS.includes(key)).join("`/`")}\` this inventory cannot name` : `"${type}" spreads ${describeConstruct(property.expression)}, whose keys this inventory cannot read \u2014 it may contribute capabilities not listed here`
+    });
+  }
+  capabilitiesFromGroup(
+    propertyOf(config, "observations"),
+    "observation",
+    type,
+    componentPartial,
+    emit,
+    source
+  );
+  capabilitiesFromGroup(
+    propertyOf(config, "actions"),
+    "action",
+    type,
+    componentPartial,
+    emit,
+    source
+  );
+}
+function functionLike(node) {
+  if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node)) {
+    return node;
+  }
+  return void 0;
+}
+function parameterSlot(name, fn) {
+  for (const [index, parameter] of fn.parameters.entries()) {
+    if (ts.isIdentifier(parameter.name)) {
+      if (parameter.name.text === name) return { index };
+      continue;
+    }
+    if (ts.isObjectBindingPattern(parameter.name)) {
+      for (const element of parameter.name.elements) {
+        if (!ts.isIdentifier(element.name) || element.name.text !== name) continue;
+        const property = element.propertyName && ts.isIdentifier(element.propertyName) ? element.propertyName.text : name;
+        return { index, property };
+      }
+    }
+  }
+  return void 0;
+}
+function callsWrapper(site, wrapper, compilerOptions) {
+  const callee = site.call.expression;
+  if (!ts.isIdentifier(callee) || callee.text !== wrapper.wrapperName) return false;
+  if (site.source.fileName === wrapper.source.fileName) {
+    return true;
+  }
+  for (const statement of site.source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const clause = statement.importClause;
+    if (!clause) continue;
+    const named = clause.name?.text === wrapper.wrapperName || clause.namedBindings && ts.isNamedImports(clause.namedBindings) && clause.namedBindings.elements.some((element) => element.name.text === wrapper.wrapperName);
+    if (!named) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const resolved = ts.resolveModuleName(
+      statement.moduleSpecifier.text,
+      site.source.fileName,
+      compilerOptions,
+      ts.sys
+    ).resolvedModule;
+    if (resolved?.resolvedFileName === wrapper.source.fileName) return true;
+  }
+  return false;
+}
+function normalizedText(node, source) {
+  return node.getText(source).replace(/\s+/g, " ").trim();
+}
+function siteIdentity(source, node) {
+  const labels = [];
+  let enclosingCall = "";
+  let scope;
+  for (let parent = node.parent; parent && parent !== source; parent = parent.parent) {
+    if (!enclosingCall && ts.isCallExpression(parent)) {
+      enclosingCall = normalizedText(parent, source);
+    }
+    const named = (ts.isFunctionDeclaration(parent) || ts.isMethodDeclaration(parent)) && parent.name && (ts.isIdentifier(parent.name) || ts.isStringLiteral(parent.name)) ? parent.name.text : ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name) ? parent.name.text : void 0;
+    if (named !== void 0) {
+      labels.push(named);
+      scope ??= parent;
+    }
+  }
+  return { labels: labels.reverse(), enclosingCall, scope: scope ?? source };
+}
+function occurrence(scope, node, source) {
+  const text = normalizedText(node, source);
+  const start = node.getStart(source);
+  let rank = 0;
+  const visit = (candidate) => {
+    if (candidate.kind === node.kind && candidate.getStart(source) < start && normalizedText(candidate, source) === text) {
+      rank += 1;
+    }
+    ts.forEachChild(candidate, visit);
+  };
+  ts.forEachChild(scope, visit);
+  return rank;
+}
+function stableSite(source, node) {
+  const { labels, enclosingCall, scope } = siteIdentity(source, node);
+  return createHash("sha256").update(
+    `${labels.join("/")}\0${enclosingCall}\0${normalizedText(node, source)}\0${occurrence(
+      scope,
+      node,
+      source
+    )}`
+  ).digest("hex").slice(0, 12);
+}
+var packageNameCache = /* @__PURE__ */ new Map();
+function packageNameFor(file) {
+  let dir = dirname2(file);
+  for (; ; ) {
+    if (packageNameCache.has(dir)) return packageNameCache.get(dir);
+    const packagePath = join3(dir, "package.json");
+    if (existsSync3(packagePath)) {
+      let name;
+      try {
+        const parsed = JSON.parse(readFileSync3(packagePath, "utf8"));
+        if (typeof parsed.name === "string") name = parsed.name;
+      } catch {
+      }
+      packageNameCache.set(dir, name);
+      return name;
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+var IMPLEMENTATION_PACKAGES = /* @__PURE__ */ new Set([
+  "@agent-surface/core",
+  "@agent-surface/react",
+  "@agent-surface/orpc",
+  "@agent-surface/testing",
+  "@agent-surface/webmcp",
+  "@agent-surface/cli"
+]);
+function isAgentSurfaceImplementation(file) {
+  return IMPLEMENTATION_PACKAGES.has(packageNameFor(file) ?? "");
+}
+function extractCapabilities(options) {
+  const root = resolve2(options.root);
+  const tsconfigPath = options.tsconfig ? isAbsolute(options.tsconfig) ? options.tsconfig : join3(root, options.tsconfig) : findTsconfig(root);
+  if (!tsconfigPath || !existsSync3(tsconfigPath)) {
+    throw new Error(
+      `no tsconfig.json found from ${root} \u2014 \`capabilities\` reads the TypeScript program, so it needs one (pass --tsconfig to point at it)`
+    );
+  }
+  const { fileNames, options: compilerOptions } = readProgramFiles(tsconfigPath);
+  const program = ts.createProgram(fileNames, compilerOptions);
+  const capabilities = [];
+  let filesAnalyzed = 0;
+  let filesOutsideRoot = 0;
+  const deferred = [];
+  const callsByName = /* @__PURE__ */ new Map();
+  for (const source of program.getSourceFiles()) {
+    if (source.isDeclarationFile) continue;
+    if (source.fileName.includes("/node_modules/")) continue;
+    if (!isInside(root, source.fileName) && isAgentSurfaceImplementation(source.fileName)) {
+      filesOutsideRoot += 1;
+      continue;
+    }
+    filesAnalyzed += 1;
+    const emit = {
+      push: (capability) => capabilities.push(capability),
+      origin: (node) => ({
+        file: relative(root, source.fileName),
+        line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+        site: stableSite(source, node)
+      })
+    };
+    const imports = importedRegistrations(source);
+    for (const renamed of renamedRegistrationExports(source, imports)) {
+      emit.push({
+        capabilityId: UNRESOLVED_ID,
+        kind: "action",
+        origin: emit.origin(renamed.node),
+        resolution: "unresolved",
+        reason: "dynamic-callee",
+        note: `${renamed.hook}() leaves this module as \`${renamed.exported}\`, so nothing at its call sites elsewhere proves they register anything \u2014 whatever they author is not in this catalog`
+      });
+    }
+    let pendingName;
+    const visit = (node, enclosing) => {
+      const fn = functionLike(node);
+      if (fn) {
+        const named = ts.isFunctionDeclaration(node) && node.name ? node.name.text : pendingName;
+        enclosing = { fn, ...named ? { name: named } : {} };
+        pendingName = void 0;
+      } else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+        pendingName = node.name.text;
+      }
+      if (ts.isCallExpression(node)) {
+        visitCall(node, emit, source, imports, deferred, enclosing);
+        if (ts.isIdentifier(node.expression)) {
+          const name = node.expression.text;
+          const sites = callsByName.get(name) ?? [];
+          sites.push({ call: node, source });
+          callsByName.set(name, sites);
+        }
+      }
+      ts.forEachChild(node, (child) => visit(child, enclosing));
+    };
+    visit(source);
+  }
+  for (const wrapper of deferred) {
+    const sites = (callsByName.get(wrapper.wrapperName) ?? []).filter(
+      (site) => callsWrapper(site, wrapper, compilerOptions)
+    );
+    const types = /* @__PURE__ */ new Map();
+    const dynamic = [];
+    for (const site of sites) {
+      const argument = site.call.arguments[wrapper.slot.index];
+      const value = wrapper.slot.property && argument && ts.isObjectLiteralExpression(argument) ? propertyOf(argument, wrapper.slot.property) : argument;
+      const text = value ? literalText(value) : void 0;
+      if (text !== void 0) types.set(text, site.call);
+      else dynamic.push(site);
+    }
+    for (const type of [...types.keys()].sort()) {
+      const componentPartial = hasSpread(wrapper.config) ? "the component config spreads another object, so some metadata here may be dynamic" : void 0;
+      for (const [group, kind] of [
+        ["observations", "observation"],
+        ["actions", "action"]
+      ]) {
+        capabilitiesFromGroup(
+          propertyOf(wrapper.config, group),
+          kind,
+          type,
+          componentPartial,
+          wrapper.emit,
+          wrapper.source
+        );
+      }
+    }
+    if (types.size === 0 || dynamic.length > 0) {
+      wrapper.emit.push({
+        capabilityId: UNRESOLVED_ID,
+        kind: "action",
+        origin: wrapper.emit.origin(wrapper.site),
+        resolution: "unresolved",
+        reason: "dynamic-type",
+        note: types.size === 0 ? `\`type\` is a parameter of ${wrapper.wrapperName}(), and no call site of it in this program passes a string literal` : `\`type\` is a parameter of ${wrapper.wrapperName}(); ${types.size} call site${types.size === 1 ? "" : "s"} resolved, ${dynamic.length} pass${dynamic.length === 1 ? "es" : ""} a non-literal`
+      });
+    }
+  }
+  capabilities.sort(
+    (a, b) => a.capabilityId.localeCompare(b.capabilityId) || a.origin.file.localeCompare(b.origin.file) || a.origin.line - b.origin.line
+  );
+  return {
+    capabilities,
+    tsconfig: tsconfigPath,
+    root,
+    filesAnalyzed,
+    filesOutsideRoot,
+    domain: "not-analyzed"
+  };
+}
+function isInside(root, file) {
+  const rel = relative(root, file);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function authoredIds(inventory) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const capability of inventory.capabilities) {
+    if (capability.resolution === "unresolved") continue;
+    if (capability.capabilityId.endsWith(UNRESOLVED_ID)) continue;
+    ids.add(capability.capabilityId);
+  }
+  return ids;
+}
+function unresolved(inventory) {
+  return inventory.capabilities.filter((capability) => capability.resolution === "unresolved");
+}
+
+// src/analysis.ts
+import { dirname as dirname3 } from "path";
+import { matchesScope } from "@agent-surface/core/explain";
+function readInventory(options) {
+  if (options.depth === "runtime") return void 0;
+  return extractCapabilities({
+    root: dirname3(options.configPath),
+    ...options.tsconfig ? { tsconfig: options.tsconfig } : {}
+  });
+}
+function staticConfigScope(options) {
+  return options.scope ?? readLiteralConfigScope(options.configPath);
+}
+async function mountScenarios(options, onEach) {
+  if (options.depth === "static") return void 0;
+  const runner = await createSurfaceRunner(options.configPath);
+  try {
+    if (options.scenario && !runner.scenarioNames.includes(options.scenario)) {
+      throw new UsageError(
+        `unknown scenario "${options.scenario}" \u2014 this config defines ` + runner.scenarioNames.map((name) => `"${name}"`).join(", ")
+      );
+    }
+    const scenarios = options.scenario ? [options.scenario] : runner.scenarioNames;
+    const effectiveScope = options.scope ?? runner.config.scope;
+    const results = [];
+    const failures = [];
+    for (const scenario of scenarios) {
+      let result;
+      try {
+        result = await runner.collect({
+          scenario,
+          ...options.scope ? { scope: options.scope } : {}
+        });
+      } catch (error) {
+        failures.push({
+          scenario,
+          message: error instanceof Error ? error.message : String(error)
+        });
+        continue;
+      }
+      results.push(result);
+      await onEach?.(result);
+    }
+    return {
+      scenarios,
+      declaredScenarios: runner.scenarioNames,
+      results,
+      failures,
+      baselineDir: baselineDirFor(
+        options.configPath,
+        options.baselineDir ?? runner.config.baselineDir
+      ),
+      ...effectiveScope ? { scope: effectiveScope } : {},
+      domainCapabilities: Object.keys(runner.config.manifest?.tools ?? {}).map((path) => `domain:${path}`).sort(),
+      domainManifestConfigured: runner.config.manifest !== void 0
+    };
+  } finally {
+    await runner.close();
+  }
+}
+function componentTypeOf(capabilityId) {
+  const withoutPlane = capabilityId.replace(/^(view|domain):/, "");
+  const dot = withoutPlane.lastIndexOf(".");
+  return dot === -1 ? withoutPlane : withoutPlane.slice(0, dot);
+}
+function scopeInventory(inventory, scope) {
+  if (!inventory || !scope) return inventory;
+  return {
+    ...inventory,
+    capabilities: inventory.capabilities.filter(
+      (capability) => capability.resolution === "unresolved" || matchesScope(componentTypeOf(capability.capabilityId), scope)
+    )
+  };
+}
+function scopeCapabilityIds(ids, scope) {
+  return scope ? ids.filter((id) => matchesScope(componentTypeOf(id), scope)) : ids;
+}
+function joinCoverage(inventory, runtime, options) {
+  if (!inventory || !runtime) return void 0;
+  if (runtime.failures.length > 0) return void 0;
+  const effectiveScope = options.scope ?? runtime.scope;
+  const inScope = (capabilityId) => matchesScope(componentTypeOf(capabilityId), effectiveScope);
+  const origins = /* @__PURE__ */ new Map();
+  for (const capability of inventory.capabilities) {
+    if (!origins.has(capability.capabilityId)) {
+      origins.set(capability.capabilityId, capability.origin);
+    }
+  }
+  const authored = new Set([...authoredIds(inventory)].filter(inScope));
+  for (const capabilityId of runtime.domainCapabilities) {
+    if (inScope(capabilityId)) authored.add(capabilityId);
+    if (!origins.has(capabilityId)) {
+      origins.set(capabilityId, { file: "oRPC manifest", line: 0 });
+    }
+  }
+  const reachedIds = /* @__PURE__ */ new Set();
+  for (const result of runtime.results) {
+    for (const capability of result.explanation.capabilities) {
+      reachedIds.add(capability.capabilityId);
+    }
+  }
+  const allowlistPath = allowlistPathFor(runtime.baselineDir);
+  const wholeAllowlist = readAllowlist(allowlistPath);
+  const allowlist = Object.fromEntries(
+    Object.entries(wholeAllowlist).filter(([id]) => inScope(id))
+  );
+  const unreadAllowlistPath = unreadAllowlistPathFor(runtime.baselineDir);
+  return buildCoverageReport({
+    unreadAllowlist: readAllowlist(unreadAllowlistPath, "file#reason#site"),
+    unreadAllowlistPath,
+    domainAuthoritative: runtime.domainManifestConfigured,
+    authored,
+    origins,
+    reachedIds,
+    scenarios: runtime.scenarios,
+    ...effectiveScope ? { scope: effectiveScope } : {},
+    unresolved: unresolved(inventory),
+    allowlist,
+    allowlistOutOfScope: Object.keys(wholeAllowlist).length - Object.keys(allowlist).length,
+    allowlistPath
+  });
+}
+
+export {
+  SCENARIO_MANIFEST_FILE,
+  baselinePath,
+  normalize,
+  readBaseline,
+  writeBaseline,
+  readScenarioManifest,
+  writeScenarioManifest,
+  annotate,
+  diff,
+  formatValue,
+  ALLOWLIST_FILE,
+  UNREAD_ALLOWLIST_FILE,
+  unreadKey,
+  coverageExitCode,
+  findTsconfig,
+  extractCapabilities,
+  authoredIds,
+  unresolved,
+  readInventory,
+  staticConfigScope,
+  mountScenarios,
+  scopeInventory,
+  scopeCapabilityIds,
+  joinCoverage
+};
+//# sourceMappingURL=chunk-Q5WOLWEW.js.map