oh-my-opencode 5.1.51 → 5.1.54

package/dist/skills/programming/references/python/one-liners.md

@@ -87,17 +87,17 @@ Replace `<SCRIPT_NAME>` with the actual filename. Add argument descriptions if t
 
 ## Template generator
 
-Use `scripts/new-script.py` to scaffold a new PEP 723 script with all boilerplate pre-filled:
+Use `../../scripts/python/new-script.ts` (Bun) to scaffold a new PEP 723 script with all boilerplate pre-filled:
 
 ```bash
 # Generate to temp directory (default)
-uv run scripts/new-script.py my_tool
+bun run ../../scripts/python/new-script.ts my_tool
 
 # Generate to specific path
-uv run scripts/new-script.py my_tool --output ./scripts/my_tool.py
+bun run ../../scripts/python/new-script.ts my_tool --output ./scripts/my_tool.py
 
-# With extra dependencies
-uv run scripts/new-script.py my_tool --deps "polars" "duckdb" "rich"
+# With extra dependencies (repeat --deps for each)
+bun run ../../scripts/python/new-script.ts my_tool --deps polars --deps duckdb --deps rich
 ```
 
 ## Common dependency sets

package/dist/skills/programming/references/testing/README.md

@@ -0,0 +1,82 @@
+# Testing
+
+Read this before creating or editing any test file (`*.test.*`, `*.spec.*`, `*_test.go`, `test_*.py`, `tests/`, `__tests__/`) and before deciding whether a change needs a test at all. The per-language recipes live beside their language (`../go/testing.md`, `../rust/proptest-insta.md`, the "In tests" sections of the other READMEs); this file is the language-independent contract they all assume. [`junk-classes.md`](junk-classes.md) is the companion table: every class there is a test this file tells you not to write.
+
+## Before writing: the authoring gate
+
+Answer all four; a missing answer means do not add the test yet.
+
+1. **What observable behavior, invariant, or independent contract does it protect?** Name it in the test name.
+2. **What credible regression makes it fail?** If no plausible edit to the production owner turns it red, it is a [change certificate or cannot-fail](junk-classes.md), not a test.
+3. **Why does existing coverage not already catch that failure?** Each contract has one primary owner test at the strongest boundary. Extend a table row or a shared fixture instead of adding a near-duplicate, a copy in another package, or a replay through a wrapper.
+4. **Does it need a production seam no production caller needs** (an export, flag, getter, reset hook, wrapper, injection point)? If yes, test at the real boundary instead; a seam that exists for one test is a [seam keeper](junk-classes.md).
+
+The run proves the change; a test proves that the next change cannot silently undo it. So add a test only where the repository keeps tests for this behavior AND a regression would otherwise pass unnoticed by the run and the existing tests. A bug fix starts from a reproduction that fails on the pre-fix code for the intended reason (an existing owner test that already fails may serve as that proof). Prose has no behavioral seam ([Prompt tests](#prompt-tests-assert-behavior-never-text) below).
+
+A test that fails on the unchanged base is a product bug to fix at its owner; a test your own change turns red is fixed at the code or at the test. Neither is deleted or edited green to unblock a run.
+
+## Shape
+
+### The pyramid, cheapest rung first
+
+| Rung | Count | Purpose | Budget |
+|---|---|---|---|
+| Unit | many | pure-function correctness for every meaningful input class (happy, edge, boundary, error path) | < 10 ms each; whole unit suite < 30 s |
+| Integration | some | the real adapter against the real downstream (DB, queue, HTTP) via `testcontainers`, `httptest`, or the equivalent; never a unit test pretending to be one | < 1 s each; suite < 5 min |
+| E2E scenario | few | one narrative per user-visible outcome, driven through the real surface (HTTP route, CLI invocation, TUI keystroke), asserting the observable outcome, not internal state; include at least one error-path scenario | seconds, on CI |
+
+A user-visible outcome never driven through its real surface is unverified; a green unit suite does not stand in for that run.
+
+### Given / When / Then
+
+Every test is three blocks: the preconditions and fixtures, the single action under test, the observable outcome AND only that outcome. One `When` per test; several `When`s are several tests. Names state behavior and condition (`it("<does X> when <Y>")`, `Test_<Subject>_<Outcome>_when_<Condition>`, `#[test] fn behavior_when_condition`) so a failure reads without the body. Twelve assertions in one test hide eleven failures behind the first: split by `Then`.
+
+### Less mock, the better
+
+1. **Real object** when constructable in under a millisecond (domain types, pure functions, value objects).
+2. **In-memory fake**: a real implementation of the interface backed by a map or slice (stores, caches, queues), with its own test proving it behaves like the real one.
+3. **Testcontainer or sandbox**: real Postgres, Redis, S3-compatible store.
+4. **Wire-level fake**: `httptest.Server`, `respx`, `msw`; fake at the wire, not at the SDK.
+5. **Mock**, only when 1-4 are infeasible (clock, randomness, an external SaaS with no sandbox), at the narrowest seam, never a whole service.
+
+If the test fails when the owner's *implementation* changes but its *behavior* did not, it is over-mocked: delete the mock and assert on observable outputs. A mock that returns whatever the assertion then checks is a [mock echo](junk-classes.md). A boundary list (allowlist, flag filter) is tested with the real list imported from production, not a copy.
+
+### Accurate, efficient, deterministic, isolated
+
+- **Accurate**: the test fails for the bug it names and only that bug. Assert the contract, not a dump; no coupling to format, ordering, whitespace, or unrelated fields. Snapshots pin structure (CLI help, a JSON shape), never behavior or prose.
+- **Efficient**: when a suite crosses its budget, profile and split it; fast tests run on every save, slow ones on push.
+- **Deterministic**: no `sleep`, no wall-clock dependence, no order dependence (`-shuffle=on`, pytest-randomly, a random vitest seed). Inject a clock. For async behavior subscribe to the exact event or state change BEFORE triggering the action, then await it with a bounded timeout that fails with a message; the timeout is a circuit breaker, never the synchronization. A test that passes 9 of 10 runs is broken.
+- **Isolated**: every test starts from a known fixture and tears down (`t.TempDir()`, `t.Setenv()`, transactional rollback). Two tests that pass alone and fail together are a fixture leak; fix the leak, never the order, and never `.only` / `.skip` / a separate process to hide it. Suite-global resources (sandbox roots, listen ports, container names) are namespaced per run (`mktemp`, port `0`, unique names) so two checkouts running the suite concurrently cannot interfere; the signature of that leak is "a different test fails each run".
+
+### Prompt tests: assert behavior, never text
+
+A prompt, skill, rule, or markdown file is prose; its wording changes every sprint. `toContain("<sentence>")`, `not.toContain("old wording")`, a snapshot of prose, a word count, a phrase-occurrence count: each stays green while the behavior it claims to guard breaks, then blocks every legitimate rewording. Assert only what a machine consumes: a builder's routing decision (`expect(getPromptSource(model)).toBe("gpt-5-6")`), a structural token the runtime dispatches on (a tool name, a tag, a parsed frontmatter field), the conditional the code enforces (skill loaded -> tool present; `verbose=false` -> directive absent), equality between two shipped copies of one artifact, or the minimal routing-bearing fragment of a parsed `description` that a router dispatches on (such a pin lets a later rewrite change every sentence around it while proving the routing contract survived). If nothing consumes the text, write no test. Nearby prose pins are existing violations, not a convention.
+
+When delegating test-writing, hand the child the behavior the test must distinguish ("fails if override precedence breaks"), never a ready-made assertion string, prompt fragment, or marker to copy: a prescribed mechanism that is wrong gets implemented faithfully and ships behind a green suite.
+
+## After writing: test your test
+
+A test earns its place by failing. Before the PR, for each new or reshaped test:
+
+1. **Break the owner** (flip the condition, drop the branch, return a constant, skip the write) and run the test. Confirm the mutated bytes are actually in the file before reading the result; a no-op edit "passes" identically to the original.
+2. **Red for the intended reason?** Read the failure message: a loose pattern can match the base's generic error by coincidence (a false red), and a fake that simulates the failure by a different mechanism than the guard reads fails with the fix present.
+3. **Still green?** Then one of: the test is vacuous (fix the assertion); the mutant is equivalent (a `try/catch`, fallback, or normalization maps it back to the same outcome: retarget the mutation at the observable claim); a second rule already produces the same outcome (make the input exercise only the rule under test and assert the recorded reason); or the mutated code is dead (delete the code, not the test's teeth).
+4. **Restore byte for byte.** Never commit a mutation.
+
+Assertion shapes that survive this step:
+
+| Vacuous shape | Why it passes with the bug present | Discriminating shape |
+|---|---|---|
+| expected value derived from the output under test | compares a projection of the output to itself | derive the expected value from the test's input |
+| override fixture equal to its fallback | precedence is never exercised | every value the code must select or override differs from the fallback |
+| `>= n` / `> 0` over independently produced items | removing one item still satisfies the bound | pin the exact set |
+| a count after deduplication where duplicates are byte-identical to a mandatory item | dropping all duplicates gives the same count | distinct payloads, assert retention and placement |
+| the argv, flags, URL, or request handed to a child | an input transcript, not the child's outcome | drive the real component and assert the state it resolved, with a control case |
+| a counter or filter keyed on a value the code path never produces | both sides count zero | count the operation itself |
+| a copy of the production component, props, or allowlist | the copy passes while the shipped one is broken | mount or import the real one |
+| a timing assertion for an off-thread or performance claim | passes on the base at fixture size | prove performance on the field harness; keep the unit test to behavior |
+| a gated or fallback path tested without forcing it | the base's own error path produces the same side effect | force the path (flag, crash limit) and assert the reason the new path records |
+
+## Delegation and review
+
+The gate reviewer applies [`junk-classes.md`](junk-classes.md) to every test in the diff and blocks a prose pin as HIGH; a test that would be deleted there is a test not to write. Deleting such a test is a fix, not a coverage loss, and needs the proof rule in that file.

package/dist/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/dist/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/dist/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/dist/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());