@pikku/deploy-standalone 0.12.13 → 0.12.17

package/dist/runtime/cli.js

@@ -0,0 +1,193 @@
+/** Where the migrations live, when the operator has moved them. */
+export const MIGRATIONS_DIR_ENV = 'PIKKU_MIGRATIONS_DIR';
+const usage = (hasDb, engine) => [
+    'Usage: <bundle> [command]',
+    '',
+    '  serve            Start the server. The default when no command is given.',
+    '  version          Print the version this artifact was built from.',
+    '  help             Print this.',
+    ...(hasDb
+        ? [
+            '',
+            '  db migrate       Apply pending migrations to the database this build opens.',
+            '  db status        List applied and pending migrations.',
+            ...(engine === 'sqlite'
+                ? ['  backup <path>    Copy the database to <path>, consistently.']
+                : []),
+        ]
+        : []),
+    '',
+    'Environment:',
+    `  ${MIGRATIONS_DIR_ENV}   Migrations directory, when not the one beside the bundle.`,
+].join('\n');
+export function parseStandaloneCommand(argv, options) {
+    const write = options.write ?? ((line) => console.log(line));
+    const [command, ...rest] = argv;
+    if (command === undefined || command === 'serve')
+        return { kind: 'serve' };
+    if (command === 'version' || command === '--version' || command === '-v') {
+        write(options.version);
+        return { kind: 'exit', code: 0 };
+    }
+    if (command === 'help' || command === '--help' || command === '-h') {
+        write(usage(options.hasDb, options.engine));
+        return { kind: 'exit', code: 0 };
+    }
+    const needsDb = command === 'db' || command === 'backup';
+    if (needsDb && !options.hasDb) {
+        write(`This build opens no database, so there is nothing for \`${command}\` to act on.`);
+        return { kind: 'exit', code: 1 };
+    }
+    if (command === 'db') {
+        const action = rest[0];
+        if (action === 'migrate' || action === 'status') {
+            return { kind: 'db', action };
+        }
+        write(action === undefined
+            ? 'db needs an action: migrate or status.'
+            : `Unknown db action: ${action}. Expected migrate or status.`);
+        return { kind: 'exit', code: 1 };
+    }
+    if (command === 'backup') {
+        // Postgres has pg_dump, which understands roles, extensions and large
+        // objects that copying bytes out from in here would silently drop. Offering
+        // the word for both engines would promise a backup on one of them that is
+        // not one.
+        if (options.engine !== 'sqlite') {
+            write('backup is for the SQLite builds, whose database is a file this process owns. Use pg_dump against DATABASE_URL.');
+            return { kind: 'exit', code: 1 };
+        }
+        const destination = rest[0];
+        if (!destination) {
+            write('backup needs a path to write the copy to.');
+            return { kind: 'exit', code: 1 };
+        }
+        return { kind: 'backup', destination };
+    }
+    write(`Unknown command: ${command}\n\n${usage(options.hasDb, options.engine)}`);
+    return { kind: 'exit', code: 1 };
+}
+/**
+ * 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 const resolveMigrationsDir = (bundleDir, env = process.env) => env[MIGRATIONS_DIR_ENV] ?? bundleDir;
+/**
+ * The migration executor for whichever database this build opens.
+ *
+ * Both drivers are reached by dynamic import so a SQLite build never carries
+ * the Postgres one into its bundle, and vice versa.
+ */
+const executorFor = async (db) => {
+    if (db.engine === 'sqlite') {
+        const { SqliteMigrationExecutor, loadSqliteRuntime } = await import('@pikku/migrator-sql/sqlite');
+        const runtime = await loadSqliteRuntime();
+        const handle = runtime.open(db.databaseFile);
+        return {
+            executor: new SqliteMigrationExecutor(handle),
+            close: () => handle.close(),
+        };
+    }
+    const { PostgresMigrationExecutor } = await import('@pikku/migrator-sql/postgres');
+    return {
+        executor: new PostgresMigrationExecutor(postgresClient(db.sql)),
+        close: () => { },
+    };
+};
+/**
+ * A `PostgresMigrationClient` over the app's own postgres.js connection.
+ *
+ * `begin` is what makes a failed migration roll back: postgres.js hands the
+ * handler a single reserved connection, so the DDL and the bookkeeping row are
+ * one transaction rather than statements a pool may spread across three.
+ *
+ * `simple()` on the plain path is deliberate — a migration file is many
+ * statements, and the extended protocol accepts only one per message.
+ */
+const postgresClient = (sql) => ({
+    async query(text, params) {
+        const rows = (await sql.unsafe(text, params ?? []));
+        return { rows };
+    },
+    async exec(text) {
+        return sql.unsafe(text).simple();
+    },
+    begin(handler) {
+        return sql.begin((tx) => handler(postgresClient(tx)));
+    },
+});
+const stdout = { write: (line) => console.log(line) };
+export async function runDbCommand(action, db, out = stdout) {
+    const { migrate, pendingMigrations } = await import('@pikku/migrator-sql');
+    const { executor, close } = await executorFor(db);
+    try {
+        if (action === 'migrate') {
+            const { applied, skipped } = await migrate(executor, db.migrationsDir);
+            for (const name of applied)
+                out.write(`applied  ${name}`);
+            out.write(applied.length === 0
+                ? `Already up to date (${skipped.length} applied previously).`
+                : `Applied ${applied.length} migration(s).`);
+            return;
+        }
+        await executor.ensureTrackingTable();
+        const applied = await executor.getApplied();
+        const pending = pendingMigrations(db.migrationsDir, applied);
+        for (const row of applied) {
+            out.write(`applied  ${row.name}  ${row.applied_at}`);
+        }
+        for (const name of pending)
+            out.write(`pending  ${name}`);
+        out.write(`${applied.length} applied, ${pending.length} pending.`);
+    }
+    finally {
+        close();
+    }
+}
+/**
+ * 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 async function runBackupCommand(destination, db, out = stdout) {
+    const { loadSqliteRuntime } = await import('@pikku/migrator-sql/sqlite');
+    const runtime = await loadSqliteRuntime();
+    const handle = runtime.open(db.databaseFile);
+    try {
+        handle.exec(`VACUUM INTO '${destination.replace(/'/g, "''")}'`);
+        out.write(`Copied ${db.databaseFile} to ${destination}.`);
+    }
+    finally {
+        handle.close();
+    }
+}
+/**
+ * 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 async function runStandaloneCommand(command, db, out = stdout) {
+    if (command.kind === 'serve')
+        return 'serve';
+    if (command.kind === 'exit')
+        process.exit(command.code);
+    if (!db) {
+        throw new Error('This build opens no database.');
+    }
+    if (command.kind === 'db') {
+        await runDbCommand(command.action, db, out);
+        return 'done';
+    }
+    if (db.engine !== 'sqlite') {
+        throw new Error('backup is only available on a SQLite build.');
+    }
+    await runBackupCommand(command.destination, db, out);
+    return 'done';
+}

package/dist/runtime/index.d.ts

@@ -7,3 +7,5 @@
  */
 export { DATA_DIR_ENV, PARENT_PID_ENV, watchParentProcess, } from './parent-watch.js';
 export type { ParentWatch, ParentWatchOptions } from './parent-watch.js';
