@yansirplus/cli 0.5.17

package/dist/lib/public-api-model.mjs

@@ -0,0 +1,306 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+export const apiSourceMode = (pkg) => pkg.apiSourceMode ?? "manual";
+
+export const sourceTsdocModes = new Set(["source-tsdoc"]);
+
+const statusTags = new Set(["public", "experimental", "internal", "deprecated"]);
+
+const hasExportModifier = (node) =>
+  node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) === true;
+
+const hasDefaultModifier = (node) =>
+  node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) === true;
+
+const nameFromDeclaration = (name) => (ts.isIdentifier(name) ? name.text : null);
+
+const resolveRelativeModule = (fromFile, specifier) => {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    path.join(base, "index.ts"),
+    path.join(base, "index.tsx"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  }
+  throw new Error(`cannot resolve export module ${specifier} from ${fromFile}`);
+};
+
+export const exportedNamesFromAst = (file, seen) => {
+  const source = fs.readFileSync(file, "utf8");
+  const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+  const names = new Set();
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportDeclaration(statement)) {
+      const specifier =
+        statement.moduleSpecifier !== undefined && ts.isStringLiteral(statement.moduleSpecifier)
+          ? statement.moduleSpecifier.text
+          : null;
+
+      if (statement.exportClause === undefined) {
+        if (specifier !== null && specifier.startsWith(".")) {
+          const target = resolveRelativeModule(file, specifier);
+          for (const name of exportedNamesFromSource(target, seen)) names.add(name);
+        }
+        continue;
+      }
+
+      if (ts.isNamespaceExport(statement.exportClause)) {
+        names.add(statement.exportClause.name.text);
+        continue;
+      }
+
+      for (const element of statement.exportClause.elements) {
+        names.add(element.name.text);
+      }
+      continue;
+    }
+
+    if (ts.isExportAssignment(statement)) {
+      names.add(statement.isExportEquals === true ? "export=" : "default");
+      continue;
+    }
+
+    if (!hasExportModifier(statement)) continue;
+
+    if (hasDefaultModifier(statement)) {
+      names.add("default");
+      continue;
+    }
+
+    if (
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement) ||
+      ts.isClassDeclaration(statement) ||
+      ts.isFunctionDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)
+    ) {
+      const name = statement.name === undefined ? null : nameFromDeclaration(statement.name);
+      if (name !== null) names.add(name);
+      continue;
+    }
+
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        const name = nameFromDeclaration(declaration.name);
+        if (name !== null) names.add(name);
+      }
+    }
+  }
+
+  return names;
+};
+
+export const exportedNamesFromSource = (file, seen = new Set()) => {
+  const abs = path.resolve(file);
+  if (seen.has(abs)) return new Set();
+  seen.add(abs);
+  return exportedNamesFromAst(abs, seen);
+};
+
+const plainComment = (comment) => {
+  if (comment === undefined) return "";
+  if (typeof comment === "string") return comment;
+  if (Array.isArray(comment)) return comment.map((part) => part.text).join("");
+  return String(comment);
+};
+
+const tsdocForNode = (node, sourceFile) => {
+  const docs = node.jsDoc ?? [];
+  const doc = docs.at(-1);
+  if (doc === undefined) {
+    return { summary: "", tags: [] };
+  }
+
+  const tags = [];
+  for (const tag of doc.tags ?? []) {
+    tags.push({
+      name: tag.tagName.getText(sourceFile),
+      text: plainComment(tag.comment).trim(),
+    });
+  }
+
+  return {
+    summary: plainComment(doc.comment).replace(/\s+/gu, " ").trim(),
+    tags,
+  };
+};
+
+const sourceExportRecordsFromAst = (file, entrypoint, seen) => {
+  const abs = path.resolve(file);
+  if (seen.has(abs)) return [];
+  seen.add(abs);
+
+  const source = fs.readFileSync(abs, "utf8");
+  const sourceFile = ts.createSourceFile(abs, source, ts.ScriptTarget.Latest, true);
+  const records = [];
+
+  const pushRecord = (name, node) => {
+    const tsdoc = tsdocForNode(node, sourceFile);
+    const matchingTags = tsdoc.tags.filter((tag) => statusTags.has(tag.name));
+    const status = matchingTags.length === 1 ? matchingTags[0] : null;
+    records.push({
+      entrypoint,
+      name,
+      key: `${entrypoint}:${name}`,
+      file: abs,
+      summary: tsdoc.summary,
+      tags: tsdoc.tags,
+      status,
+      statusTags: matchingTags,
+    });
+  };
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportDeclaration(statement)) {
+      const specifier =
+        statement.moduleSpecifier !== undefined && ts.isStringLiteral(statement.moduleSpecifier)
+          ? statement.moduleSpecifier.text
+          : null;
+      if (statement.exportClause === undefined && specifier !== null && specifier.startsWith(".")) {
+        records.push(
+          ...sourceExportRecordsFromAst(resolveRelativeModule(abs, specifier), entrypoint, seen),
+        );
+      }
+      continue;
+    }
+
+    if (ts.isExportAssignment(statement)) {
+      pushRecord(statement.isExportEquals === true ? "export=" : "default", statement);
+      continue;
+    }
+
+    if (!hasExportModifier(statement)) continue;
+
+    if (hasDefaultModifier(statement)) {
+      pushRecord("default", statement);
+      continue;
+    }
+
+    if (
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement) ||
+      ts.isClassDeclaration(statement) ||
+      ts.isFunctionDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)
+    ) {
+      const name = statement.name === undefined ? null : nameFromDeclaration(statement.name);
+      if (name !== null) pushRecord(name, statement);
+      continue;
+    }
+
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        const name = nameFromDeclaration(declaration.name);
+        if (name !== null) pushRecord(name, statement);
+      }
+    }
+  }
+
+  return records;
+};
+
+const packageEntrypoints = (root, pkg) => {
+  const pkgDir = path.join(root, pkg.path);
+  const manifest = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+  return Object.entries(manifest.exports ?? {})
+    .map(([entrypoint, exportSpec]) => {
+      const source = exportSpec?.default ?? exportSpec;
+      return typeof source === "string" && source.startsWith("./")
+        ? { entrypoint, file: path.join(pkgDir, source) }
+        : null;
+    })
+    .filter((entry) => entry !== null);
+};
+
+export const exportedNamesForPackage = (root, pkg) =>
+  packageEntrypoints(root, pkg).flatMap(({ entrypoint, file }) =>
+    [...exportedNamesFromSource(file)].map((name) => ({
+      entrypoint,
+      name: String(name),
+      key: `${entrypoint}:${String(name)}`,
+    })),
+  );
+
+export const sourceTsdocRecordsForPackage = (root, pkg) =>
+  packageEntrypoints(root, pkg)
+    .flatMap(({ entrypoint, file }) => sourceExportRecordsFromAst(file, entrypoint, new Set()))
+    .sort((left, right) => left.key.localeCompare(right.key));
+
+export const validateSourceTsdocRecords = (pkg, records) => {
+  const failures = [];
+  const seen = new Set();
+
+  for (const record of records) {
+    if (seen.has(record.key)) {
+      failures.push(`${pkg.name}: duplicate exported symbol record ${record.key}`);
+      continue;
+    }
+    seen.add(record.key);
+
+    if (record.summary.length === 0) {
+      failures.push(`${pkg.name}: ${record.key} is missing a TSDoc summary`);
+    }
+    if (record.statusTags.length !== 1) {
+      failures.push(
+        `${pkg.name}: ${record.key} must have exactly one API status tag (@public, @experimental, @internal, or @deprecated)`,
+      );
+      continue;
+    }
+    if (record.status?.name === "internal") {
+      failures.push(`${pkg.name}: ${record.key} is tagged @internal but exported`);
+    }
+    if (record.status?.name === "deprecated" && record.status.text.length === 0) {
+      failures.push(`${pkg.name}: ${record.key} has @deprecated without a reason`);
+    }
+  }
+
+  return failures;
+};
+
+const listSection = (records) =>
+  records.length === 0
+    ? "None."
+    : records.map((record) => `- \`${record.key}\` - ${record.summary}`).join("\n");
+
+export const sourceTsdocApiMarkdown = (pkg, records) => {
+  const byStatus = (status) => records.filter((record) => record.status?.name === status);
+  const deprecated = byStatus("deprecated");
+  const deprecatedSection =
+    deprecated.length === 0
+      ? "None."
+      : deprecated
+          .map(
+            (record) => `- \`${record.key}\` - ${record.summary} Deprecated: ${record.status.text}`,
+          )
+          .join("\n");
+
+  return [
+    `# ${pkg.name} Public API Intent`,
+    "",
+    "<!-- generated by packages/cli/src/generate/generate-docs.mjs; edit exported TSDoc in package source -->",
+    "",
+    "## Public exports",
+    "",
+    listSection(byStatus("public")),
+    "",
+    "## Experimental exports",
+    "",
+    listSection(byStatus("experimental")),
+    "",
+    "## Deprecated exports",
+    "",
+    deprecatedSection,
+    "",
+    "## Internal-only exports",
+    "",
+    "Any package file or symbol not listed above.",
+    "",
+  ].join("\n");
+};

