coding-agent-skills 0.2.8

package/scripts/lib/adapter-repo-map.mjs

@@ -0,0 +1,358 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  ADAPTER_MANIFEST_FILENAME,
+  readSafeJsonFile,
+} from "./adapter-discovery.mjs";
+import { PILOT_VERSION, redactSensitiveText } from "./pack-rules.mjs";
+import {
+  readProjectAdapterDeclaration,
+  validateProjectAdapters,
+} from "./project-adapter-installation.mjs";
+
+const DEFAULT_CORE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+const REFUSED_BEHAVIOR = [
+  "no target project builds",
+  "no target project tests",
+  "no package installs",
+  "no runtime checks",
+  "no deployments",
+  "no migrations",
+  "no secret-file reads",
+  "no project writes",
+];
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function unique(values) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value))];
+}
+
+function describeApprovedPath(projectRoot, relativePath) {
+  if (
+    typeof relativePath !== "string" ||
+    !relativePath ||
+    relativePath.startsWith("/") ||
+    relativePath.split(/[\\/]+/).includes("..") ||
+    /(^|\/)\.env(?:\.|$)/.test(relativePath)
+  ) {
+    return {
+      path: String(relativePath),
+      status: "unsafe",
+      type: "unknown",
+    };
+  }
+
+  const absolute = path.resolve(projectRoot, relativePath);
+  if (!inside(projectRoot, absolute)) {
+    return {
+      path: relativePath,
+      status: "unsafe",
+      type: "unknown",
+    };
+  }
+
+  let current = projectRoot;
+  for (const segment of path.relative(projectRoot, absolute).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) {
+      return {
+        path: relativePath,
+        status: "missing",
+        type: "unknown",
+      };
+    }
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      return {
+        path: relativePath,
+        status: "symlink",
+        type: "unknown",
+      };
+    }
+  }
+
+  const stat = fs.lstatSync(absolute);
+  return {
+    path: relativePath,
+    status: "present",
+    type: stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other",
+  };
+}
+
+function gitSummary(projectRoot) {
+  const summary = {
+    root: null,
+    branchState: null,
+    hasUncommittedChanges: false,
+    warnings: [],
+  };
+
+  const revParse = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (revParse.status === 0) summary.root = revParse.stdout.trim();
+
+  const status = spawnSync("git", ["status", "--short", "--branch"], {
+    cwd: projectRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (status.status !== 0) {
+    summary.warnings.push("git status unavailable");
+    return summary;
+  }
+
+  const lines = status.stdout.split(/\r?\n/).filter(Boolean);
+  summary.branchState = lines[0] ?? null;
+  summary.hasUncommittedChanges = lines.length > 1;
+  if (summary.hasUncommittedChanges) {
+    summary.warnings.push("working tree has local changes; filenames omitted");
+  }
+  if (/\[(?:ahead|behind|gone|diverged)[^\]]*\]/i.test(summary.branchState ?? "")) {
+    summary.warnings.push("branch state indicates remote divergence; revalidate after update");
+  }
+  return summary;
+}
+
+function loadRepoMapAdapters(loaded) {
+  const adapters = [];
+  const errors = [];
+  const declarations = loaded.declaration.adapters ?? [];
+  const container = path.resolve(loaded.projectRoot, loaded.declaration.adapterRoot);
+  const manifestCandidates = [];
+
+  if (!inside(loaded.projectRoot, container) || !fs.existsSync(container)) {
+    return { adapters, errors: ["adapter-root-not-found"] };
+  }
+
+  for (const entry of fs.readdirSync(container, { withFileTypes: true })) {
+    if (entry.isSymbolicLink() || !entry.isDirectory()) continue;
+    const manifestPath = path.join(container, entry.name, ADAPTER_MANIFEST_FILENAME);
+    if (!inside(loaded.projectRoot, manifestPath) || !fs.existsSync(manifestPath)) continue;
+    const record = readSafeJsonFile(manifestPath);
+    if (!record.value) {
+      errors.push(...record.codes);
+      continue;
+    }
+    manifestCandidates.push({
+      manifestPath,
+      manifest: record.value,
+    });
+  }
+
+  for (const declaration of declarations) {
+    if (!(declaration.skillIds ?? []).includes("repo-map")) continue;
+    const match = manifestCandidates.find(
+      (candidate) => candidate.manifest.adapterId === declaration.id,
+    );
+    if (!match) {
+      errors.push("declared-repo-map-adapter-not-found");
+      continue;
+    }
+    adapters.push({
+      declaration,
+      manifestPath: path.relative(loaded.projectRoot, match.manifestPath),
+      manifest: match.manifest,
+    });
+  }
+
+  return { adapters, errors };
+}
+
+export function buildAdapterRepoMapReport(projectRootInput, options = {}) {
+  const coreRoot = path.resolve(options.coreRoot ?? DEFAULT_CORE_ROOT);
+  const validation = validateProjectAdapters(projectRootInput, { coreRoot });
+  if (!validation.ok) {
+    return {
+      ok: false,
+      status: "failed",
+      codes: validation.codes,
+      validation,
+    };
+  }
+  if (!validation.acceptedSkills.includes("repo-map")) {
+    return {
+      ok: false,
+      status: "failed",
+      codes: ["repo-map-not-enabled"],
+      validation,
+    };
+  }
+
+  const loaded = readProjectAdapterDeclaration(projectRootInput);
+  if (!loaded.ok) {
+    return {
+      ok: false,
+      status: "failed",
+      codes: loaded.codes,
+      validation,
+    };
+  }
+
+  const { adapters, errors } = loadRepoMapAdapters(loaded);
+  if (errors.length > 0 || adapters.length === 0) {
+    return {
+      ok: false,
+      status: "failed",
+      codes: errors.length > 0 ? unique(errors) : ["repo-map-adapter-not-found"],
+      validation,
+    };
+  }
+
+  const rootMarkers = adapters.flatMap(
+    (adapter) => adapter.manifest.project?.detection?.rootMarkers ?? [],
+  );
+  const maximumDepth = Math.max(
+    ...adapters.map((adapter) => adapter.manifest.project?.detection?.maximumDepth ?? 0),
+  );
+  const documentationPrecedence = unique(
+    adapters.flatMap((adapter) => adapter.manifest.extensions.documentationPrecedence),
+  ).map((relativePath) => describeApprovedPath(loaded.projectRoot, relativePath));
+  const safeReadPaths = unique(
+    adapters.flatMap((adapter) => adapter.manifest.extensions.safeReadPaths),
+  ).map((relativePath) => describeApprovedPath(loaded.projectRoot, relativePath));
+  const ignoredPaths = unique(
+    adapters.flatMap((adapter) => adapter.manifest.extensions.ignoredPaths),
+  );
+  const requiredEvidence = unique(
+    adapters.flatMap((adapter) => adapter.manifest.extensions.requiredEvidence),
+  );
+  const packageManagers = unique(
+    adapters.flatMap((adapter) => adapter.manifest.extensions.expectedPackageManagers),
+  );
+  const git = gitSummary(loaded.projectRoot);
+
+  return {
+    ok: true,
+    status: "complete",
+    coreVersion: PILOT_VERSION,
+    projectRoot: loaded.projectRoot,
+    declarationPath: loaded.declarationPath,
+    adapterRoot: loaded.declaration.adapterRoot,
+    projectId: loaded.declaration.projectId,
+    adapterIds: adapters.map((adapter) => adapter.manifest.adapterId).sort(),
+    manifestPaths: adapters.map((adapter) => adapter.manifestPath).sort(),
+    enabledSkills: ["repo-map"],
+    rootMarkers,
+    maximumDepth,
+    scope: "declared-project-root",
+    requireApprovalOutsideScope: true,
+    documentationPrecedence,
+    safeReadPaths,
+    ignoredPaths,
+    requiredEvidence,
+    packageManagers,
+    git,
+    warnings: unique([
+      ...git.warnings,
+      "adapter-aware repo-map is metadata-only and read-only",
+    ]),
+    refusedBehavior: REFUSED_BEHAVIOR,
+    validation,
+  };
+}
+
+function formatPathRecord(record, index, numbered = false) {
+  const prefix = numbered ? `${index + 1}.` : "-";
+  return `${prefix} ${record.path} (${record.type} ${record.status})`;
+}
+
+function formatList(title, values) {
+  if (!values.length) return [`## ${title}`, "- none declared"];
+  return [`## ${title}`, ...values.map((value) => `- ${value}`)];
+}
+
+export function renderAdapterRepoMapReport(report) {
+  if (!report.ok) {
+    return [
+      "# Adapter-Aware Repo Map",
+      "",
+      `Status: ${report.status}`,
+      `Rejection codes: ${(report.codes ?? []).join(", ")}`,
+    ].join("\n");
+  }
+
+  const lines = [
+    "# Adapter-Aware Repo Map",
+    "",
+    `Status: ${report.status}`,
+    `Core version: ${report.coreVersion}`,
+    `Project ID: ${report.projectId}`,
+    `Project root: ${redactSensitiveText(report.projectRoot)}`,
+    `Declaration: ${report.declarationPath}`,
+    `Adapter root: ${report.adapterRoot}`,
+    `Adapter IDs: ${report.adapterIds.join(", ")}`,
+    `Adapter manifests: ${report.manifestPaths.join(", ")}`,
+    `Enabled skills: ${report.enabledSkills.join(", ")}`,
+    "",
+    "## Git State",
+    `- Git root: ${redactSensitiveText(report.git.root ?? "not detected")}`,
+    `- Branch state: ${redactSensitiveText(report.git.branchState ?? "not detected")}`,
+    `- Local changes: ${report.git.hasUncommittedChanges ? "present; filenames omitted" : "not detected"}`,
+    "",
+    "## Adapter Bounds",
+    `- Scope: ${report.scope}`,
+    `- Maximum detection depth: ${report.maximumDepth}`,
+    `- Approval outside scope: ${report.requireApprovalOutsideScope ? "required" : "not declared"}`,
+    ...report.rootMarkers.map(
+      (marker) => `- Root marker: ${marker.kind} ${marker.path}`,
+    ),
+    "",
+    "## Documentation Precedence",
+    ...(report.documentationPrecedence.length
+      ? report.documentationPrecedence.map((record, index) =>
+          formatPathRecord(record, index, true),
+        )
+      : ["- none declared"]),
+    "",
+    "## Safe Read Paths",
+    ...(report.safeReadPaths.length
+      ? report.safeReadPaths.map((record, index) => formatPathRecord(record, index))
+      : ["- none declared"]),
+    "",
+    ...formatList("Ignored Paths", report.ignoredPaths),
+    "",
+    ...formatList("Required Evidence", report.requiredEvidence),
+    "",
+    ...formatList("Package Manager Hints", report.packageManagers),
+    "",
+    ...formatList("Warnings", report.warnings),
+    "",
+    ...formatList("Refused Behavior", report.refusedBehavior),
+    "",
+    "No target project build, test, runtime, deployment, migration, package installation, or secret-file read was performed.",
+  ];
+
+  return lines.join("\n");
+}
+
+export function adapterRepoMapCliResult(projectRoot, options = {}) {
+  if (!projectRoot) {
+    return {
+      exitCode: 2,
+      stream: "stderr",
+      lines: ["usage: node scripts/render-adapter-repo-map.mjs <project-root>"],
+    };
+  }
+
+  const report = buildAdapterRepoMapReport(projectRoot, options);
+  return {
+    exitCode: report.ok ? 0 : 1,
+    stream: report.ok ? "stdout" : "stderr",
+    lines: renderAdapterRepoMapReport(report).split("\n"),
+    report,
+  };
+}

package/scripts/lib/adapter-upgrade-chain.mjs

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { checkAdapterUpgrade } from "./adapter-upgrade.mjs";
+import { PILOT_VERSION, PREVIOUS_PILOT_VERSION } from "./pack-rules.mjs";
+import { readProjectAdapterDeclaration } from "./project-adapter-installation.mjs";
+import { writeSafeEvidenceJson } from "./safe-evidence-output.mjs";
+import { compareSemver, parseSemver } from "./semver.mjs";
+import { buildAdapterChainEvidence } from "./upgrade-evidence.mjs";
+
+const DEFAULT_CORE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+const REVISION_NAME = /^([0-9]{2})-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function baseFailure(code) {
+  return {
+    ok: false,
+    status: "failed",
+    revisionCount: 0,
+    transitionCount: 0,
+    passedTransitions: 0,
+    failedTransitions: 0,
+    transitions: [],
+    codes: [code],
+  };
+}
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function discoverRevisions(chainRootInput) {
+  const input = String(chainRootInput ?? "");
+  if (!input.trim()) return { ok: false, codes: ["missing-chain-root"] };
+  if (input.split(/[\\/]+/).includes("..")) {
+    return { ok: false, codes: ["root-path-traversal"] };
+  }
+
+  const chainRoot = path.resolve(input);
+  if (!fs.existsSync(chainRoot)) return { ok: false, codes: ["chain-root-not-found"] };
+  const stat = fs.lstatSync(chainRoot);
+  if (stat.isSymbolicLink()) return { ok: false, codes: ["symlink-escape"] };
+  if (!stat.isDirectory()) return { ok: false, codes: ["chain-root-not-directory"] };
+
+  const realRoot = fs.realpathSync(chainRoot);
+  const revisions = [];
+  const codes = new Set();
+
+  for (const entry of fs.readdirSync(realRoot, { withFileTypes: true })) {
+    if (/^\.env(?:\.|$)/.test(entry.name)) continue;
+    const match = REVISION_NAME.exec(entry.name);
+    if (!match) {
+      codes.add("unexpected-chain-entry");
+      continue;
+    }
+    const candidate = path.join(realRoot, entry.name);
+    if (entry.isSymbolicLink()) {
+      codes.add("symlink-escape");
+      continue;
+    }
+    if (!entry.isDirectory()) {
+      codes.add("revision-not-directory");
+      continue;
+    }
+    const realCandidate = fs.realpathSync(candidate);
+    if (!inside(realRoot, realCandidate)) {
+      codes.add("symlink-escape");
+      continue;
+    }
+    revisions.push({
+      order: Number(match[1]),
+      root: realCandidate,
+    });
+  }
+
+  revisions.sort((left, right) => left.order - right.order);
+  if (revisions.length < 2) codes.add("insufficient-chain-revisions");
+  revisions.forEach((revision, index) => {
+    if (revision.order !== index + 1) codes.add("non-contiguous-chain-order");
+  });
+
+  return {
+    ok: codes.size === 0,
+    chainRoot: realRoot,
+    revisions,
+    codes: [...codes].sort(),
+  };
+}
+
+function expectedVersion(projectRoot) {
+  const loaded = readProjectAdapterDeclaration(projectRoot);
+  const version = loaded.declaration?.core?.expectedVersion;
+  return parseSemver(version) ? version : null;
+}
+
+function pinKind(pin) {
+  return typeof pin === "string" && /^\d+\.\d+\.\d+$/.test(pin)
+    ? "stale-exact-pin"
+    : "stale-compatible-range";
+}
+
+function progressionCodes(beforeRoot, afterRoot) {
+  const before = readProjectAdapterDeclaration(beforeRoot);
+  const after = readProjectAdapterDeclaration(afterRoot);
+  if (!before.ok || !after.ok) return [];
+
+  const beforeVersion = before.declaration.core?.expectedVersion;
+  const afterVersion = after.declaration.core?.expectedVersion;
+  const comparison = compareSemver(afterVersion, beforeVersion);
+  if (comparison === null) return ["incompatible-core-chain"];
+  if (comparison === 0) return [pinKind(after.declaration.core?.versionPin)];
+
+  const parsedBefore = parseSemver(beforeVersion);
+  const parsedAfter = parseSemver(afterVersion);
+  const adjacentPatch =
+    parsedBefore &&
+    parsedAfter &&
+    parsedBefore[0] === parsedAfter[0] &&
+    parsedBefore[1] === parsedAfter[1] &&
+    parsedAfter[2] === parsedBefore[2] + 1;
+  const adjacentMinorBoundary =
+    parsedBefore &&
+    parsedAfter &&
+    parsedBefore[0] === parsedAfter[0] &&
+    parsedAfter[1] === parsedBefore[1] + 1 &&
+    parsedAfter[2] === 0;
+  const currentReleaseBoundary =
+    beforeVersion === PREVIOUS_PILOT_VERSION && afterVersion === PILOT_VERSION;
+  return adjacentPatch || adjacentMinorBoundary || currentReleaseBoundary
+    ? []
+    : ["incompatible-core-chain"];
+}
+
+export function checkAdapterUpgradeChain(chainRootInput, options = {}) {
+  const discovery = discoverRevisions(chainRootInput);
+  if (!discovery.ok) {
+    return {
+      ...baseFailure(discovery.codes[0]),
+      revisionCount: discovery.revisions?.length ?? 0,
+      codes: discovery.codes,
+    };
+  }
+
+  const coreRoot = path.resolve(options.coreRoot ?? DEFAULT_CORE_ROOT);
+  const transitions = [];
+  const chainCodes = new Set();
+
+  for (let index = 0; index < discovery.revisions.length - 1; index += 1) {
+    const beforeRoot = discovery.revisions[index].root;
+    const afterRoot = discovery.revisions[index + 1].root;
+    const targetCoreVersion = expectedVersion(afterRoot) ?? PILOT_VERSION;
+    const result = checkAdapterUpgrade(beforeRoot, afterRoot, {
+      coreRoot,
+      targetCoreVersion,
+    });
+    const codes = new Set([
+      ...result.codes,
+      ...progressionCodes(beforeRoot, afterRoot),
+    ]);
+    for (const code of codes) chainCodes.add(code);
+    transitions.push({
+      stepIndex: index + 1,
+      ok: codes.size === 0,
+      codes: [...codes].sort(),
+      result,
+    });
+  }
+
+  const lastVersion = expectedVersion(discovery.revisions.at(-1).root);
+  if (lastVersion !== PILOT_VERSION) chainCodes.add("chain-target-stale");
+
+  const firstContext = transitions[0]?.result.context?.before;
+  const lastContext = transitions.at(-1)?.result.context?.after;
+  const passedTransitions = transitions.filter((transition) => transition.ok).length;
+  const failedTransitions = transitions.length - passedTransitions;
+  const ok = chainCodes.size === 0 && failedTransitions === 0;
+
+  return {
+    ok,
+    status: ok ? "complete" : "failed",
+    revisionCount: discovery.revisions.length,
+    transitionCount: transitions.length,
+    passedTransitions,
+    failedTransitions,
+    transitions,
+    codes: [...chainCodes].sort(),
+    targetCoreVersion: PILOT_VERSION,
+    context: {
+      before: firstContext,
+      after: lastContext,
+    },
+  };
+}
+
+export function formatAdapterChainSummary(result) {
+  if (result.ok) {
+    return [
+      `adapter upgrade chain complete: ${result.revisionCount} revisions, ` +
+        `${result.transitionCount} transitions accepted`,
+    ];
+  }
+  return [
+    `adapter upgrade chain failed: ${result.failedTransitions} of ` +
+      `${result.transitionCount} transitions rejected`,
+    `rejection codes: ${result.codes.join(",")}`,
+  ];
+}
+
+export function adapterChainCliResult(chainRoot, options = {}) {
+  if (!chainRoot) {
+    return {
+      exitCode: 2,
+      stream: "stderr",
+      lines: [
+        "usage: node scripts/check-adapter-upgrade-chain.mjs " +
+          "<chain-root> [--json | --output <file>]",
+      ],
+    };
+  }
+
+  const result = checkAdapterUpgradeChain(chainRoot, options);
+  const evidence = buildAdapterChainEvidence(result, options);
+  if (options.output) {
+    const written = writeSafeEvidenceJson(options.output, evidence, {
+      baseDirectory: options.outputBase,
+    });
+    if (!written.ok) {
+      return {
+        exitCode: 2,
+        stream: "stderr",
+        lines: [`adapter chain evidence output failed: ${written.code}`],
+        result,
+        evidence,
+      };
+    }
+  }
+  if (options.json) {
+    return {
+      exitCode: result.ok ? 0 : 1,
+      stream: "stdout",
+      lines: [JSON.stringify(evidence, null, 2)],
+      result,
+      evidence,
+    };
+  }
+  return {
+    exitCode: result.ok ? 0 : 1,
+    stream: result.ok ? "stdout" : "stderr",
+    lines: [
+      ...formatAdapterChainSummary(result),
+      ...(options.output ? ["sanitized evidence output written"] : []),
+    ],
+    result,
+    evidence,
+  };
+}