+export { parseStandaloneCommand, runStandaloneCommand, runDbCommand, runBackupCommand, resolveMigrationsDir, MIGRATIONS_DIR_ENV, } from './cli.js';
+export type { StandaloneCommand, StandaloneDb, StandaloneSqliteDb, StandalonePostgresDb, PostgresSql, CommandOutput, ParseOptions, } from './cli.js';

package/dist/runtime/index.js

@@ -6,3 +6,4 @@
  * in TypeScript instead of being a string the adapter emits and nobody runs.
  */
 export { DATA_DIR_ENV, PARENT_PID_ENV, watchParentProcess, } from './parent-watch.js';
+export { parseStandaloneCommand, runStandaloneCommand, runDbCommand, runBackupCommand, resolveMigrationsDir, MIGRATIONS_DIR_ENV, } from './cli.js';

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@pikku/deploy-standalone",
-  "version": "0.12.13",
+  "version": "0.12.17",
   "description": "Standalone deploy adapter for Pikku — bundles a project into a node bundle or a compiled bun executable",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc -b",
     "tsc": "tsc --noEmit",
-    "test": "node --test --import tsx src/*.test.ts"
+    "test": "node --test --import tsx \"src/**/*.test.ts\""
   },
   "devDependencies": {
     "typescript": "^6.0.3"
@@ -18,6 +18,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@pikku/deploy": "^0.12.2"
+    "@pikku/deploy": "^0.12.5",
+    "@pikku/migrator-sql": "^0.12.3"
   }
 }