coding-agent-skills 0.2.8

package/scripts/lib/project-adapter-installation.mjs

@@ -0,0 +1,327 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  ADAPTER_SCHEMA_VERSION,
+  EXTERNAL_ADAPTER_LOCATIONS,
+  readSafeJsonFile,
+  validateExternalAdapters,
+} from "./adapter-discovery.mjs";
+import { PILOT_SKILLS, PILOT_VERSION } from "./pack-rules.mjs";
+import { validateValue } from "./schema-validator.mjs";
+import { parseSemver, parseVersionPin, satisfiesVersionPin } from "./semver.mjs";
+
+export const PROJECT_DECLARATION_VERSION = "1.0.0";
+export const PROJECT_DECLARATION_LOCATIONS = [
+  ".coding-agent/skills.json",
+  "coding-agent.skills.json",
+];
+
+const DEFAULT_CORE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function baseFailure(code) {
+  return {
+    ok: false,
+    status: "failed",
+    acceptedAdapters: 0,
+    acceptedSkills: [],
+    codes: [code],
+  };
+}
+
+function inspectRelativePath(root, relative) {
+  if (
+    typeof relative !== "string" ||
+    relative.startsWith("/") ||
+    relative.split(/[\\/]+/).includes("..") ||
+    /(^|\/)\.env(?:\.|$)/.test(relative)
+  ) {
+    return ["unsafe-project-path"];
+  }
+
+  const candidate = path.resolve(root, relative);
+  if (!inside(root, candidate)) return ["unsafe-project-path"];
+
+  let current = root;
+  for (const segment of path.relative(root, candidate).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) break;
+    if (fs.lstatSync(current).isSymbolicLink()) return ["symlink-escape"];
+  }
+  return [];
+}
+
+function discoverDeclaration(projectRoot) {
+  const candidates = [];
+  const failures = [];
+
+  for (const relative of PROJECT_DECLARATION_LOCATIONS) {
+    const pathIssues = inspectRelativePath(projectRoot, relative);
+    if (pathIssues.length) {
+      failures.push(...pathIssues);
+      continue;
+    }
+    const file = path.join(projectRoot, relative);
+    if (!fs.existsSync(file)) continue;
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) {
+      failures.push("symlink-escape");
+    } else if (!stat.isFile()) {
+      failures.push("declaration-not-regular-file");
+    } else {
+      candidates.push({ file, relative });
+    }
+  }
+
+  if (failures.length) return { candidate: null, codes: failures };
+  if (candidates.length === 0) {
+    return { candidate: null, codes: ["missing-project-declaration"] };
+  }
+  if (candidates.length > 1) {
+    return { candidate: null, codes: ["ambiguous-project-declaration"] };
+  }
+  return { candidate: candidates[0], codes: [] };
+}
+
+function declarationSchema(coreRoot) {
+  const file = path.join(
+    coreRoot,
+    "schemas",
+    "project-adapter-installation.schema.json",
+  );
+  if (!fs.existsSync(file)) return null;
+  return readSafeJsonFile(file, { scanSensitive: false }).value;
+}
+
+function schemaCodes(errors) {
+  const codes = new Set();
+  for (const error of errors) {
+    codes.add("declaration-schema");
+    if (/adapterRoot/.test(error)) codes.add("invalid-adapter-location");
+    if (/expectedVersion|versionPin/.test(error)) codes.add("invalid-core-version");
+    if (/compatibleSkillIds|skillIds/.test(error)) codes.add("unsupported-skill-id");
+    if (/adapterSchemaVersion/.test(error)) codes.add("unsupported-adapter-version");
+    if (/noSecrets/.test(error)) codes.add("secret-guarantee-missing");
+    if (/evidenceOutput|approvalPolicyReference/.test(error)) {
+      codes.add("unsafe-project-path");
+    }
+  }
+  return [...codes];
+}
+
+function versionCodes(declaration, coreVersion) {
+  const codes = [];
+  const expected = declaration.core?.expectedVersion;
+  const pin = declaration.core?.versionPin;
+
+  if (!parseSemver(expected) || !parseVersionPin(pin)) {
+    codes.push("invalid-semver");
+    return codes;
+  }
+  if (expected !== coreVersion) codes.push("unsupported-core-version");
+  if (!satisfiesVersionPin(coreVersion, pin)) codes.push("core-pin-mismatch");
+  if (!satisfiesVersionPin(expected, pin)) codes.push("expected-version-outside-pin");
+  return codes;
+}
+
+function declarationCompatibilityCodes(declaration, discovery) {
+  const codes = [];
+  const declaredAdapters = new Map();
+
+  for (const adapter of declaration.adapters ?? []) {
+    if (declaredAdapters.has(adapter.id)) codes.push("duplicate-adapter-declaration");
+    declaredAdapters.set(adapter.id, adapter);
+    for (const skill of adapter.skillIds ?? []) {
+      if (!(declaration.compatibleSkillIds ?? []).includes(skill)) {
+        codes.push("skill-not-declared-compatible");
+      }
+    }
+  }
+
+  if (declaration.adapterSchemaVersion !== ADAPTER_SCHEMA_VERSION) {
+    codes.push("unsupported-adapter-version");
+  }
+
+  const actualAdapters = new Map();
+  for (const adapter of discovery.accepted) {
+    if (actualAdapters.has(adapter.adapterId)) codes.push("duplicate-installed-adapter");
+    actualAdapters.set(adapter.adapterId, adapter);
+    if (adapter.rootLocation !== declaration.adapterRoot) {
+      codes.push("adapter-location-mismatch");
+    }
+    if (adapter.projectId !== declaration.projectId) {
+      codes.push("adapter-project-mismatch");
+    }
+
+    const declared = declaredAdapters.get(adapter.adapterId);
+    if (!declared) {
+      codes.push("installed-adapter-not-declared");
+      continue;
+    }
+    if (declared.version !== adapter.adapterVersion) {
+      codes.push("adapter-version-mismatch");
+    }
+    const declaredSkills = [...(declared.skillIds ?? [])].sort();
+    if (JSON.stringify(declaredSkills) !== JSON.stringify(adapter.skills)) {
+      codes.push("adapter-skill-mismatch");
+    }
+  }
+
+  for (const adapterId of declaredAdapters.keys()) {
+    if (!actualAdapters.has(adapterId)) codes.push("declared-adapter-not-installed");
+  }
+
+  const actualSkills = [
+    ...new Set(discovery.accepted.flatMap((adapter) => adapter.skills)),
+  ].sort();
+  const declaredSkills = [...new Set(declaration.compatibleSkillIds ?? [])].sort();
+  if (JSON.stringify(actualSkills) !== JSON.stringify(declaredSkills)) {
+    codes.push("project-skill-set-mismatch");
+  }
+
+  return codes;
+}
+
+export function readProjectAdapterDeclaration(projectRootInput) {
+  const input = String(projectRootInput ?? "");
+  if (!input.trim()) return { ok: false, codes: ["missing-project-root"] };
+  if (input.split(/[\\/]+/).includes("..")) {
+    return { ok: false, codes: ["root-path-traversal"] };
+  }
+
+  const projectRoot = path.resolve(input);
+  if (!fs.existsSync(projectRoot)) {
+    return { ok: false, codes: ["project-root-not-found"] };
+  }
+  const rootStat = fs.lstatSync(projectRoot);
+  if (rootStat.isSymbolicLink()) return { ok: false, codes: ["symlink-escape"] };
+  if (!rootStat.isDirectory()) {
+    return { ok: false, codes: ["project-root-not-directory"] };
+  }
+
+  const realRoot = fs.realpathSync(projectRoot);
+  const declarationRecord = discoverDeclaration(realRoot);
+  if (!declarationRecord.candidate) {
+    return {
+      ok: false,
+      codes: [...new Set(declarationRecord.codes)],
+    };
+  }
+
+  const parsed = readSafeJsonFile(declarationRecord.candidate.file);
+  if (!parsed.value) {
+    return {
+      ok: false,
+      codes: parsed.codes,
+    };
+  }
+
+  return {
+    ok: true,
+    projectRoot: realRoot,
+    declarationPath: declarationRecord.candidate.relative,
+    declaration: parsed.value,
+    codes: [],
+  };
+}
+
+export function validateProjectAdapters(projectRootInput, options = {}) {
+  const loaded = readProjectAdapterDeclaration(projectRootInput);
+  if (!loaded.ok) {
+    return {
+      ...baseFailure(loaded.codes[0]),
+      codes: loaded.codes,
+    };
+  }
+
+  const coreRoot = path.resolve(options.coreRoot ?? DEFAULT_CORE_ROOT);
+  const coreVersion = options.coreVersion ?? PILOT_VERSION;
+  const schema = declarationSchema(coreRoot);
+  if (!schema) return baseFailure("project-declaration-schema-unavailable");
+
+  const realRoot = loaded.projectRoot;
+  const declaration = loaded.declaration;
+  const codes = new Set(schemaCodes(validateValue(schema, declaration)));
+
+  if (declaration.declarationVersion !== PROJECT_DECLARATION_VERSION) {
+    codes.add("unsupported-declaration-version");
+  }
+  if (!EXTERNAL_ADAPTER_LOCATIONS.includes(declaration.adapterRoot)) {
+    codes.add("invalid-adapter-location");
+  }
+  for (const relative of [
+    declaration.adapterRoot,
+    declaration.evidenceOutput,
+    declaration.approvalPolicyReference,
+  ]) {
+    for (const code of inspectRelativePath(realRoot, relative)) codes.add(code);
+  }
+  for (const code of versionCodes(declaration, coreVersion)) codes.add(code);
+  if (declaration.noSecrets !== true) codes.add("secret-guarantee-missing");
+  if (
+    declaration.validationCommand !==
+    "node <shared-core>/scripts/validate-project-adapters.mjs <project-root>"
+  ) {
+    codes.add("invalid-validation-command");
+  }
+
+  const discovery = validateExternalAdapters(realRoot, { coreRoot, coreVersion });
+  for (const record of [...discovery.rejected, ...discovery.failures]) {
+    for (const code of record.codes) codes.add(code);
+  }
+  if (discovery.discovered === 0) codes.add("no-project-adapters");
+  for (const code of declarationCompatibilityCodes(declaration, discovery)) {
+    codes.add(code);
+  }
+
+  const acceptedSkills = [
+    ...new Set(discovery.accepted.flatMap((adapter) => adapter.skills)),
+  ].filter((skill) => PILOT_SKILLS.includes(skill)).sort();
+  return {
+    ok: codes.size === 0,
+    status: codes.size === 0 ? "complete" : "failed",
+    acceptedAdapters: discovery.accepted.length,
+    acceptedSkills,
+    codes: [...codes].sort(),
+  };
+}
+
+export function formatProjectAdapterSummary(result) {
+  if (result.ok) {
+    return [
+      `project adapter validation complete: ${result.acceptedAdapters} adapters, ` +
+        `${result.acceptedSkills.length} skills, core pin accepted`,
+    ];
+  }
+  return [
+    `project adapter validation failed: ${result.acceptedAdapters} adapters accepted`,
+    `rejection codes: ${result.codes.join(",")}`,
+  ];
+}
+
+export function projectAdapterCliResult(projectRoot, options = {}) {
+  if (!projectRoot) {
+    return {
+      exitCode: 2,
+      stream: "stderr",
+      lines: ["usage: node scripts/validate-project-adapters.mjs <project-root>"],
+    };
+  }
+  const result = validateProjectAdapters(projectRoot, options);
+  return {
+    exitCode: result.ok ? 0 : 1,
+    stream: result.ok ? "stdout" : "stderr",
+    lines: formatProjectAdapterSummary(result),
+    result,
+  };
+}

