@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/outputs.ts

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ResolvedConfig } from "../config.ts";
+import { lines, mergeSection } from "../scripts/managed-text.ts";
+import { LESSONS_DIR, INDEX_NAME, lessonProblems, renderLessonsIndex } from "../scripts/lessons.ts";
+import { nightly } from "./nightly.ts";
+import { release } from "./release.ts";
+import { releaseWorkflow } from "./release-workflow.ts";
+import { mapSections } from "./maps.ts";
+import { isSelfName } from "./stock.ts";
+import { renderTrees } from "./trees.ts";
+import type { PackageJson, Workspace, WorkspacePackage } from "./workspace.ts";
+
+/**
+ * One path repo sync owns, at a root-relative POSIX path. A `link` is a directory symlink (a junction on win32)
+ * to `target`, absolute or relative to the link's directory. `tracked` says whether the path is committed.
+ * `managed` says who owns the text: `whole` is sync's alone (marked generated, read-only in the editor); `block`
+ * is a file the user also writes, of which sync owns a marked section. An `executable` file is written mode 0755 on POSIX.
+ */
+export type Output =
+  | { kind: "file"; path: string; content: string; tracked: boolean; managed: Managed; executable?: boolean }
+  | { kind: "link"; path: string; target: string; tracked: boolean; managed: Managed };
+export type Managed = "whole" | "block";
+/** What a generator sees; `read` returns a root-relative file's text, or null when it is missing. */
+export type SyncContext = {
+  root: string;
+  config: ResolvedConfig;
+  workspace: Workspace;
+  read(rel: string): string | null;
+};
+/** Computes outputs from the context alone; it never writes, so sync can validate everything first. */
+export type Generator = (ctx: SyncContext) => { outputs: Output[]; errors: string[] };
+
+const BUNFIG_PATH = "bunfig.toml";
+const BUNFIG_HEADER = "# Generated by repo sync. Do not edit.";
+// auto = "disable": with no node_modules above a script, bun would fetch a missing import from the registry.
+const BUNFIG = `${BUNFIG_HEADER}\n[install]\nlinker = "hoisted"\nauto = "disable"\n`;
+
+const INDEX_PATH = "references/INDEX.md";
+const INDEX_NEW = "# References\n";
+const STACK_SCOPE = "@workerstack/";
+const DEPENDENCY_DIR = `${"node"}_modules/`;
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"] as const;
+
+/** bunfig.toml, refusing to replace one that lacks the generated header. */
+export const bunfig: Generator = (ctx) => {
+  const existing = ctx.read(BUNFIG_PATH);
+  if (existing !== null && lines(existing)[0] !== BUNFIG_HEADER) {
+    return { outputs: [], errors: [`${BUNFIG_PATH} is hand-written; delete it so repo sync can own it`] };
+  }
+  return {
+    outputs: [{ kind: "file", path: BUNFIG_PATH, content: BUNFIG, tracked: true, managed: "whole" }],
+    errors: [],
+  };
+};
+
+/**
+ * The repo:packages and repo:stack sections of references/INDEX.md, under the docs pack; in this repo also the
+ * repo:skills and repo:refs maps of its own skills and references.
+ */
+export const index: Generator = (ctx) => {
+  if (!ctx.config.packs.includes("docs")) return { outputs: [], errors: [] };
+
+  const errors: string[] = [];
+  const sections: [name: string, body: string][] = [];
+  const packageIndexes: Output[] = [];
+  const { packages } = ctx.workspace;
+  if (packages.length > 0) {
+    const entries: string[] = [];
+    for (const { dir, manifest } of packages) {
+      const text = ctx.read(`${dir}/${INDEX_PATH}`);
+      if (text === null) {
+        errors.push(`${dir} has no ${INDEX_PATH}; every workspace package needs one`);
+        continue;
+      }
+      const title = lines(text)
+        .map((line) => line.trim())
+        .find((line) => line !== "");
+      const description = title === undefined ? "" : `: ${title.replace(/^# /, "")}`;
+      entries.push(`- [${manifest.name || dir}](../${dir}/${INDEX_PATH})${description}`);
+      const deps = mergeSection(text, "deps", depsLines(dir, manifest, packages).join("\n"));
+      if (deps.ok)
+        packageIndexes.push({
+          kind: "file",
+          path: `${dir}/${INDEX_PATH}`,
+          content: deps.text,
+          tracked: true,
+          managed: "block",
+        });
+      else errors.push(`${dir}/${INDEX_PATH}: ${deps.error}`);
+    }
+    sections.push(["packages", entries.join("\n")]);
+  }
+  const stack = stackNames(ctx.workspace).map((name) => `- [${name}](../node_modules/${name}/${INDEX_PATH})`);
+  sections.push(["stack", stack.join("\n")]);
+  if (isSelfName(ctx.workspace.manifest.name)) {
+    const maps = mapSections(ctx.root);
+    sections.push(["skills", maps.skills], ["refs", maps.refs]);
+  }
+
+  let text = ctx.read(INDEX_PATH) ?? INDEX_NEW;
+  for (const [name, body] of sections) {
+    const merged = mergeSection(text, name, body);
+    if (merged.ok) text = merged.text;
+    else errors.push(`${INDEX_PATH}: ${merged.error}`);
+  }
+  if (errors.length > 0) return { outputs: [], errors };
+  return {
+    outputs: [{ kind: "file", path: INDEX_PATH, content: text, tracked: true, managed: "block" }, ...packageIndexes],
+    errors: [],
+  };
+};
+
+/**
+ * The repo:deps lines of the INDEX of package `dir`: one link per dependency (any field) that is a workspace package,
+ * then one per other `@workerstack/*` package, each group sorted by name. A workspace package wins over the installed
+ * one, so a workspace `@workerstack/x` is linked in place.
+ */
+function depsLines(dir: string, manifest: PackageJson, packages: readonly WorkspacePackage[]): string[] {
+  const names = new Set(DEPENDENCY_FIELDS.flatMap((field) => Object.keys(manifest[field] ?? {})));
+  const inWorkspace = new Map(
+    packages.flatMap((pkg) => (pkg.manifest.name === undefined ? [] : [[pkg.manifest.name, pkg.dir] as const])),
+  );
+  const link = (name: string, target: string) =>
+    `- [${name}](${path.posix.relative(`${dir}/references`, `${target}/${INDEX_PATH}`)})`;
+  const workspace = [...names].filter((name) => inWorkspace.has(name)).sort();
+  const stack = [...names].filter((name) => !inWorkspace.has(name) && name.startsWith(STACK_SCOPE)).sort();
+  return [
+    ...workspace.map((name) => link(name, inWorkspace.get(name) as string)),
+    ...stack.map((name) => link(name, `${DEPENDENCY_DIR}${name}`)),
+  ];
+}
+
+/** Under the agents pack, `.repo/lessons/INDEX.md` for the lessons under `.repo/lessons`, and one error per lesson that breaks the format. */
+export const lessons: Generator = (ctx) => {
+  if (!ctx.config.packs.includes("agents")) return { outputs: [], errors: [] };
+  const errors = lessonProblems(ctx.root);
+  if (!fs.existsSync(path.join(ctx.root, LESSONS_DIR))) return { outputs: [], errors };
+  const output: Output = {
+    kind: "file",
+    path: `${LESSONS_DIR}/${INDEX_NAME}`,
+    content: renderLessonsIndex(ctx.root),
+    tracked: true,
+    managed: "whole",
+  };
+  return { outputs: [output], errors };
+};
+
+/** The agent trees of the enabled hosts, under the agents pack; a failed render is its errors and no outputs. */
+export const trees: Generator = (ctx) => {
+  if (!ctx.config.packs.includes("agents")) return { outputs: [], errors: [] };
+  const result = renderTrees(ctx);
+  return result.ok ? { outputs: result.outputs, errors: [] } : { outputs: [], errors: result.errors };
+};
+
+/** Every generator, in the order sync runs and reports them. */
+export const GENERATORS: readonly Generator[] = [bunfig, index, lessons, trees, release, nightly, releaseWorkflow];
+
+/** Every `@workerstack/*` dependency name of the root and its packages, deduped and sorted. */
+function stackNames(workspace: Workspace): string[] {
+  const names = new Set<string>();
+  for (const manifest of [workspace.manifest, ...workspace.packages.map((pkg) => pkg.manifest)]) {
+    for (const field of DEPENDENCY_FIELDS) {
+      for (const name of Object.keys(manifest[field] ?? {})) if (name.startsWith(STACK_SCOPE)) names.add(name);
+    }
+  }
+  return [...names].sort();
+}

