@sequenceholdings/orm 0.1.1 → 0.1.3

package/templates/orm-namespace/CLAUDE.md

@@ -0,0 +1,82 @@
+# Sequence ORM namespace
+
+This directory defines ONE Sequence ORM namespace: TypeScript table
+definitions with row-level policies, plus handwritten GraphQL operations.
+`seq-studio orm apply` pushes it to Atlas, which validates, compiles, and
+applies it. Your app never talks to Postgres — it calls the data plane with
+`{ op: <hash>, variables }` through the generated hooks/functions.
+
+## The loop
+
+1. Edit `schema/*.ts` (tables, columns, links, policies) and/or
+   `graphql/**/*.ts` (operations).
+2. `seq-studio orm generate` — refreshes `schema.graphql` + generated types.
+3. `seq-studio orm diff` — preview the migration for a schema change.
+4. `seq-studio orm apply -e <env>` — pushes. Schema changes write a reviewed
+   migration file into `migrations/`; operation-only edits take the fast path
+   (seconds, no migration).
+5. Commit `schema/`, `graphql/`, `schema.graphql`, `generated/`, and
+   `migrations/` together.
+
+## Hard rules
+
+- **Never hand-edit `migrations/`.** Migration files are generated by
+  `seq-studio orm apply`/`diff` and replayed verbatim by the server. Editing
+  or deleting a committed migration breaks the ledger.
+- **Never hand-edit `schema.graphql` or `generated/`.** Both are outputs of
+  `seq-studio orm generate`. To change the API surface, change `schema/*.ts`.
+- **No raw SQL.** There is no query escape hatch: every read/write is a
+  GraphQL document in `graphql/`, compiled at push time. For genuinely exotic
+  multi-statement writes, declare a table `action` — parameterized, gated,
+  audited.
+- **Every table needs row policies.** At minimum declare `read` plus either a
+  legacy `write` policy or split `insert` / `update` policies when create and
+  resolve are different actors. Policies are the row security boundary and are
+  compiled into every operation touching the table. There is no "no policy"
+  fallback — an unrestricted table must say so explicitly (`allow: true`
+  variant or a `true` policy) so the decision is reviewable.
+- **Exactly one `defineNamespace`** (in `sequence.config.ts`), and every
+  table module must call `defineTable` at import time — the CLI collects
+  registrations by importing your files.
+- **Renames need hints.** Renaming a column or table without
+  `.renamedFrom('old_name')` (column) / `renamedFrom` (table config) is a
+  DROP + CREATE — data loss. The diff will refuse ambiguous renames; add the
+  hint instead of forcing.
+- **Capabilities/roles are declared here, granted in the Permissions UI.**
+  Never hardcode user identities in policies; use `claim('sub')` /
+  `claim('org')` and grants.
+
+## Policy DSL quick reference
+
+```
+author_sub = claim('sub')                 -- row value vs caller claim
+org = claim('org') and status = 'open'    -- boolean algebra
+exists(deal, org = claim('org'))          -- traverse a declared link
+capability('deals-read')                  -- boolean grant check
+role('deal-manager')                      -- boolean role check
+```
+
+Variants widen access per grant (permissive union):
+
+```ts
+policies: {
+  read: {
+    default: "author_sub = claim('sub')",
+    variants: [
+      { when: "capability('deals-read')", policy: "org = claim('org')" },
+      { when: "role('deal-manager')", allow: true },
+    ],
+  },
+}
+```
+
+## GraphQL operations
+
+- Named operations only; one export per document; gate with
+  `@requires(capability: "…")` / `@requires(role: "…")`.
+- Dynamic filters are policy-bounded: `$where: <Table>BoolExp` /
+  `$orderBy` / whole-input write objects are validated against a
+  schema-derived whitelist and AND-ed with the table policy at runtime —
+  they can never widen access.
+- Joins follow declared links (`toOne` / `toMany` / `toPlatformUser`) — there
+  are no ad-hoc joins at query time. Declare the link, then select through it.

