skilldrop-cli 0.16.28 → 0.16.30

package/packs/dev-team/skills/codebase-tour/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: codebase-tour
+description: Get a newcomer (a new engineer, or the agent itself) oriented in an unfamiliar repository before they make one specific change, with a short tour scoped to that change. It gives the install, run and test commands taken from CI, package scripts and the Makefile; the path the change touches, traced through the code with file:line citations; where the change goes; the conventions the code actually follows; the traps (generated files, a second copy of the logic, untested code, env vars, flags); and a first step that can be checked. Use when someone says "I'm new to this repo", "get me oriented", "where would I make this change", "walk me through the code for X", "onboard me before I start this ticket", or "how do I run and test this".
+---
+
+# codebase-tour
+
+Orients someone in a repository they have never seen, for **one change they are about to make**. The tour is not a map of the system. It follows the path the change will touch, and it ends at the file and function where the work starts.
+
+Two failures make a plain orientation worse than none. The first is a **confident wrong command**: `make dev` copied from a README into a repo whose Makefile has no `dev` target. The second is the **trap nobody mentions**: the generated file someone hand-edits, the second copy of the logic that stays unchanged, the test suite that skips the area. This skill is built around two rules. **Every claim cites the file and line it was read from. The README gives leads to check; the code gives the facts.**
+
+Boundaries: a full as-is architecture write-up is `reverse-architecture`. A diagram is `interactive-diagram` or `architecture-diagrams`. A standing agent-policy file for the repo is `agents-md-generator`. Writing the change itself is `feature-implement-loop`, which takes this tour's "where the change goes" and first step as its input. Reviewing the finished diff is `pre-merge-review`.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open the reply with the 3–5 things this person most needs to know for this change. A directory listing is never first.
+- **Use only what you read.** Every statement carries `path:line` (or a path, for a whole file) from this repository. Anything not checked is tagged `[inferred]` with the reason. A fact the repo doesn't give goes under "Open questions". It is not filled in from what the framework usually does.
+- **Deliver from what you have.** Read the repo, state any assumption in one line, and produce the tour. Ask nothing when the repo and the change are both in hand.
+- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end.
+- **For this skill:** where the README and the code disagree, say so in one line with both citations, and follow the code.
+
+1. **Pin the change in code terms.** Restate it in one sentence using the words the code will use. ✅ *"Reject `POST /orders/{order_id}/refunds` when the event ended more than 14 days ago."* ❌ *"Tighten up refunds."* If no change is named, tour the main path from the primary entry point, tag that scope `[assumption]`, and replace "Where the change goes" with one line asking for the change.
+
+2. **Inventory what the repo says about itself.** Run the fact lister. It is read-only: it prints commands, test files, generated-file markers, env reads and README claims that don't resolve, each with `path:line`.
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/repo_facts.py" <repo-root>
+   # Other IDEs (from the skill folder)
+   python3 scripts/repo_facts.py <repo-root>
+   ```
+
+   If no script can run, read these by hand in order: CI workflows (`.github/workflows/`, `.gitlab-ci.yml`), then package scripts, `Makefile`, `justfile`, `tox.ini`, `noxfile.py` and `pyproject.toml`, then `README` and `CONTRIBUTING`. CI ranks first because its commands are the ones that have to pass.
+
+3. **Take commands only from those files, and say which ones ran.** Quote each command with its source. ✅ `make test` (`.github/workflows/ci.yml:21`, which runs `pytest -q -m "not e2e"` per `Makefile:8`). ❌ `make dev` (named in the README; the Makefile has no `dev` target). Prefer CI's form of a command over the script's bare form, and list anything CI needs that a laptop lacks (a database service, an env var set in the workflow). Give each command one status:
+   - `ran: passed` or `ran: failed` with the first error line. Run only commands that stay inside the repo: tests, lint, typecheck or build, and only when the toolchain and dependencies are already installed.
+   - `read, not run` for everything else. That covers dependency installs, anything that needs a database, a network service or credentials, deploys, migrations, publishing, and generators that rewrite tracked files. Run these only when the user asks.
+
+   A command to run one test file or one test is **derived**. It goes through the repo's own script or runner, plus that runner's filter argument, and it is labelled `derived from <source>`. ✅ `pytest -q -m "not e2e" tests/rules/test_refunds.py` (derived from `Makefile:8`). ❌ `python -m unittest` in a repo that runs pytest. A runner the repo never calls is invented. Leave it out.
+
+4. **Trace the path the change touches.** Search for the change's nouns: the route string, the CLI flag, the field or column name, the error code. Work outward to the entry point (`main`, the server bootstrap, the console script, the job scheduler). Then write the path forward as numbered hops. Each hop is `path:line` `function`, plus one line on what it does there. Stop at the far edge of the change, usually the database call or the outbound request. Keep it to 10 hops or fewer. A hop you couldn't trace is `[inferred]`, with what you'd need to confirm it.
+
+5. **Say where the change goes, and why there.** Name the files and functions. Justify each one with the pattern its nearest sibling already follows. ✅ *"Every other refund rule lives in `check_refundable` (`tallyhall/rules/refunds.py:9`), which the route calls at `tallyhall/api/refunds.py:22`. The window check goes in `check_refundable` too."* List **everything that has to change together**: a spec and the types generated from it, a registry the new code must be added to, a second copy of the logic.
+
+6. **Read the conventions from the code nearest the change, not from the README.** Cover naming, how errors are raised and returned, test layout and naming, how config and env vars are read, and logging, but only the ones this change will hit. Each gets a citation from code. ✅ *"Errors: raise `RefundRejected(code, message)`; the route turns it into a 422 (`tallyhall/rules/refunds.py:4`, `tallyhall/api/refunds.py:25`)."* Where a file on the path breaks its own convention, say so. That file is the one a newcomer copies by mistake. Every README or `CONTRIBUTING` claim the code contradicts (a command, a path, where config lives, how a plugin is registered) goes under "Where the README is wrong", with both citations.
+
+7. **Hunt the traps.** Check each one and report what you found. Write "none found" when a check comes up empty, so the person knows it was done.
+   - **Generated files**: the marker line, the source they come from, the command that regenerates them, and whether CI checks for drift.
+   - **Duplicated logic**: search for the change's identifiers, SQL, literals and constants outside the main path. A second copy is either updated in the same change or left alone on purpose, and the tour says which is the open question.
+   - **Untested code on the path**: name each function on the path that no test calls.
+   - **Tests the default command skips**: markers (`-m "not slow"`), build tags, include globs.
+   - **Env vars and feature flags the path reads**: the name, the default, and the line that reads it.
+   - **Vendored code** on the path, and where it comes from upstream.
+
+8. **Find the tests for the area, and how to run just those.** Name the test files that exercise the path, the command for the whole suite, and the derived command for only these files. When the area has no tests, say so plainly: ✅ *"Nothing tests `tallyhall/admin/bulk_refund.py`. The first step adds one."*
+
+9. **Name the first step: small, local, and verifiable.** It says what to do in which file, the command to run, and the result that shows it worked. A failing test next to an existing one is the usual best first step. ✅ *"Add `test_rejects_refund_after_window` to `tests/rules/test_refunds.py`, with an order whose event ended 15 days ago; run `pytest -q -m "not e2e" tests/rules/test_refunds.py`; it fails until `check_refundable` checks the window."*
+
+10. **List open questions for a maintainer.** Five at most. Each one can be answered in a sentence and points at the evidence that raised it. ✅ *"Should the support bulk-refund tool (`tallyhall/admin/bulk_refund.py:27`) apply the 14-day window too, or is it the override?"*
+
+11. **Write it with [`templates/codebase-tour.md`](templates/codebase-tour.md), under the caps.** The whole tour is ≤ ~120 lines and each section is ≤ ~15 lines, about one screen. The scope line names what was **deliberately skipped**: the areas not on the path, the services not read. That way the person knows it is a scoped tour and not a survey. If a section would overflow, cut the hops and conventions furthest from the change first.
+
+12. **Reply.** Lead with the 3–5 bullets, then the tour. Put the tour in the reply. Write it to a file only when the user names a path, and change nothing else in the repository.
+
+**Non-interactive runs** (subagent, CI, headless): an unnamed change becomes a main-path tour tagged `[assumption]` (step 1). Unclear scope boundaries become `[assumption]` lines at the top. A repository that cannot be read emits `BLOCKED: need read access to the repository — every claim in the tour cites a file in it`, followed by one plain sentence saying the tour follows once the files can be read. A tour is never written from a description of a repo.
+
+## Useful references in this skill
+
+- [`templates/codebase-tour.md`](templates/codebase-tour.md): the tour skeleton, with section order and line budgets
+- [`scripts/repo_facts.py`](scripts/repo_facts.py): read-only, stdlib-only fact lister (commands with provenance, README commands and paths that don't resolve, tests, generated markers, env reads)
+- [`examples/refund-window.md`](examples/refund-window.md): worked input → output for a Python service, including a README that disagrees with the code and a second copy of a rule
+
+## Quality bar
+
+- **Every claim has a citation or an `[inferred]` tag.** Run a spot check: pick any three statements in the tour, and each must lead to a file and line that says it.
+- **Zero invented commands.** Every command traces to CI, a package script, a Makefile, a tox or nox session or pyproject, or it is a labelled derived filter of a runner the repo already calls.
+- **Ran and read are never blurred.** Every command carries `ran: passed`, `ran: failed`, or `read, not run`.
+- **README-versus-code conflicts are named**, each with both citations and the code taken as the fact.
+- **Scoped, not surveyed.** The path stops at the change's far edge, the tour fits the caps, and the scope line says what was skipped.
+- **The trap checks all report**, including "none found". A second copy of the logic, when one exists, is named with its location.
+- **The tests for the area are named, with a command for just those**, or the tour says plainly that there are none.
+- **It ends at a place to work.** Files and functions, then a first step with a command and an expected result, then at most five open questions.
+- **The reply leads with the 3–5 things that matter**, not a tree.
+
+## When to use this skill
+
+- ✅ "I'm new to this repo and need to add X. Get me oriented."
+- ✅ A ticket is picked up in an unfamiliar codebase and the first hour is going on finding where things live
+- ✅ An agent is about to implement a change in a repo it has not read, and needs the commands and traps before writing code
+- ✅ "How do I run and test this, and where would this change go?"
+- ✅ Handing a scoped piece of work to a contractor or a new teammate with a page that is true
+
+## When NOT to use this skill
+
+- ❌ A full as-is architecture write-up or diagram of the whole system: `reverse-architecture`
+- ❌ Drawing a diagram of a flow or a system: `interactive-diagram` or `architecture-diagrams`
+- ❌ Writing a standing `AGENTS.md` or agent-policy file for the repo: `agents-md-generator`
+- ❌ Writing the code for the change: `feature-implement-loop`
+- ❌ Reviewing a diff that already exists: `pre-merge-review`
+
+## Anti-patterns to avoid
+
+- ❌ **Copying the README's commands.** A README goes stale first. Check every command it names against the scripts and CI, and report the ones that don't exist.
+- ❌ **Ecosystem-default commands.** `pytest` for a repo that runs `nox -s tests`, `make test` in a repo with no Makefile. The repo says what it runs.
+- ❌ **"Run the tests" without saying whether you did.** A reader can't tell a command that passed from one copied out of a file.
+- ❌ **The architecture survey.** Twelve services described, and the one function the change touches never named. Follow the path; skip the rest and say so.
+- ❌ **A directory tree as the opening.** The person can run `ls`. Open with what changes their next hour.
+- ❌ **Conventions from the style guide.** `CONTRIBUTING.md` says "use custom error classes"; the handler on the path returns `{ error: string }`. Report what the code does, and flag the gap.
+- ❌ **Missing the second copy.** The change lands in the API route, and the admin tool with its own copy of the same rule keeps the old behaviour. Search for the identifiers before naming where the change goes.
+- ❌ **Editing a generated file in the first step.** Name the source and the regenerate command instead.
+- ❌ **Running something with side effects to "check it works".** Deploys, migrations, installs that hit the network, and generators that rewrite tracked files stay `read, not run` unless the user asks.
+- ❌ **A first step that can't be checked.** "Get familiar with the handler" is not a step. Name a file, a command and an expected result.
+- ❌ **Showing the machinery.** No skill names, script names or caps in the reply or the tour.

package/packs/dev-team/skills/codebase-tour/evals/eval_queries.json

@@ -0,0 +1,13 @@
+[
+  { "query": "I'm new to this repo and need to add rate limiting to the login endpoint. Get me oriented.", "should_trigger": true },
+  { "query": "Before I start this ticket, walk me through the code that handles invoice exports", "should_trigger": true },
+  { "query": "Where would I make this change? I've never seen this codebase", "should_trigger": true },
+  { "query": "How do I run and test this project, and where does the payment retry logic live?", "should_trigger": true },
+  { "query": "Onboard me to this repo so I can fix the timezone bug in the scheduler", "should_trigger": true },
+
+  { "query": "Reverse-engineer the architecture of this whole system and draw the as-is diagram", "should_trigger": false },
+  { "query": "Write an AGENTS.md for this repo so agents stop running the wrong commands", "should_trigger": false },
+  { "query": "Implement the carrier filter on GET /shipments with tests, here are the acceptance criteria", "should_trigger": false },
+  { "query": "Review my diff before I merge it", "should_trigger": false },
+  { "query": "Make an interactive diagram of how a request flows through our services", "should_trigger": false }
+]

package/packs/dev-team/skills/codebase-tour/evals/evals.json

@@ -0,0 +1,77 @@
+{
+  "skill_name": "codebase-tour",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm new to this repo (it's the current directory) and my first ticket is to add a `carrier` filter to GET /shipments, so dispatchers can see one carrier's shipments at a time. Get me oriented before I start: how to run it, where the change goes, and anything that will bite me.",
+      "assertions": [
+        "Opens with a short list of the few things that matter most for this change, before any section, and does not open with a directory listing",
+        "Every command given is cited to package.json or .github/workflows/ci.yml and marked as either run or only read; `npm run dev` is not given as a way to run the server",
+        "Says where the README and the code disagree: there is no `dev` script (package.json has `start:watch`), there is no `src/routes/` (routes are registered in src/http/routes.ts), and config comes from env vars in src/config.ts, not config/default.json",
+        "Says the change goes in `parseListQuery` (src/http/handlers/shipments.ts) and `buildShipmentFilter` (src/domain/shipments/filter.ts), and that openapi.yaml needs the new query parameter",
+        "Names src/generated/api-types.ts as generated from openapi.yaml by `npm run gen:types`, says not to edit it by hand, and notes that CI fails if it drifts (.github/workflows/ci.yml)",
+        "Names src/jobs/export-shipments.ts as a second copy of the shipment filtering that the change does not reach on its own, notes it has no tests, and raises whether it needs the carrier filter too",
+        "Names tests/http/shipments.test.ts and tests/domain/filter.test.ts as the tests for the area, with a way to run just those through the repo's vitest script, and notes DATABASE_URL is required to start the server (src/config.ts)",
+        "Does not invent commands, files, scripts or tools that are not in the repo"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Never touched this codebase before. I need to add support for Northwind Credit Union's CSV export (header: Transaction Date, Merchant, Amount; dates like 2026-03-02). Where do I start, and how do I run the tests? The repo is the folder you're in.",
+      "assertions": [
+        "Says the README is wrong that a new parser module is picked up automatically: the PARSERS registry in src/ledgerline/parsers/__init__.py has to list it",
+        "Names HEADER_SIGNATURES in src/ledgerline/detect.py as a second place the new bank must be added, or detection fails for the new header",
+        "Gives the test command from noxfile.py or CI (`nox -s tests`, `nox -s lint tests`), says `python setup.py test` from the README cannot work because there is no setup.py, and notes the tests session skips tests marked `slow`",
+        "Gives a way to run a single test file through the runner the repo already uses (nox posargs or pytest), labelled as derived from the repo's config rather than presented as a defined command",
+        "Points to AcmeParser as the parser to copy and flags that HarborParser has no tests and does not use parse_amount or raise ParseError like the others",
+        "Identifies src/ledgerline/_version.py as generated by setuptools-scm and not to be edited",
+        "Each convention it states (ParseError naming the column, money.parse_amount for amounts, CSV samples in tests/fixtures/) is cited to a file in the repo",
+        "Does not invent commands, files, scripts or tools that are not in the repo"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I've got a ticket to switch webhook delivery retries in this repo to exponential backoff. I don't really know Go and I've never seen this code. Write me an orientation to docs/backoff-tour.md and don't change anything else.",
+      "assertions": [
+        "Writes docs/backoff-tour.md and modifies no other file in the repo",
+        "Says the README is wrong about config.yaml: there is no such file, and retry settings are the env vars TIDEPOOL_MAX_ATTEMPTS and TIDEPOOL_RETRY_DELAY read in internal/config/config.go",
+        "Says the README is wrong that `make test` includes the database tests: they sit behind the `integration` build tag and run with `make test-integration`, which needs Postgres and TIDEPOOL_DATABASE_URL",
+        "Names `Deliver` in internal/dispatch/dispatcher.go as where the change goes, and the injectable `sleep` field used by internal/dispatch/dispatcher_test.go as the way to test the delays",
+        "Names internal/replay/replay.go as a second retry loop with its own fixed delay that the change must also update or deliberately leave, and notes it has no tests",
+        "Names internal/store/query.sql.go as generated by sqlc from query.sql, regenerated with `make generate`, and not to be edited by hand",
+        "Every command is cited to the Makefile or .github/workflows/ci.yml and marked as run or only read; it does not claim to have run the integration tests",
+        "Does not invent commands, files, scripts or tools that are not in the repo"
+      ]
+    },
+    {
+      "id": 4,
+      "held_out": "2026-10-20",
+      "prompt": "Hi! I joined the checkout team on Monday and I've been handed ticket SHIP-214: \"Raise the EU free-shipping threshold from EUR 50 to EUR 60. UK and US stay as they are.\" I'm new to this repo and haven't used FastAPI much. Before I start, can you get me oriented: how do I install, run and test this thing, and where exactly would I make the change?",
+      "assertions": [
+        "Gives install/run/test commands taken from the Makefile and .github/workflows/ci.yml (`make install` / `pip install -e \".[dev]\"`, `make run` / `uvicorn shipcalc.main:app`, `make test` / pytest) and explicitly says the README's `pip install -r requirements.txt`, `flask run` and `python -m unittest discover` are stale (there is no requirements.txt and the app is FastAPI, not Flask).",
+        "Says the EU threshold's source of truth is data/rates.csv (line 2, `free_threshold` column), that src/shipcalc/generated/rates_table.py is generated (DO NOT EDIT header on line 1) and must not be hand-edited, and that the change is: edit the CSV, then run `make gen`; it notes that CI's `make check-generated` step fails if the generated file is out of sync with the CSV.",
+        "Finds the second, hard-coded copy of the threshold in src/shipcalc/api/preview.py line 5 (`FREE_SHIPPING_MIN`, used by the /preview/banner route) and says it must also change to 60, or the cart banner and the actual quote will disagree.",
+        "Traces the quote path with file:line citations: the /quote handler in src/shipcalc/api/routes.py (shipping_cost call at line 24) -> shipping_cost in src/shipcalc/shipping.py (line 13) -> the threshold comparison against RATES[region][\"free_threshold\"] at shipping.py line 15.",
+        "Flags the feature flag SHIPCALC_FF_FREE_SHIPPING read in src/shipcalc/shipping.py line 10 (free shipping applies only when it is exactly \"on\", and it is not in .env.example or the Makefile run target), so a local manual check of the new threshold will show no change unless the flag is set; also notes SHIPCALC_API_KEY is required at startup (src/shipcalc/config.py line 12).",
+        "Points out that shipping.py and preview.py have no tests while discounts and tax do (tests/unit/test_discounts.py, tests/unit/test_tax.py), and recommends adding boundary tests (e.g. 59.99 vs 60.00 for EU, plus UK/US unchanged) that follow the existing style: pytest functions, Decimal money values, and the flag set via monkeypatch or the environment.",
+        "Ends with one concrete first step whose result can be checked (e.g. run `make test` and see it pass before changing anything, or edit the CSV, run `make gen` and confirm `git diff` touches only the EU line of rates_table.py), and keeps the tour focused on this ticket instead of walking through tax and discounts in detail.",
+        "Invents no commands, files, functions or settings that are not in the repo (e.g. no requirements.txt, no `python -m shipcalc` or `flask run` as a working command, no existing test_shipping.py, no config value for the threshold outside rates.csv/preview.py)."
+      ]
+    },
+    {
+      "id": 5,
+      "held_out": "2026-10-20",
+      "prompt": "First week here, and my ticket is CAB-112: \"Let guests book stays of up to 21 nights (currently capped at 14).\" I'm new to this codebase. Can you walk me through the code for the booking flow, tell me where the change goes, and how I run and test it? I really don't want to break anything on my first PR.",
+      "assertions": [
+        "Gives commands from the root package.json and .github/workflows/ci.yml: `npm install`, `npm test` (which runs `node --test` in each workspace), `npm run gen` / `npm run gen:check`, and `npm run dev:api` (which reads ../../.env, so .env must be copied from .env.example first). It says the README's `yarn install`, `cd api && yarn start`, `yarn test` and the `api/config.js` reference are stale: the repo uses npm workspaces under packages/ and there is no api/ directory or config.js.",
+        "Identifies packages/api/src/generated/schema.js as generated (DO NOT EDIT on line 1, written by scripts/gen-schema.mjs) and says to change the nights `maximum` in packages/api/openapi.json (line 24) and run `npm run gen`, noting that CI's `npm run gen:check` fails if schema.js is hand-edited or stale.",
+        "Lists every copy of the 14-night limit that must move to 21: packages/api/openapi.json line 24 (via the regenerated schema.js), packages/api/src/services/bookings.js line 6 (`MAX_NIGHTS`), and packages/web/src/bookingForm.js line 2 (`MAX_NIGHTS`, the client-side check). It warns that changing only one of them gives a confusing 400 or 422, or a form that blocks valid stays. The README line also needs updating.",
+        "Traces the POST /bookings request path with file:line citations: packages/api/src/server.js mounts the router -> packages/api/src/routes/bookings.js line 7 runs `validate('BookingRequest')` -> packages/api/src/middleware/validate.js line 15 enforces `maximum` from the generated schema (400) -> createBooking / maxNightsFor in packages/api/src/services/bookings.js enforces MAX_NIGHTS (422).",
+        "Flags the `long-stays` feature flag (FEATURE_FLAGS env var parsed in packages/api/src/flags.js; checked at services/bookings.js line 10, giving members LONG_STAY_MAX_NIGHTS = 28). It notes the schema maximum is checked first, so members can never actually reach 28. It asks the ticket owner how the 21-night limit should interact with that flag instead of deciding alone.",
+        "Notes that services/bookings.js and web/src/bookingForm.js have no tests while pricing and format do (packages/api/test/pricing.test.js, packages/web/test/format.test.js). It warns that a new test importing services/bookings.js will throw unless DATABASE_URL is set, because packages/api/src/db.js lines 2-4 check it at import time, and suggests setting it (plus FEATURE_FLAGS if needed) before a dynamic import, using node:test and node:assert/strict as the existing tests do.",
+        "Ends with one concrete first step that can be checked (e.g. run `npm install && npm test` and see 5 passing tests, or change openapi.json, run `npm run gen` and confirm `npm run gen:check` passes and the diff shows only the nights maximum), scoped to this ticket.",
+        "Invents no commands, files, functions or settings that are not in the repo (e.g. no yarn scripts, no api/config.js, no `npm run lint` or `npm run build`, no existing bookings test, no .env file claimed to exist)."
+      ]
+    }
+  ]
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: example-only
+        ports: ["5432:5432"]
+    env:
+      DATABASE_URL: postgres://postgres:example-only@localhost:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run gen:types && git diff --exit-code src/generated
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test -- --coverage