package/scripts/lib/safe-evidence-output.mjs

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function resolveSafeEvidenceOutput(outputPath, options = {}) {
+  const value = String(outputPath ?? "");
+  if (!value.trim()) return { ok: false, code: "missing-output-path" };
+  if (path.isAbsolute(value) || value.split(/[\\/]+/).includes("..")) {
+    return { ok: false, code: "unsafe-output-path" };
+  }
+  if (
+    value.split(/[\\/]+/).some((segment) => /^\.env(?:\.|$)/.test(segment)) ||
+    path.extname(value) !== ".json"
+  ) {
+    return { ok: false, code: "unsafe-output-path" };
+  }
+
+  const base = path.resolve(options.baseDirectory ?? process.cwd());
+  if (
+    !fs.existsSync(base) ||
+    fs.lstatSync(base).isSymbolicLink() ||
+    !fs.lstatSync(base).isDirectory()
+  ) {
+    return { ok: false, code: "output-base-unavailable" };
+  }
+  const target = path.resolve(base, value);
+  if (!inside(base, target)) return { ok: false, code: "unsafe-output-path" };
+
+  let current = base;
+  for (const segment of path.relative(base, target).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (!fs.existsSync(current)) break;
+    if (fs.lstatSync(current).isSymbolicLink()) {
+      return { ok: false, code: "output-symlink-escape" };
+    }
+  }
+
+  const parent = path.dirname(target);
+  if (!fs.existsSync(parent) || !fs.lstatSync(parent).isDirectory()) {
+    return { ok: false, code: "output-parent-unavailable" };
+  }
+  if (fs.existsSync(target)) return { ok: false, code: "output-already-exists" };
+  return { ok: true, target };
+}
+
+export function writeSafeEvidenceJson(outputPath, evidence, options = {}) {
+  const resolved = resolveSafeEvidenceOutput(outputPath, options);
+  if (!resolved.ok) return resolved;
+
+  try {
+    fs.writeFileSync(resolved.target, `${JSON.stringify(evidence, null, 2)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+  } catch {
+    return { ok: false, code: "output-write-failed" };
+  }
+  return { ok: true, code: "evidence-output-written" };
+}
+
+export function parseEvidenceCliArguments(argv, positionalCount) {
+  const positional = argv.slice(0, positionalCount);
+  const flags = argv.slice(positionalCount);
+  let json = false;
+  let output = null;
+
+  for (let index = 0; index < flags.length; index += 1) {
+    const flag = flags[index];
+    if (flag === "--json" && !json && output === null) {
+      json = true;
+      continue;
+    }
+    if (flag === "--output" && !json && output === null && flags[index + 1]) {
+      output = flags[index + 1];
+      index += 1;
+      continue;
+    }
+    return { ok: false, positional, json: false, output: null };
+  }
+
+  return {
+    ok: positional.every((value) => typeof value === "string" && value.length > 0),
+    positional,
+    json,
+    output,
+  };
+}

package/scripts/lib/schema-validator.mjs

@@ -0,0 +1,146 @@
+import { isDeepStrictEqual } from "node:util";
+
+function valueType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (Number.isInteger(value)) return "integer";
+  return typeof value;
+}
+
+function matchesType(value, expected) {
+  if (expected === "number") return typeof value === "number" && Number.isFinite(value);
+  if (expected === "integer") return Number.isInteger(value);
+  if (expected === "object") {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+  }
+  return valueType(value) === expected;
+}
+
+function decodePointerPart(part) {
+  return part.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+function resolveLocalReference(rootSchema, reference) {
+  if (!reference.startsWith("#/")) {
+    throw new Error(`only local schema references are supported: ${reference}`);
+  }
+
+  return reference
+    .slice(2)
+    .split("/")
+    .map(decodePointerPart)
+    .reduce((current, part) => current?.[part], rootSchema);
+}
+
+function childPath(parent, key) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(key))
+    ? `${parent}.${key}`
+    : `${parent}[${JSON.stringify(String(key))}]`;
+}
+
+function validateNode(schema, value, currentPath, rootSchema, errors) {
+  if (typeof schema === "boolean") {
+    if (!schema) errors.push(`${currentPath}: value is rejected by the schema`);
+    return;
+  }
+
+  if (schema.$ref) {
+    const referenced = resolveLocalReference(rootSchema, schema.$ref);
+    if (!referenced) {
+      errors.push(`${currentPath}: unresolved schema reference ${schema.$ref}`);
+      return;
+    }
+    validateNode(referenced, value, currentPath, rootSchema, errors);
+  }
+
+  if ("const" in schema && !isDeepStrictEqual(value, schema.const)) {
+    errors.push(`${currentPath}: expected constant ${JSON.stringify(schema.const)}`);
+  }
+
+  if (schema.enum && !schema.enum.some((candidate) => isDeepStrictEqual(candidate, value))) {
+    errors.push(`${currentPath}: value is not in the allowed enum`);
+  }
+
+  if (schema.type) {
+    const expectedTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!expectedTypes.some((expected) => matchesType(value, expected))) {
+      errors.push(
+        `${currentPath}: expected ${expectedTypes.join(" or ")}, received ${valueType(value)}`,
+      );
+      return;
+    }
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      errors.push(`${currentPath}: string is shorter than ${schema.minLength}`);
+    }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${currentPath}: string does not match ${schema.pattern}`);
+    }
+    if (
+      schema.format === "date-time" &&
+      (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value) ||
+        Number.isNaN(Date.parse(value)))
+    ) {
+      errors.push(`${currentPath}: invalid UTC date-time`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      errors.push(`${currentPath}: expected at least ${schema.minItems} items`);
+    }
+    if (schema.uniqueItems) {
+      for (let index = 0; index < value.length; index += 1) {
+        if (value.slice(0, index).some((item) => isDeepStrictEqual(item, value[index]))) {
+          errors.push(`${currentPath}[${index}]: duplicate array item`);
+        }
+      }
+    }
+    if (schema.items) {
+      value.forEach((item, index) => {
+        validateNode(schema.items, item, `${currentPath}[${index}]`, rootSchema, errors);
+      });
+    }
+  }
+
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    for (const required of schema.required ?? []) {
+      if (!Object.hasOwn(value, required)) {
+        errors.push(`${currentPath}: missing required property ${required}`);
+      }
+    }
+
+    for (const [key, item] of Object.entries(value)) {
+      if (schema.properties?.[key]) {
+        validateNode(
+          schema.properties[key],
+          item,
+          childPath(currentPath, key),
+          rootSchema,
+          errors,
+        );
+      } else if (schema.additionalProperties === false) {
+        errors.push(`${childPath(currentPath, key)}: additional property is not allowed`);
+      } else if (
+        schema.additionalProperties &&
+        typeof schema.additionalProperties === "object"
+      ) {
+        validateNode(
+          schema.additionalProperties,
+          item,
+          childPath(currentPath, key),
+          rootSchema,
+          errors,
+        );
+      }
+    }
+  }
+}
+
+export function validateValue(schema, value) {
+  const errors = [];
+  validateNode(schema, value, "$", schema, errors);
+  return errors;
+}

