@yansirplus/cli 0.5.17 → 0.5.19

package/dist/generate/generate-docs.mjs

@@ -1,345 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import {
-  checkProjectionSink,
-  defineProjectionSpec,
-  runProjectionSink,
-} from "../lib/projection-sink.mjs";
-import {
-  apiSourceMode,
-  sourceTsdocApiMarkdown,
-  sourceTsdocModes,
-  sourceTsdocRecordsForPackage,
-  validateSourceTsdocRecords,
-} from "../lib/public-api-model.mjs";
-
-const root = process.cwd();
-const check = process.argv.includes("--check");
-const surfacePath = path.join(root, "docs/surface.json");
-const rootPackage = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-const rawSurfaceText = fs.readFileSync(surfacePath, "utf8");
-const rawSurface = JSON.parse(rawSurfaceText);
-const releaseVersion = rootPackage.agentOsRelease?.version;
-const releaseLine =
-  typeof releaseVersion === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(releaseVersion)
-    ? `${releaseVersion.split(".").slice(0, 2).join(".")}.x`
-    : undefined;
-const hardCodedReleaseLinePattern = /\b\d+\.\d+\.x\b/u;
-
-const expandReleaseTokens = (value) => {
-  if (typeof value === "string") {
-    return releaseLine === undefined ? value : value.replaceAll("{releaseLine}", releaseLine);
-  }
-  if (Array.isArray(value)) return value.map(expandReleaseTokens);
-  if (value !== null && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value).map(([key, entry]) => [key, expandReleaseTokens(entry)]),
-    );
-  }
-  return value;
-};
-
-const surface = expandReleaseTokens(rawSurface);
-
-const generatedNotice = (source) =>
-  `<!-- generated by packages/cli/src/generate/generate-docs.mjs; edit ${source} -->`;
-
-const read = (file) => fs.readFileSync(path.join(root, file), "utf8");
-
-const docsSourceFacts = {
-  kind: "source-set",
-  ref: "docs.generate-docs.source-facts",
-  sources: [
-    { kind: "file", ref: "package.json" },
-    { kind: "file", ref: "docs/surface.json" },
-    { kind: "directory", ref: "docs/packages" },
-    { kind: "directory", ref: "docs/api" },
-    { kind: "tsdoc", ref: "exported public API TSDoc" },
-  ],
-};
-
-const fileProjection = (file) =>
-  defineProjectionSpec({
-    id: `docs.generate-docs:${file}`,
-    version: 1,
-    source: docsSourceFacts,
-    project: (text, ctx) => ctx.ok(`${text.replace(/\s+$/u, "")}\n`),
-  });
-
-const fileSink = (file) => {
-  const target = path.join(root, file);
-  return {
-    id: file,
-    read: () =>
-      fs.existsSync(target)
-        ? { _tag: "found", output: fs.readFileSync(target, "utf8") }
-        : { _tag: "missing" },
-    write: (output) => {
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, output);
-    },
-    equals: (actual, expected) => actual === expected,
-  };
-};
-
-const write = async (file, text) => {
-  const spec = fileProjection(file);
-  const sink = fileSink(file);
-  if (check) {
-    const result = await checkProjectionSink(spec, text, sink);
-    if (result._tag === "projection_failed") {
-      failures.push(`${file} projection failed: ${result.result.reason}`);
-    } else if (result._tag === "stale") {
-      failures.push(`${file} is stale`);
-    }
-    return;
-  }
-
-  const result = await runProjectionSink(spec, text, sink);
-  if (result._tag === "projection_failed") {
-    failures.push(`${file} projection failed: ${result.result.reason}`);
-  }
-};
-
-const sectionBody = (text, heading) => {
-  const marker = `## ${heading}`;
-  const start = text.indexOf(marker);
-  if (start === -1) throw new Error(`missing section ${heading}`);
-  const after = text.slice(start + marker.length);
-  const next = after.search(/^## /m);
-  return (next === -1 ? after : after.slice(0, next)).trim();
-};
-
-const optionalSectionBody = (text, heading, fallback) => {
-  const marker = `## ${heading}`;
-  return text.includes(marker) ? sectionBody(text, heading) : fallback;
-};
-
-const pad = (value, width) => `${value}${" ".repeat(Math.max(0, width - value.length))}`;
-
-const table = (headers, rows) => {
-  const widths = headers.map((header, index) =>
-    Math.max(header.length, ...rows.map((row) => row[index].length)),
-  );
-  const line = (row) => `| ${row.map((cell, index) => pad(cell, widths[index])).join(" | ")} |`;
-  const divider = `| ${widths.map((width) => "-".repeat(width)).join(" | ")} |`;
-  return [line(headers), divider, ...rows.map(line)].join("\n");
-};
-
-const githubDocsBase = "https://github.com/yansircc/agentOS/blob/main/docs";
-
-const rewriteDocsLinksForGithub = (text, sourceFile) =>
-  text.replace(/\[([^\]\n]+)\]\(([^)\s]+)(\s+"[^"]*")?\)/gu, (full, label, href, title = "") => {
-    if (!href.endsWith(".md") && !href.includes(".md#")) return full;
-    const [rawPath, rawAnchor] = href.split("#");
-    if (!rawPath.endsWith(".md")) return full;
-    const sourceDir = path.posix.dirname(sourceFile);
-    const target = path.posix.normalize(path.posix.join(sourceDir, rawPath));
-    if (!target.startsWith("docs/")) return full;
-    const anchor = rawAnchor === undefined ? "" : `#${rawAnchor}`;
-    return `[${label}](${githubDocsBase}/${target.slice("docs/".length)}${anchor}${title})`;
-  });
-
-const replaceBlock = async (file, id, content) => {
-  const source = read(file);
-  const startMarker = `<!-- agentos:generated ${id}:start -->`;
-  const endMarker = `<!-- agentos:generated ${id}:end -->`;
-  const start = source.indexOf(startMarker);
-  const end = source.indexOf(endMarker);
-  if (start === -1 || end === -1 || end < start) {
-    throw new Error(`${file} missing generated block ${id}`);
-  }
-  const next = end + endMarker.length;
-  await write(
-    file,
-    `${source.slice(0, start + startMarker.length)}\n\n${content}\n\n${source.slice(end, next)}${source.slice(next)}`,
-  );
-};
-
-const packages = surface.packages;
-const packagesByPath = new Map(packages.map((pkg) => [pkg.path, pkg]));
-const failures = [];
-
-if (releaseLine === undefined) {
-  failures.push("package.json agentOsRelease.version must be a semver release source");
-}
-
-if (hardCodedReleaseLinePattern.test(rawSurfaceText)) {
-  failures.push("docs/surface.json must use {releaseLine}; hard-coded release lines are forbidden");
-}
-
-const workspacePackagePaths = () => {
-  const rootPackage = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-  const workspaces = Array.isArray(rootPackage.workspaces)
-    ? rootPackage.workspaces
-    : Array.isArray(rootPackage.workspaces?.packages)
-      ? rootPackage.workspaces.packages
-      : [];
-  const paths = new Set();
-
-  for (const workspace of workspaces) {
-    if (typeof workspace !== "string") continue;
-    if (workspace.endsWith("/*")) {
-      const base = workspace.slice(0, -2);
-      const baseDir = path.join(root, base);
-      if (!fs.existsSync(baseDir)) continue;
-      for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        const packagePath = `${base}/${entry.name}`;
-        if (fs.existsSync(path.join(root, packagePath, "package.json"))) {
-          paths.add(packagePath);
-        }
-      }
-      continue;
-    }
-
-    if (fs.existsSync(path.join(root, workspace, "package.json"))) {
-      paths.add(workspace);
-    }
-  }
-
-  return [...paths].sort((left, right) => left.localeCompare(right));
-};
-
-for (const pkg of packages) {
-  const packageJsonPath = path.join(root, pkg.path, "package.json");
-  if (!fs.existsSync(packageJsonPath)) {
-    failures.push(`${pkg.path}/package.json missing`);
-    continue;
-  }
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
-  if (packageJson.name !== pkg.name) {
-    failures.push(`${pkg.path}: package.json name ${packageJson.name} does not match ${pkg.name}`);
-  }
-}
-
-for (const packagePath of workspacePackagePaths()) {
-  const pkgPath = String(packagePath);
-  if (!packagesByPath.has(pkgPath)) {
-    failures.push(`${pkgPath} is missing from docs/surface.json`);
-  }
-}
-
-for (const pkg of packages) {
-  const packageDocPath = `docs/packages/${pkg.slug}.md`;
-  const packageDoc = read(packageDocPath);
-  const packageSection = (heading) =>
-    rewriteDocsLinksForGithub(sectionBody(packageDoc, heading), packageDocPath);
-  const readme = [
-    generatedNotice(`docs/surface.json and ${packageDocPath}`),
-    "",
-    `# ${pkg.name}`,
-    "",
-    "## Purpose",
-    "",
-    packageSection("Purpose"),
-    "",
-    "## Public API Status",
-    "",
-    pkg.readmeStatus,
-    "",
-    "## Invariant",
-    "",
-    packageSection("Invariant"),
-    "",
-    "## Minimal Usage",
-    "",
-    packageSection("Minimal Usage"),
-    "",
-    "## Verification",
-    "",
-    packageSection("Verification"),
-    "",
-  ].join("\n");
-  await write(`${pkg.path}/README.md`, readme);
-
-  if (pkg.apiSource !== undefined) {
-    const mode = apiSourceMode(pkg);
-    if (sourceTsdocModes.has(mode)) {
-      const records = sourceTsdocRecordsForPackage(root, pkg);
-      failures.push(...validateSourceTsdocRecords(pkg, records));
-      await write(pkg.apiSource, sourceTsdocApiMarkdown(pkg, records));
-    } else if (mode !== "manual") {
-      failures.push(`${pkg.name}: unsupported apiSourceMode ${mode}`);
-    }
-
-    const apiDoc = read(pkg.apiSource);
-    const publicApiSource = sourceTsdocModes.has(mode)
-      ? `docs/surface.json and exported TSDoc in ${pkg.path}/src`
-      : `docs/surface.json and ${pkg.apiSource}`;
-    const publicApi = [
-      generatedNotice(publicApiSource),
-      "",
-      `# ${pkg.name} Public API`,
-      "",
-      `Status: ${pkg.apiStatus}`,
-      "",
-      "## Public exports",
-      "",
-      sectionBody(apiDoc, "Public exports"),
-      "",
-      "## Experimental exports",
-      "",
-      sectionBody(apiDoc, "Experimental exports"),
-      "",
-      "## Deprecated exports",
-      "",
-      optionalSectionBody(apiDoc, "Deprecated exports", "None."),
-      "",
-      "## Internal-only exports",
-      "",
-      sectionBody(apiDoc, "Internal-only exports"),
-      "",
-    ].join("\n");
-    await write(`${pkg.path}/PUBLIC_API.md`, publicApi);
-  }
-}
-
-const primaryPackages = packages.filter((pkg) => pkg.primary === true);
-const releasePosture = `Current release posture: ${surface.release.line} ${surface.release.posture}. ${surface.release.publicApiMeaning}`;
-
-await replaceBlock("README.md", "release-posture", releasePosture);
-
-const rootPackageMap = table(
-  ["Package", "Role"],
-  primaryPackages.map((pkg) => [`\`${pkg.name}\``, pkg.role]),
-);
-
-await replaceBlock("README.md", "package-map", rootPackageMap);
-
-const runtimePackageMap = table(
-  ["Package", "Published", "Status", "Boundary"],
-  packages.map((pkg) => [
-    `\`${pkg.name}\``,
-    pkg.published === true ? "yes" : "no",
-    pkg.status,
-    pkg.boundary,
-  ]),
-);
-
-await replaceBlock("docs/runtime-packages.md", "runtime-package-map", runtimePackageMap);
-
-await replaceBlock(
-  "docs/runtime-packages.md",
-  "holds",
-  surface.holds.map((hold) => hold.text).join("\n\n"),
-);
-
-const skillPackageMap = table(
-  ["Need", "Package"],
-  primaryPackages.map((pkg) => [pkg.need, `\`${pkg.name}\``]),
-);
-
-await replaceBlock("skills/agentos/references/package-map.md", "package-map", skillPackageMap);
-
-if (failures.length > 0) {
-  console.error(failures.join("\n"));
-  process.exit(1);
-}
-
-if (check) {
-  console.log("generated docs are current");
-} else {
-  console.log("generated docs updated");
-}

