grafeo-ogm 1.8.7 → 1.9.1

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 1.9.1 (2026-06-13) — 🩹 `grafeo generate` formatting DX
+
+> **A first-run papercut from the 1.9.0 CLI.** Prettier is a *dev* dependency (kept out of the runtime footprint on purpose), so a consumer who runs `grafeo generate` without prettier installed got a terse `Prettier formatting failed; output written without formatting.` — accurate, but unhelpful. The output was always valid TypeScript; only the message was poor. `1.9.1` makes that path friendly and honest.
+
+### 🩹 Actionable "formatting skipped" warning
+
+When prettier isn't available, the generator now detects the missing-module case specifically and emits: *"prettier is not installed — generated types were written unformatted. Run `npm i -D prettier` for formatted output, or set `generate.formatOutput: false` to silence this warning."* A genuine prettier *error* (as opposed to a missing install) now reports its actual detail instead of a generic string. The warning carries a dedicated `FORMATTING_SKIPPED` code (previously mislabeled `UNSUPPORTED_TYPE`).
+
+### 🔧 prettier declared as an optional peer dependency
+
+`prettier` is now listed under `peerDependencies` with `peerDependenciesMeta.prettier.optional = true`. This documents the relationship for tooling and package managers without auto-installing it — the runtime footprint is unchanged (still just `jiti`), and consumers who want formatted codegen opt in by installing prettier.
+
+### Tests
+
+Added coverage that forces the prettier-missing path and asserts the actionable `FORMATTING_SKIPPED` warning. Full suite green; lint, format, and type-check clean.
+
+---
+
+## 1.9.0 (2026-06-13) — 🚀 the `grafeo` CLI
+
+> **The first developer-facing command-line tool.** Until now grafeo-ogm was a library you imported; the schema-to-types step, the constraint/index provisioning, and seeding were all things you wired up by hand. `1.9.0` ships `grafeo` — a thin, lazy-loaded CLI over machinery the library already had. Three commands: `grafeo generate` (codegen, including a CI staleness gate), `grafeo db push` (declarative constraint/index sync against a live database), and `grafeo db seed` (idempotent project seeding). Config lives in a typed `grafeo.config.ts`. **The CLI adds exactly one runtime dependency (`jiti`), and importing the library doesn't pull it in.** No library API surface changed; existing consumers upgrade transparently.
+
+### ✨ `grafeo generate` — codegen with a CI staleness gate
+
+Wraps the existing `generateTypes()` so the type-emit step is no longer bespoke per project. Three modes:
+
+- **One-shot** (default) — read schema, emit the TypeScript file, exit.
+- **`--watch`** — re-emit on schema change via a debounced `fs.watch`, with a `--poll <ms>` fallback for filesystems where native watch events are unreliable (network mounts, some container bind-mounts).
+- **`--verify`** — emit into memory and byte-compare against the on-disk file. Writes **nothing**; exits `1` on drift. This is the CI gate: a build fails if a committed types file has fallen behind its schema, the same way a `git diff --exit-code` after codegen would, but without a working-tree mutation.
+
+### ✨ `grafeo db push` — declarative constraint & index sync
+
+Diffs the constraints and indexes **declared in your SDL** against what's actually live in the database, then reconciles them. Declarations are derived from directives: `@id`/`@unique` → unique constraints, `@fulltext` → fulltext indexes, `@vector` → vector indexes. The live state is read via `SHOW CONSTRAINTS` / `SHOW INDEXES`.
+
+The planner sorts everything into four buckets and prints them before touching anything:
+
+- **create** — declared in SDL, missing in the DB.
+- **in-sync** — declared and already present.
+- **orphans** — managed-looking artifacts present in the DB but no longer declared in SDL (candidates for removal).
+- **unmanaged** — DB artifacts outside grafeo's naming convention, left strictly untouched (hand-rolled DBA constraints, other tools' indexes).
+
+`push` is **additive-by-default and idempotent** — re-running it is a no-op once in sync, and it never drops anything on the happy path. Destructive orphan drops are gated behind `--force-drop` **and** `--yes` (or an interactive confirmation); `--dry-run` prints the plan and exits without executing. Orphan detection is scoped by naming convention, so DBA-created constraints never even enter the orphan bucket — they land in *unmanaged* and are left alone.
+
+### ✨ `grafeo db seed` — idempotent project seeding
+
+Runs your project's seed script — resolved as config `seed` → `./seed.ts` → `./seed.js` — handing it a fully constructed, **already-connected** OGM so the script doesn't re-derive connection details. The driver is **always closed**, including when the seed script throws, so a failed seed never leaks a live connection. The docs promote `upsert` for seed data specifically because it's idempotent: re-seeding a populated database converges instead of duplicating.
+
+### ✨ Config: `grafeo.config.ts` and connection precedence
+
+Configuration loads from `grafeo.config.ts` / `.js` / `.json`, transpiled on the fly via `jiti` (the single new runtime dependency). A `defineConfig` export gives you full type inference on the config object. Connection settings resolve by precedence: **explicit flag > config file > `NEO4J_*` environment variables**.
+
+One deliberate omission: **the password is never accepted as a CLI flag.** A password passed on the command line leaks into process listings (`ps`), shell history, and CI logs — so it must come from config or the environment. This is a security constraint, not an oversight.
+
+### Lazy loading — `generate` doesn't touch the driver
+
+Commands are loaded lazily so the cheap path stays cheap. `grafeo generate` does pure codegen and **never loads `neo4j-driver`** — only `db push` / `db seed` pull in the driver, and only when invoked. Symmetrically, importing the library from application code does **not** pull in `jiti`; the config loader lives behind the CLI entry point. No bloat leaks in either direction.
+
+### Internal — single source of truth for constraint/index Cypher (no behavior change)
+
+The Cypher that creates constraints and indexes was previously emitted inside `OGM.assertIndexesAndConstraints()`. `db push`'s planner needs the *same* statements to diff against the live DB, so that generation was extracted into one module — `src/schema/index-statements.ts` — now shared by both `assertIndexesAndConstraints()` and the planner. The emitted statement text and ordering are **byte-identical** to 1.8.7; this is a pure refactor with no behavioral effect on existing OGM users.
+
+### SECURITY — orphan `DROP CONSTRAINT` re-validates the introspected name
+
+The orphan-drop path takes a constraint *name read back from the live database* and puts it into a `DROP CONSTRAINT` statement. Constraint names are normally grafeo-generated and safe, but a live database can carry a name with unsafe characters (created by another tool, or maliciously). Before any introspected name enters Cypher, it is now re-validated through `assertSafeIdentifier`. A name that fails validation is **demoted to *unmanaged*** — it is never dropped, and the destructive path never runs against an untrusted identifier. Defense in depth: the drop path treats DB-sourced names with the same suspicion as user input.
+
+### Minor — NLS audit metadata version bump
+
+NLS audit metadata now emits `ogmPolicySetVersion: "1.7.0"`, dropping the stale `-beta.0` pre-release suffix it had been carrying. The policy format reached GA in 1.7.0 and is unchanged — this only corrects the reported version string. If you assert on the exact audit-metadata value, update your expectation from `1.7.0-beta.0` to `1.7.0`.
+
+### Tests
+
+New CLI coverage for all three commands and the config loader: `generate` one-shot/`--watch`/`--verify`-drift, the four-bucket `db push` planner with additive/idempotent/`--dry-run`/`--force-drop` paths and the unsafe-name demotion, `db seed` driver-always-closed-on-failure, and connection precedence. The `index-statements.ts` extraction is pinned by byte-identical statement assertions against the prior `assertIndexesAndConstraints()` output. Full suite green; lint, format, and type-check clean.
+
+---
+
 ## 1.8.7 (2026-06-12) — 🚨 SECURITY + correctness
 
 > **Three HIGH correctness bugs, two subgraph guards, and three security hardenings** from the post-1.8.6 comprehensive audit. Two of the three HIGH bugs are "fixed one site, missed the sibling" regressions of earlier fixes (v1.8.1 and v1.8.3) — sibling-site sweeps are now part of the fix checklist. Upgrade if you use `withContext`, nested relationship updates, union relationship filters, write restrictives, or subgraph operations.

