@xhulz/nina 0.45.0 → 0.46.0

package/releases/0.46.0/surfaces/pii/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot pii.1 -->
+8. **Sensitive personal data is classified, and the classification is enforced.** What counts as sensitive here — identity documents, financial identifiers, anything a person would not expect to be readable by whoever can read a log — is declared in `.claude/architecture.md` § *Privacy*, along with the regime that governs it ({{PRIVACY_REGIME}}). Encrypted at rest. **No sensitive value in a log, an error message, a URL, an analytics event, or an agent transcript** — the places nobody thinks about are exactly the ones that persist. Document bytes live only in the object store, referenced by key, never in the database in clear text.
+
+<!-- nina:slot pii.2 -->
+- **personal data**: where it is collected, stored, logged or sent

package/releases/0.46.0/surfaces/prisma/tree/.claude/agents/architect.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.46.0/surfaces/prisma/tree/.claude/agents/dba.md

@@ -0,0 +1,42 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | **before ANY `prisma` CLI command** — `validate`, `format`, `migrate dev`, `migrate diff`, `migrate deploy`. Flags differ between versions, and one of them (`migrate diff --shadow-database-url` against a live database) destroys the database it points at |
+| `prisma-client-api` | auditing a new or changed query — filters, operators, `$transaction` semantics. Through a driver adapter, cite the adapter's installed source for what a transaction does: the skill describes the default engine, and an adapter can roll back less |
+
+<!-- nina:slot prisma.2 -->
+Neither skill covers a **caching or edge layer sitting on top of the client** — cache strategy,
+edge-client behaviour and the rule about never caching a read that authorizes a write belong to that
+layer's own integration doc, declared like any other integration. A skill does not replace it.
+
+<!-- nina:slot prisma.3 -->
+- **With Prisma, both offline.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`; it must pass. Then run `prisma migrate diff` in its **offline, file-only form** and read the generated SQL, not just the Prisma delta. Its flags changed in Prisma 7, so read the installed major (`prisma --version`) before writing the command:
+
+   ```
+   # Prisma 6. Compare the PREVIOUS schema against the working one — pure file-to-file, no database.
+   git show HEAD:{{DB_PKG}}/prisma/schema.prisma > /tmp/schema-head.prisma
+   pnpm --filter {{DB_PKG_NAME}} exec prisma migrate diff \
+     --from-schema-datamodel /tmp/schema-head.prisma \
+     --to-schema-datamodel prisma/schema.prisma \
+     --script
+   ```
+
+   From Prisma 7 the two flags are `--from-schema` and `--to-schema`, and the schema engine starts from the
+   datasource in `prisma.config.ts` even for this diff: with none there, it prints nothing and exits 0. For
+   SQLite a placeholder the diff never opens is enough, a `file:` URL under a gitignored directory; for any
+   other provider, find out what the diff opens before you give it one. Never a real database's URL. A first schema has nothing at `HEAD`: diff it `--from-empty`. Compare the output against the
+   hand-written `migration.sql` to confirm the declarative parts match.
+
+   ⚠️ **Do NOT reach for `--from-migrations`.** It looks like the natural choice and it is a trap:
+   Prisma refuses it without a shadow database (`--shadow-database-url`, or from Prisma 7 a
+   `shadowDatabaseUrl` in `prisma.config.ts`), which pushes you toward supplying a database URL — the exact move that destroys databases (below). The file-to-file form above answers the
+   same question with no database involved.
+
+   ⛔ **NEVER point `--shadow-database-url`, `--from-url`, `--to-url`, `--from-schema-datasource` — or, from Prisma 7, a `shadowDatabaseUrl` or the config datasource behind `--from-config-datasource` — at a real database, most of all not the one `{{SECRETS_LOCAL}}` names.** Prisma **executes** the entire migration history against whatever database those flags name, which **DESTROYS ALL DATA** in it. A shadow database must be a disposable, empty database and nothing else. It does not announce itself: the command completes with a reassuring "empty migration" result and no error, having already destroyed everything in the database it was pointed at. If the offline form above cannot answer your question, **STOP and report that to the orchestrator** instead of reaching for a database URL.
+
+<!-- nina:slot prisma.4 -->
+- **Where reads are cached through Prisma Accelerate,** every `findUnique` / `findMany` on a hot read path names its `cacheStrategy` (`ttl` / `swr`), and one that feeds a correctness-critical write names none.
+
+<!-- nina:slot prisma.5 -->
+- **On an edge runtime,** new Prisma code paths use the edge client of the installed major: `@prisma/client/edge` up to Prisma 6; from 7, the client the `prisma-client` generator writes with the platform's `runtime` set, imported from where it is generated — `@prisma/client/edge` fails there with `MODULE_NOT_FOUND`.
+
+<!-- nina:slot prisma.6 -->
+- Run a Prisma command that writes to a real database — `prisma migrate dev`, `migrate deploy`, `migrate reset`, `migrate resolve`, `db push`, `db execute`, `$executeRaw*` — or **any `prisma migrate diff` variant carrying a database URL**, which silently wipes the database it points at.

package/releases/0.46.0/surfaces/prisma/tree/.claude/agents/devops.md

@@ -0,0 +1,11 @@
+<!-- nina:slot prisma.1 -->
+- **`prisma-cli`** — before `migrate deploy` or any other Prisma CLI command against a real database.
+
+<!-- nina:slot prisma.2 -->
+- **Prisma migrations go out with `prisma migrate deploy`**, and nothing else changes a shared database's schema.
+
+<!-- nina:slot prisma.3 -->
+- Run `prisma migrate diff --shadow-database-url <url>` against any live database. It **executes** the migration history against that database, destroying everything in it, and reports success. Use a disposable shadow database or don't run it.
+
+<!-- nina:slot prisma.4 -->
+- Run `prisma migrate reset` against a shared database, ever.

package/releases/0.46.0/surfaces/prisma/tree/.claude/agents/implementer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.46.0/surfaces/prisma/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | a Prisma CLI command |

package/releases/0.46.0/surfaces/prisma/tree/.claude/agents/reviewer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.46.0/surfaces/prisma/tree/.claude/patterns.md

@@ -0,0 +1,15 @@
+<!-- nina:slot prisma.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot prisma.2 -->
+- Where Prisma reads are cached through Accelerate, `cacheStrategy` lives in `{{DB_PKG}}`: services do not add, strip, or override cache policies.
+
+<!-- nina:slot prisma.3 -->
+
+### Prisma
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- N+1 is solved with `include` / `select`, chosen deliberately.
+- Where reads are cached through Accelerate, every `findUnique` / `findMany` on a hot path defines its `cacheStrategy`, and no direct connection string is embedded in code.
+- Tests run a real Prisma client against a real database; the client is never mocked.

package/releases/0.46.0/surfaces/prisma/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot prisma.1 -->
+| Run any `prisma` CLI command (the database gate, devops, and the integration gate where there is one) | `prisma-cli` | flags differ between versions; `migrate diff --shadow-database-url` against a live DB wiped dev/staging once |
+
+<!-- nina:slot prisma.2 -->
+| Write or audit a Prisma query (architect, implementer, the database gate, reviewer) | `prisma-client-api` | filters, operators, `$transaction` semantics. a caching or edge layer on top of the client is **NOT covered** — its cache strategy belongs to that layer's own integration doc |

package/src/commands/check.mjs

@@ -9,7 +9,7 @@
  */
 
 import { readFile, readdir } from 'node:fs/promises';
-import { describeMove, HARNESS, interruptedMove, readProfile, surfacesIn } from '../paths.mjs';
+import { deferredWhy, describeMove, HARNESS, interruptedMove, readProfile, surfacesIn } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
 import { parseGraph, validateGraph } from '../graph.mjs';
 import { frontmatterFindings, installedSkills, modelFindings, toolFindings } from '../tools.mjs';
@@ -243,7 +243,7 @@ export async function check(argv, ctx) {
   const deferredUsed = new Set();
   let deferrable = false;
   const owe = (key, problem) => {
-    const why = typeof deferred[key] === 'string' ? deferred[key].trim() : '';
+    const why = deferredWhy(profile, key);
     if (why) {
       deferredUsed.add(key);
       notes.push(`deferred: ${key} — ${why}`);
@@ -298,7 +298,7 @@ export async function check(argv, ctx) {
   // one only to tailor it.
   const defaulted = await defaultedSlots(resolved.dir);
   const open = [...slots].filter((s) => !filled.has(s) && !defaulted.has(s));
-  const missing = open.filter((s) => !expected.has(s) && !(typeof deferred[s] === 'string' && deferred[s].trim()));
+  const missing = open.filter((s) => !expected.has(s) && !deferredWhy(profile, s));
   for (const s of open.filter((s) => !expected.has(s) && !missing.includes(s))) owe(s, `project slot ${s} has no fragment`);
   const awaited = open.filter((s) => expected.has(s));
   const orphan = [...filled].filter((s) => !slots.has(s));

package/src/commands/compose.mjs

@@ -17,7 +17,7 @@
  */
 
 import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
-import { HARNESS, layerRootFor, readProfile } from '../paths.mjs';
+import { HARNESS, deferredWhy, layerRootFor, readProfile } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -553,8 +553,8 @@ export async function composeProject(target, ctx, options = {}) {
     }
     // A name the project deferred, with its reason, reads as not decided: a stage that meets it asks
     // instead of guessing, and the raw placeholder it would otherwise read looks like an editing slip.
-    for (const [name, why] of Object.entries(profile.deferred ?? {})) {
-      if (typeof why === 'string' && why.trim() && NAME.test(name)) text = text.split(`{{${name}}}`).join(`[${name}: not decided yet]`);
+    for (const name of Object.keys(profile.deferred ?? {})) {
+      if (deferredWhy(profile, name) && NAME.test(name)) text = text.split(`{{${name}}}`).join(`[${name}: not decided yet]`);
     }
     // What is still a placeholder is owed: no default answers it, and the project has not declared it, or has
     // declared it null. Left raw, it reached a stage as `{{TENANT_KEY}}` — once inside a shell block it was told to
@@ -611,8 +611,12 @@ export async function compose(argv, ctx) {
   // A surface's own slot left empty is a bug in the harness, not the project's to fill, so drift mode
   // still reports it; only the project's slots are left to the declaration detector.
   const reported = driftOnly ? result.unfilled.filter((slot) => !/ project\.\d+$/.test(slot)) : result.unfilled;
-  const owed = reported.filter((slot) => !expected.has(slot));
+  // A project slot the profile defers, with its reason, is a decision not made yet, here as in `check`.
+  const { profile } = readProfile(target);
+  const deferred = reported.filter((slot) => !expected.has(slot) && deferredWhy(profile, slot));
+  const owed = reported.filter((slot) => !expected.has(slot) && !deferred.includes(slot));
   const awaited = reported.filter((slot) => expected.has(slot));
+  if (deferred.length > 0) console.log(`  ${deferred.length} slot(s) deferred in ${HARNESS}/profile.json — \`nina check\` says why each waits`);
   if (owed.length > 0) {
     console.log(`  ${owed.length} slot(s) have no fragment in a declared layer:`);
     for (const slot of owed.slice(0, 12)) console.log(`    ${slot}`);

package/src/paths.mjs

@@ -125,6 +125,21 @@ export function readProfile(target) {
   }
 }
 
+/**
+ * Why a profile defers a name — a vocabulary name, a document, or a project slot as `<path> <slot id>` — or
+ * `''` when it does not. A deferral with no reason counts for nothing: `check` says so, and every other reader
+ * treats the name as owed. `compose --check` once read the profile's deferrals not at all, and failed on six
+ * slots a new project had deferred while `check` was clean.
+ *
+ * @param {object | undefined} profile - The parsed profile.
+ * @param {string} key - The deferred name.
+ * @returns {string} The reason, trimmed; empty when the name is not deferred.
+ */
+export function deferredWhy(profile, key) {
+  const why = profile?.deferred?.[key];
+  return typeof why === 'string' ? why.trim() : '';
+}
+
 /**
  * Where a project's layers are read from.
  *