package/templates/orm-namespace/codegen.ts

@@ -0,0 +1,22 @@
+import type { CodegenConfig } from '@graphql-codegen/cli'
+
+/**
+ * graphql-codegen config. `seq-studio orm generate` writes ./schema.graphql
+ * from your table definitions, then runs this config when present — emitting
+ * typed Apollo hooks (`use<Name>Query`) and server functions (`db<Name>`)
+ * over the persisted-operation client.
+ *
+ * schema.graphql and the generated output are committed: reviews see the API
+ * surface change alongside the schema change that caused it.
+ */
+const config: CodegenConfig = {
+  schema: './schema.graphql',
+  documents: ['graphql/**/*.ts'],
+  generates: {
+    './generated/': {
+      preset: '@sequenceholdings/orm/codegen',
+    },
+  },
+}
+
+export default config

package/templates/orm-namespace/gitignore

@@ -0,0 +1,5 @@
+# Commit schema.graphql, migrations/, and generated/ — reviews should see
+# API-surface and DDL changes alongside the schema change that caused them.
+node_modules/
+*.log
+.DS_Store

package/templates/orm-namespace/graphql/example/queries.ts

@@ -0,0 +1,56 @@
+/**
+ * Handwritten GraphQL operations. `seq-studio orm apply` compiles every
+ * exported document at push time; the wire carries only `{ op: <hash>,
+ * variables }` — never query text, never SQL. Type names come from the
+ * generated `schema.graphql` (`seq-studio orm generate`).
+ *
+ * Gate an operation with `@requires(capability: "…")` or
+ * `@requires(role: "…")` — checked before execution, on top of the
+ * table policies that are always compiled in.
+ */
+
+export const GetOpenDeals = /* GraphQL */ `
+  query GetOpenDeals($status: DealStatus!) @requires(capability: "deals-read") {
+    deals(where: { status: { _eq: $status } }, orderBy: [{ createdAt: DESC }], limit: 20) {
+      id
+      title
+      amount
+      author {
+        name
+        email
+      }
+      comments(limit: 3, orderBy: [{ createdAt: DESC }]) {
+        id
+        body
+      }
+    }
+  }
+`
+
+/**
+ * Policy-bounded dynamic arguments (§4f): the filter tree is built by the
+ * caller at runtime, validated against the schema-derived whitelist, and
+ * always AND-ed with the table's read policy — clients can only narrow
+ * within policy-visible rows.
+ */
+export const SearchDeals = /* GraphQL */ `
+  query SearchDeals($where: DealBoolExp, $orderBy: [DealOrderBy!], $limit: Int)
+  @requires(capability: "deals-read") {
+    deals(where: $where, orderBy: $orderBy, limit: $limit) {
+      id
+      title
+      status
+      amount
+    }
+  }
+`
+
+export const AddComment = /* GraphQL */ `
+  mutation AddComment($dealId: uuid!, $body: String!) {
+    insertCommentsOne(object: { dealId: $dealId, body: $body }) {
+      id
+      body
+      createdAt
+    }
+  }
+`

