cipherstash · auxesis · May 4, 2026 · May 4, 2026 · May 4, 2026 · May 4, 2026
@@ -0,0 +1,8 @@
+---
+"@cipherstash/cli": patch
+"@cipherstash/wizard": patch
+"@cipherstash/protect": patch
+"@cipherstash/drizzle": patch
+---
+
+Render every user-facing CLI string and execute every shell-out under the detected package manager (`npx` / `bunx` / `pnpm dlx` / `yarn dlx`), completing the work started in #379. Affected surfaces: `@cipherstash/cli` top-level + `auth` + `env` help, `db install` Drizzle migration steps, `db migrate` not-implemented warning, the Supabase migration SQL header, the Supabase status fallback exec, the `@cipherstash/protect` `stash` Stricli help (set/get/list/delete), the `@cipherstash/wizard` usage line and agent command allowlist, and the `@cipherstash/drizzle` `generate-eql-migration` help + drizzle-kit invocation. A new `pnpm run lint:runners` lint runs in CI and fails on any reintroduction of a hardcoded runner literal.
@@ -31,6 +31,12 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Lint — no hardcoded package-manager runners
+        run: pnpm run lint:runners
+
+      - name: Test — lint script self-tests
+        run: pnpm run test:scripts
+
       - name: Create .env file in ./packages/protect/
         run: |
           touch ./packages/protect/.env

@@ -9,6 +9,8 @@
   },
   "dependencies": {
     "stash": "workspace:*",
+    "@cipherstash/drizzle": "workspace:*",
+    "@cipherstash/protect": "workspace:*",
     "@cipherstash/wizard": "workspace:*"
   },
   "devDependencies": {

@@ -1,4 +1,4 @@
-import { execFileSync } from 'node:child_process'
+import { execFileSync, spawnSync } from 'node:child_process'
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
@@ -22,6 +22,20 @@ const RUNNER: Record<PackageManager, string> = {
   yarn: 'yarn dlx',
 }
 
+const BIN = {
+  cli: resolve(REPO_ROOT, 'packages/cli/dist/bin/stash.js'),
+  wizard: resolve(REPO_ROOT, 'packages/wizard/dist/bin/wizard.js'),
+  protect: resolve(REPO_ROOT, 'packages/protect/dist/bin/stash.js'),
+  drizzleGen: resolve(REPO_ROOT, 'packages/drizzle/dist/bin/generate-eql-migration.js'),
+} as const
+
+const UA: Record<PackageManager, string> = {
+  npm: 'npm/10.0.0',
+  bun: 'bun/1.0.0',
+  pnpm: 'pnpm/10.0.0',
+  yarn: 'yarn/4.0.0',
+}
+
 // Suite A — pure-function rendering of "Next Steps" via the CLI's init
 // providers. Imports source so we exercise the production code path
 // without needing the binary to be built.
@@ -182,3 +196,23 @@ describe.skipIf(!authConfigured)(
     })
   },
 )
+
+// Suite C — ensures that all built binaries render the correct runner prefix
+// in their --help output when executed under different package manager environments.
+describe('binaries — help text uses detected runner', () => {
+  for (const pm of PMS) {
+    for (const [name, bin] of Object.entries(BIN) as Array<[keyof typeof BIN, string]>) {
+      it(`${name} --help renders ${RUNNER[pm]} for pm=${pm}`, () => {
+        const result = spawnSync('node', [bin, '--help'], {
+          env: { ...process.env, npm_config_user_agent: UA[pm] },
+          encoding: 'utf8',
+        })
+        expect(result.status, `${name} --help (pm=${pm}) stderr: ${result.stderr}`).toBe(0)
+        expect(result.stdout).toContain(RUNNER[pm])
+        if (RUNNER[pm] !== 'npx') {
+          expect(result.stdout).not.toMatch(/\bnpx\b/)
+        }
+      })
+    }
+  }
+})
@@ -47,16 +47,19 @@
     "dev": "turbo dev --filter './packages/*'",
     "clean": "rimraf --glob **/.next **/.turbo **/dist **/node_modules",
     "code:fix": "biome check --write",
