create-warlock 4.1.15 → 4.2.0

package/templates/warlock/skills/data-and-persistence/SKILL.md

@@ -1,330 +0,0 @@
----
-name: data-and-persistence
-description: 'How this project models, stores, and migrates data with `@warlock.js/cascade` — money as integer minor units (`total_cents`, `amount_cents`) with `currency` alongside, time as UTC `Date` columns named `<verb>_at` (e.g. `synced_at`, `checked_out_at`, `abandoned_at`), opaque IDs in URLs (UUID / nanoid), audit columns auto-managed by the framework (`created_at` / `updated_at`), soft-delete via cascade''s delete strategy (`@warlock.js/cascade/configure-delete-strategy/SKILL.md`), schemas defined with `v.object` and inferred into `Infer<>` types, models declared via `@RegisterModel()` + `Model<Schema>` + typed getters (`this.get<T>(key, default)`), migrations via `Migration.create(Model, {...columns}, { unique })` with column types `text() / integer() / double() / bool() / json() / arrayText()`, relations via `@BelongsTo("Name")` and `@HasMany("Name")`, snake_case columns + camelCase getters. Triggers: defining a model / schema / cascade blueprint; writing a migration; choosing a column type for currency, prices, totals, balances, refunds, fees; choosing how to store a timestamp / date; deciding ID format; adding audit columns; designing soft-delete vs hard-delete; defining relations (BelongsTo, HasMany); user asks "how do we store money", "UTC vs local time", "what ID format do we use", "should this be soft-deleted", "migration rules", "BelongsTo vs HasMany", "what does the model look like", "how do I add a column". Skip: API response shape (load `skills/api-design/SKILL.md`); query performance / N+1 / caching (load `skills/observability-and-resilience/SKILL.md`); pure business-logic refactors with no schema change; framework primitive deep-dive — load the relevant `@warlock.js/cascade/*` skill (define-model, paginate-results, configure-delete-strategy, etc.).'
----
-
-# Data & persistence
-
-**Status:** Stable
-**Applies to:** Every model, schema, migration, and persisted entity in `src/app/**`.
-
-How we store data so it survives a year of new requirements, a currency conversion bug, and a timezone-aware feature request. Framework mechanics live in `@warlock.js/cascade/skills/*` — this skill is the **project-level conventions** layered on top.
-
-> **Sub-agent rule:** Before writing any model, schema, or migration, read this file.
-
----
-
-## 1. Money — integer minor units, always
-
-### 1.1 The rule
-
-- Store money as **integers in the currency's smallest unit** — cents for USD, halalas for SAR.
-- Column name carries the unit: `total_cents`, `amount_cents`, `fee_cents`, `discount_cents`.
-- A `currency` column lives next to every money column (or once per row if the entity is mono-currency).
-
-The Cart model is the project's canonical example:
-
-```typescript
-// ✅ from cart.model.ts
-export const cartSchema = v.object({
-  /* ... */
-  total_cents: v.number().default(0),
-  total_items: v.number().default(0),
-  currency: v.string().default("USD"),
-  /* ... */
-});
-```
-
-### 1.2 Why never floats
-
-```typescript
-0.1 + 0.2 === 0.3        // false
-1234.567 * 100           // 123456.69999999999
-```
-
-Compound a million orders' subtotals across a payout report and you'll be off by enough to matter. Integer cents prevents this entire class of bug.
-
-### 1.3 The AI-pricing exception
-
-`ai-models.input_price` and `ai-models.output_price` are stored as `v.number()` — not cents. This is **deliberate**: AI provider pricing is sub-cent per token (e.g. $0.000002), where integer minor units round to zero. The exception is *only* AI / token pricing; business money (orders, products, payments, balances, refunds) follows the cents rule.
-
-### 1.4 Display formatting at the edge
-
-Formatting (`$12.99`, `12.99 SAR`) is the resource layer's job — see `skills/api-design/SKILL.md` § 5. The model and service work in cents; the resource converts.
-
----
-
-## 2. Time — UTC at rest, convert at the edge
-
-### 2.1 Storage
-
-- All timestamp columns store **UTC**, full stop.
-- The column type is `date()` in the migration; the schema type is `v.date()` returning `Date`.
-
-### 2.2 Naming — `<verb>_at`
-
-Time columns end with `_at` and describe what happened, in past tense:
-
-| Column          | Meaning                          |
-| --------------- | -------------------------------- |
-| `created_at`    | row was created                  |
-| `updated_at`    | row was last updated             |
-| `synced_at`     | row was synced from a source     |
-| `checked_out_at`| cart was checked out             |
-| `abandoned_at`  | cart was marked abandoned        |
-| `expires_at`    | row will become invalid          |
-
-```typescript
-// ✅ from cart.model.ts
-synced_at: v.date().optional(),
-abandoned_at: v.date().optional(),
-checked_out_at: v.date().optional(),
-```
-
-### 2.3 Conversion happens at the response layer
-
-Services and models work in UTC `Date` objects. Timezone conversion (UTC → user's local timezone) happens once, at the resource / response layer, using the authenticated user's preference. Never store timezone-adjusted timestamps.
-
-### 2.4 Date library
-
-The project uses `dayjs` for time arithmetic and formatting (already in dependencies). Never `moment`, never hand-rolled UTC math. The framework's `@mongez/time-wizard` provides typed helpers on top of dayjs — prefer it where available.
-
----
-
-## 3. IDs
-
-### 3.1 The rule
-
-- **Internal primary keys** may be sequential — they're cheap, indexed, and never leave the database.
-- **Any ID that crosses a process boundary** (URL, response body, log line, webhook) is opaque — UUID or nanoid.
-
-### 3.2 Project default
-
-Cascade generates string IDs by default for new records. Use those as the public identifier. Don't expose `_id` (Mongo) or sequential integers (Postgres serial) in URLs even if they exist internally.
-
-### 3.3 Why
-
-Sequential keys leak business volume (`/orders/42178` tells anyone you've placed ~42k orders) and invite enumeration attacks (incrementing the path to find someone else's resource). Opaque IDs prevent both.
-
----
-
-## 4. Audit columns
-
-### 4.1 Framework-managed
-
-Cascade auto-adds `created_at` and `updated_at` to every model. You do **not** add them to the schema or migration — the framework handles them.
-
-### 4.2 Author tracking
-
-For entities where "who created this" matters (most business entities), add author columns to the resource:
-
-```typescript
-// ✅ from ai-model.resource.ts
-created_by: "string",
-updated_by: "string",
-deleted_by: "string",
-```
-
-These store the user-id of the actor at the time of the action. Wire them in the service:
-
-```typescript
-await ordersRepository.create({ ...input, created_by: user.id });
-```
-
-### 4.3 What to audit
-
-Every entity that's user-mutable: yes. Read-only reference data (countries, currencies, system enums): no — audit columns are noise there.
-
----
-
-## 5. Soft-delete vs hard-delete
-
-### 5.1 Default to soft-delete for user-visible entities
-
-Soft-delete keeps the row, sets `deleted_at` + `deleted_by`. The entity is excluded from default queries but recoverable.
-
-### 5.2 Hard-delete for ephemeral data
-
-Use hard-delete for:
-
-- Sessions, OTPs, refresh tokens (expired = gone)
-- Cache entries
-- Idempotency-key records past their TTL
-- GDPR right-to-erasure requests (when triggered)
-
-### 5.3 Mechanics
-
-Configure the delete strategy at the model level — see `@warlock.js/cascade/configure-delete-strategy/SKILL.md` for the framework's per-model knobs (`paranoid`, `forever`, `cascade`).
-
-### 5.4 Restore is admin-only
-
-If an entity supports restore, expose it through an admin endpoint, never end-user UI (unless the feature is explicitly "trash / undelete" — a deliberate UX, not an accident).
-
----
-
-## 6. Migrations
-
-### 6.1 Forward-only
-
-Never edit a shipped migration. Once it's on `main`, the only change is a new migration on top.
-
-### 6.2 File location
-
-Migrations live inside the model folder: `src/app/<module>/models/<model>/migrations/<timestamp>-<noun>.migration.ts`. The framework's `yarn cli migrate` discovers them.
-
-### 6.3 Definition shape
-
-```typescript
-// ✅ from ai-model.migration.ts
-import { arrayText, bool, double, integer, json, Migration, text } from "@warlock.js/cascade";
-import { AiModel } from "../ai-model.model";
-
-export default Migration.create(
-  AiModel,
-  {
-    provider: text().notNullable(),
-    code: text().notNullable(),
-    name: text().notNullable(),
-    context: integer().notNullable(),
-    is_free: bool().notNullable(),
-    input_price: double().notNullable(),
-    config: json().nullable(),
-    features: arrayText().nullable(),
-  },
-  {
-    unique: [{ columns: ["provider", "provider_model_id"] }],
-  },
-);
-```
-
-Column type helpers: `text()`, `integer()`, `double()`, `bool()`, `json()`, `arrayText()`, `date()`. Always declare `.notNullable()` or `.nullable()` explicitly — never leave nullability implicit.
-
-### 6.4 Backfill separately from schema change
-
-Two migrations, not one:
-
-1. Schema change (add column nullable, or add column with default).
-2. Backfill (populate the column from existing data).
-
-This keeps each migration short, fast, and safe to revert in stages.
-
-### 6.5 Long-running backfills
-
-If a backfill is going to touch millions of rows, gate it behind a feature flag and run it as a background job — not inside the migration runner. The migration just creates the schema; the backfill is application code.
-
----
-
-## 7. Indexes
-
-### 7.1 Every query path has a supporting index
-
-- Foreign keys are indexed by default.
-- Any column you filter or sort on regularly gets an index.
-- Composite indexes match query order (`WHERE org_id = ? AND status = ?` → index `(org_id, status)`).
-
-### 7.2 Add the index alongside the query
-
-If a new query is introduced, the index lands in the same PR. Don't push slow queries to production and patch later.
-
-### 7.3 Tooling
-
-`yarn db.indexes` runs the framework's index management. Define indexes declaratively in the migration's options.
-
----
-
-## 8. Schema conventions
-
-### 8.1 Column naming — snake_case
-
-All database column names use `snake_case`: `created_at`, `total_cents`, `provider_model_id`. This matches the wire-format convention in resources.
-
-### 8.2 Foreign keys — `<noun>_id`
-
-`user_id`, `organization_id`, `cart_id`. Always singular, always `_id` suffix. Cascade's `@BelongsTo("Name")` decorator wires the relation off this column by convention.
-
-### 8.3 Booleans — affirmative
-
-`is_active`, `is_free`, `has_shipped`, `was_refunded`. Never negative (`is_not_deleted`, `is_unverified`) — negative booleans break readability under negation (`!isNotDeleted` reads as a riddle).
-
-### 8.4 Enums — string in the column, enum in the schema
-
-```typescript
-status: v.enum(CartStatus).default(CartStatus.ACTIVE),
-```
-
-The enum is defined once in `app/<module>/types/<noun>-status.type.ts` and referenced everywhere. Never use raw string literals for status fields outside the type definition.
-
-### 8.5 Defaults
-
-Declare defaults in the schema (`v.string().default("USD")`), not just in the migration. The schema default keeps `Infer<>` clean and gives the service a sensible starting value.
-
----
-
-## 9. Models — structural rules
-
-### 9.1 File layout
-
-```
-src/app/<module>/models/<noun>/
-  <noun>.model.ts        ← @RegisterModel() + schema + class + getters
-  index.ts               ← re-export
-  migrations/
-    <timestamp>-<noun>.migration.ts
-```
-
-### 9.2 The model file shape (Cart is the gold standard)
-
-```typescript
-// 1. schema first
-export const cartSchema = v.object({ /* columns */ });
-export type CartSchema = Infer<typeof cartSchema>;
-
-// 2. class with decorator
-@RegisterModel()
-export class Cart extends Model<CartSchema> {
-  public static table = "carts";
-  public static schema = cartSchema;
-
-  // 3. relations
-  @BelongsTo("Organization")
-  public organization?: Organization;
-
-  @HasMany("CartItem")
-  public items?: CartItem[];
-
-  // 4. typed getters — one per persisted field accessed from app code
-  public get totalCents() {
-    return this.get<number>("total_cents", 0);
-  }
-}
-```
-
-### 9.3 Typed getters over `.get<T>("field")` at call sites
-
-This is project policy (see memory `feedback_use_model_getters`). Every column accessed from application code gets a typed getter on the model. One line beats `cart.get<number>("total_cents")` across N call sites.
-
-### 9.4 Class-level JSDoc for non-obvious domain logic
-
-The Cart model has a multi-paragraph JSDoc explaining identity ownership, lead linkage, source-of-truth rules, and currency snapshotting. Mirror this for any model whose semantics aren't obvious from the columns alone.
-
----
-
-## 10. Review checklist
-
-Before merging a change that touches a model, schema, or migration:
-
-- [ ] Money columns are `integer cents` with `currency` alongside (AI-pricing is the only exception)
-- [ ] Time columns end with `_at`, store UTC `Date`
-- [ ] No timezone-adjusted timestamps in storage
-- [ ] IDs exposed in URLs / responses are opaque
-- [ ] Audit columns (`created_by`, `updated_by`) wired where author tracking matters
-- [ ] Soft-delete strategy chosen deliberately, configured via cascade
-- [ ] Migration is forward-only, not editing a shipped file
-- [ ] Backfill is a separate migration / background job from the schema change
-- [ ] Every new query path has a supporting index
-- [ ] Column names snake_case, foreign keys `<noun>_id`
-- [ ] Booleans are affirmative (`is_active`, never `is_not_deleted`)
-- [ ] Enums defined once in `types/`, never repeated as string literals
-- [ ] Defaults declared in the schema, not only in the migration
-- [ ] Every accessed column has a typed getter on the model
-- [ ] Class-level JSDoc on the model if domain semantics aren't obvious

package/templates/warlock/skills/git-workflow/SKILL.md

@@ -1,282 +0,0 @@
----
-name: git-workflow
-description: 'Git, branching, commit messages, PRs, and CI gates for this project — conventional commits with module-scoped types (`feat(orders): ...`, `fix(auth): ...`, `refactor(cart): ...`, `docs(users): ...`, `chore: ...`), branch naming (`feat/`, `fix/`, `chore/`, `refactor/`, `docs/` prefix + slug), PR size cap (~400 LoC), required reviewers, CI gates (`yarn tsc` / `yarn lint` / `yarn test` / `yarn audit --level=high`), no force-push to `main`, squash-merge policy, tagging and releases. Triggers: writing a commit message; opening / reviewing / merging a PR; naming a branch; setting up CI; user asks "commit format", "conventional commits", "branch naming", "how big should a PR be", "what CI gates do we need", "how do we release", "can I force push", "squash or merge", "scope in commit message", "what scopes are valid". Skip: code style inside files (load `skills/code-standards/SKILL.md`); deploy mechanics / pm2 setup; framework primitive questions; publishing / semantic-versioning of npm packages.'
----
-
-# Git workflow
-
-**Status:** Stable
-**Applies to:** Every commit, branch, and pull request in the project.
-
-The process layer that lets a team of N work without stepping on each other and lets a reader six months later understand why a line is there.
-
-> **Sub-agent rule:** Before opening a commit or PR, read this file.
-
----
-
-## 1. Commit messages — conventional commits
-
-### 1.1 Format
-
-```
-<type>(<scope>): <imperative summary>
-
-[optional body — explains the WHY when the diff doesn't]
-
-[optional footer — BREAKING CHANGE, ticket refs, co-authors]
-```
-
-Examples:
-
-```
-feat(orders): add cancellation flow with refund + audit trail
-fix(auth): reject expired refresh tokens on rotation
-docs(users): document the profile-update endpoint
-refactor(cart): extract totals calculation into a util
-```
-
-### 1.2 Types
-
-| Type        | Use for                                          |
-| ----------- | ------------------------------------------------ |
-| `feat`      | New user-visible feature or capability           |
-| `fix`       | Bug fix                                          |
-| `refactor`  | Internal restructure with no behaviour change    |
-| `docs`      | Documentation only (skills, README, code docs)   |
-| `test`      | Adding or updating tests only                    |
-| `chore`     | Tooling, config, scripts — no app code change    |
-| `perf`      | Performance improvement                          |
-| `build`     | Build system or external dependencies            |
-| `ci`        | CI configuration                                 |
-| `style`     | Formatting only (rare — Prettier handles this)   |
-
-### 1.3 Scope
-
-The scope identifies what area of the codebase changed. Use:
-
-- The module name for app-level changes: `feat(orders): ...`, `fix(auth): ...`
-- Omit when the change is genuinely cross-cutting: `chore: bump node version`
-
-### 1.4 Summary
-
-- Imperative present tense: "add" not "added", "fix" not "fixed"
-- Under 72 characters
-- No trailing period
-- Lowercase first word (after the type / scope)
-
-### 1.5 Body — explain the WHY
-
-If the diff doesn't make the reasoning obvious, the body does. One short paragraph is usually enough. Skip the body for trivial changes.
-
-### 1.6 Breaking changes
-
-Either:
-
-- Add `!` after type: `feat(api)!: rename /users to /accounts`
-- Or include a `BREAKING CHANGE:` footer with details
-
-Both work; pick one per project and use it consistently. Project default: footer (more visible in `git log` output).
-
-### 1.7 Ticket references
-
-When the change traces to a ticket, reference it in the footer:
-
-```
-feat(orders): add cancellation flow
-
-Refs: WAR-1234
-```
-
----
-
-## 2. Branch naming
-
-### 2.1 Format
-
-`<type>/<short-slug>` — lowercase, hyphenated, no spaces.
-
-Examples:
-
-```
-feat/order-cancel-endpoint
-fix/login-rate-limit
-refactor/extract-cart-totals-helper
-docs/skills-code-standards-section-9
-chore/bump-vitest-to-4
-```
-
-### 2.2 Types match commit types
-
-Use the same vocabulary as commits: `feat/`, `fix/`, `refactor/`, `docs/`, `test/`, `chore/`, `perf/`, `ci/`.
-
-### 2.3 Optional ticket prefix
-
-When the team uses ticket tracking, `<type>/<ticket-id>-<slug>` is fine:
-
-```
-feat/war-1234-order-cancel-endpoint
-```
-
-### 2.4 Never work directly on `main`
-
-Even one-line doc fixes get a branch. The protected-branch rule (§ 7) makes this enforced, not optional.
-
----
-
-## 3. Pull requests
-
-### 3.1 Size cap — under 400 lines changed
-
-400 lines of meaningful changes (excluding lockfiles, generated code, snapshot data). Beyond that, the review becomes performative — reviewers skim, real issues slip through.
-
-### 3.2 When it's bigger, split
-
-A common shape:
-
-1. **Prep PR** — pure refactor / extraction, no behaviour change. Lands first.
-2. **Feature PR** — the actual new logic, smaller because the prep already landed.
-3. **Tests PR** — coverage for the feature.
-
-Each PR is independently mergeable, independently reviewable.
-
-### 3.3 Description template
-
-```markdown
-## What
-One-line summary of the change.
-
-## Why
-The reason — link to a ticket, design doc, or bug report.
-
-## How to verify
-Steps a reviewer can take to confirm it works.
-
-## Screenshots / recordings
-If UI or output changed.
-
-## Notes for reviewer
-Anything that's intentionally weird or worth knowing.
-```
-
-### 3.4 Self-review first
-
-Read your own diff before requesting review. The number of "oh I forgot to remove that" moments you catch yourself saves the reviewer a round-trip and saves your reputation.
-
-### 3.5 Required reviewers
-
-- **Default** — 1 reviewer
-- **Security, auth, payments, data migrations** — 2 reviewers, one with domain ownership
-
----
-
-## 4. Review
-
-### 4.1 Read the diff cover to cover
-
-Not just the changed lines — the surrounding context too. A line that looks fine in isolation may be obviously broken in context.
-
-### 4.2 Suggestion vs. blocker — label it
-
-- **Blocker**: must change before merge. State it as such.
-- **Suggestion**: nice-to-have, optional, can land later. Mark it explicitly so the author isn't guessing.
-- **Question**: you don't understand something — ask, don't assume.
-
-### 4.3 Approve means "I'd be on call for this"
-
-Approval is a load-bearing signature. Approve only if you're comfortable owning the code after the author rotates off the project.
-
-### 4.4 No "LGTM" without reading
-
-A drive-by approve is worse than no approve — it gives false confidence. If you don't have time to review properly, say so and let someone else.
-
----
-
-## 5. CI gates
-
-Every PR runs these. All must pass before merge. The exact commands match `package.json` scripts:
-
-| Gate                          | Command                       | Blocks on                          |
-| ----------------------------- | ----------------------------- | ---------------------------------- |
-| Type-check                    | `yarn tsc`                    | Any TS error                       |
-| Lint                          | `yarn lint`                   | Any ESLint error                   |
-| Tests                         | `yarn test --run`             | Any failed test                    |
-| Coverage (recommended floor)  | `yarn test:coverage`          | TBD per team policy                |
-| Dependency audit              | `yarn audit --level=high`     | High / critical vulnerabilities    |
-| Format check                  | `yarn format --check`         | Any unformatted file               |
-
-Additional rules:
-
-- No `.only` / `.skip` in committed tests (lint rule or CI grep).
-- No `console.log` in committed code (lint rule).
-- No `TODO` without a ticket reference (warning, not blocker).
-
----
-
-## 6. Merging
-
-### 6.1 Squash merge
-
-One commit per PR onto `main`. The squashed commit message is the conventional-commit format from § 1, generated from the PR title.
-
-This keeps `main`'s history readable — one logical change per commit — while allowing PR branches to have messy work-in-progress commits.
-
-### 6.2 `main` is always green
-
-If `main` is red, the team's first job is to make it green. No new PRs merge until it is.
-
-### 6.3 Hotfix flow
-
-Same conventional commits + same CI gates + expedited review (1 reviewer, can be self-review for true emergencies if a maintainer is on the call). Hotfix PRs are still squash-merged.
-
----
-
-## 7. Protected branches
-
-`main` is protected:
-
-- No direct push.
-- No force-push.
-- Required CI checks pass before merge.
-- Required reviewer count met.
-- Linear history (squash merges only — no merge commits).
-
-These are enforced in the repo settings, not just on the honour system.
-
----
-
-## 8. Tags and releases
-
-### 8.1 Versioning
-
-For a single-monolith app (most templates), versioning is optional — date-tags work fine if you want them at all.
-
-For a library / framework package, semver:
-
-```
-v<major>.<minor>.<patch>
-```
-
-### 8.2 Changelog
-
-Generate from conventional commits — every well-formed history can be turned into a readable changelog automatically. Tools: `changesets`, `conventional-changelog`, or the framework's own release script.
-
-### 8.3 Release notes
-
-For user-facing apps, ship release notes alongside the tag — what changed, what to test, any known issues.
-
----
-
-## 9. Review checklist
-
-Before merging:
-
-- [ ] Commit message follows `<type>(<scope>): <imperative summary>`
-- [ ] Branch name matches `<type>/<slug>`
-- [ ] PR under ~400 lines changed (or split into staged PRs)
-- [ ] Self-reviewed before requesting review
-- [ ] Description filled (what / why / how to verify)
-- [ ] Required reviewer count met
-- [ ] All CI gates green
-- [ ] No `.only` / `.skip` / `console.log` left in
-- [ ] Squash-merge selected, squashed message in conventional format
-- [ ] `main` stays green after merge