@pikku/deploy-standalone 0.12.13 → 0.12.17

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # @pikku/deploy-standalone
 
+## 0.12.17
+
+### Patch Changes
+
+- b2e038b: Rename `@pikku/sql-migrator` to `@pikku/migrator-sql`, so a future migrator for
+  another store sorts beside it rather than under a second prefix. The package has
+  never been published under either name, so nothing depends on the old one.
+- Updated dependencies [b2e038b]
+  - @pikku/migrator-sql@0.12.3
+
+## 0.12.16
+
+### Patch Changes
+
+- f970f8f: Rename `@pikku/db-migrator` to `@pikku/migrator-sql`.
+
+  It applies `.sql` files and keeps their bookkeeping; it is not a database
+  service, and `db-` read as though it were one. Nothing was ever published under
+  the old name, so there is no alias to keep.
+
+- Updated dependencies [f970f8f]
+  - @pikku/migrator-sql@0.12.2
+
+## 0.12.15
+
+### Patch Changes
+
+- a057bec: Give a standalone bundle a command line.
+
+  An operator holding a standalone artifact on a machine had one thing they could
+  do with it: start it. Applying the migrations it needs meant a checkout of the
+  project and a second copy of the CLI on a production box, and answering "which
+  build is this" meant asking whoever ran the deploy.
+
+  The bundle now takes a command. `serve` remains the default, so an existing
+  `node bundle.js` is unchanged. `version` prints the version the project declared
+  at build time. `db migrate` and `db status` apply and report the migrations that
+  now ship beside the bundle under `db/<engine>/` — the same path Fabric's build
+  container stages them to, so the two producers of an artifact cannot disagree
+  about where the SQL lives. `backup <path>` writes a consistent copy of a SQLite
+  database with `VACUUM INTO`; on postgres it refuses and names `pg_dump`, which
+  is the tool for it.
+
+  Both engines are supported: a postgres build migrates over the connection it
+  already opens. `PostgresMigrationClient` grew an optional `begin`, because a
+  pooled client is free to answer `BEGIN`, the migration and `COMMIT` on three
+  different connections — which leaves a failed migration half applied with
+  nothing to roll back.
+
+  There is deliberately no way to invoke an RPC. A running server already answers
+  them with auth, sessions and middleware applied; an in-process invoke would
+  answer them with none of that.
+
+- Updated dependencies [a057bec]
+- Updated dependencies [a057bec]
+  - @pikku/migrator-sql@0.12.1
+  - @pikku/deploy@0.12.5
+
+## 0.12.14
+
+### Patch Changes
+
+- 3d75643: Run the app's server lifecycle in generated entries, and make an out-of-band
+  account signable-in.
+
+  `pikkuServerLifecycle` was only ever called by `pikku dev` and `pikku serve`, so
+  an app that seeds its first admin account, probes a dependency, or warms a cache
+  in `beforeStart` did all of that in development and silently skipped it
+  everywhere it was actually deployed. The standalone entry and the shared node
+  server entry — the one behind every `target: 'server'` unit — now import the
+  app's lifecycle and call it: `beforeStart` after `init` and before the port
+  opens, so work that must finish before the first request has, `afterStart` once
+  the server is listening, and the stop hooks handed to the signal handler that
+  already owns shutdown rather than a second listener racing it. Each shutdown
+  step is isolated from the ones after it, so a hook that throws is logged without
+  taking the service teardown and the socket close down with it.
+
+  Separately, `createAuthUser` and `setAuthUserPassword` wrote credential accounts
+  with no `issuer`. From better-auth 1.7 a credential account is matched by its
+  issuer as well as its provider, so those accounts were invisible to sign-in,
+  `updatePassword` and `findCredentialAccount` — a user who plainly existed in the
+  table was reported as "user not found". The field is written only when the
+  resolved schema has it, so older better-auth keeps working, and
+  `setAuthUserPassword` repairs an account that predates the fix.
+
+- 3d75643: Give a standalone artifact the database connection every other provider's runtime hands it.
+
+  `createSingletonServices` receives `kysely` from whatever is hosting the app —
+  `pikku dev` builds one, a Cloudflare deploy binds one — so app code is written
+  expecting it, and the generated templates throw outright when it is absent. The
+  standalone provider is its own host and supplied nothing, so a bundle built from
+  a project with a database started, called the services factory, and died on the
+  first line of it. The artifact was only ever startable by projects that had no
+  database at all, which is not the case the provider exists to serve.
+
+  The generated entry now opens the database itself and passes `kysely` in.
+  `EntryGenerationContext` carries a `db` descriptor, and the engine is read from
+  the migrations directory the project actually wrote — `db/sqlite` or
+  `db/postgres`, the same two conventions the migrator emits to. Having both is
+  refused rather than resolved: choosing on directory order would choose which
+  database the deployed app talks to, and an app running happily against the
+  wrong but entirely valid schema is invisible until someone reads the data.
+
+  For SQLite the adapter emits the dialect its runtime can actually use —
+  `@pikku/kysely-node-sqlite` for the node bundle, `@pikku/kysely-bun-sqlite` for a
+  compiled bun binary, which has no `node:sqlite` to reach for. For Postgres it
+  emits `PikkuKysely` from `@pikku/kysely-postgres`, connected from `DATABASE_URL`,
+  the same variable every other pikku host reads, so an artifact dropped onto a
+  machine already running a pikku app needs no new one. An unset `DATABASE_URL`
+  fails by name rather than as a driver error about an undefined connection
+  string.
+
+  The connection pool is closed on shutdown, in `afterStop` — after the app's own
+  stop hook and the draining server have both finished with it, since a pool
+  closed any earlier takes the queries they are still entitled to make down with
+  it. SQLite needs no counterpart: the process exiting releases the file.
+
+  The project's generated coercion map is applied to either engine, so a deployed
+  app and `pikku dev` agree about which columns are dates and which are booleans.
+  It is attached when the project generated one and skipped when it did not — the
+  map is built from `db/annotations.ts` rather than from the dialect, so an app
+  that annotates no columns is one with nothing to coerce rather than one that
+  should be handed no database at all.
+
+  A SQLite file is located by `PIKKU_DATA_DIR` rather than derived from the bundle's
+  own path: a deploy that swaps the release directory would otherwise take the
+  database with it. `PIKKU_DATABASE_FILE` overrides it outright, for when the path
+  has to match one something else already chose — notably `pikku db migrate`,
+  which has to open the same file or the app runs against an unmigrated schema.
+  Neither being set fails with the variable's name rather than as a SQLite error
+  about a path of `undefined`.
+
+- Updated dependencies [3d75643]
+- Updated dependencies [3d75643]
+  - @pikku/deploy@0.12.4
+
 ## 0.12.13
 
 ### Patch Changes