package/cli/sync/oxlint-config.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from "vitest";
+import type { LintSkip } from "../config.ts";
+import { oxlintConfig } from "./oxlint-config.ts";
+import type { PackageJson, Workspace } from "./workspace.ts";
+
+const workspace = (manifest: PackageJson, packages: Workspace["packages"] = []): Workspace => ({
+  root: "/repo",
+  manifest,
+  packages,
+});
+const configOf = (ws: Workspace, skips: readonly LintSkip[] = []): unknown => {
+  const built = oxlintConfig(ws, skips);
+  if (!built.ok) throw new Error(built.errors.join("\n"));
+  return JSON.parse(built.value);
+};
+
+const SIZE = { skipBlankLines: true, skipComments: true };
+const OFF = Object.fromEntries(
+  ["correctness", "suspicious", "pedantic", "perf", "style", "restriction", "nursery"].map((name) => [name, "off"]),
+);
+const REPO_RULES = {
+  "repo/as-needs-reason": "error",
+  "repo/boundaries": "error",
+  "repo/class-file": "error",
+  "repo/config-file": "error",
+  "repo/entry-file": "error",
+  "repo/env-in-config": "error",
+  "repo/filename-matches-export": "error",
+  "repo/index-file": "error",
+  "repo/no-commented-out-code": "error",
+  "repo/no-mock-of-subject": "error",
+  "repo/no-module-side-effects": "error",
+  "repo/no-module-state": "error",
+  "repo/no-side-effect-import": "error",
+  "repo/no-v8-ignore": "error",
+  "repo/skip-on-platform": "error",
+  "repo/todo-needs-id": "error",
+  "repo/types-file": "error",
+  "unicorn/prefer-node-protocol": "error",
+};
+const BASE_RULES = {
+  "eslint/max-lines": ["error", { max: 200, ...SIZE }],
+  "eslint/max-lines-per-function": ["error", { max: 30, ...SIZE }],
+  "eslint/max-params": ["error", { max: 3 }],
+  "eslint/complexity": ["error", { max: 10 }],
+  "eslint/max-depth": ["error", { max: 4 }],
+  "eslint/no-shadow": "error",
+  "eslint/no-else-return": "error",
+  "eslint/no-nested-ternary": "error",
+  "eslint/no-param-reassign": "error",
+  "eslint/no-await-in-loop": "error",
+  "eslint/require-await": "error",
+  "eslint/no-console": "error",
+  "import/no-cycle": "error",
+  "import/no-default-export": "error",
+  "typescript/consistent-type-assertions": ["error", { assertionStyle: "as", objectLiteralTypeAssertions: "allow" }],
+  "typescript/no-explicit-any": "error",
+  "typescript/no-non-null-assertion": "error",
+  "typescript/no-floating-promises": "error",
+  "typescript/no-unnecessary-condition": "error",
+  "typescript/no-unsafe-argument": "error",
+  "typescript/no-unsafe-assignment": "error",
+  "typescript/switch-exhaustiveness-check": "error",
+};
+const TEST_OVERRIDE = {
+  files: ["**/*.{test,spec}.{ts,tsx}", "**/*.e2e.{ts,tsx}"],
+  rules: {
+    "repo/no-module-side-effects": "off",
+    "repo/no-module-state": "off",
+    "vitest/expect-expect": "error",
+    "vitest/no-conditional-tests": "error",
+    "vitest/no-focused-tests": "error",
+    "vitest/no-disabled-tests": "error",
+    "vitest/warn-todo": "error",
+    "eslint/no-console": "off",
+  },
+};
+const CONFIG_OVERRIDE = {
+  files: ["**/*.config.ts"],
+  rules: { "import/no-default-export": "off", "repo/no-module-side-effects": "off" },
+};
+
+describe("oxlintConfig base", () => {
+  it("loads the repo plugin, turns every rule on at error, all categories off, type-aware, tests and configs relaxed, fixtures and reject files ignored", () => {
+    expect(configOf(workspace({ name: "app" }))).toEqual({
+      plugins: ["eslint", "typescript", "unicorn", "oxc", "import", "vitest"],
+      jsPlugins: [{ name: "repo", specifier: "@workerstack/repo/lint" }],
+      categories: OFF,
+      options: { typeAware: true, respectEslintDisableDirectives: false },
+      ignorePatterns: ["**/fixtures/**", "**/*.reject.{ts,tsx}"],
+      rules: { ...REPO_RULES, ...BASE_RULES },
+      overrides: [TEST_OVERRIDE, CONFIG_OVERRIDE],
+    });
+  });
+});
+
+describe("oxlintConfig per package", () => {
+  it("lets each bin of the root and every package run at import, and each ./lint export default-export and assemble its plugin", () => {
+    const ws = workspace({ name: "app", bin: "./bin/app.ts", exports: { "./lint": { default: "./lint/index.ts" } } }, [
+      { dir: "packages/cli", manifest: { bin: { cli: "./bin/cli.ts", "cli-dev": "bin/dev.ts" } } },
+      { dir: "packages/rules", manifest: { exports: { ".": "./index.ts", "./lint": "./cli/lint/index.ts" } } },
+    ]);
+    expect(configOf(ws)).toMatchObject({
+      overrides: [
+        TEST_OVERRIDE,
+        CONFIG_OVERRIDE,
+        {
+          files: ["bin/app.ts", "packages/cli/bin/cli.ts", "packages/cli/bin/dev.ts"],
+          rules: { "repo/no-module-side-effects": "off" },
+        },
+        {
+          files: ["lint/index.ts", "packages/rules/cli/lint/index.ts"],
+          rules: { "import/no-default-export": "off", "repo/index-file": "off" },
+        },
+      ],
+    });
+  });
+
+  it("reads no override from a bin or ./lint export of another shape", () => {
+    const ws = workspace({ bin: 7, exports: "./index.ts" }, [
+      { dir: "a", manifest: { bin: { a: 1 }, exports: { "./lint": { import: "./lint.ts" } } } },
+      { dir: "b", manifest: { bin: ["./bin/b.ts"], exports: { "./lint": 3 } } },
+      { dir: "c", manifest: { bin: null, exports: null } },
+    ]);
+    expect(configOf(ws)).toHaveProperty("overrides", [TEST_OVERRIDE, CONFIG_OVERRIDE]);
+  });
+});
+
+const REASON = "the parsed config cache lives for the process";
+const APP = workspace({ name: "app", bin: "./bin/app.ts" });
+
+it("oxlintConfig writes one override per skip after every other, turning off only the named rules for the named files", () => {
+  const skips = [
+    { files: ["src/cache.ts"], rules: ["repo/no-module-state"], reason: REASON },
+    { files: ["src/**/*.ts", "lib/*.ts"], rules: ["eslint/max-lines", "vitest/no-disabled-tests"], reason: REASON },
+  ];
+  expect(configOf(APP, skips)).toEqual(
+    expect.objectContaining({
+      rules: { ...REPO_RULES, ...BASE_RULES },
+      overrides: [
+        TEST_OVERRIDE,
+        CONFIG_OVERRIDE,
+        { files: ["bin/app.ts"], rules: { "repo/no-module-side-effects": "off" } },
+        { files: ["src/cache.ts"], rules: { "repo/no-module-state": "off" } },
+        { files: ["src/**/*.ts", "lib/*.ts"], rules: { "eslint/max-lines": "off", "vitest/no-disabled-tests": "off" } },
+      ],
+    }),
+  );
+});
+
+it("oxlintConfig refuses a rule the generated config does not run, naming the entry", () => {
+  const skips = [
+    { files: ["src/a.ts"], rules: ["repo/no-module-state"], reason: REASON },
+    { files: ["src/b.ts"], rules: ["eslint/no-console", "repo/no-modul-state"], reason: REASON },
+    { files: ["src/c.ts"], rules: ["no-module-state"], reason: REASON },
+  ];
+  expect(oxlintConfig(APP, skips)).toEqual({
+    ok: false,
+    errors: [
+      'workerstack.config.ts: lint.skip[1].rules: "repo/no-modul-state" is not a rule the generated config runs',
+      'workerstack.config.ts: lint.skip[2].rules: "no-module-state" is not a rule the generated config runs',
+    ],
+  });
+});
+
+it("oxlintConfig accepts the script rules in a skip and leaves them out of its overrides, writing none for an entry of only them", () => {
+  const skips = [
+    { files: ["src/retry.ts"], rules: ["repo/magic-number", "repo/magic-string"], reason: REASON },
+    { files: ["src/user.ts"], rules: ["repo/guard-rejects"], reason: REASON },
+    { files: ["src/cache.ts"], rules: ["repo/magic-number", "repo/no-module-state"], reason: REASON },
+  ];
+  expect(configOf(APP, skips)).toHaveProperty("overrides", [
+    TEST_OVERRIDE,
+    CONFIG_OVERRIDE,
+    { files: ["bin/app.ts"], rules: { "repo/no-module-side-effects": "off" } },
+    { files: ["src/cache.ts"], rules: { "repo/no-module-state": "off" } },
+  ]);
+});

