@yansirplus/cli 0.5.17 → 0.5.19

package/dist/generate/project-docs-site.mjs

@@ -1,190 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-const root = process.cwd();
-const check = process.argv.includes("--check");
-const watch = process.argv.includes("--watch");
-const docsRoot = path.join(root, "docs");
-const targetRoot = path.join(root, "tooling/docs-site/src/content/docs");
-const failures = [];
-
-const generatedNotice = (source) =>
-  `<!-- generated by packages/cli/src/generate/project-docs-site.mjs; edit ${source} -->`;
-
-const walk = (dir) => {
-  if (!fs.existsSync(dir)) return [];
-  const out = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      out.push(...walk(full));
-      continue;
-    }
-    if (entry.isFile()) out.push(full);
-  }
-  return out;
-};
-
-const slash = (value) => value.replaceAll(path.sep, "/");
-const relRoot = (file) => slash(path.relative(root, file));
-const escapeYaml = (value) => value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
-
-const isProjectedSource = (file) => {
-  const rel = slash(path.relative(docsRoot, file));
-  if (!file.endsWith(".md")) return false;
-  if (rel.startsWith("templates/")) return false;
-  return true;
-};
-
-const siteRouteForDocsRel = (docsRel, anchor = "") => {
-  const normalized = slash(docsRel).replace(/\.md$/u, "");
-  if (normalized === "README") return `/${anchor}`;
-  return `/${normalized}/${anchor}`;
-};
-
-const targetRelForDocsRel = (docsRel) => {
-  if (docsRel === "README.md") return "index.md";
-  return docsRel;
-};
-
-const parseTargetHref = (href, sourceDocsRel) => {
-  if (!href.endsWith(".md") && !href.includes(".md#")) return null;
-  const [rawPath, rawAnchor] = href.split("#");
-  if (!rawPath.endsWith(".md")) return null;
-  const sourceDir = path.posix.dirname(sourceDocsRel);
-  const targetDocsRel = slash(path.posix.normalize(path.posix.join(sourceDir, rawPath)));
-  const anchor = rawAnchor === undefined ? "" : `#${rawAnchor}`;
-  return siteRouteForDocsRel(targetDocsRel, anchor);
-};
-
-const rewriteLinksForSite = (text, sourceDocsRel) =>
-  text.replace(/\[([^\]\n]+)\]\(([^)\s]+)(\s+"[^"]*")?\)/gu, (full, label, href, title = "") => {
-    const rewritten = parseTargetHref(href, sourceDocsRel);
-    return rewritten === null ? full : `[${label}](${rewritten}${title})`;
-  });
-
-const projectMarkdown = (sourceFile, options = {}) => {
-  const docsRel = slash(path.relative(docsRoot, sourceFile));
-  const sourceRel = relRoot(sourceFile);
-  const source = fs.readFileSync(sourceFile, "utf8").replace(/\s+$/u, "");
-  const h1 = source.match(/^# (.+)$/mu);
-  const title = h1?.[1] ?? sourceRel;
-  const withoutH1 =
-    h1 === null ? source : source.replace(/^# .+\r?\n\r?\n?/u, "").replace(/\s+$/u, "");
-  const bodyPrefix = options.bodyPrefix ?? "";
-  const body = `${bodyPrefix}${rewriteLinksForSite(withoutH1, docsRel)}`;
-  return [
-    "---",
-    `title: "${escapeYaml(title)}"`,
-    "---",
-    "",
-    generatedNotice(sourceRel),
-    "",
-    body,
-    "",
-  ].join("\n");
-};
-
-const formatProjectedMarkdown = (expected) => {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-docs-site-"));
-  try {
-    for (const [targetRel, content] of expected) {
-      const target = path.join(tmpDir, targetRel);
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, `${content.replace(/\s+$/u, "")}\n`);
-    }
-    const result = spawnSync("vp", ["fmt", tmpDir, "--write"], {
-      cwd: root,
-      encoding: "utf8",
-    });
-    if (result.status !== 0) {
-      failures.push(
-        `docs-site projection formatting failed: ${result.stderr || result.stdout || result.status}`,
-      );
-      return expected;
-    }
-    const formatted = new Map();
-    for (const targetRel of expected.keys()) {
-      formatted.set(targetRel, fs.readFileSync(path.join(tmpDir, targetRel), "utf8"));
-    }
-    return formatted;
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-};
-
-const removeEmptyDirs = (dir) => {
-  if (!fs.existsSync(dir)) return;
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isDirectory()) removeEmptyDirs(path.join(dir, entry.name));
-  }
-  if (dir !== targetRoot && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
-};
-
-const project = () => {
-  failures.length = 0;
-  const sources = walk(docsRoot).filter(isProjectedSource).sort();
-  const expected = new Map();
-
-  for (const source of sources) {
-    const docsRel = slash(path.relative(docsRoot, source));
-    const targetRel = targetRelForDocsRel(docsRel);
-    expected.set(targetRel, projectMarkdown(source));
-  }
-  const formattedExpected = formatProjectedMarkdown(expected);
-
-  for (const [targetRel, content] of formattedExpected) {
-    const target = path.join(targetRoot, targetRel);
-    const expectedText = `${content.replace(/\s+$/u, "")}\n`;
-    if (check) {
-      const actual = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
-      if (actual !== expectedText) failures.push(`${slash(path.relative(root, target))} is stale`);
-      continue;
-    }
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, expectedText);
-  }
-
-  const actualTargets = walk(targetRoot)
-    .filter((file) => file.endsWith(".md"))
-    .map((file) => slash(path.relative(targetRoot, file)))
-    .sort();
-  for (const targetRel of actualTargets) {
-    if (!formattedExpected.has(targetRel)) {
-      const target = path.join(targetRoot, targetRel);
-      if (check) {
-        failures.push(`${slash(path.relative(root, target))} is stale extra projection`);
-      } else {
-        fs.rmSync(target);
-      }
-    }
-  }
-  if (!check) removeEmptyDirs(targetRoot);
-
-  if (failures.length > 0) {
-    console.error(failures.join("\n"));
-    process.exitCode = 1;
-    return false;
-  }
-
-  console.log(`projected docs site content for ${expected.size} pages`);
-  return true;
-};
-
-project();
-
-if (watch) {
-  console.log("watching docs/** for docs-site projection changes");
-  let timer = null;
-  const schedule = () => {
-    if (timer !== null) clearTimeout(timer);
-    timer = setTimeout(() => {
-      timer = null;
-      project();
-    }, 100);
-  };
-  fs.watch(docsRoot, { recursive: true }, schedule);
-}

