@clossys/launcher 0.3.1 → 0.5.0

package/dist/setup-template-scripts.js

@@ -0,0 +1,568 @@
+/**
+ * Pure renderers for the setup template acts' script and workflow files.
+ *
+ * Each renderer returns exact file bytes; path scope optionally takes the
+ * supported authoring agent provenance. With no input it preserves legacy
+ * bytes. Rendering is pure, so
+ * the text is a pure function of this module alone: no clock, no randomness,
+ * no filesystem, no environment. Everything that reads a clock or a
+ * repository does so inside the emitted script, when a workflow runs it, and
+ * never here.
+ *
+ * Files rendered here:
+ * - `.github/scripts/clossys-collect-adoption-snapshot.mjs`
+ * - `.github/workflows/clossys-adoption-evidence.yml`
+ * - `.github/workflows/clossys-path-scope.yml`
+ *
+ * The path-scope script is standalone, so it runs the same under a test as it
+ * does inside the workflow that embeds it.
+ */
+/**
+ * The path patterns an apply pull request may own, in the change-set
+ * contract's order. The path-scope script embeds this list.
+ */
+export const OWNED_PATH_PATTERNS = [
+    "clossys/**",
+    ".agents/skills/clossys-*/**",
+    ".claude/skills/clossys-*",
+    ".cursor/skills/clossys-*",
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".starter/request.json",
+    ".github/workflows/clossys-*",
+    ".github/scripts/clossys-*",
+    "package.json",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    ".yarnrc.yml",
+    "pnpm-workspace.yaml",
+    "**/repository-profile.json",
+    "**/repository-declaration.json",
+];
+const CHECKOUT = "actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0";
+const UPLOAD_ARTIFACT = "actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7";
+const HEREDOC_TERMINATOR = "CLOSSYS_PATH_SCOPE";
+// ---------------------------------------------------------------------------
+// The snapshot collector script
+// ---------------------------------------------------------------------------
+// The emitted scripts' module import lines are kept as quoted strings so that no
+// line of this module's own source begins with an import statement.
+const COLLECTOR_IMPORTS = [
+    'import { createHash } from "node:crypto";',
+    'import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";',
+    'import { dirname, resolve, sep } from "node:path";',
+].join("\n");
+const PATH_SCOPE_IMPORTS = 'import { execFileSync } from "node:child_process";';
+const SNAPSHOT_COLLECTOR = String.raw `// Clossys adoption snapshot collector.
+//
+// This script is consumer-owned: it lives in this repository, and you review
+// and change it like any other code here. It is uncredentialed. It reads no
+// package or registry secret, installs nothing, and runs no package, Advisor
+// or target command. The trusted decision job never reads or trusts what this
+// script produces, because a pull request controls the workflow that runs it
+// and can change this file.
+//
+// Usage: node clossys-collect-adoption-snapshot.mjs <request.json> <output-dir>
+//
+// From the request it takes snapshot.repository, evidence.assessment and
+// evidence.targetInput. It copies exactly those two files, found relative to
+// the working directory (the repository root), into <output-dir>, and writes
+// <output-dir>/snapshot.json with the pull request facts from the environment
+// (REPOSITORY, PR_NUMBER, BASE_SHA, HEAD_SHA, RUN_ID) and each file's size and
+// SHA-256.
+//
+// It refuses, with exit code 2 and one line on stderr, a request or an
+// environment value it cannot vouch for; an evidence path that is not a
+// normalized relative path, is missing, is a symlink, is not a regular file, or
+// is larger than 524288 bytes; and an output directory that already holds
+// anything. A refusal leaves nothing half-written.
+${COLLECTOR_IMPORTS}
+
+const NAME = "clossys-collect-adoption-snapshot";
+const MAX_BYTES = 524288;
+const COMMIT = /^[0-9a-f]{40}$/;
+
+class Refusal extends Error {}
+
+function refuse(message) {
+  throw new Refusal(message);
+}
+
+function show(text) {
+  return String(text).replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "?").slice(0, 200);
+}
+
+function env(name) {
+  const value = process.env[name];
+  return typeof value === "string" ? value : "";
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNormalizedRelativePath(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 240) return false;
+  if (value.includes("\\") || value.startsWith("/") || /^[A-Za-z]:/.test(value)) return false;
+  if (/[\u0000-\u001f\u007f]/.test(value)) return false;
+  return value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+
+function sha256(data) {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+function readBounded(path, label) {
+  let link;
+  try {
+    link = lstatSync(path);
+  } catch {
+    refuse(label + " is missing or unreadable");
+  }
+  if (link.isSymbolicLink() || !link.isFile()) refuse(label + " is not a regular non-symlink file");
+  if (link.size > MAX_BYTES) refuse(label + " is larger than " + MAX_BYTES + " bytes");
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  } catch {
+    refuse(label + " cannot be opened");
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_BYTES) refuse(label + " is not a bounded regular file");
+    const content = readFileSync(fd);
+    if (content.length > MAX_BYTES) refuse(label + " is larger than " + MAX_BYTES + " bytes");
+    return content;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function readEvidence(root, path) {
+  const label = "evidence file " + show(path);
+  const candidate = resolve(root, path);
+  if (!candidate.startsWith(root + sep)) refuse(label + " is outside the working directory");
+  let real;
+  try {
+    real = realpathSync(candidate);
+  } catch {
+    refuse(label + " is missing or unreadable");
+  }
+  if (real !== candidate) refuse(label + " passes through a symbolic link");
+  return readBounded(candidate, label);
+}
+
+function readRequest(requestArgument) {
+  const content = readBounded(resolve(requestArgument), "request file");
+  let request;
+  try {
+    request = JSON.parse(content.toString("utf8"));
+  } catch {
+    refuse("the request is not valid JSON");
+  }
+  if (!isRecord(request) || !isRecord(request.snapshot) || typeof request.snapshot.repository !== "string" || request.snapshot.repository === "") {
+    refuse("the request has no snapshot.repository");
+  }
+  if (!isRecord(request.evidence)) refuse("the request has no evidence paths");
+  const assessment = request.evidence.assessment;
+  const targetInput = request.evidence.targetInput;
+  if (!isNormalizedRelativePath(assessment)) refuse("the request's evidence.assessment is not a normalized relative path");
+  if (!isNormalizedRelativePath(targetInput)) refuse("the request's evidence.targetInput is not a normalized relative path");
+  if (assessment === targetInput) refuse("the request names the same evidence path twice; the two must be distinct");
+  for (const path of [assessment, targetInput]) {
+    if (path.toLowerCase() === "snapshot.json") refuse("the request's evidence path " + show(path) + " collides with snapshot.json");
+  }
+  return { repository: request.snapshot.repository, paths: [assessment, targetInput] };
+}
+
+function readEnvironment(repository) {
+  if (env("REPOSITORY") !== repository) refuse("REPOSITORY does not equal the request's snapshot.repository");
+  const pullRequest = env("PR_NUMBER");
+  if (!/^[1-9][0-9]*$/.test(pullRequest) || !Number.isSafeInteger(Number(pullRequest))) refuse("PR_NUMBER is not a positive safe integer");
+  const baseSha = env("BASE_SHA");
+  if (!COMMIT.test(baseSha)) refuse("BASE_SHA is not a 40-character lowercase hex commit");
+  const headSha = env("HEAD_SHA");
+  if (!COMMIT.test(headSha)) refuse("HEAD_SHA is not a 40-character lowercase hex commit");
+  const runId = env("RUN_ID");
+  if (!/^[0-9]+$/.test(runId)) refuse("RUN_ID is not a non-empty run of digits");
+  return { pullRequestNumber: Number(pullRequest), baseSha, headSha, runId };
+}
+
+function checkOutputDirectory(out) {
+  let stat = null;
+  try {
+    stat = lstatSync(out);
+  } catch (error) {
+    if (!error || error.code !== "ENOENT") refuse("the output directory cannot be inspected");
+  }
+  if (stat === null) return;
+  if (stat.isSymbolicLink() || !stat.isDirectory()) refuse("the output path exists and is not a directory");
+  if (readdirSync(out).length > 0) refuse("the output directory already exists and is not empty");
+}
+
+function write(out, files, manifestText) {
+  let firstCreated;
+  try {
+    firstCreated = mkdirSync(out, { recursive: true });
+    for (const file of files) {
+      const target = resolve(out, file.path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, file.content, { flag: "wx" });
+    }
+    writeFileSync(resolve(out, "snapshot.json"), manifestText, { flag: "wx" });
+  } catch {
+    try {
+      if (firstCreated !== undefined) rmSync(firstCreated, { recursive: true, force: true });
+      else for (const name of readdirSync(out)) rmSync(resolve(out, name), { recursive: true, force: true });
+    } catch {
+      // Nothing more can be done; the refusal below still reports the failure.
+    }
+    refuse("the snapshot could not be written");
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length !== 2 || args[0] === "" || args[1] === "") refuse("usage: node clossys-collect-adoption-snapshot.mjs <request.json> <output-dir>");
+  const out = resolve(args[1]);
+  const request = readRequest(args[0]);
+  const facts = readEnvironment(request.repository);
+  checkOutputDirectory(out);
+
+  const root = realpathSync(process.cwd());
+  const files = request.paths.map((path) => ({ path, content: readEvidence(root, path) }));
+  files.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+
+  const before = {
+    schemaVersion: 1,
+    provider: "github-actions",
+    eventName: "pull_request",
+    repository: request.repository,
+    pullRequestNumber: facts.pullRequestNumber,
+    baseSha: facts.baseSha,
+    headSha: facts.headSha,
+    workflowRunId: facts.runId,
+    artifactName: "adoption-snapshot-" + facts.runId,
+  };
+  const capturedAt = new Date().toISOString();
+  const listed = files.map((file) => ({ path: file.path, size: file.content.length, sha256: sha256(file.content) }));
+  const digest = sha256(Buffer.from(JSON.stringify({ ...before, capturedAt, files: listed }, null, 2), "utf8"));
+  const manifest = { ...before, digest, capturedAt, files: listed };
+
+  write(out, files, JSON.stringify(manifest, null, 2) + "\n");
+  console.log(NAME + ": wrote " + files.length + " evidence file(s) and snapshot.json");
+  return 0;
+}
+
+try {
+  process.exitCode = main();
+} catch (error) {
+  console.error(NAME + ": " + (error instanceof Refusal ? show(error.message) : "unexpected failure"));
+  process.exitCode = 2;
+}
+`;
+/** The bytes of `.github/scripts/clossys-collect-adoption-snapshot.mjs`. */
+export function renderSnapshotCollector() {
+    return SNAPSHOT_COLLECTOR;
+}
+// ---------------------------------------------------------------------------
+// The adoption evidence workflow
+// ---------------------------------------------------------------------------
+const ADOPTION_EVIDENCE_WORKFLOW = [
+    "# Clossys adoption evidence, written by Clossys Launcher.",
+    "#",
+    "# This is the uncredentialed half of the adoption check. It runs on",
+    "# pull_request, checks out the pull request head with no persisted credential,",
+    "# and uploads a small snapshot of two evidence files as an artifact. It holds no",
+    "# secret, installs nothing, and runs no package, Advisor or target command.",
+    "#",
+    "# The artifact this workflow uploads is NOT read by the trusted decision job.",
+    "# A pull request controls this workflow and can edit it, so what it produces is",
+    "# not evidence the decision trusts.",
+    "#",
+    "# The collector is a plain script in this repository:",
+    "# .github/scripts/clossys-collect-adoption-snapshot.mjs. It reads the two",
+    "# evidence paths named by .starter/request.json and copies exactly those files.",
+    "name: Clossys adoption evidence",
+    "",
+    "on:",
+    "  pull_request:",
+    "    types: [opened, synchronize, reopened]",
+    "",
+    "permissions:",
+    "  contents: read",
+    "",
+    "jobs:",
+    "  collect-adoption-evidence:",
+    "    runs-on: ubuntu-latest",
+    "    timeout-minutes: 10",
+    "    steps:",
+    "      - name: Check out the pull request head",
+    `        uses: ${CHECKOUT}`,
+    "        with:",
+    "          ref: ${{ github.event.pull_request.head.sha }}",
+    "          persist-credentials: false",
+    "",
+    "      # Values reach the script only through the environment, never through its",
+    "      # text. The script runs no package, Advisor or target command.",
+    "      - name: Collect the snapshot",
+    "        env:",
+    "          REPOSITORY: ${{ github.repository }}",
+    "          PR_NUMBER: ${{ github.event.pull_request.number }}",
+    "          BASE_SHA: ${{ github.event.pull_request.base.sha }}",
+    "          HEAD_SHA: ${{ github.event.pull_request.head.sha }}",
+    "          RUN_ID: ${{ github.run_id }}",
+    "        run: |",
+    "          node .github/scripts/clossys-collect-adoption-snapshot.mjs \\",
+    "            .starter/request.json \\",
+    '            "$RUNNER_TEMP/adoption-snapshot"',
+    "",
+    "      - name: Upload the snapshot",
+    `        uses: ${UPLOAD_ARTIFACT}`,
+    "        with:",
+    "          name: adoption-snapshot-${{ github.run_id }}",
+    "          path: ${{ runner.temp }}/adoption-snapshot",
+    "          if-no-files-found: error",
+    "          retention-days: 7",
+    "",
+].join("\n");
+/** The bytes of `.github/workflows/clossys-adoption-evidence.yml`. */
+export function renderAdoptionEvidenceWorkflow() {
+    return ADOPTION_EVIDENCE_WORKFLOW;
+}
+// ---------------------------------------------------------------------------
+// The path-scope script and workflow
+// ---------------------------------------------------------------------------
+const PATH_SCOPE_SCRIPT = String.raw `// Clossys path scope.
+//
+// Fails a Clossys apply pull request that changes a file Clossys does not own,
+// or an owned file the pull request's own ledger does not name. It reads git
+// only: git diff and git show, run without a shell. It never runs, loads or
+// evaluates anything from the checked-out files.
+//
+// Inputs come from the environment only: HEAD_REF (the pull request head
+// branch), BASE_SHA and HEAD_SHA (40 lowercase hex commits). Exit codes: 0
+// passed (or not an apply pull request), 1 findings, 2 could not check. Every
+// doubt is a 2.
+${PATH_SCOPE_IMPORTS}
+
+const APPLY_PREFIX = "clossys/apply-";
+const LEDGER_PATH = "clossys/.state/installed.json";
+const EXEMPT = new Set([LEDGER_PATH, "package-lock.json", "pnpm-lock.yaml", "package.json"]);
+const OWNED = ${JSON.stringify(OWNED_PATH_PATTERNS, null, 2)};
+const MAX_PRINTED = 50;
+const MAX_BUFFER = 64 * 1024 * 1024;
+const COMMIT = /^[0-9a-f]{40}$/;
+const DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+// matcher:begin
+const SAFE_PATH = /^(?:(?!\.\.?\/)[^/\\\u0000-\u001f]+\/)*(?!\.\.?$)[^/\\\u0000-\u001f]+$/u;
+
+function isSafePath(path) {
+  return SAFE_PATH.test(path);
+}
+
+function isPattern(pattern) {
+  if (pattern === "**" || !isSafePath(pattern)) return false;
+  return pattern.split("/").every((segment) => segment === "**" || !segment.includes("**"));
+}
+
+function segmentMatches(segment, glob) {
+  const source = glob.split("*").map((part) => part.replace(/[.+?^$\{}()|[\]\\]/g, "\\$&")).join("[^/]*");
+  return new RegExp("^" + source + "$", "u").test(segment);
+}
+
+function segmentsMatch(path, pattern) {
+  if (pattern.length === 0) return path.length === 0;
+  const head = pattern[0];
+  const rest = pattern.slice(1);
+  if (head === "**") {
+    for (let skip = 0; skip <= path.length; skip += 1) if (segmentsMatch(path.slice(skip), rest)) return true;
+    return false;
+  }
+  return path.length > 0 && segmentMatches(path[0], head) && segmentsMatch(path.slice(1), rest);
+}
+
+function matches(path, pattern) {
+  if (!isSafePath(path) || !isPattern(pattern)) return false;
+  return segmentsMatch(path.split("/"), pattern.split("/"));
+}
+// matcher:end
+
+class Refusal extends Error {}
+
+function refuse(message) {
+  throw new Refusal(message);
+}
+
+function clean(text) {
+  return String(text).replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "?").slice(0, 300);
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function gitOutput(args, what) {
+  try {
+    return execFileSync("git", args, { maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return refuse(what + " failed");
+  }
+}
+
+function decode(buffer, what) {
+  try {
+    return DECODER.decode(buffer);
+  } catch {
+    return refuse(what + " is not valid UTF-8");
+  }
+}
+
+function changedPaths(baseSha, headSha) {
+  const output = gitOutput(
+    ["diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--diff-filter=ACDMRTUXB", baseSha + "..." + headSha],
+    "git diff",
+  );
+  const parts = decode(output, "the changed path list").split("\u0000");
+  if (parts.pop() !== "") refuse("the changed path list is not NUL-terminated");
+  return parts;
+}
+
+function namedPaths(headSha) {
+  const text = decode(gitOutput(["show", "--no-textconv", headSha + ":" + LEDGER_PATH], "reading the head ledger"), "the head ledger");
+  let ledger;
+  try {
+    ledger = JSON.parse(text);
+  } catch {
+    return refuse("the head ledger is not valid JSON");
+  }
+  if (!isRecord(ledger) || !Array.isArray(ledger.files)) refuse("the head ledger has no files array");
+  const named = new Set();
+  for (const row of ledger.files) {
+    if (!isRecord(row) || typeof row.path !== "string") refuse("a row in the head ledger's files has no string path");
+    named.add(row.path);
+  }
+  for (const member of ["entries", "keys"]) {
+    if (!Object.hasOwn(ledger, member)) continue;
+    if (!Array.isArray(ledger[member])) refuse("the head ledger's " + member + " is not an array");
+    for (const row of ledger[member]) {
+      if (!isRecord(row) || typeof row.file !== "string") refuse("a row in the head ledger's " + member + " has no string file");
+      named.add(row.file);
+    }
+  }
+  return named;
+}
+
+function main() {
+  const headRef = process.env.HEAD_REF;
+  if (typeof headRef !== "string" || headRef === "") refuse("HEAD_REF is not set");
+  if (!headRef.startsWith(APPLY_PREFIX)) {
+    console.log("path-scope: not a Clossys apply pull request (the head branch does not start with " + APPLY_PREFIX + "); nothing to check");
+    return 0;
+  }
+  const baseSha = process.env.BASE_SHA;
+  const headSha = process.env.HEAD_SHA;
+  if (typeof baseSha !== "string" || !COMMIT.test(baseSha)) refuse("BASE_SHA is not a 40-character lowercase hex commit");
+  if (typeof headSha !== "string" || !COMMIT.test(headSha)) refuse("HEAD_SHA is not a 40-character lowercase hex commit");
+
+  const changed = changedPaths(baseSha, headSha);
+  const named = namedPaths(headSha);
+  const findings = [];
+  for (const path of changed) {
+    if (!OWNED.some((pattern) => matches(path, pattern))) findings.push("outside-owned-scope: " + clean(path));
+    if (!EXEMPT.has(path) && !named.has(path)) findings.push("not-named-by-ledger: " + clean(path));
+  }
+  if (findings.length === 0) {
+    console.log("path-scope: " + changed.length + " path(s) checked");
+    return 0;
+  }
+  for (const finding of findings.slice(0, MAX_PRINTED)) console.error(finding);
+  const shown = Math.min(findings.length, MAX_PRINTED);
+  console.error("path-scope: " + findings.length + " finding(s) in " + changed.length + " changed path(s)" + (shown < findings.length ? "; first " + shown + " shown" : ""));
+  return 1;
+}
+
+try {
+  process.exitCode = main();
+} catch (error) {
+  console.error("path-scope: refused: " + (error instanceof Refusal ? error.message : "unexpected failure"));
+  process.exitCode = 2;
+}
+`;
+/**
+ * The standalone path-scope script (its text ends in one LF). The
+ * path-scope workflow embeds it; a test runs it with `node` directly.
+ */
+export function renderPathScopeScript(agentProvenance = undefined) {
+    if (agentProvenance === undefined)
+        return PATH_SCOPE_SCRIPT;
+    if (!["codex", "claude", "cursor"].includes(agentProvenance))
+        throw new TypeError("unsupported agent provenance");
+    // Keep legacy bytes unchanged. Explicit provenance opts into the expanded
+    // branch recognizer; every supported namespace still runs the full checks.
+    return PATH_SCOPE_SCRIPT
+        .replace('const APPLY_PREFIX = "clossys/apply-";', 'const APPLY_PREFIX = "a supported apply branch";\nconst APPLY_BRANCH = /^(clossys|codex|claude|cursor)\\/apply-[0-9a-f]{12}$/;')
+        .replace('if (!headRef.startsWith(APPLY_PREFIX)) {', 'if (!APPLY_BRANCH.test(headRef)) {\n    if (headRef.includes("/apply")) refuse("unsupported or malformed apply branch");');
+}
+const PATH_SCOPE_WORKFLOW_HEAD = [
+    "# Clossys path scope, written by Clossys Launcher.",
+    "#",
+    "# This applies to pull requests whose head branch starts with clossys/apply-.",
+    "# For those it lists every file the pull request changes, deletions included,",
+    "# and fails unless each one matches a path Clossys may own and, apart from the",
+    "# ledger, package.json and the lockfiles, is named by the pull request's own",
+    "# clossys/.state/installed.json. Any other pull request passes with a notice.",
+    "# That decision is made inside the script, not by a job condition, so this job",
+    "# and its check always run.",
+    "#",
+    "# This workflow runs in the pull request's own context, so a pull request can",
+    "# edit it. It catches an agent's mistakes, not a hostile author. The trusted",
+    "# admission job is the separate workflow_run workflow, which runs from the",
+    "# protected base.",
+    "#",
+    "# The script only runs git diff and git show. It never runs, loads or evaluates",
+    "# anything from the checked-out files, and the branch name reaches it only",
+    "# through the environment.",
+    "name: Clossys path scope",
+    "",
+    "on:",
+    "  pull_request:",
+    "    types: [opened, synchronize, reopened]",
+    "",
+    "permissions:",
+    "  contents: read",
+    "",
+    "jobs:",
+    "  path-scope:",
+    "    runs-on: ubuntu-latest",
+    "    timeout-minutes: 10",
+    "    steps:",
+    "      - name: Check out the pull request head",
+    `        uses: ${CHECKOUT}`,
+    "        with:",
+    "          ref: ${{ github.event.pull_request.head.sha }}",
+    "          fetch-depth: 0",
+    "          persist-credentials: false",
+    "",
+    "      # The branch name and both commits reach the script only through the",
+    "      # environment, never through its text.",
+    "      - name: Check the changed paths",
+    "        env:",
+    "          HEAD_REF: ${{ github.event.pull_request.head.ref }}",
+    "          BASE_SHA: ${{ github.event.pull_request.base.sha }}",
+    "          HEAD_SHA: ${{ github.event.pull_request.head.sha }}",
+    "        run: |",
+    `          node --input-type=module - <<'${HEREDOC_TERMINATOR}'`,
+];
+const RUN_BODY_INDENT = "          ";
+/** The bytes of `.github/workflows/clossys-path-scope.yml`: the script embedded in a quoted heredoc. */
+export function renderPathScopeWorkflow(agentProvenance = undefined) {
+    const body = renderPathScopeScript(agentProvenance).slice(0, -1)
+        .split("\n")
+        .map((line) => (line === "" ? "" : `${RUN_BODY_INDENT}${line}`));
+    const head = agentProvenance === undefined ? PATH_SCOPE_WORKFLOW_HEAD : PATH_SCOPE_WORKFLOW_HEAD.map((line) => line.replace("head branch starts with clossys/apply-.", "head branch is a legacy or supported agent apply branch."));
+    return [...head, ...body, `${RUN_BODY_INDENT}${HEREDOC_TERMINATOR}`, ""].join("\n");
+}
+//# sourceMappingURL=setup-template-scripts.js.map

