skilldrop-cli 0.16.29 → 0.16.30

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/openapi.json

@@ -0,0 +1,30 @@
+{
+  "openapi": "3.0.3",
+  "info": { "title": "cabinbook", "version": "1.4.0" },
+  "paths": {
+    "/bookings": {
+      "post": {
+        "requestBody": {
+          "content": {
+            "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" } }
+          }
+        },
+        "responses": { "201": { "description": "Created" } }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "BookingRequest": {
+        "type": "object",
+        "required": ["cabinId", "checkIn", "nights"],
+        "properties": {
+          "cabinId": { "type": "string" },
+          "checkIn": { "type": "string", "format": "date" },
+          "nights": { "type": "integer", "minimum": 1, "maximum": 14 },
+          "guests": { "type": "integer", "minimum": 1, "maximum": 8 }
+        }
+      }
+    }
+  }
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@cabinbook/api",
+  "version": "1.4.0",
+  "private": true,
+  "type": "module",
+  "main": "src/server.js",
+  "scripts": {
+    "dev": "node --env-file=../../.env --watch src/server.js",
+    "start": "node src/server.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "express": "^4.19.2"
+  }
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/db.js

@@ -0,0 +1,19 @@
+// In production this is a pg pool built from DATABASE_URL; locally an in-memory stand-in.
+const url = process.env.DATABASE_URL;
+if (!url) {
+  throw new Error('DATABASE_URL is not set. Copy .env.example to .env.');
+}
+
+const bookings = [];
+
+export const db = {
+  url,
+  async insertBooking(row) {
+    const saved = { id: String(bookings.length + 1), ...row };
+    bookings.push(saved);
+    return saved;
+  },
+  async bookingsForCabin(cabinId) {
+    return bookings.filter((b) => b.cabinId === cabinId);
+  },
+};

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/flags.js

@@ -0,0 +1,8 @@
+// Feature flags come from a comma-separated env var, e.g. FEATURE_FLAGS=long-stays,new-pricing
+const enabled = new Set(
+  (process.env.FEATURE_FLAGS ?? '').split(',').map((f) => f.trim()).filter(Boolean),
+);
+
+export function isEnabled(flag) {
+  return enabled.has(flag);
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/generated/schema.js

@@ -0,0 +1,32 @@
+// DO NOT EDIT. Generated by scripts/gen-schema.mjs from packages/api/openapi.json.
+// Change openapi.json and run `npm run gen`.
+
+export const schemas = {
+  "BookingRequest": {
+    "type": "object",
+    "required": [
+      "cabinId",
+      "checkIn",
+      "nights"
+    ],
+    "properties": {
+      "cabinId": {
+        "type": "string"
+      },
+      "checkIn": {
+        "type": "string",
+        "format": "date"
+      },
+      "nights": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 14
+      },
+      "guests": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 8
+      }
+    }
+  }
+};

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/middleware/validate.js

@@ -0,0 +1,20 @@
+import { schemas } from '../generated/schema.js';
+
+export function validate(schemaName) {
+  const schema = schemas[schemaName];
+  return (req, res, next) => {
+    const errors = [];
+    for (const field of schema.required ?? []) {
+      if (req.body?.[field] === undefined) errors.push(`${field} is required`);
+    }
+    for (const [field, rule] of Object.entries(schema.properties)) {
+      const value = req.body?.[field];
+      if (value === undefined) continue;
+      if (rule.type === 'integer' && !Number.isInteger(value)) errors.push(`${field} must be an integer`);
+      if (rule.minimum !== undefined && value < rule.minimum) errors.push(`${field} must be >= ${rule.minimum}`);
+      if (rule.maximum !== undefined && value > rule.maximum) errors.push(`${field} must be <= ${rule.maximum}`);
+    }
+    if (errors.length) return res.status(400).json({ errors });
+    next();
+  };
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/routes/bookings.js

@@ -0,0 +1,15 @@
+import { Router } from 'express';
+import { validate } from '../middleware/validate.js';
+import { createBooking } from '../services/bookings.js';
+
+export const bookingsRouter = Router();
+
+bookingsRouter.post('/bookings', validate('BookingRequest'), async (req, res, next) => {
+  try {
+    const booking = await createBooking(req.body, req.member);
+    res.status(201).json(booking);
+  } catch (err) {
+    if (err.status) return res.status(err.status).json({ error: err.message });
+    next(err);
+  }
+});

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/server.js

@@ -0,0 +1,15 @@
+import express from 'express';
+import { bookingsRouter } from './routes/bookings.js';
+
+const app = express();
+app.use(express.json());
+app.use((req, _res, next) => {
+  // Members are identified by the upstream proxy.
+  const id = req.get('x-member-id');
+  req.member = id ? { id } : null;
+  next();
+});
+app.use(bookingsRouter);
+
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => console.log(`cabinbook api on :${port}`));

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/services/bookings.js