package/cli/sync/oxlint-config.ts

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { CONFIG_FILE, type LintSkip } from "../config.ts";
+import { binsOf, isRecord } from "../lint/manifest.ts";
+import { SCRIPT_RULES } from "../lint/script-rules.ts";
+import type { PackageJson, Workspace } from "./workspace.ts";
+
+/** The generated config sync writes at the root. */
+export const OXLINT_CONFIG_PATH = ".oxlintrc.json";
+/** The skip-free copies `repo check` writes beside it for one run, each named for its process. */
+export const UNSKIPPED_CONFIG_GLOB = ".oxlintrc.unskipped-*.json";
+export const unskippedConfigPath = (pid: number): string => UNSKIPPED_CONFIG_GLOB.replace("*", String(pid));
+/** Fixture trees are copies of other repos' files: never linted or formatted. */
+export const FIXTURES = "**/fixtures/**";
+/** Reject files hold code that must not compile, checked by `repo check` and `repo turn` instead of linted. */
+const REJECT_FILES = "**/*.reject.{ts,tsx}";
+const TESTS = ["**/*.{test,spec}.{ts,tsx}", "**/*.e2e.{ts,tsx}"];
+const CONFIGS = "**/*.config.ts";
+const CATEGORIES = ["correctness", "suspicious", "pedantic", "perf", "style", "restriction", "nursery"] as const;
+/** Size limits count code only: blank lines and comments are free. */
+const CODE_LINES = { skipBlankLines: true, skipComments: true };
+const OFF_SIDE_EFFECTS = { "repo/no-module-side-effects": "off" };
+const OFF_DEFAULT_EXPORT = { "import/no-default-export": "off" };
+
+/** Every rule the base turns on; each is an error, none a warning. The `repo/` rules are `@workerstack/repo/lint`'s. */
+const RULES: Record<string, string | [string, Record<string, unknown>]> = {
+  "repo/as-needs-reason": "error",
+  "repo/boundaries": "error",
+  "repo/class-file": "error",
+  "repo/config-file": "error",
+  "repo/entry-file": "error",
+  "repo/env-in-config": "error",
+  "repo/filename-matches-export": "error",
+  "repo/index-file": "error",
+  "repo/no-commented-out-code": "error",
+  "repo/no-mock-of-subject": "error",
+  "repo/no-module-side-effects": "error",
+  "repo/no-module-state": "error",
+  "repo/no-side-effect-import": "error",
+  "repo/no-v8-ignore": "error",
+  "repo/skip-on-platform": "error",
+  "repo/todo-needs-id": "error",
+  "repo/types-file": "error",
+  "unicorn/prefer-node-protocol": "error",
+  "eslint/max-lines": ["error", { max: 200, ...CODE_LINES }],
+  "eslint/max-lines-per-function": ["error", { max: 30, ...CODE_LINES }],
+  "eslint/max-params": ["error", { max: 3 }],
+  "eslint/complexity": ["error", { max: 10 }],
+  "eslint/max-depth": ["error", { max: 4 }],
+  "eslint/no-shadow": "error",
+  "eslint/no-else-return": "error",
+  "eslint/no-nested-ternary": "error",
+  "eslint/no-param-reassign": "error",
+  "eslint/no-await-in-loop": "error",
+  "eslint/require-await": "error",
+  "eslint/no-console": "error",
+  "import/no-cycle": "error",
+  "import/no-default-export": "error",
+  // `repo/as-needs-reason` checks `x as T`; this refuses `<T>x`, which takes no reason comment. Object literals stay
+  // free so `{} as T` reaches the reason check too.
+  "typescript/consistent-type-assertions": ["error", { assertionStyle: "as", objectLiteralTypeAssertions: "allow" }],
+  "typescript/no-explicit-any": "error",
+  "typescript/no-non-null-assertion": "error",
+  "typescript/no-floating-promises": "error",
+  "typescript/no-unnecessary-condition": "error",
+  "typescript/no-unsafe-argument": "error",
+  "typescript/no-unsafe-assignment": "error",
+  "typescript/switch-exhaustiveness-check": "error",
+};
+
+/** Test rules, only in test files, where module-scope setup and printing are allowed. */
+const TEST_RULES: Record<string, string> = {
+  "repo/no-module-state": "off",
+  "vitest/expect-expect": "error",
+  "vitest/no-conditional-tests": "error",
+  "vitest/no-focused-tests": "error",
+  "vitest/no-disabled-tests": "error",
+  "vitest/warn-todo": "error",
+  "eslint/no-console": "off",
+};
+
+/** The file a manifest's `./lint` export names, as a path or as its `default` condition. */
+function lintExportOf(manifest: PackageJson): unknown[] {
+  const target = isRecord(manifest.exports) ? manifest.exports["./lint"] : undefined;
+  return [isRecord(target) ? target.default : target];
+}
+
+/** Every string `pick` finds in the root's and each package's manifest, as a root-relative POSIX path, sorted. */
+function filesOf(workspace: Workspace, pick: (manifest: PackageJson) => unknown[]): string[] {
+  const all = [{ dir: "", manifest: workspace.manifest }, ...workspace.packages];
+  const files = all.flatMap(({ dir, manifest }) =>
+    pick(manifest).flatMap((file) => (typeof file === "string" ? [path.posix.join(dir, file)] : [])),
+  );
+  return [...new Set(files)].sort();
+}
+
+/**
+ * A bin runs its main at import, and a plugin entry must default-export the plugin it assembles from its rules: each
+ * gets an override when there is one.
+ */
+function packageOverrides(workspace: Workspace): { files: string[]; rules: Record<string, string> }[] {
+  const overrides = [
+    { files: filesOf(workspace, (manifest) => binsOf(manifest.bin)), rules: OFF_SIDE_EFFECTS },
+    { files: filesOf(workspace, lintExportOf), rules: { ...OFF_DEFAULT_EXPORT, "repo/index-file": "off" } },
+  ];
+  return overrides.filter((override) => override.files.length > 0);
+}
+
+/** The generated config's text, or why a skip could not be turned into an override. */
+export type Built = { ok: true; value: string } | { ok: false; errors: string[] };
+
+const isOn = (setting: string | [string, unknown]) => (Array.isArray(setting) ? setting[0] : setting) === "error";
+
+/** Every rule key the generated config sets to `error`, in the base or in the test override. */
+const runRules = (): Set<string> =>
+  new Set(
+    [...Object.entries(RULES), ...Object.entries(TEST_RULES)].flatMap(([rule, setting]) =>
+      isOn(setting) ? [rule] : [],
+    ),
+  );
+
+/** One line per skipped rule name neither the generated config nor a script check runs, naming its entry. */
+function unknownRules(skips: readonly LintSkip[]): string[] {
+  const run = runRules();
+  return skips.flatMap((skip, index) =>
+    skip.rules
+      .filter((rule) => !run.has(rule) && !SCRIPT_RULES.includes(rule))
+      .map((rule) => `${CONFIG_FILE}: lint.skip[${index}].rules: "${rule}" is not a rule the generated config runs`),
+  );
+}
+
+/**
+ * Each `lint.skip` entry as an override turning off its oxlint rules for its files; the script rules are no oxlint
+ * rules (`repo check` and `repo turn` drop their hits), so an entry of only those writes none.
+ */
+function skipOverrides(skips: readonly LintSkip[]): { files: readonly string[]; rules: Record<string, string> }[] {
+  return skips.flatMap((skip) => {
+    const rules = skip.rules.filter((rule) => !SCRIPT_RULES.includes(rule));
+    return rules.length === 0
+      ? []
+      : [{ files: skip.files, rules: Object.fromEntries(rules.map((rule) => [rule, "off"])) }];
+  });
+}
+
+/**
+ * The oxlint config: the repo plugin and the named rules, type-aware, with eslint-disable comments ignored. Each
+ * `lint.skip` entry is an override written last, so it turns off only its rules for only its files.
+ */
+export function oxlintConfig(workspace: Workspace, skips: readonly LintSkip[]): Built {
+  const errors = unknownRules(skips);
+  if (errors.length > 0) return { ok: false, errors };
+  const config = {
+    plugins: ["eslint", "typescript", "unicorn", "oxc", "import", "vitest"],
+    // A specifier, not a path: oxlint resolves it from the config's node_modules, or from NODE_PATH (`repo lint`).
+    jsPlugins: [{ name: "repo", specifier: "@workerstack/repo/lint" }],
+    categories: Object.fromEntries(CATEGORIES.map((category) => [category, "off"])),
+    options: { typeAware: true, respectEslintDisableDirectives: false },
+    ignorePatterns: [FIXTURES, REJECT_FILES],
+    rules: RULES,
+    overrides: [
+      { files: TESTS, rules: { ...OFF_SIDE_EFFECTS, ...TEST_RULES } },
+      // vitest and workerstack configs must default-export, and call their define helper at import.
+      { files: [CONFIGS], rules: { ...OFF_DEFAULT_EXPORT, ...OFF_SIDE_EFFECTS } },
+      ...packageOverrides(workspace),
+      ...skipOverrides(skips),
+    ],
+  };
+  return { ok: true, value: `${JSON.stringify(config, null, 2)}\n` };
+}