package/templates/orm-namespace/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "my-namespace",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "validate": "seq-studio orm validate",
+    "generate": "seq-studio orm generate",
+    "diff": "seq-studio orm diff",
+    "apply": "seq-studio orm apply",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@apollo/client": "^3.11.0",
+    "@sequenceholdings/orm": "^2.0.0",
+    "graphql": "^16.11.0"
+  },
+  "devDependencies": {
+    "@graphql-codegen/cli": "^5.0.7",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/orm-namespace/schema/tables.ts

@@ -0,0 +1,71 @@
+import { defineEnum, defineTable, t, toMany, toOne, toPlatformUser } from '@sequenceholdings/orm'
+
+/**
+ * Tables are TypeScript, but they SERIALIZE to data — the server never runs
+ * this file. Property names are camelCase and become snake_case Postgres
+ * columns (`authorSub` → `author_sub`); pass a string to the builder to
+ * override (`t.text('legacy_name')`).
+ *
+ * Every table carries its own row-level policies. The policy DSL:
+ *   - `claim('sub')` / `claim('org')` — the caller's identity claims
+ *   - `capability('x')` / `role('y')` — boolean grants, resolved per caller
+ *   - `exists(link, <predicate>)` — traverse a declared link
+ *   - variants: `default` applies to everyone; each variant WIDENS access
+ *     when its `when` guard matches (permissive union — grants only ever
+ *     widen, never narrow).
+ */
+export const dealStatus = defineEnum('deal_status', ['open', 'won', 'lost'])
+
+export const deals = defineTable(
+  'deals',
+  {
+    id: t.uuid().primaryKey().default('gen_random_uuid()'),
+    title: t.text().notNull(),
+    status: t.enum(dealStatus).notNull().default('open'),
+    amount: t.numeric(),
+    org: t.text().notNull().description('Organization the deal belongs to'),
+    authorSub: t.text().notNull().description('Auth0 sub of the creator'),
+    createdAt: t.timestamptz().notNull().default('now()'),
+  },
+  {
+    description: 'Deals owned by their author, readable org-wide with the deals-read capability',
+    indexes: [{ columns: ['org'] }, { columns: ['authorSub'] }],
+    links: {
+      comments: toMany(() => comments, { on: 'dealId' }),
+      author: toPlatformUser({ on: 'authorSub' }),
+    },
+    policies: {
+      read: {
+        default: "author_sub = claim('sub')",
+        variants: [
+          { when: "capability('deals-read')", policy: "org = claim('org')" },
+          { when: "role('deal-manager')", allow: true },
+        ],
+      },
+      write: "author_sub = claim('sub')",
+    },
+  },
+)
+
+export const comments = defineTable(
+  'comments',
+  {
+    id: t.uuid().primaryKey().default('gen_random_uuid()'),
+    dealId: t.uuid().notNull(),
+    body: t.text().notNull(),
+    authorSub: t.text().notNull(),
+    createdAt: t.timestamptz().notNull().default('now()'),
+  },
+  {
+    description: 'Comments on deals — visibility follows the parent deal',
+    indexes: [{ columns: ['dealId'] }],
+    links: {
+      deal: toOne(() => deals, { on: 'dealId' }),
+      author: toPlatformUser({ on: 'authorSub' }),
+    },
+    policies: {
+      read: "exists(deal, org = claim('org'))",
+      write: "author_sub = claim('sub')",
+    },
+  },
+)

package/templates/orm-namespace/sequence.config.ts

@@ -0,0 +1,32 @@
+import { defineNamespace } from '@sequenceholdings/orm'
+
+/**
+ * The namespace config — exactly one per directory.
+ *
+ * Capabilities and roles are DECLARED here (verbatim custom-roles grammar);
+ * who HOLDS them is granted later in the Permissions UI (FGA), never in code.
+ * Table policies reference them with `capability('…')` / `role('…')`.
+ */
+export default defineNamespace({
+  // Rename me: the namespace becomes your Postgres schema (orm_<namespace>).
+  namespace: 'my_namespace',
+  description: 'Describe what this namespace stores and who uses it.',
+  capabilities: {
+    roles: {
+      definitions: {
+        'deal-manager': {
+          description: 'Full access to every deal in the namespace',
+          default: false,
+          inherits: [],
+          grants: ['deals-read'],
+        },
+      },
+      capabilities: {
+        'deals-read': {
+          description: 'Read all deals in the caller org (instead of author-only)',
+        },
+      },
+    },
+    uses: [],
+  },
+})

package/templates/orm-namespace/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["sequence.config.ts", "codegen.ts", "schema", "graphql", "generated"]
+}