feat: stash-forge push command

Author: calvinbrewer

.changeset/config.json

@@ -7,5 +7,8 @@
   "access": "restricted",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": []
+  "ignore": [],
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  }
 }

.changeset/curvy-bushes-mix.md

@@ -0,0 +1,5 @@
+---
+"@cipherstash/stack": minor
+---
+
+Exposed a public method on the Encryption client to expose the build Encryption schema.

examples/basic/encrypt.ts

@@ -1,4 +1,5 @@
 import 'dotenv/config'
+
 import { Encryption, encryptedColumn, encryptedTable } from '@cipherstash/stack'
 
 export const users = encryptedTable('users', {

examples/basic/package.json

@@ -12,7 +12,8 @@
   "description": "",
   "dependencies": {
     "@cipherstash/stack": "workspace:*",
-    "dotenv": "^16.4.7"
+    "dotenv": "^16.6.1",
+    "pg": "8.13.1"
   },
   "devDependencies": {
     "@cipherstash/stack-forge": "workspace:*",

examples/basic/stash.config.ts

@@ -2,4 +2,5 @@ import { defineConfig } from '@cipherstash/stack-forge'
 
 export default defineConfig({
   databaseUrl: process.env.DATABASE_URL!,
+  client: './encrypt.ts',
 })

packages/stack-forge/README.md

@@ -30,6 +30,8 @@ bun add -D @cipherstash/stack-forge
 
 ## Quick Start
 
+You can install EQL in two ways: **direct install** (connects to the DB and runs the SQL) or **Drizzle migration** (generates a migration file; you run `drizzle-kit migrate` yourself). The steps below use the direct install path.
+
 ### 1. Create a config file
 
 Create `stash.config.ts` in your project root:
@@ -56,6 +58,10 @@ npx stash-forge install
 
 That's it. EQL is now installed in your database.
 
+If your encryption client lives elsewhere, set `client` in `stash.config.ts` (e.g. `client: './lib/encryption.ts'`). That path is used by `stash-forge push`.
+
+**Using Drizzle?** To install EQL via your migration pipeline instead, run `npx stash-forge install --drizzle`, then `npx drizzle-kit migrate`. See [install --drizzle](#install---drizzle) below.
+
 ---
 
 ## Configuration
@@ -68,9 +74,24 @@ import { defineConfig } from '@cipherstash/stack-forge'
 export default defineConfig({
   // Required: PostgreSQL connection string
   databaseUrl: process.env.DATABASE_URL!,
+
+  // Optional: path to your encryption client (default: './src/encryption/index.ts')
+  // Used by `stash-forge push` to load the encryption schema
+  client: './src/encryption/index.ts',
+
+  // Optional: CipherStash workspace and credentials (for future schema sync)
+  workspaceId: process.env.CS_WORKSPACE_ID,
+  clientAccessKey: process.env.CS_CLIENT_ACCESS_KEY,
 })
 ```
 
+| Option | Required | Description |
+|--------|----------|-------------|
+| `databaseUrl` | Yes | PostgreSQL connection string |
+| `client` | No | Path to encryption client file (default: `'./src/encryption/index.ts'`). Used by `push` to load the encryption schema. |
+| `workspaceId` | No | CipherStash workspace ID |
+| `clientAccessKey` | No | CipherStash client access key |
+
 The CLI automatically loads `.env` files before evaluating the config, so `process.env` references work out of the box.
 
 The config file is resolved by walking up from the current working directory, similar to how `tsconfig.json` resolution works.
@@ -97,6 +118,9 @@ npx stash-forge install [options]
 | `--force` | Reinstall even if EQL is already installed |
 | `--supabase` | Use Supabase-compatible install (excludes operator families + grants Supabase roles) |
 | `--exclude-operator-family` | Skip operator family creation (for non-superuser database roles) |
+| `--drizzle` | Generate a Drizzle migration instead of direct install |
+| `--name <value>` | Migration name when using `--drizzle` (default: `install-eql`) |
+| `--out <value>` | Drizzle output directory when using `--drizzle` (default: `drizzle`) |
 
 **Standard install:**
 
@@ -120,7 +144,57 @@ The `--supabase` flag:
 npx stash-forge install --dry-run
 ```
 
-### Permission Pre-checks
+#### `install --drizzle`
+
+If you use [Drizzle ORM](https://orm.drizzle.team/) and want EQL installation as part of your migration history, use the `--drizzle` flag. It creates a Drizzle migration file containing the EQL install SQL, then you run your normal Drizzle migrations to apply it.
+
+```bash
+npx stash-forge install --drizzle
+npx drizzle-kit migrate
+```
+
+**How it works:**
+
+1. Runs `drizzle-kit generate --custom --name=<name>` to create an empty migration.
+2. Downloads the EQL install script from the [EQL GitHub releases](https://github.com/cipherstash/encrypt-query-language/releases/latest).
+3. Writes the EQL SQL into the generated migration file.
+
+With a custom migration name or output directory:
+
+```bash
+npx stash-forge install --drizzle --name setup-eql --out ./migrations
+npx drizzle-kit migrate
+```
+
+You need `drizzle-kit` installed in your project (`npm install -D drizzle-kit`). The `--out` directory must match your Drizzle config (e.g. `drizzle.config.ts`).
+
+### `push`
+
+Load your encryption schema from the file specified by `client` in `stash.config.ts` and apply it to the database (or preview with `--dry-run`).
+
+```bash
+npx stash-forge push [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Load and validate the schema, then print it as JSON. No database changes. |
+
+**Push schema to the database:**
+
+```bash
+npx stash-forge push
+```
+
+This connects to Postgres, marks any existing rows in `eql_v2_configuration` as `inactive`, and inserts the current encrypt config as a new row with state `active`. Your runtime encryption (e.g. `@cipherstash/stack`) reads the active configuration from this table.
+
+**Preview your encryption schema without writing to the database:**
+
+```bash
+npx stash-forge push --dry-run
+```
+
+### Permission Pre-checks (install)
 
 Before installing, `stash-forge` verifies that the connected database role has the required permissions:
 
@@ -137,8 +211,7 @@ The following commands are defined but not yet implemented:
 | Command | Description |
 |---------|-------------|
 | `init` | Initialize CipherStash Forge in your project |
-| `push` | Push encryption schema to database |
-| `migrate` | Run pending EQL migrations |
+| `migrate` | Run pending encrypt config migrations |
 | `status` | Show EQL installation status |
 
 ---
@@ -205,11 +278,12 @@ export default defineConfig({
 
 ### `loadStashConfig`
 
-Finds and loads the nearest `stash.config.ts`, validates it with Zod, and returns the typed config:
+Finds and loads the nearest `stash.config.ts`, validates it with Zod, applies defaults (e.g. `client`), and returns the typed config:
 
 ```typescript
 import { loadStashConfig } from '@cipherstash/stack-forge'
 
 const config = await loadStashConfig()
-// config.databaseUrl is guaranteed to be a non-empty string
+// config.databaseUrl — guaranteed to be a non-empty string
+// config.client — path to encryption client (default: './src/encryption/index.ts')
 ```

packages/stack-forge/package.json

@@ -46,6 +46,7 @@
 		"zod": "3.24.2"
 	},
 	"devDependencies": {
+		"@cipherstash/stack": "workspace:*",
 		"@types/pg": "^8.11.11",
 		"tsup": "catalog:repo",
 		"tsx": "catalog:repo",

packages/stack-forge/src/bin/stash-forge.ts

@@ -2,45 +2,63 @@ import { config } from 'dotenv'
 config()
 
 import * as p from '@clack/prompts'
-import { installCommand } from '../commands/index.js'
+import { installCommand, pushCommand } from '../commands/index.js'
 
 const HELP = `
-CipherStash Forge v0.1.0
-
+CipherStash Forge
 Usage: stash-forge <command> [options]
 
 Commands:
   install    Install EQL extensions into your database
   init       Initialize CipherStash Forge in your project
   push       Push encryption schema to database
-  migrate    Run pending EQL migrations
+  migrate    Run pending encrypt config migrations
   status     Show EQL installation status
 
 Options:
   --help, -h       Show help
   --version, -v    Show version
   --force                    (install) Reinstall even if already installed
-  --dry-run                  (install) Show what would happen without making changes
+  --dry-run                  (install, push) Show what would happen without making changes
   --supabase                 (install) Use Supabase-compatible install and grant role permissions
+  --drizzle                  (install) Generate a Drizzle migration instead of direct install
   --exclude-operator-family  (install) Skip operator family creation (for non-superuser roles)
 `.trim()
 
-function parseArgs(argv: string[]) {
+interface ParsedArgs {
+  command: string | undefined
+  flags: Record<string, boolean>
+  values: Record<string, string>
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
   const args = argv.slice(2)
   const command = args[0]
   const flags: Record<string, boolean> = {}
+  const values: Record<string, string> = {}
 
-  for (const arg of args.slice(1)) {
+  const rest = args.slice(1)
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i]
     if (arg.startsWith('--')) {
-      flags[arg.slice(2)] = true
+      const key = arg.slice(2)
+      const nextArg = rest[i + 1]
+
+      // If the next argument exists and is not a flag, treat it as a value
+      if (nextArg !== undefined && !nextArg.startsWith('--')) {
+        values[key] = nextArg
+        i++ // Skip the value argument
+      } else {
+        flags[key] = true
+      }
     }
   }
 
-  return { command, flags }
+  return { command, flags, values }
 }
 
 async function main() {
-  const { command, flags } = parseArgs(process.argv)
+  const { command, flags, values } = parseArgs(process.argv)
 
   if (!command || flags.help || command === '--help' || command === '-h') {
     console.log(HELP)
@@ -59,10 +77,15 @@ async function main() {
         dryRun: flags['dry-run'],
         supabase: flags.supabase,
         excludeOperatorFamily: flags['exclude-operator-family'],
+        drizzle: flags.drizzle,
+        name: values.name,
+        out: values.out,
       })
       break
-    case 'init':
     case 'push':
+      await pushCommand({ dryRun: flags['dry-run'] })
+      break
+    case 'init':
     case 'migrate':
     case 'status':
       p.log.warn(`"stash-forge ${command}" is not yet implemented.`)

packages/stack-forge/src/commands/index.ts

@@ -1,5 +1,4 @@
 export { initCommand } from './init.js'
 export { installCommand } from './install.js'
-export { migrateCommand } from './migrate.js'
 export { pushCommand } from './push.js'
 export { statusCommand } from './status.js'