+    "lint:runners": "node scripts/lint-no-hardcoded-runners.mjs",
     "release": "pnpm run build && changeset publish",
     "test": "turbo test --filter './packages/*'",
-    "test:e2e": "turbo run test:e2e"
+    "test:e2e": "turbo run test:e2e",
+    "test:scripts": "vitest run --config scripts/vitest.config.mjs"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@changesets/cli": "^2.29.6",
     "@types/node": "^22.15.12",
     "rimraf": "^6.1.2",
-    "turbo": "2.1.1"
+    "turbo": "2.1.1",
+    "vitest": "catalog:repo"
   },
   "packageManager": "pnpm@10.33.2",
   "engines": {

@@ -13,6 +13,28 @@ import {
 } from '../commands/db/supabase-migration.js'
 import { SUPABASE_PERMISSIONS_SQL } from '../installer/index.js'
 
+/**
+ * Generate the migration header for testing purposes.
+ * Mirrors the production function but imported for testing.
+ */
+function migrationHeader(runner: string): string {
+  return `-- CipherStash EQL — installed by \`${runner} stash db install --supabase --migration\`.
+--
+-- This migration installs the CipherStash Encrypt Query Language (EQL) types,
+-- functions, and operators into the \`eql_v2\` schema, then grants Supabase's
+-- \`anon\`, \`authenticated\`, and \`service_role\` roles the access they need.
+--
+-- The all-zero \`YYYYMMDDHHMMSS\` prefix is intentional: Supabase orders
+-- migrations lexically, so this file runs before any user migration that
+-- references the \`eql_v2_encrypted\` type. Do not rename it.
+--
+-- To upgrade EQL, re-run the install command — it will refuse to overwrite
+-- this file unless you pass --force.
+--
+-- Docs: https://cipherstash.com/docs/stack/cipherstash/supabase
+`
+}
+
 describe('detectSupabaseProject', () => {
   let tmpDir: string
 
@@ -112,8 +134,8 @@ describe('writeSupabaseEqlMigration', () => {
     const result = await writeSupabaseEqlMigration({ migrationsDir })
 
     const contents = fs.readFileSync(result.path, 'utf-8')
-    // Header comment block
-    expect(contents).toMatch(/^--/)
+    // Header comment block includes the detected runner instruction
+    expect(contents).toMatch(/-- CipherStash EQL — installed by `(npx|bunx|pnpm dlx|yarn dlx) stash db install --supabase --migration`/)
     expect(contents).toContain('CipherStash')
     // EQL SQL body — the bundled supabase variant defines eql_v2.
     expect(contents).toContain('eql_v2')
@@ -225,6 +247,29 @@ describe('validateInstallFlags', () => {
   })
 })
 
+describe('migrationHeader', () => {
+  it('renders the header with the provided runner for npx', () => {
+    const header = migrationHeader('npx')
+    expect(header).toContain('-- CipherStash EQL — installed by `npx stash db install --supabase --migration`.')
+  })
+
+  it('renders the header with the provided runner for bunx', () => {
+    const header = migrationHeader('bunx')
+    expect(header).toContain('bunx stash db install')
+  })
+
+  it('renders the header with the provided runner for pnpm dlx', () => {
+    const header = migrationHeader('pnpm dlx')
+    expect(header).toContain('pnpm dlx stash db install')
+  })
+
+  it('includes all expected documentation lines', () => {
+    const header = migrationHeader('npx')
+    expect(header).toContain('eql_v2_encrypted')
+    expect(header).toContain('https://cipherstash.com/docs/stack/cipherstash/supabase')
+  })
+})
+
 describe('chooseSupabaseInstallMode', () => {
   const projectWith = {
     hasMigrationsDir: true,

@@ -216,7 +216,7 @@ async function runDbCommand(
       await testConnectionCommand({ databaseUrl })
       break
     case 'migrate':
-      p.log.warn(messages.db.migrateNotImplemented)
+      p.log.warn(messages.db.migrateNotImplemented(STASH))
       break
     default:
       p.log.error(`${messages.db.unknownSubcommand}: ${sub ?? '(none)'}`)

@@ -308,14 +308,15 @@ async function generateDrizzleMigration(
 ) {
   const migrationName = options.name ?? DEFAULT_MIGRATION_NAME
   const outDir = resolve(options.out ?? DEFAULT_DRIZZLE_OUT)
+  const drizzleCmd = `${runnerCommand(detectPackageManager(), '').trim()} drizzle-kit generate --custom --name=${migrationName}`
 
   if (options.dryRun) {
     p.log.info('Dry run — no changes will be made.')
     const source = options.latest
       ? 'Would download EQL install SQL from GitHub'
       : 'Would use bundled EQL install SQL'
     p.note(
-      `Would run: npx drizzle-kit generate --custom --name=${migrationName}\n${source}\nWould write SQL to migration file in ${outDir}`,
+      `Would run: ${drizzleCmd}\n${source}\nWould write SQL to migration file in ${outDir}`,
       'Dry Run',
     )
     p.outro('Dry run complete.')
@@ -328,7 +329,7 @@ async function generateDrizzleMigration(
   s.start('Generating custom Drizzle migration...')
 
   try {
-    execSync(`npx drizzle-kit generate --custom --name=${migrationName}`, {
+    execSync(drizzleCmd, {
       stdio: 'pipe',
       encoding: 'utf-8',
     })
@@ -439,7 +440,7 @@ async function generateDrizzleMigration(
 
   p.log.success(`Migration created: ${generatedMigrationPath}`)
   p.note(
-    'Run your Drizzle migrations to install EQL:\n\n  npx drizzle-kit migrate',
+    `Run your Drizzle migrations to install EQL:\n\n  ${runnerCommand(detectPackageManager(), '').trim()} drizzle-kit migrate`,
     'Next Steps',
   )
   printNextSteps()

@@ -5,6 +5,7 @@ import {
   SUPABASE_PERMISSIONS_SQL,
   loadBundledEqlSql,
 } from '@/installer/index.js'
+import { detectPackageManager, runnerCommand } from '@/commands/init/utils.js'
 
 /**
  * Filename of the Supabase migration that installs CipherStash EQL.
@@ -22,9 +23,11 @@ export const SUPABASE_EQL_MIGRATION_FILENAME =
 /**
  * Header comment block prepended to the generated migration. Explains *why*
  * this file exists for future maintainers reading their own migrations
- * directory.
+ * directory. The runner is resolved at call time based on the detected
+ * package manager.
  */
-const MIGRATION_HEADER = `-- CipherStash EQL — installed by \`npx stash db install --supabase --migration\`.
+function migrationHeader(runner: string): string {
+  return `-- CipherStash EQL — installed by \`${runner} stash db install --supabase --migration\`.
 --
 -- This migration installs the CipherStash Encrypt Query Language (EQL) types,
 -- functions, and operators into the \`eql_v2\` schema, then grants Supabase's
@@ -39,6 +42,7 @@ const MIGRATION_HEADER = `-- CipherStash EQL — installed by \`npx stash db ins
 --
 -- Docs: https://cipherstash.com/docs/stack/cipherstash/supabase
 `
+}
 
 export interface WriteSupabaseEqlMigrationOptions {
   /**
@@ -70,7 +74,7 @@ export interface WriteSupabaseEqlMigrationResult {
  * Generate the `<migrationsDir>/00000000000000_cipherstash_eql.sql` migration.
  *
  * The file body is, in order:
- *   1. {@link MIGRATION_HEADER} — explains why the file exists.
+ *   1. Migration header (generated from {@link migrationHeader}) — explains why the file exists.
  *   2. The bundled `cipherstash-encrypt-supabase.sql` install script.
  *   3. {@link SUPABASE_PERMISSIONS_SQL} — the same grants the runtime install
  *      path issues. One source of truth for both code paths.
@@ -104,8 +108,12 @@ export async function writeSupabaseEqlMigration(
     excludeOperatorFamily: excludeOperatorFamily || true,
   })
 
+  const pm = detectPackageManager()
+  const runner = runnerCommand(pm, '').trim()
+  const header = migrationHeader(runner)
+
   const body = [
-    MIGRATION_HEADER,
+    header,
     '',
     eqlSql.trimEnd(),
     '',

@@ -1,6 +1,7 @@
 import { existsSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import * as p from '@clack/prompts'
+import { detectPackageManager, runnerCommand } from '../init/utils.js'
 
 export interface EnvOptions {
   /** Write the emitted block to `.env.production.local` instead of stdout. */
@@ -28,17 +29,20 @@ export async function envCommand(options: EnvOptions = {}): Promise<void> {
     return
   }
 
-  p.intro('npx stash env')
+  const runner = runnerCommand(detectPackageManager(), '').trim()
+  const cliRef = `${runner} stash`
+
+  p.intro(`${cliRef} env`)
 
   const creds = await fetchProdCredentials()
   if (!creds) {
     p.log.error(
-      'Could not mint production credentials. Make sure you are logged in: npx stash auth login',
+      `Could not mint production credentials. Make sure you are logged in: ${cliRef} auth login`,
     )
     process.exit(1)
   }
 
-  const block = formatEnvBlock(creds)
+  const block = formatEnvBlock(creds, cliRef)
 
   if (options.write) {
     const target = resolve(process.cwd(), '.env.production.local')
@@ -80,9 +84,9 @@ async function fetchProdCredentials(): Promise<ProdCredentials | undefined> {
   return undefined
 }
 
-function formatEnvBlock(creds: ProdCredentials): string {
+function formatEnvBlock(creds: ProdCredentials, cliRef: string): string {
   return [
-    '# Generated by `npx stash env` — production credentials',
+    `# Generated by \`${cliRef} env\` — production credentials`,
     `CS_CLIENT_ID=${creds.clientId}`,
     `CS_CLIENT_KEY=${creds.clientKey}`,
     `CS_WORKSPACE_ID=${creds.workspaceId}`,

@@ -40,6 +40,7 @@ import { join } from 'node:path'
 import * as p from '@clack/prompts'
 import { detectSupabaseProject } from '../commands/db/detect.js'
 import { messages } from '../messages.js'
+import { detectPackageManager, runnerCommand } from '../commands/init/utils.js'
 
 export interface ResolveDatabaseUrlOptions {
   /** Value of `--database-url` if the user passed one. */
@@ -111,10 +112,17 @@ function isUrlParseable(value: string): boolean {
 
 /** Try to extract a `DB_URL=...` value from `supabase status --output env`. */
 function trySupabaseStatus(): string | undefined {
-  const candidates = [
+  const runner = runnerCommand(detectPackageManager(), '').trim()
+  // `runner` is one of 'npx' | 'bunx' | 'pnpm dlx' | 'yarn dlx'.
+  // Split on whitespace because pnpm/yarn dlx uses two tokens.
+  const dlxArgs = runner.split(/\s+/)
+  const candidates: Array<readonly [string, readonly string[]]> = [
     ['supabase', ['status', '--output', 'env']],
-    ['npx', ['--no-install', 'supabase', 'status', '--output', 'env']],
-  ] as const
+    [
+      dlxArgs[0],
+      [...dlxArgs.slice(1), 'supabase', 'status', '--output', 'env'],
+    ],
+  ]
 
   for (const [cmd, args] of candidates) {
     try {

@@ -31,7 +31,8 @@ export const messages = {
   },
   db: {
     unknownSubcommand: 'Unknown db subcommand',
-    migrateNotImplemented: '"npx stash db migrate" is not yet implemented.',
+    migrateNotImplemented: (stashRef: string) =>
+      `"${stashRef} db migrate" is not yet implemented.`,
     /** Source labels surfaced after DATABASE_URL resolution. */
     urlResolvedFromFlag: 'Using DATABASE_URL from --database-url flag',
     urlResolvedFromSupabase: 'Using DATABASE_URL from supabase status',

@@ -69,6 +69,8 @@ describe('stash CLI — non-interactive smoke', () => {
     const r = render(['db', 'migrate'])
     const { exitCode } = await r.exit
     expect(exitCode).toBe(0)
-    expect(r.output).toContain(messages.db.migrateNotImplemented)
+    // `migrateNotImplemented` is a runner-aware factory; the runner-agnostic
+    // suffix is the stable assertion target.
+    expect(r.output).toContain('stash db migrate" is not yet implemented.')
   })
 })