package/dist/setup-template-scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-template-scripts.js","sourceRoot":"","sources":["../src/setup-template-scripts.ts"],"names":[],"mappings":"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"}

package/dist/setup-templates.d.ts

@@ -0,0 +1,55 @@
+import { type TemplateAct } from "./change-set-contract.js";
+export type SetupPackageManager = "npm" | "pnpm";
+export interface StarterPinInput {
+    readonly name: string;
+    readonly version: string;
+    readonly integrity: string;
+}
+export interface StarterRequestInput {
+    readonly packageManager: unknown;
+    readonly repository: string;
+    readonly starter: StarterPinInput;
+}
+export interface TemplateRefusal {
+    readonly reason: "starter-pin-unsupported" | "package-manager-unsupported" | "input-invalid";
+    /** A position such as `starter.version`. Never the offending value. */
+    readonly at: string;
+}
+export interface TemplateFile {
+    readonly path: string;
+    readonly bytes: string;
+}
+export type TemplateResult = {
+    readonly ok: true;
+    readonly files: readonly TemplateFile[];
+} | {
+    readonly ok: false;
+    readonly refusal: TemplateRefusal;
+};
+/**
+ * The Starter versions a setup may pin, for documentation. The check below is
+ * the rule: an exact `0.2.PATCH` or `0.3.PATCH`, with no range, prerelease, build metadata, or
+ * leading zero.
+ */
+export declare const STARTER_PIN_RANGE = ">=0.2.0 <0.4.0";
+/**
+ * Whether `version` is a Starter version the templates support: exactly the
+ * rule renderStarterRequest() applies, so a repository is read as past its
+ * setup only at a pin these templates would themselves have written.
+ */
+export declare function isSupportedStarterVersion(version: unknown): boolean;
+/** Render `.starter/request.json`, or refuse at the first position, in the fixed order, that is not acceptable. */
+export declare function renderStarterRequest(input: unknown): TemplateResult;
+/** Render `.github/workflows/clossys-adoption-decision.yml` for npm or pnpm, or refuse at `packageManager`. */
+export declare function renderAdoptionDecisionWorkflow(packageManager: unknown): TemplateResult;
+/** Render `.github/workflows/clossys-ci.yml`. */
+export declare function renderProductCiWorkflow(): string;
+/**
+ * Render the files one setup act writes, or refuse. `add-caller-workflow` takes
+ * `{ packageManager }`, `write-starter-request` takes a `StarterRequestInput`,
+ * `add-ci-template` takes no input, and `add-path-scope-job` optionally takes
+ * `{ agentProvenance }`. The returned
+ * paths are always `TEMPLATE_PATHS[act]`, in that order.
+ */
+export declare function renderSetupTemplate(act: TemplateAct, input?: unknown): TemplateResult;
+//# sourceMappingURL=setup-templates.d.ts.map

package/dist/setup-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-templates.d.ts","sourceRoot":"","sources":["../src/setup-templates.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAG5E,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,6BAA6B,GAAG,eAAe,CAAC;IAC7F,uEAAuE;IACvE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAWlD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEnE;AAwDD,mHAAmH;AACnH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA6CnE;AA2ID,+GAA+G;AAC/G,wBAAgB,8BAA8B,CAAC,cAAc,EAAE,OAAO,GAAG,cAAc,CAGtF;AA6FD,iDAAiD;AACjD,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAwCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,cAAc,CAkBrF"}