@stll/oxlint-config 0.10.0 → 0.12.0

package/README.md

@@ -0,0 +1,248 @@
+# @stll/oxlint-config
+
+Shared oxlint presets, JavaScript plugins, and toolchain policy for Stella
+packages. Repository-specific rules and exceptions belong in the consuming
+repository's configuration.
+
+## Install and configure
+
+```sh
+bun add -d @stll/oxlint-config
+```
+
+Install `oxlint`, `oxlint-tsgolint`, and any other shared tools at the exact
+versions in the exported `@stll/oxlint-config/toolchain.json`. That file is the
+source for current pins; peer dependency ranges describe supported versions.
+
+Use the library preset in `oxlint.config.ts`:
+
+```ts
+import { library } from "@stll/oxlint-config";
+
+export default library({
+  ignorePatterns: ["dist/"],
+  overrides: [
+    {
+      files: ["scripts/**"],
+      rules: { "no-console": "off" },
+    },
+  ],
+});
+```
+
+The preset includes the shared `stella-lowercase` and `no-raw-colors`
+JavaScript plugins. The separate `@stll/oxlint-plugin` package provides
+portable safety and route-query rules. See the
+[repository usage guide](https://github.com/stella/tooling#usage) for other
+presets, CommonJS configuration, and plugin composition.
+
+## Shared toolchain and Bun
+
+`@stll/oxlint-config/toolchain.json` is a versioned policy for package pins,
+Bun, TypeScript install layouts, Node, Python, Rust, GitHub Actions, and
+Dependabot. Inherit the fields for tools your repository uses. The checker
+does not require tools absent from the repository.
+
+Set `packageManager` to `bun@` followed by the policy's `bun` value, and pin
+`bun-types` to that same value. Dependency pins can live in default or named
+catalogs, including Bun's `workspaces` catalogs. Bun image tags, version
+files, and mise/asdf entries also inherit the policy pin.
+
+Configure `oven-sh/setup-bun` with a tracked manifest as its version source:
+
+```yaml
+with:
+  bun-version-file: package.json
+```
+
+The action itself must use the policy's approved SHA and version comment.
+A prefixed version-file selector can use a preceding checkout in its job:
+use the exact `${{ job.workflow_repository }}` / `${{ job.workflow_sha }}` pair,
+or a same-repository checkout with no `ref`. For no-ref checkouts, omit
+`repository`, name this repository literally, or use `${{ github.repository }}`.
+The checkout must omit both `if` and `continue-on-error`, and its normalized
+path must be unique among every checkout in that job, including later steps.
+Unknown checkout destinations prevent mapped selectors from proving provenance.
+Sparse checkouts must explicitly list the selected repository-relative file,
+without the checkout prefix, in `sparse-checkout`. This applies in either cone
+mode and to delegated sources. Dynamic, empty, glob, negation, or unsupported
+sparse configurations fail; a cone-mode input alone is insufficient. Directory
+entries cannot substitute for the selected file.
+Other nonempty, nonconstant GitHub expression refs on same-repository checkouts
+(including `${{ job.workflow_repository }}`) delegate a safe static version-file selector
+to that checkout. The CLI reports delegation on stdout without validating the
+current source's version file. Literal refs and unpaired `${{ github.sha }}` /
+`${{ job.workflow_sha }}` remain rejected.
+For snapshot-bound sources, the guard maps the selector to its tracked source
+file. Literal commit SHAs,
+branches, tags, unpaired snapshot contexts, foreign repositories, and traversal
+paths fail.
+Direct `bun-version` inputs are forbidden. For snapshot-bound sources, the
+manifest referenced by `bun-version-file` must declare the shared
+`packageManager` value. Delegated commits own their version validation.
+
+The Node policy is `26.x`. Runtime selectors (`.node-version`, `.nvmrc`,
+setup-node's `node-version-file`, Node image tags and mise/asdf entries)
+must select major 26: bare major, major wildcard, minor and stable patch
+selectors within that major are allowed. Open ranges, floating aliases,
+other majors and prereleases fail. Use `node-version-file` for setup-node.
+`engines.node` remains a support range and must include every stable release
+in major 26; `>=26`, `^26` and `^24 || ^26` pass, while ranges that omit
+part of major 26 fail.
+Release and publish workflows use exact patch version-file selectors for
+reproducible builds; this repository pins `.node-version` to `26.10.0`.
+The series policy accepts that patch without weakening release validation.
+GitHub JavaScript action host runtimes (`runs.using`) are platform-managed
+and do not select the project toolchain Node version.
+
+A published package can test the minimum Node major in its `engines.node`
+support range in one declared workflow job. Add a scoped `engineFloors` entry
+to tracked root `stll-toolchain.json`:
+
+```json
+{
+  "engineFloors": [
+    {
+      "package": "packages/library",
+      "workflow": ".github/workflows/ci.yml",
+      "job": "node-floor"
+    }
+  ]
+}
+```
+
+That job may use a literal exact stable patch in setup-node's `node-version`
+whose major matches the range's minimum major and whose release satisfies
+the range (for example, `20.10.0` for `>=20.10.0`). The approved action SHA, version comment and input validation
+also apply. Other jobs and runtime files follow the shared Node series.
+Missing packages or jobs, private packages, absent setup-node selectors and
+floor mismatches fail configuration validation. `optOuts` is optional when
+only `engineFloors` is declared.
+
+Run the installed checker from the repository root in CI:
+
+```sh
+bunx --no-install stll-toolchain-check
+```
+
+The CLI checks tracked files, prints `path:line: [rule] message` diagnostics,
+and exits with status 1 on a mismatch. Updating the package updates the
+policy; update consumer pins and run the checker together.
+
+`typescriptInstallLayouts` declares the compiler package, exact specifier,
+and typecheck command for each supported layout. Prefer the direct layout.
+Use the split compatibility layout for the compiler-API consumers and peer
+blockers listed in `typescript6Compatibility`; it retains the current
+compiler for typechecking while providing the compatibility package.
+
+An exception requires a tracked root `stll-toolchain.json` with the named
+rule and a nonempty reason:
+
+```json
+{
+  "optOuts": [{ "rule": "bun-pins", "reason": "This repository uses npm." }]
+}
+```
+
+Workspace TypeScript toolchains combine the root and declared members' devDependencies.
+An included member may declare the exact TypeScript 6 compatibility API across
+dependencies, devDependencies, and peerDependencies when that shared install uses
+the complete split layout. Ambiguous or partial layouts do not grant this allowance.
+Peer ranges declare support: they must include the policy compiler release and the
+compatibility release when the selected layout uses it. Ranges do not contribute
+to the installed compiler inventory.
+
+JavaScript update roots come from the repository root, declared workspace membership,
+and directories with their own `bun.lock`, `package-lock.json`, `yarn.lock`, or
+`pnpm-lock.yaml`. Other package manifests do not create update roots; directory names
+have no special meaning. Workspace members share their owner's update entry.
+
+`node-engine` and `cloud-setup-drift` are mandatory: opt-outs cannot bypass the
+shared Node support range or generated cloud setup requirements.
+
+Opt-outs apply to the entire repository for that rule. Unknown or duplicate
+rules, empty reasons, and malformed configuration fail validation. See the
+[shared toolchain reference](https://github.com/stella/tooling#shared-toolchain)
+for the schema, rule list, runtime support ranges, and generated Dependabot
+template.
+
+## Typecheck parity project selection
+
+Run `stll-typecheck-parity` from the repository root. Without flags, it checks
+the root `tsconfig.json` and recursively discovers project references in build
+mode. Repeat `--project` to check exactly the selected configs:
+
+```sh
+stll-typecheck-parity --project packages/api/tsconfig.json --project packages/web/tsconfig.json
+```
+
+Selected configs run independently using the repository-root compiler
+installation; child packages need no compiler declaration and a root tsconfig
+is unnecessary. Their original reference metadata is preserved without
+discovering or building referenced projects. Missing, unreadable, and zero-input
+selected configs fail the check. `--help` prints usage and exits successfully;
+unknown arguments fail.
+
+## Shared cloud setup
+
+Add an explicit declaration to tracked root `stll-toolchain.json`:
+
+```json
+{
+  "optOuts": [],
+  "cloud": {
+    "services": ["postgres", "valkey"],
+    "install": "bun install --frozen-lockfile",
+    "envFile": ".env.cloud"
+  }
+}
+```
+
+Services are optional within the declared list: use `[]` for runtimes and
+dependencies only. No `cloud` declaration means no cloud setup script.
+`envFile` must be a canonical repository-relative path; its existing parent
+must be safe at runtime. Track an exact stable Node patch in root
+`.node-version` within the shared Node series. Generate and commit the script:
+
+```sh
+bunx --no-install stll-cloud-setup
+```
+
+Generation uses the installed policy's Bun, Node, PostgreSQL, and Valkey pins.
+PostgreSQL uses the PGDG major-version packages; minor updates within the pinned
+major are accepted for the disposable database. Before adding PGDG, provisioning
+reuses an existing source only after verifying its signing-key fingerprint;
+conflicts identify the source file. Existing matching-major binaries are reused. Valkey uses official versioned
+binary DEBs for the declared release and architecture, verifies the policy's
+SHA256 pins, and installs those local files with apt. It does not resolve Valkey
+from a mutable package index.
+The command writes `.agents/cloud-setup.sh` with executable permissions and
+refuses symlink parents or destinations and hard-linked destinations. `stll-toolchain-check` rejects missing,
+drifted, or undeclared tracked scripts with mandatory `cloud-setup-drift`.
+Regenerate after changing the policy or declaration. `stll-cloud-setup --help`
+prints usage without reading repository configuration.
+
+| Environment phase       | Command                               |
+| ----------------------- | ------------------------------------- |
+| Networked install       | `bash .agents/cloud-setup.sh install` |
+| Offline session startup | `bash .agents/cloud-setup.sh start`   |
+
+Both commands can be rerun. Missing or unknown subcommands print usage and
+exit 2; there is no implicit lifecycle mode. The script supports Ubuntu 24.04
+with root access or passwordless sudo and fails when required capabilities
+or pinned installations are unavailable. `install` provisions runtimes,
+dependencies, and declared services; `start` restores local services after
+cached environments lose running processes. Services bind only to localhost.
+System provisioning runs as root; frozen dependencies run as the invoking user
+with that user's home and a private, user-owned Bun cache. Package installation
+does not permit automatic downgrades.
+If a newer Valkey package is already installed, provisioning fails rather than
+downgrading it; use an environment compatible with the pinned release.
+The environment file contains `NODE_ENV=test` and declared local connection
+URLs, carries a generated ownership marker, and refuses an unowned file or
+symlink. Configure the repository's test runner to load that file; migration
+commands and repository adoption are separate configuration steps.
+
+Environments may cache filesystems without preserving service processes.
+Run `start` at every session start, including sessions that reuse installed files.
+The supported OS, privileges, and pinned runtime requirements are checked explicitly.

package/dist/cloud-setup-cli.cjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_toolchain_guard = require("./toolchain-guard.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_fs_promises = require("node:fs/promises");
+//#region src/cloud-setup-cli.ts
+const usage = "Usage: stll-cloud-setup (run from repository root)\n       stll-cloud-setup --help";
+const optionalStat = async (path) => {
+	try {
+		return await (0, node_fs_promises.lstat)(path);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+		throw error;
+	}
+};
+const main = async () => {
+	const args = process.argv.slice(2);
+	if (args.length === 1 && args.at(0) === "--help") {
+		process.stdout.write(`${usage}\n`);
+		return;
+	}
+	if (args.length !== 0) throw new Error(usage);
+	const root = await (0, node_fs_promises.realpath)(process.cwd());
+	const { files, diagnostics } = require_toolchain_guard.readToolchainInputs(root);
+	if (diagnostics.length > 0) throw new Error(diagnostics.map(({ path, message }) => `${path}: ${message}`).join("\n"));
+	const text = files["stll-toolchain.json"];
+	if (text === void 0) throw new Error("requires tracked stll-toolchain.json");
+	const { cloud } = require_toolchain_guard.parseToolchainConfiguration(JSON.parse(text));
+	if (cloud === void 0) throw new Error("requires an explicit cloud declaration");
+	const nodeVersion = files[".node-version"];
+	if (nodeVersion === void 0) throw new Error("requires tracked root .node-version");
+	const script = require_toolchain_guard.generateCloudSetup({
+		policy: require_toolchain_guard.parseToolchainPolicy(JSON.parse(await (0, node_fs_promises.readFile)(new URL("../toolchain.json", require("url").pathToFileURL(__filename).href), "utf8"))),
+		cloud,
+		nodeVersion: nodeVersion.trim()
+	});
+	const destination = (0, node_path.join)(root, require_toolchain_guard.cloudSetupPath);
+	const parent = (0, node_path.dirname)(destination);
+	const parentStat = await optionalStat(parent);
+	if (parentStat === void 0) await (0, node_fs_promises.mkdir)(parent);
+	else if (parentStat.isSymbolicLink() || !parentStat.isDirectory()) throw new Error("cloud setup parent must be a real repository directory");
+	const destinationStat = await optionalStat(destination);
+	if (destinationStat !== void 0 && (destinationStat.isSymbolicLink() || !destinationStat.isFile() || destinationStat.nlink !== 1)) throw new Error("cloud setup destination must be a single-link regular repository file");
+	const output = await (0, node_fs_promises.open)(destination, node_fs.constants.O_WRONLY | node_fs.constants.O_CREAT | node_fs.constants.O_NOFOLLOW, 493);
+	try {
+		const opened = await output.stat();
+		if (!opened.isFile() || opened.nlink !== 1) throw new Error("cloud setup destination must be a single-link regular repository file");
+		await output.truncate(0);
+		await output.writeFile(script, "utf8");
+		await output.chmod(493);
+	} finally {
+		await output.close();
+	}
+	process.stdout.write(`Generated ${require_toolchain_guard.cloudSetupPath}\n`);
+};
+main().catch((error) => {
+	process.stderr.write(`cloud-setup: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+
+//# sourceMappingURL=cloud-setup-cli.cjs.map

package/dist/cloud-setup-cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-setup-cli.cjs","names":["readToolchainInputs","parseToolchainConfiguration","generateCloudSetup","parseToolchainPolicy","cloudSetupPath","constants"],"sources":["../src/cloud-setup-cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { constants } from \"node:fs\";\nimport { lstat, mkdir, open, readFile, realpath } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\n\nimport { cloudSetupPath, generateCloudSetup } from \"./cloud-setup\";\nimport {\n  parseToolchainConfiguration,\n  readToolchainInputs,\n} from \"./toolchain-guard\";\nimport { parseToolchainPolicy } from \"./toolchain-schema\";\n\nconst usage =\n  \"Usage: stll-cloud-setup (run from repository root)\\n       stll-cloud-setup --help\";\nconst optionalStat = async (path: string) => {\n  try {\n    return await lstat(path);\n  } catch (error) {\n    if (error instanceof Error && \"code\" in error && error.code === \"ENOENT\")\n      return undefined;\n    throw error;\n  }\n};\n\nconst main = async () => {\n  const args = process.argv.slice(2);\n  if (args.length === 1 && args.at(0) === \"--help\") {\n    process.stdout.write(`${usage}\\n`);\n    return;\n  }\n  if (args.length !== 0) throw new Error(usage);\n  const root = await realpath(process.cwd());\n  const { files, diagnostics } = readToolchainInputs(root);\n  if (diagnostics.length > 0)\n    throw new Error(\n      diagnostics.map(({ path, message }) => `${path}: ${message}`).join(\"\\n\"),\n    );\n  const text = files[\"stll-toolchain.json\"];\n  if (text === undefined)\n    throw new Error(\"requires tracked stll-toolchain.json\");\n  const { cloud } = parseToolchainConfiguration(JSON.parse(text));\n  if (cloud === undefined)\n    throw new Error(\"requires an explicit cloud declaration\");\n  const nodeVersion = files[\".node-version\"];\n  if (nodeVersion === undefined)\n    throw new Error(\"requires tracked root .node-version\");\n  const policy = parseToolchainPolicy(\n    JSON.parse(\n      await readFile(new URL(\"../toolchain.json\", import.meta.url), \"utf8\"),\n    ),\n  );\n  const script = generateCloudSetup({\n    policy,\n    cloud,\n    nodeVersion: nodeVersion.trim(),\n  });\n  const destination = join(root, cloudSetupPath);\n  const parent = dirname(destination);\n  const parentStat = await optionalStat(parent);\n  if (parentStat === undefined) await mkdir(parent);\n  else if (parentStat.isSymbolicLink() || !parentStat.isDirectory())\n    throw new Error(\"cloud setup parent must be a real repository directory\");\n  const destinationStat = await optionalStat(destination);\n  if (\n    destinationStat !== undefined &&\n    (destinationStat.isSymbolicLink() ||\n      !destinationStat.isFile() ||\n      destinationStat.nlink !== 1)\n  )\n    throw new Error(\n      \"cloud setup destination must be a single-link regular repository file\",\n    );\n  const output = await open(\n    destination,\n    constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW,\n    0o755,\n  );\n  try {\n    const opened = await output.stat();\n    if (!opened.isFile() || opened.nlink !== 1)\n      throw new Error(\n        \"cloud setup destination must be a single-link regular repository file\",\n      );\n    await output.truncate(0);\n    await output.writeFile(script, \"utf8\");\n    await output.chmod(0o755);\n  } finally {\n    await output.close();\n  }\n  process.stdout.write(`Generated ${cloudSetupPath}\\n`);\n};\n\nmain().catch((error: unknown) => {\n  process.stderr.write(\n    `cloud-setup: ${error instanceof Error ? error.message : String(error)}\\n`,\n  );\n  process.exitCode = 1;\n});\n"],"mappings":";;;;;;;AAYA,MAAM,QACJ;AACF,MAAM,eAAe,OAAO,SAAiB;CAC3C,IAAI;EACF,OAAO,OAAA,GAAA,iBAAA,MAAA,CAAY,IAAI;CACzB,SAAS,OAAO;EACd,IAAI,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS,UAC9D,OAAO,KAAA;EACT,MAAM;CACR;AACF;AAEA,MAAM,OAAO,YAAY;CACvB,MAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;CACjC,IAAI,KAAK,WAAW,KAAK,KAAK,GAAG,CAAC,MAAM,UAAU;EAChD,QAAQ,OAAO,MAAM,GAAG,MAAM,GAAG;EACjC;CACF;CACA,IAAI,KAAK,WAAW,GAAG,MAAM,IAAI,MAAM,KAAK;CAC5C,MAAM,OAAO,OAAA,GAAA,iBAAA,SAAA,CAAe,QAAQ,IAAI,CAAC;CACzC,MAAM,EAAE,OAAO,gBAAgBA,wBAAAA,oBAAoB,IAAI;CACvD,IAAI,YAAY,SAAS,GACvB,MAAM,IAAI,MACR,YAAY,KAAK,EAAE,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS,CAAC,CAAC,KAAK,IAAI,CACzE;CACF,MAAM,OAAO,MAAM;CACnB,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MAAM,sCAAsC;CACxD,MAAM,EAAE,UAAUC,wBAAAA,4BAA4B,KAAK,MAAM,IAAI,CAAC;CAC9D,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,wCAAwC;CAC1D,MAAM,cAAc,MAAM;CAC1B,IAAI,gBAAgB,KAAA,GAClB,MAAM,IAAI,MAAM,qCAAqC;CAMvD,MAAM,SAASC,wBAAAA,mBAAmB;EAChC,QANaC,wBAAAA,qBACb,KAAK,MACH,OAAA,GAAA,iBAAA,SAAA,CAAe,IAAI,IAAI,qBAAA,QAAA,KAAA,CAAA,CAAA,cAAA,UAAA,CAAA,CAAA,IAAoC,GAAG,MAAM,CACtE,CAGK;EACL;EACA,aAAa,YAAY,KAAK;CAChC,CAAC;CACD,MAAM,eAAA,GAAA,UAAA,KAAA,CAAmB,MAAMC,wBAAAA,cAAc;CAC7C,MAAM,UAAA,GAAA,UAAA,QAAA,CAAiB,WAAW;CAClC,MAAM,aAAa,MAAM,aAAa,MAAM;CAC5C,IAAI,eAAe,KAAA,GAAW,OAAA,GAAA,iBAAA,MAAA,CAAY,MAAM;MAC3C,IAAI,WAAW,eAAe,KAAK,CAAC,WAAW,YAAY,GAC9D,MAAM,IAAI,MAAM,wDAAwD;CAC1E,MAAM,kBAAkB,MAAM,aAAa,WAAW;CACtD,IACE,oBAAoB,KAAA,MACnB,gBAAgB,eAAe,KAC9B,CAAC,gBAAgB,OAAO,KACxB,gBAAgB,UAAU,IAE5B,MAAM,IAAI,MACR,uEACF;CACF,MAAM,SAAS,OAAA,GAAA,iBAAA,KAAA,CACb,aACAC,QAAAA,UAAU,WAAWA,QAAAA,UAAU,UAAUA,QAAAA,UAAU,YACnD,GACF;CACA,IAAI;EACF,MAAM,SAAS,MAAM,OAAO,KAAK;EACjC,IAAI,CAAC,OAAO,OAAO,KAAK,OAAO,UAAU,GACvC,MAAM,IAAI,MACR,uEACF;EACF,MAAM,OAAO,SAAS,CAAC;EACvB,MAAM,OAAO,UAAU,QAAQ,MAAM;EACrC,MAAM,OAAO,MAAM,GAAK;CAC1B,UAAU;EACR,MAAM,OAAO,MAAM;CACrB;CACA,QAAQ,OAAO,MAAM,aAAaD,wBAAAA,eAAe,GAAG;AACtD;AAEA,KAAK,CAAC,CAAC,OAAO,UAAmB;CAC/B,QAAQ,OAAO,MACb,gBAAgB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GACzE;CACA,QAAQ,WAAW;AACrB,CAAC"}

package/dist/cloud-setup-cli.d.cts

@@ -0,0 +1 @@
+export {}

package/dist/cloud-setup-cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/cloud-setup-cli.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { a as cloudSetupPath, i as parseToolchainPolicy, n as parseToolchainConfiguration, o as generateCloudSetup, r as readToolchainInputs } from "./toolchain-guard.mjs";
+import { constants } from "node:fs";
+import { dirname, join } from "node:path";
+import { lstat, mkdir, open, readFile, realpath } from "node:fs/promises";
+//#region src/cloud-setup-cli.ts
+const usage = "Usage: stll-cloud-setup (run from repository root)\n       stll-cloud-setup --help";
+const optionalStat = async (path) => {
+	try {
+		return await lstat(path);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+		throw error;
+	}
+};
+const main = async () => {
+	const args = process.argv.slice(2);
+	if (args.length === 1 && args.at(0) === "--help") {
+		process.stdout.write(`${usage}\n`);
+		return;
+	}
+	if (args.length !== 0) throw new Error(usage);
+	const root = await realpath(process.cwd());
+	const { files, diagnostics } = readToolchainInputs(root);
+	if (diagnostics.length > 0) throw new Error(diagnostics.map(({ path, message }) => `${path}: ${message}`).join("\n"));
+	const text = files["stll-toolchain.json"];
+	if (text === void 0) throw new Error("requires tracked stll-toolchain.json");
+	const { cloud } = parseToolchainConfiguration(JSON.parse(text));
+	if (cloud === void 0) throw new Error("requires an explicit cloud declaration");
+	const nodeVersion = files[".node-version"];
+	if (nodeVersion === void 0) throw new Error("requires tracked root .node-version");
+	const script = generateCloudSetup({
+		policy: parseToolchainPolicy(JSON.parse(await readFile(new URL("../toolchain.json", import.meta.url), "utf8"))),
+		cloud,
+		nodeVersion: nodeVersion.trim()
+	});
+	const destination = join(root, cloudSetupPath);
+	const parent = dirname(destination);
+	const parentStat = await optionalStat(parent);
+	if (parentStat === void 0) await mkdir(parent);
+	else if (parentStat.isSymbolicLink() || !parentStat.isDirectory()) throw new Error("cloud setup parent must be a real repository directory");
+	const destinationStat = await optionalStat(destination);
+	if (destinationStat !== void 0 && (destinationStat.isSymbolicLink() || !destinationStat.isFile() || destinationStat.nlink !== 1)) throw new Error("cloud setup destination must be a single-link regular repository file");
+	const output = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW, 493);
+	try {
+		const opened = await output.stat();
+		if (!opened.isFile() || opened.nlink !== 1) throw new Error("cloud setup destination must be a single-link regular repository file");
+		await output.truncate(0);
+		await output.writeFile(script, "utf8");
+		await output.chmod(493);
+	} finally {
+		await output.close();
+	}
+	process.stdout.write(`Generated ${cloudSetupPath}\n`);
+};
+main().catch((error) => {
+	process.stderr.write(`cloud-setup: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cloud-setup-cli.mjs.map

package/dist/cloud-setup-cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-setup-cli.mjs","names":[],"sources":["../src/cloud-setup-cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { constants } from \"node:fs\";\nimport { lstat, mkdir, open, readFile, realpath } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\n\nimport { cloudSetupPath, generateCloudSetup } from \"./cloud-setup\";\nimport {\n  parseToolchainConfiguration,\n  readToolchainInputs,\n} from \"./toolchain-guard\";\nimport { parseToolchainPolicy } from \"./toolchain-schema\";\n\nconst usage =\n  \"Usage: stll-cloud-setup (run from repository root)\\n       stll-cloud-setup --help\";\nconst optionalStat = async (path: string) => {\n  try {\n    return await lstat(path);\n  } catch (error) {\n    if (error instanceof Error && \"code\" in error && error.code === \"ENOENT\")\n      return undefined;\n    throw error;\n  }\n};\n\nconst main = async () => {\n  const args = process.argv.slice(2);\n  if (args.length === 1 && args.at(0) === \"--help\") {\n    process.stdout.write(`${usage}\\n`);\n    return;\n  }\n  if (args.length !== 0) throw new Error(usage);\n  const root = await realpath(process.cwd());\n  const { files, diagnostics } = readToolchainInputs(root);\n  if (diagnostics.length > 0)\n    throw new Error(\n      diagnostics.map(({ path, message }) => `${path}: ${message}`).join(\"\\n\"),\n    );\n  const text = files[\"stll-toolchain.json\"];\n  if (text === undefined)\n    throw new Error(\"requires tracked stll-toolchain.json\");\n  const { cloud } = parseToolchainConfiguration(JSON.parse(text));\n  if (cloud === undefined)\n    throw new Error(\"requires an explicit cloud declaration\");\n  const nodeVersion = files[\".node-version\"];\n  if (nodeVersion === undefined)\n    throw new Error(\"requires tracked root .node-version\");\n  const policy = parseToolchainPolicy(\n    JSON.parse(\n      await readFile(new URL(\"../toolchain.json\", import.meta.url), \"utf8\"),\n    ),\n  );\n  const script = generateCloudSetup({\n    policy,\n    cloud,\n    nodeVersion: nodeVersion.trim(),\n  });\n  const destination = join(root, cloudSetupPath);\n  const parent = dirname(destination);\n  const parentStat = await optionalStat(parent);\n  if (parentStat === undefined) await mkdir(parent);\n  else if (parentStat.isSymbolicLink() || !parentStat.isDirectory())\n    throw new Error(\"cloud setup parent must be a real repository directory\");\n  const destinationStat = await optionalStat(destination);\n  if (\n    destinationStat !== undefined &&\n    (destinationStat.isSymbolicLink() ||\n      !destinationStat.isFile() ||\n      destinationStat.nlink !== 1)\n  )\n    throw new Error(\n      \"cloud setup destination must be a single-link regular repository file\",\n    );\n  const output = await open(\n    destination,\n    constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW,\n    0o755,\n  );\n  try {\n    const opened = await output.stat();\n    if (!opened.isFile() || opened.nlink !== 1)\n      throw new Error(\n        \"cloud setup destination must be a single-link regular repository file\",\n      );\n    await output.truncate(0);\n    await output.writeFile(script, \"utf8\");\n    await output.chmod(0o755);\n  } finally {\n    await output.close();\n  }\n  process.stdout.write(`Generated ${cloudSetupPath}\\n`);\n};\n\nmain().catch((error: unknown) => {\n  process.stderr.write(\n    `cloud-setup: ${error instanceof Error ? error.message : String(error)}\\n`,\n  );\n  process.exitCode = 1;\n});\n"],"mappings":";;;;;;AAYA,MAAM,QACJ;AACF,MAAM,eAAe,OAAO,SAAiB;CAC3C,IAAI;EACF,OAAO,MAAM,MAAM,IAAI;CACzB,SAAS,OAAO;EACd,IAAI,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS,UAC9D,OAAO,KAAA;EACT,MAAM;CACR;AACF;AAEA,MAAM,OAAO,YAAY;CACvB,MAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;CACjC,IAAI,KAAK,WAAW,KAAK,KAAK,GAAG,CAAC,MAAM,UAAU;EAChD,QAAQ,OAAO,MAAM,GAAG,MAAM,GAAG;EACjC;CACF;CACA,IAAI,KAAK,WAAW,GAAG,MAAM,IAAI,MAAM,KAAK;CAC5C,MAAM,OAAO,MAAM,SAAS,QAAQ,IAAI,CAAC;CACzC,MAAM,EAAE,OAAO,gBAAgB,oBAAoB,IAAI;CACvD,IAAI,YAAY,SAAS,GACvB,MAAM,IAAI,MACR,YAAY,KAAK,EAAE,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS,CAAC,CAAC,KAAK,IAAI,CACzE;CACF,MAAM,OAAO,MAAM;CACnB,IAAI,SAAS,KAAA,GACX,MAAM,IAAI,MAAM,sCAAsC;CACxD,MAAM,EAAE,UAAU,4BAA4B,KAAK,MAAM,IAAI,CAAC;CAC9D,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,wCAAwC;CAC1D,MAAM,cAAc,MAAM;CAC1B,IAAI,gBAAgB,KAAA,GAClB,MAAM,IAAI,MAAM,qCAAqC;CAMvD,MAAM,SAAS,mBAAmB;EAChC,QANa,qBACb,KAAK,MACH,MAAM,SAAS,IAAI,IAAI,qBAAqB,OAAO,KAAK,GAAG,GAAG,MAAM,CACtE,CAGK;EACL;EACA,aAAa,YAAY,KAAK;CAChC,CAAC;CACD,MAAM,cAAc,KAAK,MAAM,cAAc;CAC7C,MAAM,SAAS,QAAQ,WAAW;CAClC,MAAM,aAAa,MAAM,aAAa,MAAM;CAC5C,IAAI,eAAe,KAAA,GAAW,MAAM,MAAM,MAAM;MAC3C,IAAI,WAAW,eAAe,KAAK,CAAC,WAAW,YAAY,GAC9D,MAAM,IAAI,MAAM,wDAAwD;CAC1E,MAAM,kBAAkB,MAAM,aAAa,WAAW;CACtD,IACE,oBAAoB,KAAA,MACnB,gBAAgB,eAAe,KAC9B,CAAC,gBAAgB,OAAO,KACxB,gBAAgB,UAAU,IAE5B,MAAM,IAAI,MACR,uEACF;CACF,MAAM,SAAS,MAAM,KACnB,aACA,UAAU,WAAW,UAAU,UAAU,UAAU,YACnD,GACF;CACA,IAAI;EACF,MAAM,SAAS,MAAM,OAAO,KAAK;EACjC,IAAI,CAAC,OAAO,OAAO,KAAK,OAAO,UAAU,GACvC,MAAM,IAAI,MACR,uEACF;EACF,MAAM,OAAO,SAAS,CAAC;EACvB,MAAM,OAAO,UAAU,QAAQ,MAAM;EACrC,MAAM,OAAO,MAAM,GAAK;CAC1B,UAAU;EACR,MAAM,OAAO,MAAM;CACrB;CACA,QAAQ,OAAO,MAAM,aAAa,eAAe,GAAG;AACtD;AAEA,KAAK,CAAC,CAAC,OAAO,UAAmB;CAC/B,QAAQ,OAAO,MACb,gBAAgB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GACzE;CACA,QAAQ,WAAW;AACrB,CAAC"}

package/dist/toolchain-check-cli.cjs

@@ -1,209 +1,22 @@
 #!/usr/bin/env node
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-//#endregion
+const require_toolchain_guard = require("./toolchain-guard.cjs");
 let node_fs = require("node:fs");
-let node_child_process = require("node:child_process");
-let node_path = require("node:path");
-node_path = __toESM(node_path, 1);
-//#region src/toolchain-check.ts
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const scalar = (value) => value.trim().replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "");
-const trackedPath = (file) => !file.split("/").some((part) => part === "node_modules" || part === "vendor");
-/** Check tracked consumer files without traversing dependencies or the working tree. */
-const checkToolchain = ({ root, bunVersion, allowNonBunPackageManagers = [] }) => {
-	const files = (0, node_child_process.execFileSync)("git", [
-		"ls-files",
-		"-z",
-		"--cached"
-	], {
-		cwd: root,
-		encoding: "utf8"
-	}).split("\0").filter((file) => file !== "" && trackedPath(file));
-	const tracked = new Set(files);
-	const diagnostics = [];
-	const add = (file, line, message) => {
-		diagnostics.push({
-			path: file,
-			line,
-			message
-		});
-	};
-	const read = (file) => {
-		try {
-			return (0, node_fs.readFileSync)(node_path.default.join(root, file), "utf8");
-		} catch {
-			add(file, 1, "cannot read tracked file");
-			return;
-		}
-	};
-	const checkVersion = (file, line, value, label) => {
-		if (value !== bunVersion) add(file, line, `${label} must be ${bunVersion}, found ${String(value)}`);
-	};
-	const packages = /* @__PURE__ */ new Map();
-	for (const file of files.filter((entry) => node_path.default.basename(entry) === "package.json")) {
-		const text = read(file);
-		if (text === void 0) continue;
-		let json;
-		try {
-			json = JSON.parse(text);
-		} catch {
-			add(file, 1, "invalid package.json");
-			continue;
-		}
-		if (!isRecord(json)) {
-			add(file, 1, "package.json must contain an object");
-			continue;
-		}
-		packages.set(file, {
-			manager: json["packageManager"],
-			json,
-			text
-		});
-	}
-	const catalogSource = (json) => isRecord(json["workspaces"]) ? json["workspaces"] : json;
-	const rootCatalogs = catalogSource(packages.get("package.json")?.json ?? {});
-	for (const [file, { json, text }] of packages) {
-		const lines = text.split(/\r?\n/);
-		const reportedLines = /* @__PURE__ */ new Map();
-		const propertyLine = (key, value) => {
-			const serialized = value === void 0 ? void 0 : JSON.stringify(value);
-			const matchKey = `${key}:${serialized ?? ""}`;
-			const previous = reportedLines.get(matchKey) ?? -1;
-			const index = lines.findIndex((line, lineIndex) => lineIndex > previous && line.includes(`"${key}"`) && (serialized === void 0 || line.includes(serialized)));
-			if (index >= 0) reportedLines.set(matchKey, index);
-			return Math.max(1, index + 1);
-		};
-		if (json["packageManager"] !== void 0) {
-			if (typeof json["packageManager"] === "string" && json["packageManager"].startsWith("bun@")) checkVersion(file, propertyLine("packageManager"), json["packageManager"].slice(4), "packageManager Bun version");
-			else if (!allowNonBunPackageManagers.includes(file)) add(file, propertyLine("packageManager"), "packageManager is not Bun; use --allow-non-bun-package-manager with this path to allow it");
-		}
-		const checkDependencies = (value, resolveCatalog = false) => {
-			if (!isRecord(value) || value["bun-types"] === void 0) return;
-			const specifier = value["bun-types"];
-			const resolveVersion = () => {
-				if (!resolveCatalog || typeof specifier !== "string" || !specifier.startsWith("catalog:")) return specifier;
-				const catalogName = specifier.slice(8);
-				const source = file === "package.json" ? catalogSource(json) : rootCatalogs;
-				const catalog = catalogName === "" ? source["catalog"] : isRecord(source["catalogs"]) && source["catalogs"][catalogName];
-				return isRecord(catalog) ? catalog["bun-types"] : void 0;
-			};
-			checkVersion(file, propertyLine("bun-types", specifier), resolveVersion(), "bun-types");
-		};
-		checkDependencies(json["dependencies"], true);
-		checkDependencies(json["devDependencies"], true);
-		checkDependencies(json["catalog"]);
-		if (isRecord(json["catalogs"])) for (const catalog of Object.values(json["catalogs"])) checkDependencies(catalog);
-		if (isRecord(json["workspaces"])) {
-			checkDependencies(json["workspaces"]["catalog"]);
-			if (isRecord(json["workspaces"]["catalogs"])) for (const catalog of Object.values(json["workspaces"]["catalogs"])) checkDependencies(catalog);
-		}
-	}
-	for (const file of files) {
-		const name = node_path.default.basename(file);
-		const workflow = /^\.github\/workflows\/[^/]+\.ya?ml$/.test(file) || /^\.github\/actions\/.+\/action\.ya?ml$/.test(file);
-		const dockerfile = name.startsWith("Dockerfile") || name === "Containerfile";
-		const versionFile = name === ".bun-version" || name === ".tool-versions";
-		const mise = name === "mise.toml" || name === ".mise.toml";
-		if (!workflow && !dockerfile && !versionFile && !mise) continue;
-		const text = read(file);
-		if (text === void 0) continue;
-		if (name === ".bun-version") checkVersion(file, 1, scalar(text), ".bun-version");
-		let section = "";
-		for (const [index, original] of text.split(/\r?\n/).entries()) {
-			const line = index + 1;
-			if (/^\s*#/.test(original) || original.trim() === "") continue;
-			if (workflow) {
-				if (original.match(/(?:^\s*(?:-\s*)?|[{,]\s*)["']?bun-version["']?\s*:/) !== null) add(file, line, "bun-version literals are forbidden; use bun-version-file pointing to a package.json with the shared Bun pin");
-				const reference = original.match(/(?:^\s*(?:-\s*)?|[{,]\s*)["']?bun-version-file["']?\s*:\s*(?:"([^"]*)"|'([^']*)'|([^,}]*))/);
-				if (reference !== null) {
-					const target = scalar(reference[1] ?? reference[2] ?? reference[3] ?? "");
-					const normalized = node_path.default.posix.normalize(target);
-					const pkg = packages.get(normalized);
-					if (target === "" || node_path.default.posix.isAbsolute(target) || normalized.startsWith("../") || !tracked.has(normalized) || node_path.default.basename(normalized) !== "package.json" || pkg?.manager !== `bun@${bunVersion}`) add(file, line, `bun-version-file must reference a tracked package.json with packageManager bun@${bunVersion}, found ${target}`);
-				}
-			}
-			if (dockerfile) {
-				const image = original.match(/^\s*FROM\s+(?:--\S+\s+)*oven\/bun(?::([^\s@]+))?(?:@\S+)?(?:\s|$)/i);
-				if (image !== null) {
-					const tag = image[1];
-					if (tag !== void 0) {
-						const version = tag.match(/^(\d+\.\d+\.\d+)(?:-|$)/)?.[1];
-						checkVersion(file, line, version ?? tag, "oven/bun version");
-					} else if (!/oven\/bun@/i.test(original)) add(file, line, `oven/bun must use a ${bunVersion} version tag`);
-				}
-			}
-			if (name === ".tool-versions") {
-				const entry = original.match(/^\s*bun\s+(.+)$/);
-				if (entry !== null) checkVersion(file, line, scalar(entry[1] ?? ""), ".tool-versions Bun version");
-			}
-			if (mise) {
-				const heading = original.match(/^\s*\[([^\]]+)\]/);
-				if (heading !== null) section = heading[1] ?? "";
-				const checkMiseVersion = (value) => {
-					const inlineVersion = [...value.matchAll(/[,{]\s*([\w-]+|"[^"]+"|'[^']+')\s*=\s*("(?:\\.|[^"\\])*"|'[^']*'|[^,{}]+)\s*(?=[,}])/g)].find((field) => scalar(field[1] ?? "") === "version");
-					checkVersion(file, line, scalar(inlineVersion?.[2] ?? value), "mise Bun version");
-				};
-				const entry = original.match(/^\s*["']?bun["']?\s*=\s*(.+)$/);
-				if (entry !== null && section === "tools") checkMiseVersion(entry[1] ?? "");
-				const dotted = original.match(/^\s*tools\.bun(?:\.version)?\s*=\s*(.+)$/);
-				if (dotted !== null && section === "") checkMiseVersion(dotted[1] ?? "");
-				const tableVersion = original.match(/^\s*version\s*=\s*(.+)$/);
-				if (tableVersion !== null && section === "tools.bun") checkMiseVersion(tableVersion[1] ?? "");
-				const inlineTools = original.match(/^\s*tools\s*=\s*\{(.*)\}/);
-				if (inlineTools !== null && section === "") {
-					const inlineBun = inlineTools[1]?.match(/(?:^|,)\s*["']?bun["']?\s*=\s*(\{[^}]*\}|[^,}]+)/);
-					if (inlineBun !== null && inlineBun !== void 0) checkMiseVersion(inlineBun[1] ?? "");
-				}
-			}
-		}
-	}
-	return diagnostics;
-};
-//#endregion
 //#region src/toolchain-check-cli.ts
 try {
-	const allowNonBunPackageManagers = [];
 	const args = process.argv.slice(2);
-	for (let index = 0; index < args.length; index += 1) {
-		const argument = args[index];
-		if (argument === "--help") {
-			process.stdout.write("Usage: stll-toolchain-check [--allow-non-bun-package-manager <tracked package.json path>]\n");
-			process.exit(0);
-		}
-		const value = args.at(index + 1);
-		if (argument !== "--allow-non-bun-package-manager" || value === void 0 || value.startsWith("--")) throw new Error(`unexpected or incomplete argument: ${argument}`);
-		allowNonBunPackageManagers.push(value);
-		index += 1;
+	if (args.length === 1 && args[0] === "--help") {
+		process.stdout.write("Usage: stll-toolchain-check (opt-outs: tracked stll-toolchain.json)\n");
+		process.exit(0);
 	}
-	const toolchain = JSON.parse((0, node_fs.readFileSync)(new URL("../toolchain.json", require("url").pathToFileURL(__filename).href), "utf8"));
-	if (typeof toolchain !== "object" || toolchain === null || !("bun" in toolchain) || typeof toolchain.bun !== "string") throw new Error("installed toolchain.json must define a Bun version");
-	const diagnostics = checkToolchain({
+	if (args.length !== 0) throw new Error(`unexpected argument: ${args.at(0)}`);
+	const policy = require_toolchain_guard.parseToolchainPolicy(JSON.parse((0, node_fs.readFileSync)(new URL("../toolchain.json", require("url").pathToFileURL(__filename).href), "utf8")));
+	const diagnostics = require_toolchain_guard.checkToolchain({
 		root: process.cwd(),
-		bunVersion: toolchain.bun,
-		allowNonBunPackageManagers
+		policy,
+		onDelegated: ({ path, line, tool, selector, ref }) => process.stdout.write(`${path}:${line}: [runtime-delegated] setup-${tool} ${selector} delegates its version to checkout ref ${ref}\n`)
 	});
-	for (const diagnostic of diagnostics) process.stderr.write(`${diagnostic.path}:${diagnostic.line}: ${diagnostic.message}\n`);
+	for (const diagnostic of diagnostics) process.stderr.write(`${diagnostic.path}:${diagnostic.line}: [${diagnostic.rule}] ${diagnostic.message}\n`);
 	if (diagnostics.length > 0) process.exitCode = 1;
 } catch (error) {
 	process.stderr.write(`toolchain-check:1: ${error instanceof Error ? error.message : String(error)}\n`);