@piagent/platform 1.0.0

package/scripts/capability-catalog.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  CapabilityValidationError,
+  buildCapabilityCatalog,
+  resolveCapabilityProfile,
+  resolveCapabilityProfileDocument,
+  stableJson,
+  validateCapabilityPackageSource,
+  validateExternalActionProposal,
+  verifyCapabilityLock,
+  writeJsonAtomic,
+  writeProfileLockAtomic
+} from "../packages/piagent-core/capabilities/capability-core.js";
+import {
+  resolveCapabilitySourceRoots,
+  validateCapabilitySources,
+  vendorRemoteSource
+} from "../packages/piagent-core/capabilities/capability-sources.js";
+
+const platformRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const catalogPath = path.join(platformRoot, "catalog", "capabilities.json");
+
+function usage() {
+  process.stdout.write(`Usage:
+  piagent-capabilities catalog [--check | --write]
+  piagent-capabilities resolve --profile <profile.json> [--output <lock.json>] [--package-source <source>]
+  piagent-capabilities apply-profile --profile <source.json> --target <piagent-profile.json> [--package-source <source>] [--force]
+  piagent-capabilities doctor [--profile <profile.json>] [--lock <lock.json>] [--package-source <source>]
+  piagent-capabilities vendor --profile <profile.json> [--source <name>]
+  piagent-capabilities validate-source --package-source <source>
+  piagent-capabilities validate-action --file <proposal.json>
+
+Commands:
+  catalog          Build the deterministic capability catalog.
+  resolve          Resolve a profile to an auditable lock document.
+  apply-profile    Validate and update a profile with its lock as one fail-closed operation.
+  doctor           Validate packs, profile grants, and an optional lock document.
+  vendor           Fetch remote capability sources into the project. The only command that uses the network.
+  validate-source  Require a local source or an exact remote version, tag, or commit.
+  validate-action  Validate a dry-run external action proposal.
+`);
+}
+
+function parseArguments(values) {
+  const output = { positional: [], flags: new Map() };
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (!value.startsWith("--")) {
+      output.positional.push(value);
+      continue;
+    }
+    if (["--check", "--write", "--force", "--help"].includes(value)) {
+      if (output.flags.has(value)) throw new CapabilityValidationError(`duplicate option ${value}`);
+      output.flags.set(value, true);
+      continue;
+    }
+    if (!["--profile", "--output", "--target", "--lock", "--file", "--package-source", "--source"].includes(value)) throw new CapabilityValidationError(`unknown option ${value}`);
+    if (output.flags.has(value)) throw new CapabilityValidationError(`duplicate option ${value}`);
+    const next = values[index + 1];
+    if (!next || next.startsWith("--")) throw new CapabilityValidationError(`${value} requires a value`);
+    output.flags.set(value, next);
+    index += 1;
+  }
+  return output;
+}
+
+function assertAllowedFlags(flags, allowed) {
+  for (const flag of flags.keys()) {
+    if (!allowed.has(flag)) throw new CapabilityValidationError(`${flag} is not valid for this command`);
+  }
+}
+
+function requireExistingFile(value, option) {
+  if (!value) throw new CapabilityValidationError(`${option} is required`);
+  const absolute = path.resolve(value);
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new CapabilityValidationError(`${option} must identify a regular file`);
+  return fs.realpathSync(absolute);
+}
+
+function readJson(file) {
+  const stat = fs.statSync(file);
+  if (stat.size > 256 * 1024) throw new CapabilityValidationError(`${file} exceeds the 262144-byte limit`);
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new CapabilityValidationError(`${file} contains invalid JSON`, [error instanceof Error ? error.message : String(error)]);
+  }
+}
+
+function assertOutputBesideProfile(output, profile) {
+  const absolute = path.resolve(output);
+  const profileDirectory = path.dirname(profile);
+  const outputDirectory = fs.realpathSync(path.dirname(absolute));
+  if (outputDirectory !== profileDirectory) throw new CapabilityValidationError("--output must be in the same directory as --profile");
+  if (path.basename(absolute) !== "piagent-profile.lock.json") throw new CapabilityValidationError("--output filename must be piagent-profile.lock.json");
+  return path.join(outputDirectory, path.basename(absolute));
+}
+
+function packageSourceBesideProfile(profile) {
+  const settingsPath = path.join(path.dirname(profile), "settings.json");
+  if (!fs.existsSync(settingsPath)) return "workspace";
+  const settings = readJson(settingsPath);
+  const source = Array.isArray(settings.packages) ? settings.packages.find((item) => typeof item === "string" && item.length > 0) : undefined;
+  return source ?? "workspace";
+}
+
+// A profile lives at <project>/.pi/piagent-profile.json, so its project root is
+// two levels up. Local source paths and the vendor directory are resolved from
+// there, never from the platform, which is the whole point: a project uses its
+// own packs without forking this repository.
+function projectRootForProfile(profileFile) {
+  return path.dirname(path.dirname(profileFile));
+}
+
+function sourceRootsForProfile(profileFile) {
+  const declared = readJson(profileFile).capabilitySources;
+  if (declared === undefined) return undefined;
+  return resolveCapabilitySourceRoots(projectRootForProfile(profileFile), declared);
+}
+
+function runCatalog(flags) {
+  assertAllowedFlags(flags, new Set(["--check", "--write"]));
+  if (flags.has("--check") && flags.has("--write")) throw new CapabilityValidationError("--check and --write are mutually exclusive");
+  const catalog = buildCapabilityCatalog(platformRoot);
+  if (flags.has("--check")) {
+    if (!fs.existsSync(catalogPath)) throw new CapabilityValidationError("catalog/capabilities.json is missing");
+    const existing = fs.readFileSync(catalogPath, "utf8");
+    if (existing !== stableJson(catalog)) throw new CapabilityValidationError("catalog/capabilities.json is stale");
+    process.stdout.write(`${JSON.stringify({ ok: true, catalog: "catalog/capabilities.json", packs: catalog.packs.length })}\n`);
+    return;
+  }
+  if (flags.has("--write")) {
+    writeJsonAtomic(catalogPath, catalog);
+    process.stdout.write(`${JSON.stringify({ ok: true, catalog: "catalog/capabilities.json", packs: catalog.packs.length })}\n`);
+    return;
+  }
+  process.stdout.write(stableJson(catalog));
+}
+
+function runResolve(flags) {
+  assertAllowedFlags(flags, new Set(["--profile", "--output", "--package-source"]));
+  const profile = requireExistingFile(flags.get("--profile"), "--profile");
+  const packageSource = flags.get("--package-source") ?? "workspace";
+  const lock = resolveCapabilityProfile(platformRoot, profile, { packageSource, extraRoots: sourceRootsForProfile(profile) });
+  if (flags.has("--output")) {
+    const output = assertOutputBesideProfile(flags.get("--output"), profile);
+    writeJsonAtomic(output, lock);
+    process.stdout.write(`${JSON.stringify({ ok: true, output, packs: lock.packs.length })}\n`);
+    return;
+  }
+  process.stdout.write(stableJson(lock));
+}
+
+function runApplyProfile(flags) {
+  assertAllowedFlags(flags, new Set(["--profile", "--target", "--package-source", "--force"]));
+  const source = requireExistingFile(flags.get("--profile"), "--profile");
+  const targetValue = flags.get("--target");
+  if (!targetValue) throw new CapabilityValidationError("--target is required");
+  const target = path.resolve(targetValue);
+  if (path.basename(target) !== "piagent-profile.json") throw new CapabilityValidationError("--target filename must be piagent-profile.json");
+  const parent = fs.realpathSync(path.dirname(target));
+  const normalizedTarget = path.join(parent, path.basename(target));
+  if (fs.existsSync(normalizedTarget) && !flags.has("--force")) throw new CapabilityValidationError("target profile already exists; pass --force to replace it");
+  const profile = readJson(source);
+  const packageSource = flags.get("--package-source") ?? "workspace";
+  const lock = resolveCapabilityProfileDocument(platformRoot, profile, {
+    profileFile: path.basename(normalizedTarget),
+    packageSource,
+    extraRoots: profile.capabilitySources === undefined
+      ? undefined
+      : resolveCapabilitySourceRoots(projectRootForProfile(normalizedTarget), profile.capabilitySources)
+  });
+  const lockTarget = path.join(parent, "piagent-profile.lock.json");
+  writeProfileLockAtomic(normalizedTarget, profile, lockTarget, lock);
+  process.stdout.write(`${JSON.stringify({ ok: true, profile: normalizedTarget, lock: lockTarget, packs: lock.packs.length })}\n`);
+}
+
+function runDoctor(flags) {
+  assertAllowedFlags(flags, new Set(["--profile", "--lock", "--package-source"]));
+  const catalog = buildCapabilityCatalog(platformRoot);
+  const report = {
+    ok: true,
+    catalog: {
+      path: "catalog/capabilities.json",
+      packs: catalog.packs.length,
+      current: fs.existsSync(catalogPath) && fs.readFileSync(catalogPath, "utf8") === stableJson(catalog)
+    }
+  };
+  if (!report.catalog.current) throw new CapabilityValidationError("catalog/capabilities.json is missing or stale");
+  if (flags.has("--profile")) {
+    const profile = requireExistingFile(flags.get("--profile"), "--profile");
+    const packageSource = flags.get("--package-source") ?? packageSourceBesideProfile(profile);
+    const extraRoots = sourceRootsForProfile(profile);
+    const resolved = resolveCapabilityProfile(platformRoot, profile, { packageSource, extraRoots });
+    report.profile = {
+      path: profile,
+      projectId: resolved.profile.projectId,
+      packs: resolved.packs.map((pack) => `${pack.name}@${pack.version}`),
+      sources: (extraRoots ?? []).map((entry) => ({ name: entry.origin, source: entry.source })),
+      permissions: resolved.permissions
+    };
+    if (flags.has("--lock")) {
+      const lockFile = requireExistingFile(flags.get("--lock"), "--lock");
+      if (path.dirname(lockFile) !== path.dirname(profile)) throw new CapabilityValidationError("--lock must be in the same directory as --profile");
+      const verification = verifyCapabilityLock(platformRoot, profile, readJson(lockFile), { packageSource, extraRoots });
+      report.lock = {
+        path: lockFile,
+        current: verification.ok,
+        expectedDigest: verification.expectedDigest,
+        actualDigest: verification.actualDigest
+      };
+      if (!verification.ok) throw new CapabilityValidationError("capability lock is stale or has been modified");
+    }
+  } else if (flags.has("--lock")) {
+    throw new CapabilityValidationError("--lock requires --profile");
+  }
+  process.stdout.write(stableJson(report));
+}
+
+function runVendor(flags) {
+  assertAllowedFlags(flags, new Set(["--profile", "--source"]));
+  const profileFile = requireExistingFile(flags.get("--profile"), "--profile");
+  const projectRoot = projectRootForProfile(profileFile);
+  const declared = validateCapabilitySources(readJson(profileFile).capabilitySources, profileFile);
+  const remote = declared.filter((entry) => entry.source !== undefined);
+  const only = flags.get("--source");
+  if (only && !declared.some((entry) => entry.name === only)) {
+    throw new CapabilityValidationError(`${profileFile} declares no capability source named ${only}`);
+  }
+  const selected = only ? remote.filter((entry) => entry.name === only) : remote;
+
+  // Fetching replaces the vendored tree, so the digests are reported for the
+  // maintainer to compare against the commit they are about to make. This is
+  // the review step; nothing downstream reaches the network.
+  const vendored = selected.map((entry) => {
+    const result = vendorRemoteSource(projectRoot, entry);
+    return { name: result.name, source: result.source, digest: result.digest };
+  });
+  process.stdout.write(`${JSON.stringify({
+    ok: true,
+    projectRoot,
+    vendored,
+    localSources: declared.filter((entry) => entry.path !== undefined).map((entry) => entry.name)
+  })}\n`);
+}
+
+function runValidateAction(flags) {
+  assertAllowedFlags(flags, new Set(["--file"]));
+  const file = requireExistingFile(flags.get("--file"), "--file");
+  validateExternalActionProposal(readJson(file), { source: file });
+  process.stdout.write(`${JSON.stringify({ ok: true, file })}\n`);
+}
+
+function runValidateSource(flags) {
+  assertAllowedFlags(flags, new Set(["--package-source"]));
+  const source = flags.get("--package-source");
+  if (!source) throw new CapabilityValidationError("--package-source is required");
+  validateCapabilityPackageSource(source);
+  process.stdout.write(`${JSON.stringify({ ok: true, packageSource: source })}\n`);
+}
+
+try {
+  const parsed = parseArguments(process.argv.slice(2));
+  if (parsed.flags.has("--help") || parsed.positional.length === 0) {
+    usage();
+    process.exit(parsed.flags.has("--help") ? 0 : 2);
+  }
+  if (parsed.positional.length !== 1) throw new CapabilityValidationError("exactly one command is required");
+  const command = parsed.positional[0];
+  if (command === "catalog") runCatalog(parsed.flags);
+  else if (command === "resolve") runResolve(parsed.flags);
+  else if (command === "apply-profile") runApplyProfile(parsed.flags);
+  else if (command === "doctor") runDoctor(parsed.flags);
+  else if (command === "vendor") runVendor(parsed.flags);
+  else if (command === "validate-source") runValidateSource(parsed.flags);
+  else if (command === "validate-action") runValidateAction(parsed.flags);
+  else throw new CapabilityValidationError(`unknown command ${command}`);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`FAIL: ${message}\n`);
+  if (error instanceof CapabilityValidationError) {
+    for (const detail of error.errors) process.stderr.write(`- ${detail}\n`);
+  }
+  process.exit(1);
+}