package/packs/dev-team/skills/codebase-tour/evals/files/1/README.md

@@ -0,0 +1,23 @@
+# shipwright-api
+
+The shipments API for the Harbourline dispatch console.
+
+## Getting started
+
+```
+npm install
+npm run dev
+```
+
+The server listens on port 3000.
+
+## Layout
+
+- `src/routes/` holds one file per resource.
+- Configuration lives in `config/default.json`.
+
+## Tests
+
+```
+npm test
+```

package/packs/dev-team/skills/codebase-tour/evals/files/1/openapi.yaml

@@ -0,0 +1,21 @@
+openapi: 3.0.3
+info:
+  title: shipwright-api
+  version: 2.4.0
+paths:
+  /shipments:
+    get:
+      summary: List shipments
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [pending, in_transit, delivered]
+        - name: limit
+          in: query
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: A page of shipments

package/packs/dev-team/skills/codebase-tour/evals/files/1/package-lock.json

@@ -0,0 +1,7 @@
+{
+  "name": "shipwright-api",
+  "version": "2.4.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "shipwright-api",
+  "version": "2.4.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/server.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "start:watch": "tsx watch src/server.ts",
+    "lint": "eslint src tests",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "gen:types": "openapi-typescript openapi.yaml -o src/generated/api-types.ts"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "pg": "^8.11.3"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "eslint": "^8.57.0",
+    "openapi-typescript": "^6.7.4",
+    "supertest": "^6.3.4",
+    "tsx": "^4.7.1",
+    "typescript": "^5.4.2",
+    "vitest": "^1.4.0"
+  }
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/config.ts