package/README.md

@@ -21,6 +21,7 @@ Define your graph model once in `.graphql` and get fully typed CRUD operations,
 - [Why grafeo-ogm?](#why-grafeo-ogm)
 - [Common Use Cases](#common-use-cases)
 - [Quick Start](#quick-start)
+- [CLI](#cli)
 - [Features Overview](#features-overview)
 - [Schema Definition](#schema-definition)
 - [Query API](#query-api)
@@ -151,7 +152,15 @@ type Category @node {
 }
 ```
 
-### 2. Initialize the OGM
+### 2. Generate types (recommended)
+
+```bash
+npx grafeo generate
+```
+
+This wraps `generateTypes()` to emit typed models from your SDL — wire them in with `new OGM<ModelMap>(...)` for full inference. See the [CLI](#cli) and [Type Generation](#type-generation) sections. You can skip this and run the OGM untyped, but you forfeit compile-time safety.
+
+### 3. Initialize the OGM
 
 ```typescript
 import { OGM } from 'grafeo-ogm';
@@ -167,7 +176,7 @@ const typeDefs = fs.readFileSync('./schema.graphql', 'utf-8');
 const ogm = new OGM({ typeDefs, driver });
 ```
 
-### 3. Basic CRUD
+### 4. Basic CRUD
 
 ```typescript
 const Book = ogm.model('Book');
@@ -201,7 +210,7 @@ await Book.update({
 await Book.delete({ where: { isbn: '978-1491930892' } });
 ```
 
-### 4. Transactions
+### 5. Transactions
 
 ```typescript
 await ogm.$transaction(async (ctx) => {
@@ -213,21 +222,118 @@ await ogm.$transaction(async (ctx) => {
 
 ---
 
-## Beta features
+## CLI
+
+grafeo-ogm ships a `grafeo` binary (installed with the package — no global install needed). Run it with `npx grafeo <command>`. The CLI is plumbing over the same library machinery you can call programmatically: `generate` wraps `generateTypes()`, and `db push` reuses the constraint/index logic behind `assertIndexesAndConstraints()`.
+
+| Command | Purpose |
+|---|---|
+| `grafeo generate` | Generate TypeScript types from your SDL — one-shot, `--watch`, or `--verify` CI gate |
+| `grafeo db push` | Diff SDL-declared constraints/indexes against the live database and apply them |
+| `grafeo db seed` | Run your seed script with a constructed, connected OGM |
+
+### Configuration
+
+All commands read `grafeo.config.ts` (or `.js` / `.json`) from the working directory — first found wins. Command-line flags override config values. `defineConfig` gives full type inference:
+
+```typescript
+// grafeo.config.ts
+import { defineConfig } from 'grafeo-ogm';
+
+export default defineConfig({
+  schema: './schema.graphql',          // default: ./schema.graphql
+  out: './src/generated/ogm-types.ts', // default: ./grafeo.generated.ts
+  // generate: forwarded to generateTypes(). Set packageName ONLY if you
+  // installed grafeo-ogm under an npm alias, e.g. { packageName: '@myorg/ogm' }
+  database: {
+    uri: process.env.NEO4J_URI,
+    username: process.env.NEO4J_USERNAME,
+    // password: from config or NEO4J_PASSWORD — never a CLI flag (see below)
+  },
+  seed: './scripts/seed.ts',
+  vectorIndexes: {
+    // @vector SDL carries no dimensions; db push reads them here, keyed by index name
+    BookEmbedding: { dimensions: 1536, similarity: 'cosine' },
+  },
+});
+```
+
+**Database connection** resolves per setting in precedence order: CLI flag (`--uri`, `--username`, `--database`) > config `database` block > environment (`NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `NEO4J_DATABASE`). The **password is never accepted as a CLI flag** — argv leaks through process listings and shell history, so it must come from `NEO4J_PASSWORD` or the config file.
+
+> **Config and seed files run as trusted code.** `grafeo.config.ts` and your seed script are executed in-process (via [jiti](https://github.com/unjs/jiti)) with your database credentials — the same trust model as Prisma/Drizzle. Only run `grafeo` in a directory whose config and seed files you control.
+
+### `grafeo generate`
+
+Compiles your SDL to TypeScript types (wraps `generateTypes()` — see [Type Generation](#type-generation) for the programmatic API and the full option list).
+
+```bash
+npx grafeo generate          # one-shot
+npx grafeo generate --watch  # regenerate on schema change
+npx grafeo generate --verify # CI gate: exit 1 if the file on disk is stale
+```
+
+| Flag | Description |
+|---|---|
+| `--schema <path>` | SDL path (overrides config; default `./schema.graphql`) |
+| `--out <path>` | Output path (default `./grafeo.generated.ts`) |
+| `--watch` | Debounced regeneration on change; a failed parse prints the error and keeps watching |
+| `--verify` | Generate in memory, byte-compare against the file on disk, write nothing, exit 1 on drift |
+| `--poll <ms>` | Use polling instead of `fs.watch` (fallback where native watching misfires) |
+
+`--verify` is the CI staleness gate: commit your generated types, then run `grafeo generate --verify` in CI to fail the build if the schema changed without a regeneration.
+
+### `grafeo db push`
+
+Synchronizes the **constraints and indexes** your SDL declares (`@id`/`@unique` → unique constraints, `@fulltext` → fulltext indexes, `@vector` → vector indexes) with the live database. Constraints and indexes only — **not data**. (`db push` is deliberately scoped; use a dedicated migration tool for data.)
+
+```bash
+npx grafeo db push --dry-run          # preview the plan — DO THIS FIRST
+npx grafeo db push                    # apply (additive: creates only what's missing)
+npx grafeo db push --force-drop --yes # also drop orphaned grafeo-managed items
+```
+
+`db push` introspects `SHOW CONSTRAINTS` / `SHOW INDEXES`, diffs against your SDL, and prints a plan in four buckets:
 
-The current beta release exposes one new feature behind opt-in config:
+- **create** — declared in SDL, missing in the database
+- **in sync** — already present
+- **orphans** — grafeo-named (`{Label}_{prop}_unique`) constraints no longer in your SDL; **reported and kept** unless you pass `--force-drop`
+- **unmanaged** — constraints/indexes that don't follow grafeo's naming convention (hand-created DBA indexes, etc.); **never touched, never counted as drift**
 
-- **Node-Level Security (NLS)** — a Postgres-RLS-style filter layer that compiles into the existing WHERE pipeline. See **[Advanced Features → Node-Level Security (Beta)](#node-level-security-beta)**.
+It is **additive by default** and **idempotent** — a second run with no schema change is a no-op. Dropping orphans is destructive and gated: `--force-drop` lists the exact drops (shown in `--dry-run` too) and requires interactive confirmation, or `--yes` in non-interactive sessions like CI.
 
-The beta is purely additive: an OGM constructed without the new `policies` option emits **byte-identical Cypher** to v1.6.0. Install with:
+| Flag | Description |
+|---|---|
+| `--dry-run` | Print the full plan (including the exact Cypher, drops included) and exit without writing |
+| `--force-drop` | Permit dropping orphaned grafeo-managed constraints/indexes |
+| `--yes` | Confirm destructive drops non-interactively (required with `--force-drop` in CI) |
+| `--schema <path>`, `--uri`, `--username`, `--database` | Schema path and connection overrides |
+
+> **Vector indexes** declare no dimensions in the SDL (the `@vector` directive only names the index and its embedding property), but Neo4j requires them at creation time. Supply them in `vectorIndexes` (keyed by index name) in your config. A `@vector` index without configured dimensions is reported and skipped — never silently created or dropped.
+
+### `grafeo db seed`
+
+Runs your seed script with a constructed, connected `OGM`. It resolves the entry point from config `seed`, then `./seed.ts`, then `./seed.js`. The module's default export receives the OGM; the CLI awaits it and **always closes the driver**, even if the seed throws.
+
+```typescript
+// seed.ts
+import type { OGM } from 'grafeo-ogm';
+
+export default async function seed(ogm: OGM) {
+  const Book = ogm.model('Book');
+  // Prefer upsert over create so repeated seeds converge instead of duplicating data.
+  await Book.upsert({
+    where: { id: '1' },
+    create: { id: '1', title: 'Dune' },
+    update: { title: 'Dune' },
+  });
+}
+```
 
 ```bash
-npm install grafeo-ogm@beta
-# or
-pnpm add grafeo-ogm@beta
+npx grafeo db seed
 ```
 
-The shape of the public API is settled, but the beta window is for collecting integration feedback. Minor adjustments may land before `1.7.0` final.
+grafeo does not enforce idempotency — use `upsert` so re-running the seed is safe. Connection and schema resolve exactly as for `db push`.
 
 ---
 
@@ -834,7 +940,7 @@ const deleteResult = await deleteSubgraph(
 
 ### Computed Fields with @cypher
 
-The `@cypher` directive declares a field whose value is produced by a custom Cypher statement at query time. As of v1.6.0, scalar `@cypher` fields are resolved in three scopes — `select` / `selectionSet`, `where`, and `options.sort` — so you can project, filter, and order by them just like stored properties. Pre-1.6.0, references in `select` and `where` silently returned `NULL`.
+The `@cypher` directive declares a field whose value is produced by a custom Cypher statement at query time. Scalar `@cypher` fields are resolved in three scopes — `select` / `selectionSet`, `where`, and `options.sort` — so you can project, filter, and order by them just like stored properties.
 
 #### Declaration
 
@@ -938,11 +1044,9 @@ These are not OGM bugs — they are Cypher-language constraints. Pattern compreh
 
 Each scope (`where`, `select`, sort) emits its own `CALL { WITH n; WITH n AS this; <statement> }` block per `@cypher` field reference. A query that references the same `@cypher` field in all three scopes emits three `CALL` blocks. This is functionally correct and parameter-isolated, but worth knowing if your statement is expensive (multi-hop traversals, aggregations over large fan-outs). For frequently-accessed computed values, consider materializing as a stored property updated on write instead.
 
-### Node-Level Security (Beta)
-
-> **Beta — install with `npm install grafeo-ogm@beta`.**
+### Node-Level Security
 
-Node-Level Security (NLS) is a per-request filter layer that compiles into the existing WHERE pipeline. Policies return `<Node>Where` partials, so every operator, quantifier, connection filter, and nested traversal already supported by `WhereCompiler` is automatically available inside policies — no new DSL.
+Node-Level Security (NLS) is a per-request filter layer that compiles into the existing WHERE pipeline. It is opt-in: an OGM constructed without the `policies` option emits byte-identical Cypher to a no-policy OGM. Policies return `<Node>Where` partials, so every operator, quantifier, connection filter, and nested traversal already supported by `WhereCompiler` is automatically available inside policies — no new DSL.
 
 #### Declaration
 
@@ -1083,7 +1187,7 @@ When `policies` is configured, every OGM-emitted query attaches transaction meta
 
 ```typescript
 {
-  ogmPolicySetVersion: '1.7.0-beta.0',
+  ogmPolicySetVersion: '1.7.0',
   ctxFingerprint: '<sha256 of sorted ctx KEYS — never values>',
   modelType: 'Book',
   operation: 'read',
@@ -1094,14 +1198,13 @@ When `policies` is configured, every OGM-emitted query attaches transaction meta
 
 Disable via `policyDefaults: { auditMetadata: false }`. The fingerprint is intentionally key-only — no ctx values are leaked.
 
-#### Beta limits
+#### Limitations
 
 - **`@cypher` scalar fields inside a policy `where`-partial throw when the policy is injected into nested-selection enforcement.** Refactor the policy to use stored properties or a relationship traversal.
-- **`upsert`** evaluates create- and update-side policies at the application layer (MERGE has no WHERE). Documented limit; full MERGE-aware enforcement is deferred to v1.7.1.
-- **Restrictives are split into read-side and write-side flavors.** A restrictive's `operations` array determines which `when` signature applies. Read-side ops (`read|delete|aggregate|count`) → `when(ctx)` returns a where-partial or boolean. Write-side ops (`create|update`) → `when(ctx, input)` returns a boolean only. Mixed arrays (e.g. `['read', 'create']`) are rejected at construction time — split into two restrictives. Each flavor is invoked exactly once per query (read-side at compile, write-side at the application layer); the dual-invocation contract bug from earlier beta iterations is fixed. Use `isReadRestrictive` / `isWriteRestrictive` if you need to inspect a policy at runtime.
+- **`upsert`** evaluates create- and update-side policies at the application layer (MERGE has no WHERE). Documented limit; full MERGE-aware enforcement is not yet implemented.
+- **Restrictives are split into read-side and write-side flavors.** A restrictive's `operations` array determines which `when` signature applies. Read-side ops (`read|delete|aggregate|count`) → `when(ctx)` returns a where-partial or boolean. Write-side ops (`create|update`) → `when(ctx, input)` returns a boolean only. Mixed arrays (e.g. `['read', 'create']`) are rejected at construction time — split into two restrictives. Each flavor is invoked exactly once per query (read-side at compile, write-side at the application layer). Use `isReadRestrictive` / `isWriteRestrictive` if you need to inspect a policy at runtime.
 - **InterfaceModel CASE-per-label fallback.** Implementers without a registered policy fall back to interface-level enforcement on their branch. The OGM emits a `logger.warn` at construction time when an interface has policies and one of its implementers does not — silence the warning by registering an explicit policy on each implementer.
-- **AsyncLocalStorage** opt-in is deferred to v1.7.1. Beta is explicit `withContext()` only — create one wrapper per request, discard after.
-- **Live Neo4j integration tests are not part of the beta.** Mock-driver coverage is extensive but a real-DB suite is a `1.7.0` final blocker.
+- **No AsyncLocalStorage integration.** Context is supplied via explicit `withContext()` only — create one wrapper per request, discard after.
 
 ### Raw Cypher
 
@@ -1221,7 +1324,9 @@ type Article @node @vector(indexes: [
 
 ### Creating the index in Neo4j
 
-grafeo-ogm does **not** create vector indexes for you in this release. Run the `CREATE VECTOR INDEX` Cypher yourself as part of your migration:
+The `grafeo db push` CLI creates `@vector` indexes for you — the directive carries no dimensions, so supply them in your config's `vectorIndexes` map (keyed by index name) and `db push` issues the `CREATE VECTOR INDEX`. See the [CLI → `grafeo db push`](#grafeo-db-push) section. The runtime `assertIndexesAndConstraints()` does **not** create vector indexes (only fulltext indexes and unique constraints).
+
+You can also run the Cypher yourself as part of a migration:
 
 ```cypher
 CREATE VECTOR INDEX article_content_idx FOR (n:Article) ON n.embedding
@@ -1323,7 +1428,7 @@ The following were intentionally left out of this release:
 - **`@embedded(from:, using:)` auto-write directive** — automatic embedding on create / update. Requires a pluggable embedder port and peer-dependency adapters.
 - **Third-party embedder SDKs** (`grafeo-ogm/embedders/openai`, etc.) — tracked for a future release with optional peer dependencies.
 - **Relationship-level `@vector` indexes** — the current Neo4j / official spec only supports node vector indexes.
-- **Automatic index creation via `assertIndexesAndConstraints`** — you must run `CREATE VECTOR INDEX` yourself.
+- **Vector index creation via the runtime `assertIndexesAndConstraints`** — that method covers fulltext indexes and unique constraints only. Create vector indexes with the `grafeo db push` CLI (see [CLI](#cli)) or run `CREATE VECTOR INDEX` yourself.
 
 ---
 
@@ -1588,7 +1693,7 @@ Pure query builders (e.g. `cypher-query-builder`) help you compose Cypher fragme
 
 ### Is grafeo-ogm production-ready?
 
-Yes. The library has 1,093 unit tests covering compilers, mutations, fulltext, transactions, security, scalar type mapping, and edge cases. It targets Neo4j 5.x and follows semver — see [CHANGELOG.md](CHANGELOG.md).
+Yes. The library has over 1,400 unit tests covering compilers, mutations, fulltext, transactions, security, scalar type mapping, the CLI, and edge cases. It targets Neo4j 5.x and follows semver — see [CHANGELOG.md](CHANGELOG.md).
 
 ### Does grafeo-ogm work with Neo4j Aura?
 
@@ -1620,7 +1725,7 @@ Negligible. grafeo-ogm compiles each query once per shape (selection sets are ca
 
 ### Is there a CLI / migration tool / studio?
 
-Not yet. The library focuses on the runtime API and type generation. Schema migrations are intentionally out of scope — Neo4j's labels and properties are flexible enough that you typically migrate via Cypher scripts (`MATCH (n:OldLabel) SET n:NewLabel REMOVE n:OldLabel`) which you can run via `ogm.$executeRaw(...)`.
+There is a CLI — the `grafeo` binary ships with the package (`grafeo generate`, `grafeo db push`, `grafeo db seed`). See the [CLI](#cli) section. There is no studio. Data migrations are intentionally out of scope: `db push` syncs SDL-declared constraints and indexes only, never data. Neo4j's labels and properties are flexible enough that you typically migrate data via Cypher scripts (`MATCH (n:OldLabel) SET n:NewLabel REMOVE n:OldLabel`) which you can run via `ogm.$executeRaw(...)`.
 
 ### How do I report a bug or request a feature?
 

package/dist/cjs/cli/commands/db-push.d.ts

@@ -0,0 +1,3 @@
+import type { CliIO } from '../types';
+export declare function runDbPush(argv: string[], io: CliIO): Promise<number>;
+//# sourceMappingURL=db-push.d.ts.map

package/dist/cjs/cli/commands/db-push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-push.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/db-push.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AA+ItC,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAgE1E"}

package/dist/cjs/cli/commands/db-push.js

@@ -0,0 +1,197 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDbPush = runDbPush;
+const fs = __importStar(require("node:fs"));
+const node_util_1 = require("node:util");
+const parser_1 = require("../../schema/parser");
+const config_1 = require("../config");
+const driver_1 = require("../driver");
+const errors_1 = require("../errors");
+const introspect_1 = require("../introspect");
+const push_planner_1 = require("../push-planner");
+function parseDbPushFlags(argv) {
+    try {
+        const { values } = (0, node_util_1.parseArgs)({
+            args: argv,
+            options: {
+                schema: { type: 'string' },
+                uri: { type: 'string' },
+                username: { type: 'string' },
+                database: { type: 'string' },
+                'dry-run': { type: 'boolean' },
+                'force-drop': { type: 'boolean' },
+                yes: { type: 'boolean' },
+                debug: { type: 'boolean' },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        return values;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new errors_1.CliError(`db push: ${message}`);
+    }
+}
+/**
+ * Print the FULL diff — including the destructive part. Under `--force-drop`
+ * the orphan section shows the exact drop Cypher; otherwise it reports the
+ * orphans as kept. Rendering the drops here (not in the confirmation step) is
+ * what makes `--dry-run --force-drop` preview the drops instead of hiding
+ * them — dry-run is exactly when you need to see what would be removed.
+ */
+function renderPlan(plan, io, willDrop) {
+    if (plan.create.length === 0)
+        if (plan.orphans.length === 0)
+            // Only claim a clean "in sync" when there is genuinely nothing to do —
+            // outstanding orphans mean the schema is not in sync.
+            io.out('✓ No changes — constraints and indexes are in sync');
+        else
+            io.out('No constraints or indexes to create.');
+    else {
+        io.out(`Plan — ${plan.create.length} to create, ${plan.inSync.length} in sync:`);
+        for (const statement of plan.create) {
+            io.out(`  + ${statement.name}`);
+            io.out(`      ${statement.cypher}`);
+        }
+    }
+    if (plan.orphans.length > 0)
+        if (willDrop) {
+            // "eligible to drop" — this is the plan; consent is resolved afterward.
+            io.out(`Orphans — ${plan.orphans.length} eligible to drop (--force-drop):`);
+            for (const orphan of plan.orphans)
+                io.out(`  - ${orphan.dropCypher}`);
+        }
+        else {
+            io.out(`Orphans — ${plan.orphans.length} kept (use --force-drop to remove):`);
+            for (const orphan of plan.orphans)
+                io.out(`  - ${orphan.name}`);
+        }
+    if (plan.unmanaged.length > 0)
+        io.out(`Unmanaged — ${plan.unmanaged.length} ignored: ${plan.unmanaged.join(', ')}`);
+}
+async function resolveDropConsent(plan, io, yes) {
+    if (yes)
+        return 'granted';
+    if (io.interactive && io.confirm)
+        // Strict `=== true`: only an explicit boolean true consents, so a
+        // misbehaving embedder returning a truthy non-boolean can't authorize a drop.
+        return (await io.confirm(`Drop the ${plan.orphans.length} item(s) listed above?`)) === true
+            ? 'granted'
+            : 'declined';
+    return 'blocked';
+}
+async function applyCreates(driver, database, plan, io) {
+    if (plan.create.length === 0)
+        return;
+    const session = driver.session(database ? { database } : undefined);
+    try {
+        for (const statement of plan.create) {
+            await session.run(statement.cypher);
+            io.out(`✓ created ${statement.name}`);
+        }
+    }
+    finally {
+        await session.close();
+    }
+}
+async function applyDrops(driver, database, plan, io) {
+    if (plan.orphans.length === 0)
+        return;
+    const session = driver.session(database ? { database } : undefined);
+    try {
+        for (const orphan of plan.orphans) {
+            await session.run(orphan.dropCypher);
+            io.out(`✓ dropped ${orphan.name}`);
+        }
+    }
+    finally {
+        await session.close();
+    }
+}
+async function runDbPush(argv, io) {
+    const flags = parseDbPushFlags(argv);
+    const { config } = await (0, config_1.loadConfigFile)(io.cwd);
+    const schemaPath = (0, config_1.resolveSchemaPath)(flags, config, io.cwd);
+    const typeDefs = fs.readFileSync(schemaPath, 'utf-8');
+    const schema = (0, parser_1.parseSchema)(typeDefs);
+    const connection = (0, config_1.resolveConnection)(flags, config, io.env);
+    // GrafeoVectorIndexConfig is structurally a VectorIndexCreationConfig.
+    const vectorConfig = config.vectorIndexes;
+    const dryRun = flags['dry-run'] === true;
+    const forceDrop = flags['force-drop'] === true;
+    const driver = (0, driver_1.createDriver)(io, connection);
+    try {
+        const live = await (0, introspect_1.fetchLiveSchema)(driver, connection.database);
+        const plan = (0, push_planner_1.planSchemaSync)(schema, live, vectorConfig);
+        const willDrop = forceDrop && plan.orphans.length > 0;
+        renderPlan(plan, io, willDrop);
+        // `@vector` indexes without dimensions are reported, never silently
+        // skipped, and never block the rest of the plan.
+        for (const needs of plan.needsConfig)
+            io.err(`warning: vector index "${needs.indexName}" ` +
+                `(${needs.typeName}.${needs.embeddingProperty}) skipped — set ` +
+                `vectorIndexes['${needs.indexName}'].dimensions in grafeo.config.ts to create it`);
+        // Nothing to create and nothing to drop → no writes (idempotent re-run).
+        if (plan.create.length === 0 && !willDrop)
+            return 0;
+        if (dryRun) {
+            io.out('');
+            io.out('Dry run — no changes applied.');
+            return 0;
+        }
+        // Resolve drop consent FIRST, so a hard block (non-interactive, no --yes)
+        // aborts cleanly without having applied anything. An interactive decline,
+        // by contrast, still lets the additive creates proceed.
+        let consent;
+        if (willDrop) {
+            consent = await resolveDropConsent(plan, io, flags.yes === true);
+            if (consent === 'blocked')
+                throw new errors_1.CliError('Destructive changes (--force-drop) require --yes in a non-interactive session.');
+        }
+        // Additive creates are never gated.
+        await applyCreates(driver, connection.database, plan, io);
+        if (consent === 'granted')
+            await applyDrops(driver, connection.database, plan, io);
+        else if (consent === 'declined')
+            io.out('Drop declined — orphans kept.');
+        return 0;
+    }
+    finally {
+        await driver.close();
+    }
+}
+//# sourceMappingURL=db-push.js.map

package/dist/cjs/cli/commands/db-push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-push.js","sourceRoot":"","sources":["../../../../src/cli/commands/db-push.ts"],"names":[],"mappings":"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"}

package/dist/cjs/cli/commands/db-seed.d.ts

@@ -0,0 +1,3 @@
+import type { CliIO } from '../types';
+export declare function runDbSeed(argv: string[], io: CliIO): Promise<number>;
+//# sourceMappingURL=db-seed.d.ts.map

package/dist/cjs/cli/commands/db-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-seed.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/db-seed.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,UAAU,CAAC;AAwGpD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CA+B1E"}