package/dist/adapter.d.ts

@@ -66,6 +66,17 @@ export declare class StandaloneProviderAdapter implements ProviderAdapter {
     generateInfraManifest(): string | null;
     generateProviderConfigs(): Map<string, string>;
     getExternals(): string[];
+    /**
+     * The SQLite driver this runtime cannot load.
+     *
+     * `loadSqliteRuntime` picks its driver by looking for `globalThis.Bun`, so a
+     * node process never runs the bun branch — but esbuild still follows the
+     * import, and `bun:sqlite` sits at the top of that module as a static import
+     * it cannot resolve. Left in, the bundle fails to build; marked external, it
+     * becomes a top-level import node fails to load. Stubbing removes the branch
+     * that was already dead.
+     */
+    getStubModules(): string[];
     getPlatform(): 'node';
     deploy(options: {
         buildDir: string;

package/dist/adapter.js

@@ -24,7 +24,229 @@ const sidecarHandshakeLines = () => [
     `  watchParentProcess()`,
     `  console.log(\`${SERVER_READY_MARKER} on http://\${hostname}:\${server.port}\`)`,
 ];
-const SIDECAR_RUNTIME_IMPORT = `import { watchParentProcess } from '@pikku/deploy-standalone/runtime'`;
+/**
+ * The runtime helpers the entry imports. The database ones are left out of a
+ * build with no database, so the bundle carries no migrator it can never run.
+ */
+const runtimeImport = (ctx) => {
+    const names = ['watchParentProcess', 'parseStandaloneCommand'];
+    if (ctx.db)
+        names.push('runStandaloneCommand', 'resolveMigrationsDir');
+    return `import { ${names.join(', ')} } from '@pikku/deploy-standalone/runtime'`;
+};
+/**
+ * Environment variable naming the directory the SQLite file lives in.
+ *
+ * The database has to outlive a release. A deploy that swaps the artifact
+ * directory would take the database with it if the file sat beside the bundle,
+ * so the path comes from the environment and points somewhere the operator
+ * keeps stable across releases, rather than being derived from the bundle's own
+ * location the way the frontend directory is.
+ */
+const DATA_DIR_VAR = 'PIKKU_DATA_DIR';
+/**
+ * Full override for the database file, for when it must match a path something
+ * else already decided — notably `pikku db migrate`, which has to open the same
+ * file this opens or the app runs against an unmigrated database.
+ */
+const DATABASE_FILE_VAR = 'PIKKU_DATABASE_FILE';
+const DEFAULT_DATABASE_FILENAME = 'pikku.db';
+/**
+ * The dialect factory each runtime opens SQLite with. bun cannot use the node
+ * one — `bun:sqlite` is a different driver, and the node build reaches for
+ * `node:sqlite`, which a compiled bun binary does not carry.
+ */
+const SQLITE_FACTORY = {
+    node: {
+        specifier: '@pikku/kysely-node-sqlite',
+        fn: 'createNodeSqliteKysely',
+    },
+    bun: { specifier: '@pikku/kysely-bun-sqlite', fn: 'createBunSqliteKysely' },
+};
+/**
+ * The environment variable a Postgres build reads its connection string from.
+ *
+ * The same name every other pikku host uses, so an artifact dropped onto a
+ * machine that already runs a pikku app needs no new variable.
+ */
+const DATABASE_URL_VAR = 'DATABASE_URL';
+/** Imports the coercion plugin, for an app that generated a map. */
+const coercionImportLines = (coercionImportPath) => [
+    `import { createCoercionPlugin } from '@pikku/kysely'`,
+    `import { coercionMap as __pikkuCoercionMap } from '${coercionImportPath}'`,
+];
+/** Imports a database-backed entry needs on top of the common set. */
+const dbImportLines = (runtime, db) => [
+    ...(db.engine === 'sqlite'
+        ? [
+            `import { ${SQLITE_FACTORY[runtime].fn} } from '${SQLITE_FACTORY[runtime].specifier}'`,
+            `import { mkdirSync as __pikkuMkdirSync } from 'node:fs'`,
+        ]
+        : [`import { PikkuKysely } from '@pikku/kysely-postgres'`]),
+    ...(db.coercionImportPath ? coercionImportLines(db.coercionImportPath) : []),
+];
+/**
+ * Opens the database before services are built, so `createSingletonServices`
+ * receives `kysely` exactly as a hosted runtime would hand it over.
+ *
+ * Creating the directory rather than requiring it is deliberate: the artifact
+ * is expected to start on a machine where nothing has run yet, and a missing
+ * parent directory is the difference between a first boot that works and one
+ * that needs a documented mkdir nobody reads.
+ */
+const dbSetupLines = (runtime, db) => {
+    const plugins = db.coercionImportPath
+        ? `[createCoercionPlugin({ map: __pikkuCoercionMap })]`
+        : `[]`;
+    if (db.engine === 'sqlite') {
+        return [
+            `  const __pikkuDbFile = process.env.${DATABASE_FILE_VAR}`,
+            `    ? process.env.${DATABASE_FILE_VAR}`,
+            `    : __pikkuJoin(__pikkuRequireDataDir(), '${DEFAULT_DATABASE_FILENAME}')`,
+            `  __pikkuMkdirSync(__pikkuDirname(__pikkuDbFile), { recursive: true })`,
+            `  const kysely = ${SQLITE_FACTORY[runtime].fn}({`,
+            `    filename: __pikkuDbFile,`,
+            `    plugins: ${plugins},`,
+            `  })`,
+        ];
+    }
+    return [
+        `  const __pikkuDbUrl = process.env.${DATABASE_URL_VAR}`,
+        `  if (!__pikkuDbUrl) {`,
+        `    throw new Error(`,
+        `      'This build connects to Postgres, so it needs ${DATABASE_URL_VAR} set to the database it should open.'`,
+        `    )`,
+        `  }`,
+        `  const __pikkuPg = new PikkuKysely(logger, __pikkuDbUrl)`,
+        `  await __pikkuPg.init()`,
+        ...(db.coercionImportPath
+            ? [
+                `  const kysely = __pikkuPg.kysely.withPlugin(`,
+                `    createCoercionPlugin({ map: __pikkuCoercionMap })`,
+                `  )`,
+            ]
+            : [`  const kysely = __pikkuPg.kysely`]),
+    ];
+};
+/**
+ * Where the migrations sit relative to the running artifact.
+ *
+ * A node bundle reads them from its own directory. A compiled bun binary has no
+ * directory — `import.meta.url` points inside the embedded filesystem — so it
+ * resolves them beside the executable, which is where an operator unpacking an
+ * artifact puts them.
+ */
+const bundleDirExpression = (runtime) => runtime === 'node'
+    ? `__pikkuDirname(__pikkuFileURLToPath(import.meta.url))`
+    : `__pikkuDirname(process.execPath)`;
+/**
+ * The command line, parsed before anything is opened.
+ *
+ * `version` and `help` have to answer without a database, a config factory or a
+ * port, because the machine asking may be one where none of the three work yet
+ * — which is exactly when someone runs them.
+ */
+const commandParseLines = (ctx) => [
+    `const __pikkuCommand = parseStandaloneCommand(process.argv.slice(2), {`,
+    `  version: '${(ctx.version ?? 'unknown').replace(/'/g, "\\'")}',`,
+    `  hasDb: ${Boolean(ctx.db)},`,
+    ...(ctx.db ? [`  engine: '${ctx.db.engine}',`] : []),
+    `})`,
+    `if (__pikkuCommand.kind === 'exit') process.exit(__pikkuCommand.code)`,
+];
+/**
+ * Runs a non-serve command against the database the app itself just opened, and
+ * stops before a port is bound.
+ *
+ * Reusing the app's own connection is the point: a command that resolved its
+ * own would be free to migrate a different database than the next `serve`
+ * reads, and the two would only disagree once in production.
+ */
+const commandDispatchLines = (runtime, ctx) => {
+    if (!ctx.db) {
+        return [`  if (__pikkuCommand.kind !== 'serve') process.exit(0)`, ``];
+    }
+    const dir = `__pikkuJoin(${bundleDirExpression(runtime)}, 'db', '${ctx.db.engine}')`;
+    const handle = ctx.db.engine === 'sqlite'
+        ? `databaseFile: __pikkuDbFile,`
+        : `sql: __pikkuPg.sql,`;
+    return [
+        `  const __pikkuDbCommandTarget = {`,
+        `    engine: '${ctx.db.engine}',`,
+        `    migrationsDir: resolveMigrationsDir(${dir}),`,
+        `    ${handle}`,
+        `  }`,
+        `  if ((await runStandaloneCommand(__pikkuCommand, __pikkuDbCommandTarget)) === 'done') {`,
+        ...(ctx.db.engine === 'postgres' ? [`    await __pikkuPg.close()`] : []),
+        `    return`,
+        `  }`,
+        ``,
+    ];
+};
+/** Imports the app's own lifecycle module, when it declares one. */
+const lifecycleImportLines = (lifecycle) => [
+    `import { ${lifecycle.variable} as __pikkuLifecycle } from '${lifecycle.importPath}'`,
+];
+/**
+ * Runs the app's start hooks around the port opening, the same order and the
+ * same services `pikku dev` gives them.
+ *
+ * `beforeStart` runs after `init` so a hook can rely on everything the server
+ * resolved, and before `start` so work that must finish before the first
+ * request — a seeded admin account, a schema probe — is finished when one
+ * arrives.
+ */
+const lifecycleStartLines = () => [
+    `  await __pikkuLifecycle?.beforeStart?.(singletonServices)`,
+];
+const lifecycleAfterStartLines = () => [
+    `  await __pikkuLifecycle?.afterStart?.(singletonServices)`,
+];
+/**
+ * Hands the stop hooks to the signal handler that owns the shutdown.
+ *
+ * The connection pool is closed in `afterStop`, once the app's own hook and the
+ * server have both finished with it — a pool closed any earlier takes the
+ * queries they are still allowed to make down with it. SQLite needs no
+ * counterpart: the process exiting releases the file.
+ */
+const shutdownHooksArg = (ctx) => {
+    const before = [];
+    const after = [];
+    if (ctx.lifecycle) {
+        before.push(`await __pikkuLifecycle?.beforeStop?.(singletonServices)`);
+        after.push(`await __pikkuLifecycle?.afterStop?.(singletonServices)`);
+    }
+    if (ctx.db?.engine === 'postgres') {
+        after.push(`await __pikkuPg.close()`);
+    }
+    if (before.length === 0 && after.length === 0)
+        return '';
+    const hooks = [];
+    if (before.length > 0) {
+        hooks.push(`beforeStop: async () => { ${before.join('; ')} }`);
+    }
+    if (after.length > 0) {
+        hooks.push(`afterStop: async () => { ${after.join('; ')} }`);
+    }
+    return `{ ${hooks.join(', ')} }`;
+};
+/**
+ * Fails with the variable's name rather than whatever SQLite says about a path
+ * of `undefined/pikku.db`, which is the error an operator would otherwise have
+ * to work backwards from.
+ */
+const dataDirHelperLines = () => [
+    `function __pikkuRequireDataDir() {`,
+    `  const dir = process.env.${DATA_DIR_VAR}`,
+    `  if (!dir) {`,
+    `    throw new Error(`,
+    `      'This build bundles a SQLite database, so it needs somewhere to keep it. Set ${DATA_DIR_VAR} to a writable directory that survives a release swap, or set ${DATABASE_FILE_VAR} to the database file itself.'`,
+    `    )`,
+    `  }`,
+    `  return dir`,
+    `}`,
+];
 /**
  * `rustc -vV`, or nothing when no toolchain is installed. The triple then falls
  * back to the Node platform pair, which is right for every ordinary host — the
@@ -73,13 +295,15 @@ export class StandaloneProviderAdapter {
             `import { PikkuNodeHTTPServer } from '@pikku/node-http-server'`,
             `import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'`,
             `import { WebSocketServer } from 'ws'`,
-            SIDECAR_RUNTIME_IMPORT,
-            ...(ctx.frontend
+            runtimeImport(ctx),
+            ...(ctx.frontend || ctx.db
                 ? [
                     `import { dirname as __pikkuDirname, join as __pikkuJoin } from 'node:path'`,
                     `import { fileURLToPath as __pikkuFileURLToPath } from 'node:url'`,
                 ]
                 : []),
+            ...(ctx.db ? dbImportLines('node', ctx.db) : []),
+            ...(ctx.lifecycle ? lifecycleImportLines(ctx.lifecycle) : []),
             ``,
             ctx.configImport,
             ctx.servicesImport,
@@ -91,6 +315,8 @@ export class StandaloneProviderAdapter {
             `const port = parseInt(process.env.PORT || '3000', 10)`,
             `const hostname = process.env.HOST || '0.0.0.0'`,
             ``,
+            ...commandParseLines(ctx),
+            ``,
             `async function main() {`,
             `  const config = await ${ctx.configVar}()`,
             `  const schedulerService = new InMemorySchedulerService()`,
@@ -100,8 +326,11 @@ export class StandaloneProviderAdapter {
             `  const eventHub = new LocalEventHubService()`,
             `  workflowService.wireQueueWorkers()`,
             `  wireAgentScorerQueueWorkers()`,
+            ...(ctx.db ? dbSetupLines('node', ctx.db) : []),
+            ...commandDispatchLines('node', ctx),
             `  const singletonServices = await ${ctx.servicesVar}(config, {`,
             `    logger,`,
+            ...(ctx.db ? [`    kysely,`] : []),
             `    schedulerService,`,
             `    queueService,`,
             `    workflowService,`,
@@ -136,8 +365,10 @@ export class StandaloneProviderAdapter {
             `  await server.init()`,
             `  await schedulerService.start()`,
             `  await triggerService.start()`,
-            `  server.enableExitOnSignals()`,
+            ...(ctx.lifecycle ? lifecycleStartLines() : []),
+            `  server.enableExitOnSignals(${shutdownHooksArg(ctx)})`,
             `  await server.start()`,
+            ...(ctx.lifecycle ? lifecycleAfterStartLines() : []),
             ...sidecarHandshakeLines(),
             `}`,
             ``,
@@ -146,13 +377,14 @@ export class StandaloneProviderAdapter {
             `  process.exit(1)`,
             `})`,
             ``,
+            ...(ctx.db?.engine === 'sqlite' ? [...dataDirHelperLines(), ``] : []),
         ].join('\n');
     }
     generateBunEntrySource(ctx) {
         return [
             `// Generated standalone entry (bun runtime) — all functions in one process`,
             `import { ConsoleLogger, InMemoryQueueService, InMemoryTriggerService, InMemoryWorkflowService } from '@pikku/core/services'`,
-            SIDECAR_RUNTIME_IMPORT,
+            runtimeImport(ctx),
             `import { pikkuState } from '@pikku/core/state'`,
             `import { wireAgentScorerQueueWorkers } from '@pikku/core/agent-scorer'`,
             `import { InMemorySchedulerService } from '@pikku/schedule'`,
@@ -160,6 +392,13 @@ export class StandaloneProviderAdapter {
             ...(ctx.frontend
                 ? [`import { frontendAssets } from '${STANDALONE_FRONTEND_MANIFEST}'`]
                 : []),
+            ...(ctx.db
+                ? [
+                    `import { dirname as __pikkuDirname, join as __pikkuJoin } from 'node:path'`,
+                ]
+                : []),
+            ...(ctx.db ? dbImportLines('bun', ctx.db) : []),
+            ...(ctx.lifecycle ? lifecycleImportLines(ctx.lifecycle) : []),
             ``,
             ctx.configImport,
             ctx.servicesImport,
@@ -171,6 +410,8 @@ export class StandaloneProviderAdapter {
             `const port = parseInt(process.env.PORT || '3000', 10)`,
             `const hostname = process.env.HOST || '0.0.0.0'`,
             ``,
+            ...commandParseLines(ctx),
+            ``,
             `async function main() {`,
             `  const config = await ${ctx.configVar}()`,
             `  const schedulerService = new InMemorySchedulerService()`,
@@ -180,8 +421,11 @@ export class StandaloneProviderAdapter {
             `  const eventHub = new BunEventHubService()`,
             `  workflowService.wireQueueWorkers()`,
             `  wireAgentScorerQueueWorkers()`,
+            ...(ctx.db ? dbSetupLines('bun', ctx.db) : []),
+            ...commandDispatchLines('bun', ctx),
             `  const singletonServices = await ${ctx.servicesVar}(config, {`,
             `    logger,`,
+            ...(ctx.db ? [`    kysely,`] : []),
             `    schedulerService,`,
             `    queueService,`,
             `    workflowService,`,
@@ -208,8 +452,10 @@ export class StandaloneProviderAdapter {
             `  await server.init()`,
             `  await schedulerService.start()`,
             `  await triggerService.start()`,
-            `  server.enableExitOnSignals()`,
+            ...(ctx.lifecycle ? lifecycleStartLines() : []),
+            `  server.enableExitOnSignals(${shutdownHooksArg(ctx)})`,
             `  await server.start()`,
+            ...(ctx.lifecycle ? lifecycleAfterStartLines() : []),
             ...sidecarHandshakeLines(),
             `}`,
             ``,
@@ -218,6 +464,7 @@ export class StandaloneProviderAdapter {
             `  process.exit(1)`,
             `})`,
             ``,
+            ...(ctx.db?.engine === 'sqlite' ? [...dataDirHelperLines(), ``] : []),
         ].join('\n');
     }
     generateUnitConfigs() {
@@ -239,6 +486,21 @@ export class StandaloneProviderAdapter {
         }
         return externals;
     }
+    /**
+     * The SQLite driver this runtime cannot load.
+     *
+     * `loadSqliteRuntime` picks its driver by looking for `globalThis.Bun`, so a
+     * node process never runs the bun branch — but esbuild still follows the
+     * import, and `bun:sqlite` sits at the top of that module as a static import
+     * it cannot resolve. Left in, the bundle fails to build; marked external, it
+     * becomes a top-level import node fails to load. Stubbing removes the branch
+     * that was already dead.
+     */
+    getStubModules() {
+        if (this.runtime === 'bun')
+            return [];
+        return ['sqlite-runtime-bun'];
+    }
     getPlatform() {
         return 'node';
     }

package/dist/runtime/cli.d.ts

@@ -0,0 +1,75 @@
+/** Where the migrations live, when the operator has moved them. */
+export declare const MIGRATIONS_DIR_ENV = "PIKKU_MIGRATIONS_DIR";
+export interface StandaloneSqliteDb {
+    engine: 'sqlite';
+    migrationsDir: string;
+    /** The file the app itself opens, so a migration cannot target another one. */
+    databaseFile: string;
+}
+/**
+ * The postgres.js tagged template the app is already connected through.
+ *
+ * Taken rather than constructed so a migration runs on the app's own pool: a
+ * second connection would need the credentials resolved twice and could reach a
+ * different database than the one the next `serve` opens.
+ */
+export interface PostgresSql {
+    unsafe(query: string, parameters?: unknown[]): Promise<any> & {
+        simple(): Promise<any>;
+    };
+    begin<T>(handler: (sql: PostgresSql) => Promise<T>): Promise<T>;
+}
+export interface StandalonePostgresDb {
+    engine: 'postgres';
+    migrationsDir: string;
+    sql: PostgresSql;
+}
+export type StandaloneDb = StandaloneSqliteDb | StandalonePostgresDb;
+export type StandaloneCommand = {
+    kind: 'serve';
+} | {
+    kind: 'db';
+    action: 'migrate' | 'status';
+} | {
+    kind: 'backup';
+    destination: string;
+} | {
+    kind: 'exit';
+    code: number;
+};
+export interface ParseOptions {
+    version: string;
+    /** False for a build with no database, whose db commands cannot be answered. */
+    hasDb: boolean;
+    engine?: 'sqlite' | 'postgres';
+    write?: (line: string) => void;
+}
+export declare function parseStandaloneCommand(argv: string[], options: ParseOptions): StandaloneCommand;
+/**
+ * The migrations directory, honouring an operator who keeps them elsewhere.
+ *
+ * `bundleDir` is where the build put them, which is the same `db/<engine>/`
+ * path Fabric's build container stages into an artifact — so an artifact from
+ * either producer answers `db migrate` without being told where to look.
+ */
+export declare const resolveMigrationsDir: (bundleDir: string, env?: Record<string, string | undefined>) => string;
+export interface CommandOutput {
+    write(line: string): void;
+}
+export declare function runDbCommand(action: 'migrate' | 'status', db: StandaloneDb, out?: CommandOutput): Promise<void>;
+/**
+ * Copy the SQLite database somewhere else, while the app may be running.
+ *
+ * `VACUUM INTO` rather than copying the file: a plain copy taken while another
+ * process is mid-write captures a torn page and a write-ahead log it has no
+ * copy of, which restores as a corrupt database and only says so later.
+ */
+export declare function runBackupCommand(destination: string, db: StandaloneSqliteDb, out?: CommandOutput): Promise<void>;
+/**
+ * Run whatever the argv asked for, and say whether the caller should serve.
+ *
+ * The database is passed already open, because the entry has to open it the one
+ * way the app does — a command that resolved its own connection could migrate a
+ * different database than the next `serve` reads.
+ */
+export declare function runStandaloneCommand(command: StandaloneCommand, db: StandaloneDb | undefined, out?: CommandOutput): Promise<'serve' | 'done'>;