@@ -0,0 +1,20 @@
+export interface Config {
+  port: number;
+  databaseUrl: string;
+  maxPageSize: number;
+  legacySort: boolean;
+}
+
+export function loadConfig(): Config {
+  const databaseUrl = process.env.DATABASE_URL;
+  if (!databaseUrl) {
+    throw new Error("DATABASE_URL is required");
+  }
+  return {
+    port: Number(process.env.PORT ?? 3000),
+    databaseUrl,
+    maxPageSize: Number(process.env.MAX_PAGE_SIZE ?? 100),
+    // Old consoles sort by created_at ascending; remove once v1 console is retired.
+    legacySort: process.env.SHIPMENTS_LEGACY_SORT === "1",
+  };
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/domain/shipments/filter.ts

@@ -0,0 +1,24 @@
+import type { Config } from "../../config.js";
+import type { ListShipmentsQuery } from "../../generated/api-types.js";
+
+export interface ShipmentFilter {
+  where: string[];
+  params: unknown[];
+  orderBy: string;
+  limit: number;
+}
+
+export function buildShipmentFilter(query: ListShipmentsQuery, config: Config): ShipmentFilter {
+  const where: string[] = [];
+  const params: unknown[] = [];
+  if (query.status) {
+    params.push(query.status);
+    where.push(`status = $${params.length}`);
+  }
+  return {
+    where,
+    params,
+    orderBy: config.legacySort ? "created_at ASC" : "created_at DESC",
+    limit: query.limit ?? 50,
+  };
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/domain/shipments/repository.ts

@@ -0,0 +1,15 @@
+import pg from "pg";
+import type { Config } from "../../config.js";
+import type { ShipmentFilter } from "./filter.js";
+
+export async function queryShipments(config: Config, filter: ShipmentFilter) {
+  const client = new pg.Client({ connectionString: config.databaseUrl });
+  await client.connect();
+  try {
+    const where = filter.where.length ? "WHERE " + filter.where.join(" AND ") : "";
+    const sql = `SELECT id, status, carrier, created_at FROM shipments ${where} ORDER BY ${filter.orderBy} LIMIT ${filter.limit}`;
+    return (await client.query(sql, filter.params)).rows;
+  } finally {
+    await client.end();
+  }
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/errors.ts

@@ -0,0 +1,9 @@
+export class HttpError extends Error {
+  constructor(public status: number, public code: string, message: string) {
+    super(message);
+  }
+}
+
+export function badRequest(code: string, message: string): HttpError {
+  return new HttpError(400, code, message);
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/generated/api-types.ts

@@ -0,0 +1,9 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface ListShipmentsQuery {
+  status?: "pending" | "in_transit" | "delivered";
+  limit?: number;
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/http/handlers/shipments.ts

@@ -0,0 +1,38 @@
+import type { Request, Response, NextFunction } from "express";
+import type { Config } from "../../config.js";
+import type { ListShipmentsQuery } from "../../generated/api-types.js";
+import { badRequest } from "../../errors.js";
+import { buildShipmentFilter } from "../../domain/shipments/filter.js";
+import { queryShipments } from "../../domain/shipments/repository.js";
+
+const STATUSES = ["pending", "in_transit", "delivered"];
+
+export function parseListQuery(raw: Record<string, unknown>, config: Config): ListShipmentsQuery {
+  const query: ListShipmentsQuery = {};
+  if (raw.status !== undefined) {
+    if (typeof raw.status !== "string" || !STATUSES.includes(raw.status)) {
+      throw badRequest("invalid_status", "status must be one of " + STATUSES.join(", "));
+    }
+    query.status = raw.status as ListShipmentsQuery["status"];
+  }
+  if (raw.limit !== undefined) {
+    const limit = Number(raw.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > config.maxPageSize) {
+      throw badRequest("invalid_limit", "limit must be 1.." + config.maxPageSize);
+    }
+    query.limit = limit;
+  }
+  return query;
+}
+
+export function listShipments(config: Config) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      const query = parseListQuery(req.query, config);
+      const filter = buildShipmentFilter(query, config);
+      res.json({ items: await queryShipments(config, filter) });
+    } catch (err) {
+      next(err);
+    }
+  };
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/http/routes.ts

@@ -0,0 +1,7 @@
+import type { Express } from "express";
+import type { Config } from "../config.js";
+import { listShipments } from "./handlers/shipments.js";
+
+export function registerRoutes(app: Express, config: Config): void {
+  app.get("/shipments", listShipments(config));
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/jobs/export-shipments.ts

@@ -0,0 +1,22 @@
+// Nightly CSV export for the finance team. Runs from the scheduler, not the API.
+import pg from "pg";
+import { loadConfig } from "../config.js";
+
+export async function exportShipments(status?: string): Promise<string> {
+  const config = loadConfig();
+  const client = new pg.Client({ connectionString: config.databaseUrl });
+  await client.connect();
+  try {
+    // Same filtering as the list endpoint, kept here so the job has no HTTP dependency.
+    const params: unknown[] = [];
+    let where = "";
+    if (status) {
+      params.push(status);
+      where = "WHERE status = $1";
+    }
+    const rows = (await client.query(`SELECT id, status, carrier FROM shipments ${where} ORDER BY created_at DESC`, params)).rows;
+    return rows.map((r) => [r.id, r.status, r.carrier].join(",")).join("\n");
+  } finally {
+    await client.end();
+  }
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/src/server.ts

@@ -0,0 +1,18 @@
+import express from "express";
+import { loadConfig } from "./config.js";
+import { registerRoutes } from "./http/routes.js";
+import { HttpError } from "./errors.js";
+
+const config = loadConfig();
+const app = express();
+registerRoutes(app, config);
+
+app.use((err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+  if (err instanceof HttpError) {
+    res.status(err.status).json({ error: err.code, message: err.message });
+    return;
+  }
+  res.status(500).json({ error: "internal" });
+});
+
+app.listen(config.port);

package/packs/dev-team/skills/codebase-tour/evals/files/1/tests/domain/filter.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "vitest";
+import { buildShipmentFilter } from "../../src/domain/shipments/filter.js";
+
+const config = { port: 0, databaseUrl: "postgres://unused", maxPageSize: 100, legacySort: false };
+
+describe("buildShipmentFilter", () => {
+  it("adds a status clause with a positional parameter", () => {
+    const f = buildShipmentFilter({ status: "pending" }, config);
+    expect(f.where).toEqual(["status = $1"]);
+    expect(f.params).toEqual(["pending"]);
+  });
+
+  it("sorts ascending when legacySort is on", () => {
+    expect(buildShipmentFilter({}, { ...config, legacySort: true }).orderBy).toBe("created_at ASC");
+  });
+});

package/packs/dev-team/skills/codebase-tour/evals/files/1/tests/http/shipments.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from "vitest";
+import { parseListQuery } from "../../src/http/handlers/shipments.js";
+
+const config = { port: 0, databaseUrl: "postgres://unused", maxPageSize: 100, legacySort: false };
+
+describe("parseListQuery", () => {
+  it("accepts a known status", () => {
+    expect(parseListQuery({ status: "delivered" }, config)).toEqual({ status: "delivered" });
+  });
+
+  it("rejects an unknown status with invalid_status", () => {
+    expect(() => parseListQuery({ status: "lost" }, config)).toThrowError(/status must be one of/);
+  });
+
+  it("rejects a limit above maxPageSize", () => {
+    expect(() => parseListQuery({ limit: "500" }, config)).toThrowError(/limit must be/);
+  });
+});

package/packs/dev-team/skills/codebase-tour/evals/files/1/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "strict": true
+  },
+  "include": ["src"]
+}

package/packs/dev-team/skills/codebase-tour/evals/files/1/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { include: ["tests/**/*.test.ts"] },
+});

package/packs/dev-team/skills/codebase-tour/evals/files/2/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: |
+            3.10
+            3.12
+      - run: pip install nox
+      - run: nox -s lint tests

package/packs/dev-team/skills/codebase-tour/evals/files/2/README.md

@@ -0,0 +1,16 @@
+# ledgerline
+
+Turns bank-statement CSV exports into one ledger format.
+
+## Install
+
+    pip install -e .
+
+## Running the tests
+
+    python setup.py test
+
+## Adding a bank
+
+Drop a new module in `src/ledgerline/parsers/` and it is picked up automatically.
+Each parser subclasses `BaseParser` and implements `parse_row`.

package/packs/dev-team/skills/codebase-tour/evals/files/2/noxfile.py

@@ -0,0 +1,14 @@
+import nox
+
+
+@nox.session(python=["3.10", "3.12"])
+def tests(session):
+    session.install("-e", ".[dev]")
+    session.run("pytest", "-m", "not slow", *session.posargs)
+
+
+@nox.session
+def lint(session):
+    session.install("ruff")
+    session.run("ruff", "check", "src", "tests")
+    session.run("ruff", "format", "--check", "src", "tests")