@@ -0,0 +1,23 @@
+import { db } from '../db.js';
+import { isEnabled } from '../flags.js';
+import { quote } from './pricing.js';
+
+// Business rule: no stay may be longer than two weeks.
+const MAX_NIGHTS = 14;
+const LONG_STAY_MAX_NIGHTS = 28;
+
+export function maxNightsFor(member) {
+  if (member && isEnabled('long-stays')) return LONG_STAY_MAX_NIGHTS;
+  return MAX_NIGHTS;
+}
+
+export async function createBooking({ cabinId, checkIn, nights, guests = 1 }, member) {
+  const max = maxNightsFor(member);
+  if (nights > max) {
+    const err = new Error(`Stays are limited to ${max} nights`);
+    err.status = 422;
+    throw err;
+  }
+  const price = quote({ nights, guests });
+  return db.insertBooking({ cabinId, checkIn, nights, guests, price, memberId: member?.id ?? null });
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/src/services/pricing.js

@@ -0,0 +1,9 @@
+const NIGHTLY_RATE = 120;
+const EXTRA_GUEST_FEE = 15;
+const WEEKLY_DISCOUNT = 0.1;
+
+export function quote({ nights, guests = 1 }) {
+  const base = nights * NIGHTLY_RATE + Math.max(0, guests - 2) * EXTRA_GUEST_FEE * nights;
+  const discount = nights >= 7 ? base * WEEKLY_DISCOUNT : 0;
+  return Math.round((base - discount) * 100) / 100;
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/api/test/pricing.test.js

@@ -0,0 +1,15 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { quote } from '../src/services/pricing.js';
+
+test('charges the nightly rate for short stays', () => {
+  assert.equal(quote({ nights: 3 }), 360);
+});
+
+test('adds a fee per extra guest per night', () => {
+  assert.equal(quote({ nights: 2, guests: 4 }), 300);
+});
+
+test('applies the weekly discount from 7 nights', () => {
+  assert.equal(quote({ nights: 7 }), 756);
+});

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/web/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cabinbook/web",
+  "version": "1.4.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/web/src/bookingForm.js

@@ -0,0 +1,11 @@
+// Client-side checks for the booking form, run before POST /bookings.
+export const MAX_NIGHTS = 14;
+export const MAX_GUESTS = 8;
+
+export function validateBookingForm({ nights, guests }) {
+  const errors = {};
+  if (!Number.isInteger(nights) || nights < 1) errors.nights = 'Choose at least one night';
+  else if (nights > MAX_NIGHTS) errors.nights = `Stays are limited to ${MAX_NIGHTS} nights`;
+  if (!Number.isInteger(guests) || guests < 1 || guests > MAX_GUESTS) errors.guests = `1 to ${MAX_GUESTS} guests`;
+  return errors;
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/web/src/format.js

@@ -0,0 +1,7 @@
+export function formatPrice(amount) {
+  return `€${amount.toFixed(2)}`;
+}
+
+export function formatNights(n) {
+  return n === 1 ? '1 night' : `${n} nights`;
+}

package/packs/dev-team/skills/codebase-tour/evals/files/5/packages/web/test/format.test.js

@@ -0,0 +1,12 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { formatNights, formatPrice } from '../src/format.js';
+
+test('formats prices in euros with two decimals', () => {
+  assert.equal(formatPrice(756), '€756.00');
+});
+
+test('pluralises nights', () => {
+  assert.equal(formatNights(1), '1 night');
+  assert.equal(formatNights(14), '14 nights');
+});

package/packs/dev-team/skills/codebase-tour/evals/files/5/scripts/gen-schema.mjs

@@ -0,0 +1,27 @@
+// Generates packages/api/src/generated/schema.js from packages/api/openapi.json.
+// Usage (from the repo root): node scripts/gen-schema.mjs [--check]
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const SRC = 'packages/api/openapi.json';
+const DEST = 'packages/api/src/generated/schema.js';
+
+const spec = JSON.parse(readFileSync(SRC, 'utf8'));
+const schemas = spec.components.schemas;
+
+const out = [
+  '// DO NOT EDIT. Generated by scripts/gen-schema.mjs from packages/api/openapi.json.',
+  '// Change openapi.json and run `npm run gen`.',
+  '',
+  `export const schemas = ${JSON.stringify(schemas, null, 2)};`,
+  '',
+].join('\n');
+
+if (process.argv.includes('--check')) {
+  const current = readFileSync(DEST, 'utf8');
+  if (current !== out) {
+    console.error(`${DEST} is out of date. Run \`npm run gen\`.`);
+    process.exit(1);
+  }
+} else {
+  writeFileSync(DEST, out);
+}

package/packs/dev-team/skills/codebase-tour/examples/refund-window.md

@@ -0,0 +1,158 @@
+# Worked example: tallyhall, before adding a refund window
+
+A fictional FastAPI ticketing service. The README is two releases stale, one rule has a second copy, and one module is generated.
+
+## Input given to the skill
+
+> I've just joined and my first ticket is "refunds must be requested within 14 days of the event ending". I've never opened this repo. Get me oriented. The repo is the current directory.
+
+The files that mattered, with the line numbers the tour cites:
+
+```text
+README.md
+  5   ## Run it
+  7       make dev
+ 12   Settings live in `settings.toml`.
+
+Makefile
+  1   .PHONY: run test lint
+  3   run:
+  4   	uvicorn tallyhall.main:app --reload
+  7   test:
+  8   	pytest -q -m "not e2e"
+ 10   lint:
+ 11   	ruff check tallyhall tests
+
+.github/workflows/ci.yml
+ 17         - run: pip install -e ".[dev]"
+ 19         - run: make lint
+ 21         - run: make test
+ 23     env:
+ 24       TALLYHALL_DB_URL: sqlite:///ci.db
+
+pyproject.toml
+ 14   [tool.pytest.ini_options]
+ 15   markers = ["e2e: needs the payment sandbox"]
+
+tallyhall/main.py
+  6   app = FastAPI()
+  7   app.include_router(refunds.router)
+
+tallyhall/api/refunds.py
+ 18   @router.post("/orders/{order_id}/refunds", status_code=201)
+ 19   def create_refund(order_id: int, db=Depends(get_db)):
+ 20       order = orders.get(db, order_id)
+ 22       check_refundable(order, now=utcnow())
+ 24       except RefundRejected as e:
+ 25           raise HTTPException(422, {"code": e.code, "message": str(e)})
+ 27       return refunds.create(db, order)
+
+tallyhall/rules/refunds.py
+  4   class RefundRejected(Exception):
+  9   def check_refundable(order, now):
+ 10       if order.status != "paid":
+ 11           raise RefundRejected("not_paid", "only paid orders can be refunded")
+ 12       if order.refunded_at is not None:
+ 13           raise RefundRejected("already_refunded", "order already refunded")
+
+tallyhall/admin/bulk_refund.py
+ 27       if order.status == "paid" and order.refunded_at is None:
+ 28           refunds.create(db, order)
+
+tallyhall/models_gen.py
+  1   # generated by datamodel-codegen:
+  2   #   filename:  schemas/order.json
+
+tallyhall/settings.py
+  6   DB_URL = os.environ["TALLYHALL_DB_URL"]
+
+tests/rules/test_refunds.py   (test_rejects_unpaid, test_rejects_already_refunded)
+tests/api/test_refunds_e2e.py (marked e2e)
+```
+
+The fact lister also reported: `make dev` named at `README.md:7` with no `dev` target in the Makefile, and `settings.toml` named at `README.md:12` and not present. No test file imports `tallyhall/admin/bulk_refund.py`. The Order model (`tallyhall/models_gen.py`) has an `event_ends_at` field.
+
+---
+
+## Output
+
+**What matters for this change**
+
+- The rule goes in `check_refundable` (`tallyhall/rules/refunds.py:9`). Every other refund rule lives there, and the API calls it at `tallyhall/api/refunds.py:22`.
+- There is a second copy of the refund rules in the support bulk-refund tool (`tallyhall/admin/bulk_refund.py:27`). It doesn't call `check_refundable`, so it won't pick up the window unless someone changes it. Whether it should is the first question for a maintainer.
+- Ignore the README's `make dev` and `settings.toml`. Neither exists. Run with `make run` (`Makefile:3`); settings come from env vars (`tallyhall/settings.py:6`).
+- `tallyhall/models_gen.py` is generated from `schemas/order.json`. Don't edit it. The field the window needs, `event_ends_at`, is already there.
+- `make test` skips the e2e tests (`Makefile:8`, marker at `pyproject.toml:15`). The rule tests in `tests/rules/` do run.
+
+# Tour: tallyhall, for "refunds within 14 days of the event ending"
+
+_Read on 2026-10-20. Scope: `POST /orders/{order_id}/refunds` from the app bootstrap to `refunds.create`. Skipped on purpose: ticket purchase, the payment-provider client, deployment config._
+
+[assumption] "Within 14 days of the event ending" means `now - order.event_ends_at <= 14 days`, with the boundary day allowed.
+
+## Run it
+
+| To | Command | Source | Status |
+|---|---|---|---|
+| Install | `pip install -e ".[dev]"` | `.github/workflows/ci.yml:17` | read, not run |
+| Test (whole suite) | `make test` → `pytest -q -m "not e2e"` | `.github/workflows/ci.yml:21`, `Makefile:8` | ran: passed (14 passed, 3 deselected) |
+| Test (this area) | `pytest -q -m "not e2e" tests/rules/test_refunds.py` | derived from `Makefile:8` | ran: passed (2 passed) |
+| Lint | `make lint` → `ruff check tallyhall tests` | `.github/workflows/ci.yml:19`, `Makefile:11` | ran: passed |
+| Run locally | `make run` | `Makefile:3` | read, not run (needs `TALLYHALL_DB_URL`) |
+
+Needs: `TALLYHALL_DB_URL`, read at `tallyhall/settings.py:6` with no default; CI sets `sqlite:///ci.db` at `.github/workflows/ci.yml:24`.
+
+## The path this change touches
+
+1. `tallyhall/main.py:7`: the refunds router is mounted on the app.
+2. `tallyhall/api/refunds.py:19` `create_refund`: loads the order (line 20).
+3. `tallyhall/api/refunds.py:22`: calls `check_refundable(order, now=utcnow())`.
+4. `tallyhall/rules/refunds.py:9` `check_refundable`: raises `RefundRejected` for an unpaid order (line 10) or one already refunded (line 12).
+5. `tallyhall/api/refunds.py:25`: `RefundRejected` becomes a 422 with `{code, message}`.
+6. `tallyhall/api/refunds.py:27`: `refunds.create` writes the refund. This is the far edge.
+
+## Where the change goes
+
+- `tallyhall/rules/refunds.py` `check_refundable`: add the window check after line 13, raising `RefundRejected("refund_window_closed", …)`. This follows the two rules already there.
+- Must change with it: nothing generated. `event_ends_at` already exists in `tallyhall/models_gen.py`. Whether `tallyhall/admin/bulk_refund.py:27` changes too is open (question 1).
+
+## Conventions the code follows
+
+- **Errors:** a rule raises `RefundRejected(code, message)` with a snake_case code (`tallyhall/rules/refunds.py:11`); the route maps it to 422 (`tallyhall/api/refunds.py:25`).
+- **Time:** the route passes `now` in, so rules are tested without a clock (`tallyhall/api/refunds.py:22`).
+- **Tests:** one `test_rejects_<reason>` per rule, under `tests/rules/` (`tests/rules/test_refunds.py`).
+- **Config:** env vars read in `tallyhall/settings.py`; a missing var fails at import (`tallyhall/settings.py:6`).
+
+## Traps
+
+- **Generated:** `tallyhall/models_gen.py` from `schemas/order.json` (`tallyhall/models_gen.py:1-2`). No regenerate command is defined in the Makefile, pyproject or CI; see question 2. CI drift check: none found.
+- **Second copy:** `tallyhall/admin/bulk_refund.py:27` repeats the paid and not-refunded checks inline.
+- **Untested on the path:** none on the API path. Off the path, `tallyhall/admin/bulk_refund.py` has no test.
+- **Tests the default command skips:** `e2e` (`Makefile:8`, `pyproject.toml:15`): `tests/api/test_refunds_e2e.py`, which needs the payment sandbox.
+- **Env vars and flags on the path:** `TALLYHALL_DB_URL` only. No feature flags found.
+- **Vendored:** none.
+
+## Where the README is wrong
+
+- README says `make dev` (`README.md:7`); the Makefile has `run`, `test` and `lint` only (`Makefile:1`). Use `make run`.
+- README says settings live in `settings.toml` (`README.md:12`); there is no such file, and settings are env vars (`tallyhall/settings.py:6`).
+
+## Tests for this area
+
+- Covered by: `tests/rules/test_refunds.py` (unpaid and already-refunded rejections).
+- Run just these: `pytest -q -m "not e2e" tests/rules/test_refunds.py` (derived from `Makefile:8`).
+- Not covered: the 422 mapping is exercised only by the e2e test, which `make test` skips.
+
+## First step
+
+Add `test_rejects_refund_after_window` to `tests/rules/test_refunds.py`, with an order whose `event_ends_at` is 15 days before `now`. Run `pytest -q -m "not e2e" tests/rules/test_refunds.py`. It fails until `check_refundable` checks the window. Add a 14-day case that passes, to pin the boundary.
+
+## Open questions for a maintainer
+
+1. Should the bulk-refund tool (`tallyhall/admin/bulk_refund.py:27`) apply the window, or is it the support override that skips it?
+2. How is `tallyhall/models_gen.py` regenerated? Nothing in the repo defines the command.
+3. Is the window measured from `event_ends_at` in UTC? `utcnow()` is used at `tallyhall/api/refunds.py:22`, but the schema doesn't say what timezone the event times are in.
+
+---
+
+Why this passes the bar: every command has a source and a status, both README claims are contradicted with citations, the second copy is named and left as a question rather than silently changed or ignored, the generated file is called out before anyone edits it, and the first step names a file, a command and the failure that proves it.

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

@@ -0,0 +1,47 @@
+{
+  "name": "codebase-tour",
+  "version": "0.1.0",
+  "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\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "agents-md-generator",
+    "architecture-diagrams",
+    "feature-implement-loop",
+    "interactive-diagram",
+    "pre-merge-review",
+    "reverse-architecture"
+  ],
+  "handoff": [
+    {
+      "to": "feature-implement-loop",
+      "when": "the tour names where the change goes and a first step",
+      "purpose": "Implement the change against acceptance criteria, starting from the tour's first step and running the area's test command it found.",
+      "fallback": "If feature-implement-loop is absent, take the tour's first step: write the failing test it names, run the area's test command before and after the change, and update every place listed under 'Must change with it'."
+    }
+  ],
+  "tags": [
+    "onboarding",
+    "codebase",
+    "repo-orientation",
+    "provenance",
+    "developer-experience"
+  ],
+  "permissions": {
+    "network": [],
+    "commands": [],
+    "files": "none",
+    "notes": "scripts/repo_facts.py reads files under the repository root it is given and prints to stdout. It writes nothing and runs no commands."
+  },
+  "model": {
+    "tier": "standard",
+    "rationale": "Reading a repo and citing what it finds is generation over evidence; every claim is checked against a file, so a mid tier is enough."
+  }
+}