package/dist/main.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import {
+  algorithmicCheckerAcceptsArgs,
+  hasAlgorithmicChecker,
+  runAlgorithmicChecker,
+} from "./check/algorithmic-checks.mjs";
+import {
+  deriveAffectedGates,
+  printAffectedGates,
+  runAffectedGates,
+} from "./check/gate-selector.mjs";
+import { runDefaultGate } from "./check/default-gate.mjs";
+import { listGuards, runGroup, runGuard } from "./runner.mjs";
+
+const version = "0.5.16";
+
+const helpText = `agentOS repository CLI ${version}
+
+Usage:
+  agentos --help
+  agentos --version
+  agentos build [--cwd <path>] [--config <path>] [--package-scope <scope>]
+  agentos check all
+  agentos check default
+  agentos check structural
+  agentos check affected [--base <ref>] [--head <ref>] [--json] [--explain] [--run]
+  agentos check docs
+  agentos check effect-manifests
+  agentos check release
+  agentos check site
+  agentos check guard-coverage
+  agentos check <algorithmic-check-id>
+  agentos check guard <rule-id>
+  agentos check guards
+  agentos generate docs
+  agentos generate effect-manifests
+  agentos generate site
+  agentos generate site --watch
+`;
+
+const printHelp = () => {
+  process.stdout.write(helpText);
+};
+
+const fail = (message) => {
+  process.stderr.write(`${message}\n\n`);
+  if (
+    message.startsWith("agentos:") ||
+    message.startsWith("agentos build:") ||
+    message.startsWith("agentos check:") ||
+    message.startsWith("agentos generate:")
+  ) {
+    printHelp();
+  }
+  process.exitCode = 1;
+};
+
+const expectNoExtraArgs = (args, command) => {
+  if (args.length > 0) {
+    throw new Error(`${command}: unexpected argument ${args.join(" ")}`);
+  }
+};
+
+const runBuild = async (args) => {
+  const runner = fileURLToPath(new URL("./build/build-cli.js", import.meta.url));
+  await new Promise((resolve, reject) => {
+    const child = spawn("bun", [runner, "build", ...args], { stdio: "inherit" });
+    child.on("error", (error) => {
+      reject(new Error(`agentos build: failed to start bun: ${error.message}`));
+    });
+    child.on("exit", (code, signal) => {
+      if (signal !== null) {
+        reject(new Error(`agentos build: build runner terminated by ${signal}`));
+        return;
+      }
+      if (code !== 0) {
+        reject(new Error(`agentos build: build runner failed with exit code ${code ?? 1}`));
+        return;
+      }
+      resolve();
+    });
+  });
+};
+
+const runCheck = async (args) => {
+  const [command, ...rest] = args;
+  switch (command) {
+    case "all":
+      expectNoExtraArgs(rest, "agentos check all");
+      await runGroup("all");
+      return;
+    case "default":
+      expectNoExtraArgs(rest, "agentos check default");
+      await runDefaultGate();
+      return;
+    case "structural":
+      expectNoExtraArgs(rest, "agentos check structural");
+      await runGroup("all");
+      return;
+    case "affected": {
+      let base;
+      let head;
+      let json = false;
+      let run = false;
+      for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === "--base") {
+          base = rest[index + 1];
+          if (base === undefined) throw new Error("agentos check affected: --base requires a ref");
+          index += 1;
+        } else if (arg === "--head") {
+          head = rest[index + 1];
+          if (head === undefined) throw new Error("agentos check affected: --head requires a ref");
+          index += 1;
+        } else if (arg === "--json") {
+          json = true;
+        } else if (arg === "--explain") {
+          json = false;
+        } else if (arg === "--run") {
+          run = true;
+        } else {
+          throw new Error(`agentos check affected: unexpected argument ${arg}`);
+        }
+      }
+      const result = deriveAffectedGates({ base, head });
+      printAffectedGates(result, { json });
+      if (run) runAffectedGates(result);
+      return;
+    }
+    case "docs":
+      expectNoExtraArgs(rest, "agentos check docs");
+      await runGroup("check-docs");
+      return;
+    case "effect-manifests":
+      expectNoExtraArgs(rest, "agentos check effect-manifests");
+      await runGroup("check-effect-manifests");
+      return;
+    case "release":
+      expectNoExtraArgs(rest, "agentos check release");
+      await runGroup("release");
+      return;
+    case "site":
+      expectNoExtraArgs(rest, "agentos check site");
+      await runGroup("check-site");
+      return;
+    case "guard-coverage":
+      expectNoExtraArgs(rest, "agentos check guard-coverage");
+      await runGroup("guard-coverage");
+      return;
+    case "guard": {
+      const [ruleId, ...extra] = rest;
+      if (ruleId === undefined) throw new Error("agentos check guard: missing <rule-id>");
+      expectNoExtraArgs(extra, "agentos check guard");
+      await runGuard(ruleId);
+      return;
+    }
+    case "guards":
+      expectNoExtraArgs(rest, "agentos check guards");
+      for (const id of listGuards()) console.log(id);
+      return;
+    default:
+      if (command !== undefined && hasAlgorithmicChecker(command)) {
+        if (!algorithmicCheckerAcceptsArgs(command)) {
+          expectNoExtraArgs(rest, `agentos check ${command}`);
+        }
+        await runAlgorithmicChecker(command, rest);
+        return;
+      }
+      throw new Error(
+        "agentos check: choose one of all, default, structural, affected, docs, effect-manifests, release, site, guard-coverage, guard, guards, or an algorithmic checker id",
+      );
+  }
+};
+
+const runGenerate = async (args) => {
+  const [command, ...rest] = args;
+  switch (command) {
+    case "docs":
+      expectNoExtraArgs(rest, "agentos generate docs");
+      await runGroup("generate-docs");
+      return;
+    case "effect-manifests":
+      expectNoExtraArgs(rest, "agentos generate effect-manifests");
+      await runGroup("generate-effect-manifests");
+      return;
+    case "site":
+      if (rest[0] === "--watch") {
+        expectNoExtraArgs(rest.slice(1), "agentos generate site --watch");
+        await runGroup("generate-site-watch");
+      } else {
+        expectNoExtraArgs(rest, "agentos generate site");
+        await runGroup("generate-site");
+      }
+      return;
+    default:
+      throw new Error("agentos generate: choose one of docs, effect-manifests, site");
+  }
+};
+
+const main = async () => {
+  const args = process.argv.slice(2);
+  const [command, ...rest] = args;
+  if (command === undefined || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+  if (command === "--version" || command === "-v") {
+    console.log(version);
+    return;
+  }
+  switch (command) {
+    case "build":
+      await runBuild(rest);
+      return;
+    case "check":
+      await runCheck(rest);
+      return;
+    case "generate":
+      await runGenerate(rest);
+      return;
+    default:
+      throw new Error("agentos: choose one of build, check, generate");
+  }
+};
+
+try {
+  await main();
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}

package/dist/runner.mjs

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runCommand } from "./check/command-runner.mjs";
+import { runRuleAcceptance, validateRuleAcceptance } from "./check/manifest-rules.mjs";
+
+export const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+const manifestPath = path.join(repoRoot, "docs/agent/boundary-rules.source.json");
+
+export const loadBoundaryRules = () => {
+  const value = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  validateBoundaryRules(value);
+  return value;
+};
+
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+const requiredRuleFields = [
+  "id",
+  "owner",
+  "invariantId",
+  "kind",
+  "acceptance",
+  "diagnostics",
+  "paths",
+  "commandGroup",
+];
+
+const validateBoundaryRules = (value) => {
+  const failures = [];
+  if (!isRecord(value)) failures.push("boundary rules source must be an object");
+  if (value.schemaVersion !== 2) failures.push("boundary rules schemaVersion must be 2");
+  if (!isRecord(value.commandGroups)) failures.push("boundary rules must define commandGroups");
+  if (!Array.isArray(value.rules)) failures.push("boundary rules must define rules[]");
+
+  const commandGroups = isRecord(value.commandGroups) ? value.commandGroups : {};
+  for (const [groupId, steps] of Object.entries(commandGroups)) {
+    if (!Array.isArray(steps)) {
+      failures.push(`commandGroups.${groupId} must be an array`);
+      continue;
+    }
+    for (const [index, step] of steps.entries()) {
+      if (!isRecord(step)) {
+        failures.push(`commandGroups.${groupId}[${index}] must be an object`);
+        continue;
+      }
+      if (!["command", "group", "rule"].includes(step.type)) {
+        failures.push(`commandGroups.${groupId}[${index}] has invalid type`);
+      }
+      if (step.type === "command" && typeof step.command !== "string") {
+        failures.push(`commandGroups.${groupId}[${index}] command must be a string`);
+      }
+      if ((step.type === "group" || step.type === "rule") && typeof step.id !== "string") {
+        failures.push(`commandGroups.${groupId}[${index}] id must be a string`);
+      }
+    }
+  }
+
+  const seenRules = new Set();
+  for (const [index, rule] of (Array.isArray(value.rules) ? value.rules : []).entries()) {
+    const label = isRecord(rule) && typeof rule.id === "string" ? rule.id : `rules[${index}]`;
+    if (!isRecord(rule)) {
+      failures.push(`${label} must be an object`);
+      continue;
+    }
+    for (const field of requiredRuleFields) {
+      if (!(field in rule)) failures.push(`${label} missing ${field}`);
+    }
+    if (typeof rule.id !== "string" || rule.id.length === 0) {
+      failures.push(`${label} id must be non-empty`);
+    } else if (seenRules.has(rule.id)) {
+      failures.push(`duplicate boundary rule ${rule.id}`);
+    } else {
+      seenRules.add(rule.id);
+    }
+    validateRuleAcceptance(rule, failures);
+    if (!Array.isArray(rule.diagnostics)) failures.push(`${label} diagnostics must be an array`);
+    if (!Array.isArray(rule.paths)) failures.push(`${label} paths must be an array`);
+    if (typeof rule.commandGroup !== "string" || !(rule.commandGroup in commandGroups)) {
+      failures.push(`${label} commandGroup must reference commandGroups`);
+    }
+  }
+
+  if (failures.length > 0) {
+    throw new Error(failures.join("\n"));
+  }
+};
+
+const ruleById = (manifest, id) => manifest.rules.find((rule) => rule.id === id);
+
+const runSteps = async (manifest, steps, stack = []) => {
+  for (const step of steps) {
+    if (step.type === "command") {
+      runCommand(step.command, { cwd: repoRoot });
+      continue;
+    }
+    if (step.type === "group") {
+      if (stack.includes(step.id)) {
+        throw new Error(`cyclic command group: ${[...stack, step.id].join(" -> ")}`);
+      }
+      const group = manifest.commandGroups[step.id];
+      if (group === undefined) throw new Error(`unknown command group ${step.id}`);
+      await runSteps(manifest, group, [...stack, step.id]);
+      continue;
+    }
+    if (step.type === "rule") {
+      await runGuard(step.id, manifest);
+      continue;
+    }
+  }
+};
+
+export const runGroup = async (id, manifest = loadBoundaryRules()) => {
+  const steps = manifest.commandGroups[id];
+  if (steps === undefined) throw new Error(`unknown command group ${id}`);
+  await runSteps(manifest, steps, [id]);
+};
+
+export const runGuard = async (id, manifest = loadBoundaryRules()) => {
+  const rule = ruleById(manifest, id);
+  if (rule === undefined) throw new Error(`unknown boundary rule ${id}`);
+  await runRuleAcceptance(rule);
+};
+
+export const listGuards = (manifest = loadBoundaryRules()) =>
+  manifest.rules.map((rule) => rule.id).sort((left, right) => left.localeCompare(right));

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@yansirplus/cli",
+  "version": "0.5.17",
+  "type": "module",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agentos": "./dist/main.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "PUBLIC_API.md"
+  ],
+  "dependencies": {
+    "@yansirplus/core": "0.5.17",
+    "@yansirplus/runtime": "0.5.17"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0-beta.84"
+  }
+}