package/dist/generate/generate-effect-skill-manifests.mjs

@@ -1,193 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-
-const root = process.cwd();
-const check = process.argv.includes("--check");
-const sourcePath = path.join(root, "docs/effect-skill.json");
-const source = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
-const failures = [];
-
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-
-const stableJson = (value) =>
-  `${JSON.stringify(value, null, 2).replace(
-    /\[\n((?:\s+"(?:\\.|[^"\\])*",?\n)+)\s+\]/gu,
-    (match, body) => {
-      const items = body
-        .trim()
-        .split("\n")
-        .map((line) => line.trim().replace(/,$/u, ""));
-      return items.every((item) => item.startsWith('"') && item.endsWith('"'))
-        ? `[${items.join(", ")}]`
-        : match;
-    },
-  )}\n`;
-
-const writeJson = (file, value) => {
-  const target = path.join(root, file);
-  const expected = stableJson(value);
-  if (check) {
-    const actual = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
-    if (actual !== expected) failures.push(`${file} is stale`);
-    return;
-  }
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.writeFileSync(target, expected);
-};
-
-const validateAllowedAdapters = ({ label, allowedAdapters, resolvePath }) => {
-  if (allowedAdapters === undefined) return;
-  if (!Array.isArray(allowedAdapters)) {
-    failures.push(`${label}.allowedAdapters must be an array`);
-    return;
-  }
-  for (const [index, adapter] of allowedAdapters.entries()) {
-    const adapterLabel = `${label}.allowedAdapters[${index}]`;
-    if (!isRecord(adapter) || typeof adapter.path !== "string" || adapter.path.length === 0) {
-      failures.push(`${adapterLabel}.path must be a non-empty string`);
-      continue;
-    }
-    const target = resolvePath(adapter.path);
-    if (!fs.existsSync(path.join(root, target))) {
-      failures.push(`${adapterLabel}.path references missing file ${target}`);
-    }
-  }
-};
-
-const workspacePackagePaths = () => {
-  const rootPackage = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
-  const workspaces = Array.isArray(rootPackage.workspaces)
-    ? rootPackage.workspaces
-    : Array.isArray(rootPackage.workspaces?.packages)
-      ? rootPackage.workspaces.packages
-      : [];
-  const paths = new Set();
-
-  for (const workspace of workspaces) {
-    if (typeof workspace !== "string") continue;
-    if (workspace.endsWith("/*")) {
-      const base = workspace.slice(0, -2);
-      const baseDir = path.join(root, base);
-      if (!fs.existsSync(baseDir)) continue;
-      for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        const packagePath = `${base}/${entry.name}`;
-        if (fs.existsSync(path.join(root, packagePath, "package.json"))) {
-          paths.add(packagePath);
-        }
-      }
-      continue;
-    }
-
-    if (fs.existsSync(path.join(root, workspace, "package.json"))) {
-      paths.add(workspace);
-    }
-  }
-
-  return [...paths].sort((left, right) => left.localeCompare(right));
-};
-
-const scannerPackagesFromWorkspaces = (rootSource) => {
-  if (Object.hasOwn(rootSource, "packages")) {
-    failures.push("docs/effect-skill.json root.packages duplicates package ownership");
-  }
-
-  const packageDefaults = isRecord(rootSource.packageDefaults) ? rootSource.packageDefaults : {};
-  const packageOverrides = isRecord(rootSource.packageOverrides) ? rootSource.packageOverrides : {};
-  const paths = workspacePackagePaths();
-  const pathSet = new Set(paths);
-
-  for (const packagePath of Object.keys(packageOverrides)) {
-    if (!pathSet.has(packagePath)) {
-      failures.push(`${packagePath} has an effect scanner override but is not a workspace package`);
-    }
-  }
-
-  return paths
-    .map((packagePath) => {
-      const packagePathText = String(packagePath);
-      const override = isRecord(packageOverrides[packagePath]) ? packageOverrides[packagePath] : {};
-      if (override.scan === false) {
-        if (
-          typeof override.scanExclusionReason !== "string" ||
-          override.scanExclusionReason.trim().length === 0
-        ) {
-          failures.push(`${packagePathText} scan:false requires scanExclusionReason`);
-        }
-        return null;
-      }
-      const {
-        scan: _scan,
-        scanExclusionReason: _scanExclusionReason,
-        ...scannerOverride
-      } = override;
-      return {
-        path: packagePathText,
-        ...packageDefaults,
-        ...scannerOverride,
-      };
-    })
-    .filter(Boolean);
-};
-
-if (!isRecord(source.root)) {
-  failures.push("docs/effect-skill.json missing root manifest");
-} else {
-  validateAllowedAdapters({
-    label: "docs/effect-skill.json.root",
-    allowedAdapters: source.root.allowedAdapters,
-    resolvePath: (adapterPath) => adapterPath,
-  });
-  const {
-    packageDefaults: _packageDefaults,
-    packageOverrides: _packageOverrides,
-    ...rootSource
-  } = source.root;
-  writeJson(".effect-skill.json", {
-    packages: scannerPackagesFromWorkspaces(source.root),
-    ...rootSource,
-  });
-}
-
-const packageManifests =
-  typeof source.packageManifests === "object" && source.packageManifests !== null
-    ? source.packageManifests
-    : null;
-
-if (packageManifests === null) {
-  failures.push("docs/effect-skill.json missing packageManifests object");
-} else {
-  const expectedPackageFiles = new Set(
-    Object.keys(packageManifests).map((packagePath) => `${packagePath}/.effect-skill.json`),
-  );
-
-  for (const [packagePath, manifest] of Object.entries(packageManifests)) {
-    const packageJson = path.join(root, packagePath, "package.json");
-    if (!fs.existsSync(packageJson)) {
-      failures.push(`${packagePath} has an effect manifest but no package.json`);
-      continue;
-    }
-    validateAllowedAdapters({
-      label: `docs/effect-skill.json.packageManifests.${packagePath}`,
-      allowedAdapters: isRecord(manifest) ? manifest.allowedAdapters : undefined,
-      resolvePath: (adapterPath) => `${packagePath}/${adapterPath}`,
-    });
-    writeJson(`${packagePath}/.effect-skill.json`, manifest);
-  }
-
-  for (const workspacePath of workspacePackagePaths()) {
-    const packagePath = String(workspacePath);
-    const manifestFile = `${packagePath}/.effect-skill.json`;
-    if (fs.existsSync(path.join(root, manifestFile)) && !expectedPackageFiles.has(manifestFile)) {
-      failures.push(`${manifestFile} exists but is not declared in docs/effect-skill.json`);
-    }
-  }
-}
-
-if (failures.length > 0) {
-  console.error(failures.join("\n"));
-  process.exit(1);
-}
-
-console.log(check ? "effect skill manifests are current" : "effect skill manifests updated");