package/cli/sync/release-jobs.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { HEADER, context } from "../fixtures/release-context.ts";
+import { GENERATORS } from "./outputs.ts";
+import { release } from "./release.ts";
+
+const CI_PATH = ".github/workflows/ci.yml";
+
+describe("release gates", () => {
+  it("is a generator", () => {
+    expect(GENERATORS).toContain(release);
+  });
+
+  it("writes nothing with the pack off", () => {
+    expect(release(context(["agents", "standards", "docs"]))).toEqual({ outputs: [], errors: [] });
+  });
+
+  it("rewrites a ci.yml that has the generated header on its first line", () => {
+    const result = release(context(["release"], {}, { [CI_PATH]: `${HEADER}\nname: old\n` }));
+    expect(result.errors).toEqual([]);
+    expect(result.outputs).toHaveLength(1);
+  });
+
+  it("refuses a hand-written ci.yml", () => {
+    expect(release(context(["release"], {}, { [CI_PATH]: "name: ci\n" }))).toEqual({
+      outputs: [],
+      errors: [".github/workflows/ci.yml is hand-written; delete it so repo sync can own it"],
+    });
+  });
+});

package/cli/sync/release-reports.test.ts

@@ -0,0 +1,31 @@
+import { BASE_CONFIG } from "../fixtures/base-config.ts";
+import { expect, it } from "vitest";
+import { REPORT_FILE } from "../scripts/ci-skips.constants.ts";
+import { release } from "./release.ts";
+
+const output = release({
+  root: "/repo",
+  config: { packs: ["release"], agents: { hosts: [], skills: [] }, ...BASE_CONFIG },
+  workspace: { root: "/repo", manifest: {}, packages: [] },
+  read: () => null,
+}).outputs[0];
+const yaml = output?.kind === "file" ? output.content : "";
+const value = (key: string) => new RegExp(`^\\s+(?:- )?${key}: (.+)$`, "m").exec(yaml)?.[1] ?? "";
+const glob = (pattern: string) => new RegExp(`^${pattern.replaceAll("*", ".*")}$`);
+
+it("each OS's report file name is one the skips check reads", () => {
+  const file = value("REPORT");
+  for (const os of ["Linux", "Windows", "macOS"]) {
+    expect(file.replace("${{ runner.os }}", os)).toMatch(REPORT_FILE);
+  }
+});
+
+it("the uploaded path is the report the gates wrote, and each matrix artifact matches the download pattern", () => {
+  expect(yaml).toContain(`path: ${value("REPORT")}`);
+  const pattern = value("pattern");
+  for (const os of ["ubuntu-latest", "windows-latest", "macos-latest"]) {
+    expect(`ci-report-${os}`).toMatch(glob(pattern));
+  }
+  expect(yaml).toContain("name: ci-report-${{ matrix.os }}");
+  expect(yaml).toContain("merge-multiple: true");
+});