package/dist/lib/boundary-rules.mjs

@@ -1,63 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-
-export const readBoundaryRulesSource = (root, failures = []) => {
-  const file = "docs/agent/boundary-rules.source.json";
-  try {
-    const value = JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
-    if (!isRecord(value)) {
-      failures.push(`${file}: boundary rules source must be an object`);
-      return null;
-    }
-    return value;
-  } catch (cause) {
-    const reason = cause instanceof Error ? cause.message : String(cause);
-    failures.push(`${file}: unable to read boundary rules source: ${reason}`);
-    return null;
-  }
-};
-
-export const commandGroupContainsRule = (source, groupId, ruleId, seen = new Set()) => {
-  if (!isRecord(source.commandGroups) || seen.has(groupId)) return false;
-  const steps = source.commandGroups[groupId];
-  if (!Array.isArray(steps)) return false;
-  seen.add(groupId);
-  return steps.some((step) => {
-    if (!isRecord(step)) return false;
-    if (step.type === "rule") return step.id === ruleId;
-    if (step.type === "group" && typeof step.id === "string") {
-      return commandGroupContainsRule(source, step.id, ruleId, seen);
-    }
-    return false;
-  });
-};
-
-export const collectBoundaryRuleMembershipFailures = (root, specs) => {
-  const failures = [];
-  const source = readBoundaryRulesSource(root, failures);
-  if (source === null) return failures;
-
-  const rules = Array.isArray(source.rules) ? source.rules : [];
-  for (const spec of specs) {
-    const rule = rules.find((entry) => isRecord(entry) && entry.id === spec.ruleId);
-    if (rule === undefined) {
-      failures.push(`docs/agent/boundary-rules.source.json: missing boundary rule ${spec.ruleId}`);
-      continue;
-    }
-    if (spec.commandGroup !== undefined && rule.commandGroup !== spec.commandGroup) {
-      failures.push(
-        `docs/agent/boundary-rules.source.json: ${spec.ruleId} must declare commandGroup ${spec.commandGroup}`,
-      );
-    }
-    for (const groupId of spec.reachableFrom ?? []) {
-      if (!commandGroupContainsRule(source, groupId, spec.ruleId)) {
-        failures.push(
-          `docs/agent/boundary-rules.source.json: ${groupId} must include boundary rule ${spec.ruleId}`,
-        );
-      }
-    }
-  }
-  return failures;
-};

package/dist/lib/capability-routes.mjs