package/scripts/check-runtime-advisories.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+// Applies the runtime advisory policy to `npm audit --json` read from stdin.
+//
+// The rule is still "no high or critical advisory in the pinned Pi host tree".
+// What this adds is a way to accept one named advisory when there is provably
+// nothing to do about it, without lowering the bar for everything else.
+//
+// An accepted advisory is not forgotten:
+//   - it must still be present, so the entry disappears the moment upstream
+//     ships a fix rather than lingering as scar tissue;
+//   - it expires on a date, so accepting it can never become permanent by
+//     inattention.
+// Both of those fail the audit. A gate that quietly stops checking is worse
+// than no gate, because it reads as a pass.
+
+const ACCEPTED = [
+  {
+    id: "GHSA-mh99-v99m-4gvg",
+    package: "brace-expansion",
+    reviewBy: "2026-08-25",
+    reason: [
+      "Denial of service only: brace expansion can exhaust memory and crash the",
+      "process. No privilege escalation and no data exposure.",
+      "Nothing can fix it from here. The Pi host publishes an npm-shrinkwrap.json",
+      "that pins brace-expansion 5.0.7, and a published shrinkwrap takes",
+      "precedence over consumer overrides, so the resolution cannot be changed",
+      "by this repository. Every released Pi host carries a high brace-expansion",
+      "advisory: 0.81.1 and 0.82.0 carry this one, and 0.80.x carry the previous",
+      "GHSA-3jxr-9vmj-r5cp, so pinning an older host only trades one for another.",
+      "The fix is a regenerated shrinkwrap in a Pi release."
+    ].join(" ")
+  }
+];
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let text = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => { text += chunk; });
+    process.stdin.on("end", () => resolve(text));
+    process.stdin.on("error", reject);
+  });
+}
+
+function advisoryIdsFor(vulnerability) {
+  // `via` mixes advisory objects with plain package names for transitive
+  // effects; only the objects carry an advisory URL.
+  return (vulnerability.via ?? [])
+    .filter((item) => item && typeof item === "object" && typeof item.url === "string")
+    .map((item) => item.url.match(/(GHSA-[a-z0-9-]+)/i)?.[1])
+    .filter(Boolean);
+}
+
+function today() {
+  // Date-only comparison in UTC keeps the expiry independent of the runner's
+  // timezone.
+  return new Date().toISOString().slice(0, 10);
+}
+
+const raw = await readStdin();
+let report;
+try {
+  report = JSON.parse(raw);
+} catch {
+  console.error("FAIL: npm audit did not produce parseable JSON");
+  process.exit(1);
+}
+
+if (report.auditReportVersion !== 2) {
+  // The shape this reads is version 2. Guessing at another shape could report
+  // a clean tree because it looked in the wrong place.
+  console.error(`FAIL: unsupported npm audit report version ${report.auditReportVersion ?? "(none)"}`);
+  process.exit(1);
+}
+
+const blocking = [];
+const seen = new Set();
+for (const [name, vulnerability] of Object.entries(report.vulnerabilities ?? {})) {
+  if (!["high", "critical"].includes(vulnerability.severity)) continue;
+  const ids = advisoryIdsFor(vulnerability);
+  if (ids.length === 0) {
+    blocking.push({ name, severity: vulnerability.severity, id: "(no advisory id)" });
+    continue;
+  }
+  for (const id of ids) {
+    seen.add(id);
+    const accepted = ACCEPTED.find((entry) => entry.id === id && entry.package === name);
+    if (!accepted) blocking.push({ name, severity: vulnerability.severity, id });
+  }
+}
+
+const failures = [];
+for (const entry of blocking) {
+  failures.push(`${entry.severity} advisory ${entry.id} in ${entry.name} is not accepted`);
+}
+for (const entry of ACCEPTED) {
+  if (!seen.has(entry.id)) {
+    failures.push(`accepted advisory ${entry.id} is no longer reported; remove it from ACCEPTED in ${"scripts/check-runtime-advisories.mjs"}`);
+  } else if (today() > entry.reviewBy) {
+    failures.push(`accepted advisory ${entry.id} passed its ${entry.reviewBy} review date; confirm it still applies or remove it`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error("FAIL: runtime advisory policy");
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+const counts = report.metadata?.vulnerabilities ?? {};
+const acceptedList = ACCEPTED.map((entry) => `${entry.id} (review by ${entry.reviewBy})`).join(", ");
+console.log(`PASS: no unaccepted high or critical advisory (${counts.high ?? 0} high, ${counts.critical ?? 0} critical)`);
+if (acceptedList) console.log(`Accepted, with reasons recorded in scripts/check-runtime-advisories.mjs: ${acceptedList}`);