package/cli/sync/release-workflow.constants.ts

@@ -0,0 +1,61 @@
+import { CHECKOUT_STEP, CI_HEADER, INSTALL_STEP, SETUP_BUN_STEP } from "./release.constants.ts";
+
+/** The generated header, which must be the first line of a release.yml sync owns. */
+export const RELEASE_HEADER: string = CI_HEADER;
+export const RELEASE_PATH: string = ".github/workflows/release.yml";
+
+/** Action pin, a full commit SHA with its release as the comment. */
+const SETUP_NODE: string = "actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0";
+/** Trusted publishing needs npm 11.5.1 and Node 22.14; dist-tags under it need npm 11.21. */
+const NPM_VERSION: string = "12.2.2";
+const NODE_VERSION: string = "24";
+export const GATE_TIMEOUT_MINUTES: number = 60;
+export const PUBLISH_TIMEOUT_MINUTES: number = 25;
+export const GITHUB_TIMEOUT_MINUTES: number = 10;
+
+/** The tag every job works on: the pushed tag, or the one given by hand. */
+const TAG_ENV: string = "      TAG: ${{ inputs.tag || github.ref_name }}";
+const TOKEN_ENV: string = "      GH_TOKEN: ${{ github.token }}";
+const CHECKOUT_REF: string = "          ref: ${{ inputs.tag || github.ref }}";
+
+/** Every job checks out the tag, not the default branch a dispatch runs on. */
+export const CHECKOUT_TAG_STEP: string = `${CHECKOUT_STEP}
+        with:
+${CHECKOUT_REF}`;
+export const CHECKOUT_TAG_FULL_STEP: string = `${CHECKOUT_TAG_STEP}
+          fetch-depth: 0`;
+export const BUN_STEPS: readonly string[] = [SETUP_BUN_STEP, INSTALL_STEP];
+export const NODE_STEPS: readonly string[] = [
+  `      - uses: ${SETUP_NODE}
+        with:
+          node-version: "${NODE_VERSION}"
+          package-manager-cache: false`,
+  `      - run: npm install --global npm@${NPM_VERSION}`,
+];
+export const GATE_ENV: string = `    env:\n${TAG_ENV}\n${TOKEN_ENV}`;
+export const PUBLISH_ENV: string = `    env:\n${TAG_ENV}`;
+export const GATE_PERMISSIONS: string = "    permissions:\n      actions: read\n      contents: read";
+export const PUBLISH_PERMISSIONS: string = "    permissions:\n      contents: read\n      id-token: write";
+export const GITHUB_PERMISSIONS: string = "    permissions:\n      contents: write";
+
+/** The workflow text before the jobs; `%NAME%` is the package name, which the tags are prefixed with. */
+export const PREAMBLE: string = `name: release
+
+on:
+  push:
+    tags:
+      - "%NAME%@*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to release, e.g. %NAME%@1.0.0"
+        required: true
+
+concurrency:
+  group: release-\${{ inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:`;