@@ -1,354 +0,0 @@
-export const generatedCapabilityRuleFields = new Set([
-  "allowedPrimitivePackages",
-  "coordinationCapabilityKind",
-  "coordinationPackage",
-  "coverage",
-  "docs",
-  "invariants",
-  "sourceFactOwners",
-  "testEvidence",
-]);
-
-const unique = (values) => [...new Set(values)].sort((left, right) => left.localeCompare(right));
-
-const coordinationCapabilityKinds = new Set(["composer", "facade", "profile", "projection"]);
-
-const consumerFacingCapabilityKinds = new Set(["composer", "facade", "profile"]);
-
-const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-
-const stringArray = (value) =>
-  Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0);
-
-const authoredCapabilityRuleSourceFields = new Set(["schemaVersion", "rules"]);
-
-const resolvePrefixOwner = (prefix, namespaceOwners) => {
-  const candidates = namespaceOwners.filter(
-    (owner) => prefix.startsWith(owner.prefix) || owner.prefix.startsWith(prefix),
-  );
-  const owners = unique(candidates.map((candidate) => candidate.owner));
-  if (owners.length !== 1) {
-    return { ok: false, owners, candidates };
-  }
-  return {
-    ok: true,
-    owner: owners[0],
-    declarations: candidates
-      .filter((candidate) => candidate.owner === owners[0])
-      .map((candidate) => ({
-        prefix: candidate.prefix,
-        owner: candidate.owner,
-        filePath: candidate.filePath,
-      })),
-  };
-};
-
-const primitiveEvidence = (primitive) => {
-  if (primitive.testEvidence?.tests !== undefined) {
-    return {
-      primitive: primitive.id,
-      tests: primitive.testEvidence.tests,
-    };
-  }
-  return {
-    primitive: primitive.id,
-    noTestReason: primitive.testEvidence?.noTestReason ?? "missing evidence source",
-  };
-};
-
-export const buildCapabilityRouteProjection = ({
-  source,
-  recipes = [],
-  primitives,
-  invariants,
-  rootScripts,
-  namespaceOwners,
-}) => {
-  const failures = [];
-  const primitiveById = new Map(primitives.map((primitive) => [primitive.id, primitive]));
-  const invariantById = new Map(invariants.map((invariant) => [invariant.id, invariant]));
-  const scriptNames = new Set(Object.keys(rootScripts));
-
-  if (!isObject(source)) {
-    return { failures: ["capability rules source must be an object"], routes: [] };
-  }
-  for (const field of Object.keys(source)) {
-    if (!authoredCapabilityRuleSourceFields.has(field)) {
-      failures.push(`capability rules source must not author field ${field}`);
-    }
-  }
-  if (source.schemaVersion !== 1) failures.push("capability rules schemaVersion must be 1");
-  if (!Array.isArray(source.rules)) failures.push("capability rules source must contain rules[]");
-
-  const rules = Array.isArray(source.rules) ? source.rules : [];
-  const seenPrimitives = new Set();
-  const routes = [];
-
-  for (const [index, rule] of rules.entries()) {
-    const owner =
-      isObject(rule) && typeof rule.primitive === "string" ? rule.primitive : `rule[${index}]`;
-
-    if (!isObject(rule)) {
-      failures.push(`${owner} must be an object`);
-      continue;
-    }
-
-    for (const field of Object.keys(rule)) {
-      if (generatedCapabilityRuleFields.has(field)) {
-        failures.push(`${owner} must not author generated field ${field}`);
-      }
-    }
-
-    const required = [
-      "primitive",
-      "intents",
-      "sourceFactPrefixes",
-      "allowedPrimitives",
-      "forbiddenWrites",
-      "gates",
-    ];
-    for (const field of required) {
-      if (!(field in rule)) failures.push(`${owner} missing ${field}`);
-    }
-
-    if (typeof rule.primitive !== "string" || rule.primitive.length === 0) {
-      failures.push(`${owner} primitive must be a non-empty string`);
-      continue;
-    }
-    if (seenPrimitives.has(rule.primitive))
-      failures.push(`duplicate capability rule ${rule.primitive}`);
-    seenPrimitives.add(rule.primitive);
-
-    const primitive = primitiveById.get(rule.primitive);
-    if (primitive === undefined) {
-      failures.push(`${rule.primitive} references unknown primitive`);
-    }
-
-    if (!stringArray(rule.intents) || rule.intents.length === 0) {
-      failures.push(`${rule.primitive} intents must be a non-empty string array`);
-    }
-    if (!stringArray(rule.sourceFactPrefixes) || rule.sourceFactPrefixes.length === 0) {
-      failures.push(`${rule.primitive} sourceFactPrefixes must be a non-empty string array`);
-    }
-    if (!stringArray(rule.allowedPrimitives) || rule.allowedPrimitives.length === 0) {
-      failures.push(`${rule.primitive} allowedPrimitives must be a non-empty string array`);
-    } else if (!rule.allowedPrimitives.includes(rule.primitive)) {
-      failures.push(`${rule.primitive} allowedPrimitives must include its coordination primitive`);
-    }
-    if (!Array.isArray(rule.forbiddenWrites)) {
-      failures.push(`${rule.primitive} forbiddenWrites must be an array`);
-    }
-    if (!stringArray(rule.gates) || rule.gates.length === 0) {
-      failures.push(`${rule.primitive} gates must be a non-empty boundary gate array`);
-    }
-
-    const allowedPrimitives = stringArray(rule.allowedPrimitives) ? rule.allowedPrimitives : [];
-    const allowedPrimitiveRecords = [];
-    for (const allowedPrimitive of allowedPrimitives) {
-      const record = primitiveById.get(allowedPrimitive);
-      if (record === undefined) {
-        failures.push(
-          `${rule.primitive} allowedPrimitives references unknown primitive ${allowedPrimitive}`,
-        );
-      } else {
-        allowedPrimitiveRecords.push(record);
-      }
-    }
-
-    const sourceFactOwners = [];
-    for (const prefix of stringArray(rule.sourceFactPrefixes) ? rule.sourceFactPrefixes : []) {
-      const resolved = resolvePrefixOwner(prefix, namespaceOwners);
-      if (!resolved.ok) {
-        failures.push(
-          `${rule.primitive} sourceFactPrefixes ${JSON.stringify(prefix)} must resolve to exactly one owner; observed ${JSON.stringify(resolved.owners)}`,
-        );
-      } else {
-        sourceFactOwners.push({
-          prefix,
-          owner: resolved.owner,
-          declarations: resolved.declarations,
-        });
-      }
-    }
-
-    const forbiddenWrites = Array.isArray(rule.forbiddenWrites) ? rule.forbiddenWrites : [];
-    for (const [writeIndex, write] of forbiddenWrites.entries()) {
-      const writeOwner = `${rule.primitive} forbiddenWrites[${writeIndex}]`;
-      if (!isObject(write)) {
-        failures.push(`${writeOwner} must be an object`);
-        continue;
-      }
-      for (const field of ["actor", "action", "target", "invariant"]) {
-        if (!(field in write)) failures.push(`${writeOwner} missing ${field}`);
-      }
-      if (typeof write.actor !== "string" || write.actor.length === 0) {
-        failures.push(`${writeOwner} actor must be a non-empty string`);
-      }
-      if (typeof write.action !== "string" || write.action.length === 0) {
-        failures.push(`${writeOwner} action must be a non-empty string`);
-      }
-      if (!isObject(write.target)) {
-        failures.push(`${writeOwner} target must be an object`);
-      } else {
-        if (!["eventPrefix", "surface", "material"].includes(write.target.kind)) {
-          failures.push(`${writeOwner} target.kind must be eventPrefix, surface, or material`);
-        }
-        if (typeof write.target.value !== "string" || write.target.value.length === 0) {
-          failures.push(`${writeOwner} target.value must be a non-empty string`);
-        }
-        if (write.target.kind === "eventPrefix" && typeof write.target.value === "string") {
-          const resolved = resolvePrefixOwner(write.target.value, namespaceOwners);
-          if (!resolved.ok) {
-            failures.push(
-              `${writeOwner} target ${JSON.stringify(write.target.value)} must resolve to exactly one owner; observed ${JSON.stringify(resolved.owners)}`,
-            );
-          }
-        }
-      }
-      if (typeof write.invariant !== "string" || !invariantById.has(write.invariant)) {
-        failures.push(
-          `${writeOwner} references unknown invariant ${JSON.stringify(write.invariant)}`,
-        );
-      }
-    }
-
-    for (const gate of stringArray(rule.gates) ? rule.gates : []) {
-      if (!scriptNames.has(gate))
-        failures.push(`${rule.primitive} references unknown boundary gate ${gate}`);
-    }
-
-    const sourceOwnerNames = unique(sourceFactOwners.map((entry) => entry.owner));
-    if (
-      sourceOwnerNames.length > 1 &&
-      primitive !== undefined &&
-      !coordinationCapabilityKinds.has(primitive.capabilityKind)
-    ) {
-      failures.push(
-        `${rule.primitive} spans ${sourceOwnerNames.length} fact owners but coordination primitive kind ${JSON.stringify(
-          primitive.capabilityKind,
-        )} is not one of ${JSON.stringify([...coordinationCapabilityKinds])}`,
-      );
-    }
-
-    if (
-      primitive === undefined ||
-      failures.some((failure) => failure.startsWith(`${rule.primitive} `))
-    ) {
-      continue;
-    }
-
-    const invariantIds = unique([
-      ...allowedPrimitiveRecords.flatMap((record) => record.invariants),
-      ...forbiddenWrites.flatMap((write) =>
-        typeof write?.invariant === "string" && invariantById.has(write.invariant)
-          ? [write.invariant]
-          : [],
-      ),
-    ]);
-
-    routes.push({
-      primitive: rule.primitive,
-      intents: rule.intents,
-      coordinationPackage: primitive.package,
-      coordinationCapabilityKind: primitive.capabilityKind,
-      sourceFactPrefixes: rule.sourceFactPrefixes,
-      sourceFactOwners,
-      allowedPrimitives,
-      allowedPrimitivePackages: unique(allowedPrimitiveRecords.map((record) => record.package)),
-      forbiddenWrites,
-      gates: rule.gates,
-      invariants: invariantIds,
-      docs: unique([
-        ...allowedPrimitiveRecords.map((record) => record.docs),
-        ...invariantIds.flatMap((id) => {
-          const invariant = invariantById.get(id);
-          return invariant === undefined ? [] : [invariant.docs];
-        }),
-      ]),
-      testEvidence: allowedPrimitiveRecords.map(primitiveEvidence),
-    });
-  }
-
-  const coverage = buildCapabilityRouteCoverage({ routes, recipes, primitives });
-  failures.push(...coverage.failures);
-
-  return {
-    failures,
-    routes:
-      failures.length === 0
-        ? routes.sort((left, right) => left.primitive.localeCompare(right.primitive))
-        : [],
-    coverage: failures.length === 0 ? coverage.summary : { recipes: [], primitives: [] },
-  };
-};
-
-const routeMatchesRecipe = (route, recipe) => {
-  const recipePrimitives = new Set(recipe.primitives);
-  return (
-    recipePrimitives.has(route.primitive) ||
-    route.allowedPrimitives.some((primitive) => recipePrimitives.has(primitive))
-  );
-};
-
-const routePrimitivesForRecipe = (routes, recipe) =>
-  routes
-    .filter((route) => routeMatchesRecipe(route, recipe))
-    .map((route) => route.primitive)
-    .sort((left, right) => left.localeCompare(right));
-
-const buildCapabilityRouteCoverage = ({ routes, recipes, primitives }) => {
-  const failures = [];
-  const coveredPrimitiveIds = new Set(
-    routes.flatMap((route) => [route.primitive, ...route.allowedPrimitives]),
-  );
-  const recipeCoverage = recipes.map((recipe) => {
-    const routePrimitives = routePrimitivesForRecipe(routes, recipe);
-    const noRouteReason =
-      typeof recipe.noRouteReason === "string" ? recipe.noRouteReason.trim() : undefined;
-    if (routePrimitives.length === 0 && noRouteReason === undefined) {
-      failures.push(`${recipe.id} must have a capability route or noRouteReason`);
-    }
-    if (routePrimitives.length > 0 && noRouteReason !== undefined) {
-      failures.push(`${recipe.id} has both route coverage and noRouteReason`);
-    }
-    return {
-      id: recipe.id,
-      routePrimitives,
-      ...(noRouteReason === undefined ? {} : { noRouteReason }),
-    };
-  });
-
-  const primitiveCoverage = primitives
-    .filter((primitive) => consumerFacingCapabilityKinds.has(primitive.capabilityKind))
-    .map((primitive) => {
-      const routePrimitives = routes
-        .filter(
-          (route) =>
-            route.primitive === primitive.id || route.allowedPrimitives.includes(primitive.id),
-        )
-        .map((route) => route.primitive)
-        .sort((left, right) => left.localeCompare(right));
-      const noRouteReason =
-        typeof primitive.noRouteReason === "string" ? primitive.noRouteReason.trim() : undefined;
-      if (!coveredPrimitiveIds.has(primitive.id) && noRouteReason === undefined) {
-        failures.push(`${primitive.id} must have a capability route or noRouteReason`);
-      }
-      if (coveredPrimitiveIds.has(primitive.id) && noRouteReason !== undefined) {
-        failures.push(`${primitive.id} has both route coverage and noRouteReason`);
-      }
-      return {
-        id: primitive.id,
-        capabilityKind: primitive.capabilityKind,
-        routePrimitives,
-        ...(noRouteReason === undefined ? {} : { noRouteReason }),
-      };
-    });
-
-  return {
-    failures,
-    summary: {
-      recipes: recipeCoverage,
-      primitives: primitiveCoverage,
-    },
-  };
-};