package/scripts/lib/semver.mjs

@@ -0,0 +1,54 @@
+const NUMBER = "(?:0|[1-9]\\d*)";
+const VERSION_PATTERN = new RegExp(`^(${NUMBER})\\.(${NUMBER})\\.(${NUMBER})$`);
+const COMPARATOR_PATTERN = new RegExp(
+  `^(>=|<=|>|<|=)?(${NUMBER}\\.${NUMBER}\\.${NUMBER})$`,
+);
+
+export function parseSemver(value) {
+  const match = VERSION_PATTERN.exec(String(value ?? ""));
+  if (!match) return null;
+  return match.slice(1).map(Number);
+}
+
+export function compareSemver(left, right) {
+  const a = Array.isArray(left) ? left : parseSemver(left);
+  const b = Array.isArray(right) ? right : parseSemver(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] < b[index]) return -1;
+    if (a[index] > b[index]) return 1;
+  }
+  return 0;
+}
+
+export function parseVersionPin(value) {
+  const text = String(value ?? "").trim();
+  if (parseSemver(text)) return [{ operator: "=", version: text }];
+
+  const tokens = text.split(/\s+/).filter(Boolean);
+  if (tokens.length < 2 || tokens.length > 4) return null;
+
+  const comparators = [];
+  for (const token of tokens) {
+    const match = COMPARATOR_PATTERN.exec(token);
+    if (!match) return null;
+    comparators.push({ operator: match[1] || "=", version: match[2] });
+  }
+  return comparators;
+}
+
+export function satisfiesVersionPin(version, pin) {
+  if (!parseSemver(version)) return false;
+  const comparators = parseVersionPin(pin);
+  if (!comparators) return false;
+
+  return comparators.every(({ operator, version: target }) => {
+    const comparison = compareSemver(version, target);
+    if (operator === "=") return comparison === 0;
+    if (operator === ">") return comparison > 0;
+    if (operator === ">=") return comparison >= 0;
+    if (operator === "<") return comparison < 0;
+    if (operator === "<=") return comparison <= 0;
+    return false;
+  });
+}