lazycodex-ai 5.1.51 → 5.1.55

package/packages/omo-codex/plugin/skills/programming/references/testing/junk-classes.md

@@ -0,0 +1,56 @@
+# Junk classes, retention bar, marks
+
+One table for three jobs: writing a test (`programming`), cleaning a branch (`remove-ai-slops`), and auditing a suite. A test that matches a class below is junk unless the retention bar keeps it. The gate reviewer applies the same table; a test that would be deleted in review is a test not to write.
+
+## Marks (one per test declaration; one per row when table rows differ)
+
+| Mark | Meaning | What the ledger line names |
+|---|---|---|
+| `R` retain | guards a contract | the contract and the regression it catches |
+| `F` fix | real contract, weak assertion (a negative that passes when only one of several items is missing; `toBeTruthy` on a value that is always an object; a lower bound over independently removable items) | the repaired assertion |
+| `C` consolidate | the assertion moves into a keeper (a table row in a sibling, a stronger boundary suite); the declaration disappears | the keeper |
+| `D` delete | no contract, or another test owns it | the owner test that still fails on the regression, or why no contract exists; plus a proof receipt |
+
+## Junk classes (candidates for `D` or `C`)
+
+| Class | What it looks like | Proof that it is junk |
+|---|---|---|
+| Cannot fail | no assertion; `expect(x).toBe(x)`; expected value computed by the code under test; `assert result is not None` and nothing else; an override fixture equal to its fallback; assertion inside a callback that never runs | a mutation of the owner the test survives |
+| Change certificate | pins the diff, not a behavior: a constant, a string, a rename, a call, the shape of the edit the PR made | revert the change: the test fails for the diff, not for a regression; the run is the proof |
+| Mock echo | the mock returns the value the test then asserts; the behavior lives in the mock | mutate the owner: test stays green |
+| Implementation mirror | asserts call order, call count, private helper args, bracket-notation access to private members, internal state shape that a behavior-preserving refactor would break | a keeper at the real boundary catches the behavioral mutation |
+| Prose pin | asserts wording, headings, section order, snapshots, phrase counts, or length of `SKILL.md`, prompts, `AGENTS.md`, docs, rule text | no runtime behavior to mutate; cite the repo's prose-test rule |
+| Copied inventory | a hard-coded list of exports, files, tools, keys that mirrors the source and fails only when someone edits both | a generator or freshness check or a real consumer already owns it |
+| Source grep | reads a source file and greps for a string or import | an identifier-only refactor turns it red for no reason; a behavior mutation it misses |
+| Duplicate contract | the same input/output asserted at two or more layers with no distinct transport or lifecycle risk; an adapter package's copy of a Core package's test | the mutation is caught by both: keep the stronger boundary |
+| Layer replay | a shared helper re-tested through every wrapper that calls it | one helper owner test plus one wiring test per real wrapper |
+| Seam keeper | exists to keep a test-only export, flag, getter, or reset hook alive | `knip` or grep shows no production caller; delete test and seam together |
+| Fabricated postcondition | the fixture supplies the receipt, ordering, or stored state the owner should produce; asserts a store nothing writes | mutate the writer: test stays green |
+| Capability restatement | asserts a flag or capability is `true` instead of the delivery it promises | a delivery test owns it, or none exists (then `F`, not `D`) |
+| Input transcript | asserts the argv, flags, URL, or request the code handed to a child, not the state the child resolved | mutate the child's handling of that input: test stays green; the witness drives the real component and asserts resolved state |
+| Misnamed | the name promises a behavior its inputs never exercise | read the assertions; mark by what it actually checks |
+| Near-duplicate cases | N tests differing only in input literals | `C` into one table (`it.each` / `test.each`, or a loop over a typed array where the package's test typings lack `.each`); typecheck after; every old assertion stays a row |
+
+## Retention bar (these stay `R` even when they match a class above)
+
+Keep a test that independently guards a public API, SDK, RPC or app-server protocol, config schema or default, migration, storage format, security boundary, platform behavior, prompt-byte or shipped-copy equality between real artifacts, generated or cross-language contract, package or install payload, release, or architecture invariant (meta-audits, tracked-artifact audits). Say which one in the test. Also keep:
+
+- **Node-compat suites**: anything that runs shipped code under real Node is a platform contract even when a Bun run covers the same assertions.
+- **Issue regressions**: a test naming an issue number stays until another test is shown to fail on that exact regression.
+- **Machine-consumed text**: parsed fields, sentinel tokens, tool names, schema keys, a routing-bearing fragment of a parsed frontmatter `description`.
+- **Baseline-red tests**: a test that fails on the unchanged base is a product bug to fix at its owner, never a deletion.
+
+Outside that list, a source-inspection test survives only as the cheapest independent guard of a user-facing key, byte, or path that an identifier-only refactor leaves green. Static or slow is never a reason to delete.
+
+## Proof rule for `D` and `C`
+
+Break the production owner (flip a condition, drop a branch, return a constant, skip a write) and run the candidate and its named keeper on the unmodified test tree:
+
+| Candidate | Keeper | Verdict |
+|---|---|---|
+| green | red | candidate cannot catch this: `D` proven |
+| red | red | candidate redundant for this behavior: `D` or `C` proven |
+| red | green | candidate is the ONLY proof: `R`, or `C` it into the keeper and re-run |
+| green | green | the mutation missed the behavior: confirm the edit landed, then pick another mutation |
+
+Restore the owner byte for byte; never commit a mutation. A prose pin needs no mutation: the receipt is the assertion line plus the repo rule. Coverage diffs prove lines still execute, not that anything still asserts on them; pair a coverage diff with at least one mutation per theme.

package/packages/omo-codex/plugin/skills/programming/references/typescript/README.md

@@ -184,10 +184,9 @@ Tests are strict too, with these exceptions (configure in `.oxlintrc.json` overr
 |---|---|
 | Use `expect()` assertions | That's how testing works |
 | Use magic numbers | Test data |
-| Access private members via bracket notation | Testing internals |
 | Skip readonly on test fixtures | Mutable setup/teardown |
 
-Tests still follow the iron list — branded types, typed errors, exhaustive switch.
+Tests still follow the iron list — branded types, typed errors, exhaustive switch — and the authoring gate in [`../testing/README.md`](../testing/README.md). Private members are reached through the public boundary, never by bracket notation: a test on internals is an implementation mirror that a behavior-preserving refactor breaks.
 
 ## Existing codebases
 

package/packages/omo-codex/plugin/skills/programming/scripts/go/new-project.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+/**
+ * Scaffold a new Go project with the canonical strict layout: go.mod (go 1.23),
+ * .golangci.yml (v2 strict bundle), Taskfile.yml, cmd/server/main.go,
+ * internal/{cmd,config,api,domain,obs} skeletons, and .github/workflows/ci.yml.
+ *
+ * ─── How to run ───
+ * 1. Install Bun: curl -fsSL https://bun.sh/install | bash
+ * 2. Run:
+ *      bun run new-project.ts myservice
+ *      bun run new-project.ts myservice --module github.com/your-org/myservice
+ * ──────────────────
+ *
+ * Templates live in ./templates/. `.tmpl` files take Python string.Template
+ * placeholders ($name, ${name}, $$ for a literal $); every other file is copied verbatim.
+ * Exit codes: 0 created, 1 scaffold failure, 2 usage error.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { assertNever, runTool } from "../shared/run-tool.ts";
+
+const USAGE = `Usage: bun run new-project.ts <name> [--path <dir>] [--module <path>] [--purpose <text>]
+
+Arguments:
+  name          Project directory and default module name
+
+Options:
+  --path        Parent dir (default: current dir)
+  --module      Go module path (default: <name>)
+  --purpose     Short purpose for AGENTS.md (default: HTTP)
+  -h, --help    Show this help`;
+
+const TEMPLATES_DIR = join(import.meta.dir, "templates");
+
+const LAYOUT = [
+  "cmd/server",
+  "internal/cmd",
+  "internal/config",
+  "internal/api",
+  "internal/domain",
+  "internal/obs",
+  ".github/workflows",
+] as const;
+
+const FILES = [
+  { template: ".golangci.yml", output: ".golangci.yml", substitute: false },
+  { template: "Taskfile.yml", output: "Taskfile.yml", substitute: false },
+  { template: ".editorconfig", output: ".editorconfig", substitute: false },
+  { template: "gitignore", output: ".gitignore", substitute: false },
+  { template: "ci.yml", output: ".github/workflows/ci.yml", substitute: false },
+  { template: "run.go", output: "internal/cmd/run.go", substitute: false },
+  { template: "config.go", output: "internal/config/config.go", substitute: false },
+  { template: "main.go.tmpl", output: "cmd/server/main.go", substitute: true },
+  { template: "AGENTS.md.tmpl", output: "AGENTS.md", substitute: true },
+  { template: "README.md.tmpl", output: "README.md", substitute: true },
+] as const;
+
+// Python string.Template grammar: $$ escape, $identifier, ${identifier}, or a bare $ (invalid).
+const PLACEHOLDER = /\$(?:(\$)|([_a-z][_a-z0-9]*)|\{([_a-z][_a-z0-9]*)\}|())/gi;
+
+type ProjectOptions = {
+  readonly name: string;
+  readonly path: string;
+  readonly module: string;
+  readonly purpose: string;
+};
+
+type Cli =
+  | { readonly kind: "run"; readonly options: ProjectOptions }
+  | { readonly kind: "help" }
+  | { readonly kind: "usage"; readonly problem: string };
+
+class ScaffoldError extends Error {
+  constructor(
+    readonly kind: "exists" | "template",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ScaffoldError";
+  }
+}
+
+function parseCli(): Cli {
+  try {
+    const { values, positionals } = parseArgs({
+      args: Bun.argv.slice(2),
+      options: {
+        path: { type: "string", default: "." },
+        module: { type: "string", default: "" },
+        purpose: { type: "string", default: "HTTP" },
+        help: { type: "boolean", short: "h", default: false },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+    if (values.help) return { kind: "help" };
+    const [name, ...extra] = positionals;
+    if (name === undefined || extra.length > 0) return { kind: "usage", problem: "expected exactly one project name" };
+    const options = { name, path: values.path, module: values.module || name, purpose: values.purpose };
+    return { kind: "run", options };
+  } catch (error) {
+    if (error instanceof TypeError) return { kind: "usage", problem: error.message };
+    throw error;
+  }
+}
+
+function substitute(template: string, file: string, values: ReadonlyMap<string, string>): string {
+  return template.replace(
+    PLACEHOLDER,
+    (match: string, escaped: string | undefined, named: string | undefined, braced: string | undefined) => {
+      if (escaped !== undefined) return "$";
+      const key = named ?? braced;
+      if (key === undefined) throw new ScaffoldError("template", `${file}: invalid placeholder near "${match}"`);
+      const value = values.get(key);
+      if (value === undefined) throw new ScaffoldError("template", `${file}: unknown placeholder $${key}`);
+      return value;
+    },
+  );
+}
+
+function initGoModule(projectDir: string, module: string): void {
+  const init = runTool("go", ["mod", "init", module], projectDir);
+  switch (init.kind) {
+    case "ok":
+      console.error(`  ran go mod init ${module}`);
+      return;
+    case "unavailable":
+    case "failed": {
+      const detail = init.kind === "unavailable" ? init.reason : `exit ${init.status}: ${init.stderr.trim()}`;
+      console.error(`  warn go mod init failed (${detail}); writing fallback go.mod`);
+      writeFileSync(join(projectDir, "go.mod"), `module ${module}\n\ngo 1.23\n`);
+      return;
+    }
+    default:
+      return assertNever(init);
+  }
+}
+
+function writeFiles(projectDir: string, { name, module, purpose }: ProjectOptions): void {
+  const values = new Map([
+    ["name", name],
+    ["module", module],
+    ["short_purpose", purpose],
+  ]);
+  for (const { template, output, substitute: render } of FILES) {
+    // The generated project is LF (its .editorconfig says end_of_line = lf); a CRLF checkout of the templates must not leak in.
+    const raw = readFileSync(join(TEMPLATES_DIR, template), "utf8").replace(/\r\n/g, "\n");
+    const outPath = join(projectDir, output);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, render ? substitute(raw, template, values) : raw);
+    console.error(`  wrote ${output}`);
+  }
+}
+
+function scaffold(options: ProjectOptions): void {
+  const projectDir = join(options.path, options.name);
+  if (existsSync(projectDir)) throw new ScaffoldError("exists", `✗ ${projectDir} already exists`);
+
+  mkdirSync(projectDir, { recursive: true });
+  for (const dir of LAYOUT) mkdirSync(join(projectDir, dir), { recursive: true });
+  initGoModule(projectDir, options.module);
+  writeFiles(projectDir, options);
+
+  console.error(`\nDone! cd ${projectDir}`);
+  console.error("  go get github.com/caarlos0/env/v11");
+  console.error("  task        # fmt + lint + test");
+}
+
+function main(): number {
+  const cli = parseCli();
+  switch (cli.kind) {
+    case "help":
+      console.log(USAGE);
+      return 0;
+    case "usage":
+      console.error(`Error: ${cli.problem}\n\n${USAGE}`);
+      return 2;
+    case "run":
+      break;
+    default:
+      return assertNever(cli);
+  }
+  try {
+    scaffold(cli.options);
+    return 0;
+  } catch (error) {
+    if (error instanceof ScaffoldError) {
+      console.error(error.message);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+process.exit(main());

package/packages/omo-codex/plugin/skills/programming/scripts/python/new-project.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env bun
+/**
+ * Scaffold a new Python project with ultra-strict config from pyproject-strict.md.
+ *
+ * ─── How to run ───
+ * 1. Install Bun: curl -fsSL https://bun.sh/install | bash
+ * 2. Install uv:  curl -LsSf https://astral.sh/uv/install.sh | sh
+ * 3. Run:
+ *      bun run new-project.ts myproject
+ *      bun run new-project.ts myproject --path ./workspace
+ *      bun run new-project.ts myproject --lib   # library (publishable)
+ * ──────────────────
+ *
+ * Creates via `uv init`, then injects basedpyright + ruff ALL + pytest config.
+ * Exit codes: 0 created, 1 scaffold or uv failure, 2 usage error.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { assertNever, runTool } from "../shared/run-tool.ts";
+
+const USAGE = `Usage: bun run new-project.ts <name> [--path <dir>] [--lib]
+
+Arguments:
+  name          Project name
+
+Options:
+  -p, --path    Parent directory (default: current dir)
+  --lib         Create as publishable library (uv init --lib)
+  -h, --help    Show this help`;
+
+const TOOL_CONFIG = `
+[dependency-groups]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.8",
+    "pytest>=8",
+    "pytest-cov>=5",
+]
+
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "3.13"
+reportMissingTypeStubs = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+reportUnknownLambdaType = false
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUnnecessaryIsInstance = false
+reportUnusedCallResult = false
+reportImplicitOverride = false
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",   # trailing comma (conflicts with formatter)
+    "ISC001",   # single-line string concat (conflicts with formatter)
+    "D1",       # undocumented-public-* (too noisy early on)
+    "ANN101",   # deprecated: self annotation
+    "ANN102",   # deprecated: cls annotation
+    "S101",     # assert used (pytest needs it)
+    "PLR2004",  # magic-value-comparison (test data)
+    "FBT",      # boolean-trap (too strict for CLIs)
+    "TD",       # flake8-todos (noisy)
+    "FIX",      # fixme (noisy)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "PLR2004", "SLF001", "D", "ARG", "ANN"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers --strict-config"
+`;
+
+const GITIGNORE = `__pycache__/
+*.py[cod]
+*.so
+.venv/
+dist/
+*.egg-info/
+.coverage
+htmlcov/
+.basedpyright/
+.ruff_cache/
+`;
+
+type ProjectOptions = { readonly name: string; readonly path: string; readonly lib: boolean };
+
+type Cli =
+  | { readonly kind: "run"; readonly options: ProjectOptions }
+  | { readonly kind: "help" }
+  | { readonly kind: "usage"; readonly problem: string };
+
+class ScaffoldError extends Error {
+  constructor(
+    readonly kind: "exists" | "uv-unavailable" | "uv-init-failed",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ScaffoldError";
+  }
+}
+
+function parseCli(): Cli {
+  try {
+    const { values, positionals } = parseArgs({
+      args: Bun.argv.slice(2),
+      options: {
+        path: { type: "string", short: "p", default: "." },
+        lib: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+    if (values.help) return { kind: "help" };
+    const [name, ...extra] = positionals;
+    if (name === undefined || extra.length > 0) return { kind: "usage", problem: "expected exactly one project name" };
+    return { kind: "run", options: { name, path: values.path, lib: values.lib } };
+  } catch (error) {
+    if (error instanceof TypeError) return { kind: "usage", problem: error.message };
+    throw error;
+  }
+}
+
+function withoutDependencyGroups(pyproject: string): string {
+  const kept: string[] = [];
+  let skipping = false;
+  for (const line of pyproject.split(/(?<=\n)/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[dependency-groups]")) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && trimmed.startsWith("[")) skipping = false;
+    if (!skipping) kept.push(line);
+  }
+  return `${kept.join("").replace(/\n+$/, "")}\n`;
+}
+
+function initProject(projectDir: string, lib: boolean): void {
+  const init = runTool("uv", ["init", lib ? "--lib" : "--app", projectDir]);
+  switch (init.kind) {
+    case "ok":
+      return;
+    case "unavailable":
+      throw new ScaffoldError(
+        "uv-unavailable",
+        `uv could not be started (${init.reason}); install it: curl -LsSf https://astral.sh/uv/install.sh | sh`,
+      );
+    case "failed":
+      throw new ScaffoldError("uv-init-failed", `uv init failed: ${init.stderr}`);
+    default:
+      return assertNever(init);
+  }
+}
+
+function addDevTools(projectDir: string): void {
+  const added = runTool("uv", ["add", "--dev", "basedpyright", "ruff", "pytest", "pytest-cov"], projectDir);
+  switch (added.kind) {
+    case "ok":
+      return;
+    case "unavailable":
+      console.error(`warn: uv add --dev could not start (${added.reason}); run it once uv is reachable`);
+      return;
+    case "failed":
+      console.error(`warn: uv add --dev failed; pyproject.toml still lists the dev tools:\n${added.stderr}`);
+      return;
+    default:
+      return assertNever(added);
+  }
+}
+
+function scaffold({ name, path, lib }: ProjectOptions): void {
+  const projectDir = join(path, name);
+  if (existsSync(projectDir)) throw new ScaffoldError("exists", `${projectDir} already exists`);
+  initProject(projectDir, lib);
+
+  const pyprojectPath = join(projectDir, "pyproject.toml");
+  writeFileSync(pyprojectPath, withoutDependencyGroups(readFileSync(pyprojectPath, "utf8")) + TOOL_CONFIG);
+  addDevTools(projectDir);
+
+  mkdirSync(join(projectDir, "tests"), { recursive: true });
+  appendFileSync(join(projectDir, "tests", "__init__.py"), "");
+  writeFileSync(join(projectDir, ".gitignore"), GITIGNORE);
+
+  const srcDir = join(projectDir, "src", name.replaceAll("-", "_"));
+  if (lib && existsSync(srcDir)) appendFileSync(join(srcDir, "py.typed"), "");
+
+  console.log(`✓ Created: ${projectDir}`);
+  console.log(`  cd ${name} && uv sync && uv run basedpyright . && uv run ruff check .`);
+}
+
+function main(): number {
+  const cli = parseCli();
+  switch (cli.kind) {
+    case "help":
+      console.log(USAGE);
+      return 0;
+    case "usage":
+      console.error(`Error: ${cli.problem}\n\n${USAGE}`);
+      return 2;
+    case "run":
+      break;
+    default:
+      return assertNever(cli);
+  }
+  try {
+    scaffold(cli.options);
+    return 0;
+  } catch (error) {
+    if (error instanceof ScaffoldError) {
+      console.error(`Error: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
+process.exit(main());

package/packages/omo-codex/plugin/skills/programming/scripts/python/new-script.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+/**
+ * Generate a PEP 723 Python script with all boilerplate pre-filled: uv shebang,
+ * inline metadata (requires-python + dependencies), the mandatory "How to run"
+ * block, `from __future__ import annotations`, and a main() guard.
+ *
+ * ─── How to run ───
+ * 1. Install Bun: curl -fsSL https://bun.sh/install | bash
+ * 2. Run:
+ *      bun run new-script.ts my_tool
+ *      bun run new-script.ts my_tool --output ./scripts/my_tool.py
+ *      bun run new-script.ts my_tool --deps 'httpx2[http2,brotli,zstd]' --deps rich --deps polars
+ *      bun run new-script.ts my_tool --py 3.13
+ * ──────────────────
+ *
+ * Writes to <os tmpdir>/uv-scripts/<name>.py unless --output is given.
+ * Exit codes: 0 written, 2 usage error.
+ */
+
+import { chmodSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseArgs } from "node:util";
+import { assertNever } from "../shared/run-tool.ts";
+
+const USAGE = `Usage: bun run new-script.ts <name> [--output <path>] [--deps <dep>]... [--py <version>]
+
+Arguments:
+  name          Script name (without .py extension)
+
+Options:
+  -o, --output  Output path (default: OS temp directory)
+  -d, --deps    Dependency to include (repeat --deps for each)
+  --py          Minimum Python version (default: 3.13)
+  -h, --help    Show this help`;
+
+type ScriptOptions = {
+  readonly name: string;
+  readonly output: string | undefined;
+  readonly deps: readonly string[];
+  readonly py: string;
+};
+
+type Cli =
+  | { readonly kind: "run"; readonly options: ScriptOptions }
+  | { readonly kind: "help" }
+  | { readonly kind: "usage"; readonly problem: string };
+
+function parseCli(): Cli {
+  try {
+    const { values, positionals } = parseArgs({
+      args: Bun.argv.slice(2),
+      options: {
+        output: { type: "string", short: "o" },
+        deps: { type: "string", short: "d", multiple: true, default: [] },
+        py: { type: "string", default: "3.13" },
+        help: { type: "boolean", short: "h", default: false },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+    if (values.help) return { kind: "help" };
+    const [name, ...extra] = positionals;
+    if (name === undefined || extra.length > 0) return { kind: "usage", problem: "expected exactly one script name" };
+    return { kind: "run", options: { name, output: values.output, deps: values.deps, py: values.py } };
+  } catch (error) {
+    if (error instanceof TypeError) return { kind: "usage", problem: error.message };
+    throw error;
+  }
+}
+
+function renderScript(pythonVersion: string, deps: readonly string[], filename: string): string {
+  const depsBlock =
+    deps.length > 0
+      ? deps.map((dep) => `#     "${dep}",\n`).join("")
+      : '#     # add deps here, e.g.: "httpx2[http2,brotli,zstd]"\n';
+  const argsHint = "";
+  return `#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=${pythonVersion}"
+# dependencies = [
+${depsBlock}# ]
+# ///
+
+# ─── How to run ───
+# 1. Install uv (if not installed):
+#      curl -LsSf https://astral.sh/uv/install.sh | sh
+# 2. Run directly (no venv, no pip install needed):
+#      uv run ${filename} ${argsHint}
+# 3. Or make executable and run:
+#      chmod +x ${filename} && ./${filename}
+# ──────────────────
+
+from __future__ import annotations
+
+
+def main() -> None:
+    """TODO: implement."""
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+
+function writeScript({ name, output, deps, py }: ScriptOptions): void {
+  const filename = name.endsWith(".py") ? name : `${name}.py`;
+  const dest = output ?? join(tmpdir(), "uv-scripts", filename);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, renderScript(py, deps, filename));
+  if (process.platform !== "win32") chmodSync(dest, statSync(dest).mode | 0o111);
+
+  console.log(`✓ Created: ${dest}`);
+  console.log(`  Run: uv run ${dest}`);
+}
+
+function main(): number {
+  const cli = parseCli();
+  switch (cli.kind) {
+    case "help":
+      console.log(USAGE);
+      return 0;
+    case "usage":
+      console.error(`Error: ${cli.problem}\n\n${USAGE}`);
+      return 2;
+    case "run":
+      writeScript(cli.options);
+      return 0;
+    default:
+      return assertNever(cli);
+  }
+}
+
+process.exit(main());