@pikku/deploy-standalone 0.12.12 → 0.12.17

package/src/runtime/index.ts

@@ -0,0 +1,31 @@
+/**
+ * `@pikku/deploy-standalone/runtime` — the sliver of this package that runs
+ * inside the shipped artifact rather than on the build machine.
+ *
+ * A generated standalone entry imports from here, so the code is unit-tested
+ * 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 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/src/runtime/parent-watch.process.test.ts

@@ -0,0 +1,112 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { PARENT_PID_ENV } from './parent-watch.js'
+
+const parentWatchUrl = pathToFileURL(
+  fileURLToPath(new URL('./parent-watch.ts', import.meta.url))
+).href
+
+/**
+ * A stand-in for the compiled pikku binary: it installs the watch with its real
+ * defaults — including `process.exit` — and then holds the event loop open the
+ * way a listening server would.
+ */
+const SIDECAR = `
+import { watchParentProcess } from ${JSON.stringify(parentWatchUrl)}
+watchParentProcess({ intervalMs: 25 })
+setInterval(() => {}, 1000)
+console.log('sidecar-up')
+`
+
+const spawnNode = (args: string[], env?: NodeJS.ProcessEnv) =>
+  spawn(process.execPath, args, {
+    env: { ...process.env, ...env },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+
+const waitForExit = (child: ReturnType<typeof spawn>, timeoutMs: number) =>
+  new Promise<number | null>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error('the sidecar was still running')),
+      timeoutMs
+    )
+    child.once('exit', (code) => {
+      clearTimeout(timer)
+      resolve(code)
+    })
+  })
+
+const waitForStdout = (child: ReturnType<typeof spawn>, needle: string) =>
+  new Promise<void>((resolve, reject) => {
+    let seen = ''
+    const timer = setTimeout(
+      () => reject(new Error(`never printed ${needle}: ${seen}`)),
+      20_000
+    )
+    child.stdout?.on('data', (chunk) => {
+      seen += String(chunk)
+      if (seen.includes(needle)) {
+        clearTimeout(timer)
+        resolve()
+      }
+    })
+    child.stderr?.on('data', (chunk) => (seen += String(chunk)))
+  })
+
+describe('a sidecar whose shell dies without cleaning up', () => {
+  it('exits on its own once the watched process is gone', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'pikku-parent-watch-'))
+    const script = join(dir, 'sidecar.mjs')
+    await writeFile(script, SIDECAR, 'utf-8')
+
+    // Stands in for the desktop shell. Killed with SIGKILL, so nothing it
+    // might have done on the way out can be what stops the sidecar.
+    const shell = spawnNode(['-e', 'setInterval(() => {}, 1000)'])
+    const sidecar = spawnNode(['--import', 'tsx', script], {
+      [PARENT_PID_ENV]: String(shell.pid),
+    })
+
+    try {
+      await waitForStdout(sidecar, 'sidecar-up')
+      assert.equal(sidecar.exitCode, null, 'the sidecar must start out running')
+
+      shell.kill('SIGKILL')
+
+      const code = await waitForExit(sidecar, 20_000)
+      assert.equal(code, 0, 'an orphaned sidecar must exit cleanly')
+    } finally {
+      shell.kill('SIGKILL')
+      sidecar.kill('SIGKILL')
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps running when no shell pid was handed down', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'pikku-parent-watch-'))
+    const script = join(dir, 'sidecar.mjs')
+    await writeFile(script, SIDECAR, 'utf-8')
+
+    const sidecar = spawnNode(['--import', 'tsx', script], {
+      [PARENT_PID_ENV]: undefined,
+    })
+
+    try {
+      await waitForStdout(sidecar, 'sidecar-up')
+      await new Promise((resolve) => setTimeout(resolve, 300))
+      assert.equal(
+        sidecar.exitCode,
+        null,
+        'a server run from a terminal must not exit'
+      )
+    } finally {
+      sidecar.kill('SIGKILL')
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/runtime/parent-watch.test.ts

@@ -0,0 +1,148 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import { PARENT_PID_ENV, watchParentProcess } from './parent-watch.js'
+
+const tick = () => delay(12)
+
+describe('a sidecar that outlives the shell that spawned it', () => {
+  it('does not watch when no parent pid was handed down', async () => {
+    let orphaned = 0
+    const watch = watchParentProcess({
+      env: {},
+      onOrphaned: () => orphaned++,
+      intervalMs: 1,
+    })
+    try {
+      assert.equal(watch.watching, false)
+      await tick()
+      assert.equal(orphaned, 0)
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('ignores a pid that is not a positive integer', async () => {
+    for (const value of ['', 'abc', '0', '-1', '1.5']) {
+      const watch = watchParentProcess({
+        env: { [PARENT_PID_ENV]: value },
+        onOrphaned: () => assert.fail(`pid ${value} should not be watched`),
+        intervalMs: 1,
+      })
+      assert.equal(watch.watching, false, `pid ${JSON.stringify(value)}`)
+      await tick()
+      watch.stop()
+    }
+  })
+
+  it('stays quiet while the parent is alive', async () => {
+    let orphaned = 0
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => true,
+      onOrphaned: () => orphaned++,
+      intervalMs: 1,
+    })
+    try {
+      assert.equal(watch.watching, true)
+      await tick()
+      assert.equal(orphaned, 0)
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('fires once when the parent goes away, and stops polling', async () => {
+    let alive = true
+    let orphaned = 0
+    let probes = 0
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => {
+        probes++
+        return alive
+      },
+      onOrphaned: () => orphaned++,
+      intervalMs: 1,
+    })
+    try {
+      await tick()
+      assert.equal(orphaned, 0)
+      alive = false
+      await tick()
+      assert.equal(orphaned, 1, 'the orphan handler must run')
+      const probesAtDeath = probes
+      await tick()
+      assert.equal(orphaned, 1, 'it must not fire again')
+      assert.equal(probes, probesAtDeath, 'polling must stop after it fires')
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('reads the pid the shell passes through the environment', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: String(process.pid) },
+      onOrphaned: () => {},
+      intervalMs: 60_000,
+    })
+    try {
+      assert.equal(watch.watching, true)
+      assert.equal(watch.parentPid, process.pid)
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('treats this very process as alive by default, and a reaped pid as gone', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: String(process.pid) },
+      onOrphaned: () => assert.fail('our own pid is alive'),
+      intervalMs: 60_000,
+    })
+    watch.stop()
+
+    // A pid that cannot exist: the default probe must report it gone rather
+    // than throwing, or an orphaned sidecar would never notice.
+    let orphaned = 0
+    const dead = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '2147483646' },
+      onOrphaned: () => orphaned++,
+      intervalMs: 60_000,
+    })
+    dead.checkNow()
+    dead.stop()
+    assert.equal(orphaned, 1)
+  })
+
+  it('never keeps the process alive on its own', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => true,
+      onOrphaned: () => {},
+      intervalMs: 60_000,
+    })
+    try {
+      assert.equal(
+        watch.holdsProcessOpen,
+        false,
+        'the poll timer must be unref-ed'
+      )
+    } finally {
+      watch.stop()
+    }
+  })
+
+  it('is safe to stop twice', () => {
+    const watch = watchParentProcess({
+      env: { [PARENT_PID_ENV]: '4242' },
+      isAlive: () => true,
+      onOrphaned: () => {},
+      intervalMs: 60_000,
+    })
+    watch.stop()
+    watch.stop()
+    assert.equal(watch.watching, false)
+  })
+})

package/src/runtime/parent-watch.ts

@@ -0,0 +1,115 @@
+/**
+ * Environment variable a desktop shell uses to tell its sidecar which process
+ * it must not outlive.
+ */
+export const PARENT_PID_ENV = 'PIKKU_PARENT_PID'
+
+/**
+ * Environment variable a desktop shell uses to tell its sidecar where the
+ * SQLite file, uploaded content and runtime state belong. The shell resolves
+ * it from the platform's own app-data location, because a binary launched by
+ * double-click has no meaningful working directory.
+ */
+export const DATA_DIR_ENV = 'PIKKU_DATA_DIR'
+
+export type ParentWatchOptions = {
+  /** Where the parent pid is read from. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>
+  /** Probe for whether a pid is still running. Defaults to signal 0. */
+  isAlive?: (pid: number) => boolean
+  /** Run when the parent is found to be gone. Defaults to exiting cleanly. */
+  onOrphaned?: () => void
+  intervalMs?: number
+}
+
+export type ParentWatch = {
+  /** False when no usable parent pid was supplied — the watch is inert. */
+  readonly watching: boolean
+  readonly parentPid: number | undefined
+  /** True only if the poll timer would hold the event loop open. */
+  readonly holdsProcessOpen: boolean
+  /** Probe immediately rather than waiting for the next interval. */
+  checkNow(): void
+  stop(): void
+}
+
+/**
+ * A pid is alive if signalling it succeeds. `EPERM` also means alive — the
+ * process exists but belongs to another user — and only `ESRCH` means gone.
+ */
+const defaultIsAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+const parsePid = (raw: string | undefined): number | undefined => {
+  if (!raw) return undefined
+  if (!/^\d+$/.test(raw)) return undefined
+  const pid = Number(raw)
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined
+}
+
+/**
+ * Exit when the process that spawned us does.
+ *
+ * Tauri kills its sidecar on a clean exit, but a hard crash of the shell never
+ * runs that path. An orphaned pikku server keeps the SQLite file open, and the
+ * next launch — which single-instance only guards against a second *shell* —
+ * would be a second writer against the same database. Polling the parent is the only portable answer: neither
+ * `process.on('disconnect')` (no IPC channel here) nor a closed stdin is
+ * reliable across the platforms a desktop build targets.
+ *
+ * With no parent pid in the environment the watch is inert, so a server run
+ * from a terminal or a container behaves exactly as it did before.
+ */
+export const watchParentProcess = (
+  options: ParentWatchOptions = {}
+): ParentWatch => {
+  const env = options.env ?? process.env
+  const isAlive = options.isAlive ?? defaultIsAlive
+  const onOrphaned = options.onOrphaned ?? (() => process.exit(0))
+  const intervalMs = options.intervalMs ?? 1_000
+
+  const parentPid = parsePid(env[PARENT_PID_ENV])
+
+  let timer: ReturnType<typeof setInterval> | undefined
+  let fired = false
+
+  const stop = () => {
+    if (timer) {
+      clearInterval(timer)
+      timer = undefined
+    }
+  }
+
+  const checkNow = () => {
+    if (parentPid === undefined || fired) return
+    if (isAlive(parentPid)) return
+    fired = true
+    stop()
+    onOrphaned()
+  }
+
+  if (parentPid !== undefined) {
+    timer = setInterval(checkNow, intervalMs)
+    // The watch is a guard, not a reason to stay running: a server that has
+    // finished its work must still be allowed to exit.
+    timer.unref?.()
+  }
+
+  return {
+    get watching() {
+      return timer !== undefined
+    },
+    parentPid,
+    get holdsProcessOpen() {
+      return timer?.hasRef?.() ?? false
+    },
+    checkNow,
+    stop,
+  }
+}

package/src/sidecar-entry.test.ts

@@ -0,0 +1,89 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { SERVER_READY_MARKER } from '@pikku/deploy'
+
+import { StandaloneProviderAdapter } from './adapter.js'
+import { DATA_DIR_ENV, PARENT_PID_ENV } from './runtime/parent-watch.js'
+
+const baseContext = {
+  unit: { name: 'app', role: 'function' },
+  unitDir: '/build/app',
+  bootstrapPath: './.pikku/pikku-bootstrap.gen.js',
+  configImport: `import { createConfig } from './config.js'`,
+  configVar: 'createConfig',
+  servicesImport: `import { createSingletonServices } from './services.js'`,
+  servicesVar: 'createSingletonServices',
+  singletonServicesImport: '',
+  servicesType: 'Record<string, unknown>',
+  mcpImport: '',
+  mcpServerOption: '',
+} as never
+
+const entries = (['node', 'bun'] as const).map((runtime) => ({
+  runtime,
+  source: new StandaloneProviderAdapter({ runtime }).generateEntrySource(
+    baseContext
+  ),
+}))
+
+describe('the handshake a desktop shell reads off its sidecar', () => {
+  for (const { runtime, source } of entries) {
+    test(`the ${runtime} entry announces readiness with the shared marker`, () => {
+      assert.ok(
+        source.includes(SERVER_READY_MARKER),
+        'a shell waiting on `pikku: ready` would hang forever without it'
+      )
+      assert.match(
+        source,
+        /serverReadyLine|pikku: ready on http:\/\//,
+        'the line must carry a URL, not just the marker'
+      )
+    })
+
+    test(`the ${runtime} entry reports the port the server bound, not the one requested`, () => {
+      assert.match(
+        source,
+        /server\.port/,
+        'PORT=0 is how the shell avoids a bind race, so the requested port is useless'
+      )
+      assert.doesNotMatch(
+        source,
+        /ready on http:\/\/\$\{hostname\}:\$\{port\}/,
+        'announcing the requested port re-introduces the race'
+      )
+    })
+
+    test(`the ${runtime} entry announces readiness only after the server starts`, () => {
+      const readyAt = source.indexOf(SERVER_READY_MARKER)
+      const startAt = source.indexOf('await server.start()')
+      assert.ok(startAt > -1, 'the entry must start the server')
+      assert.ok(
+        readyAt > startAt,
+        'readiness printed before start() is a lie a parent will act on'
+      )
+    })
+
+    test(`the ${runtime} entry installs the orphan guard`, () => {
+      assert.match(
+        source,
+        /watchParentProcess\(\)/,
+        'a hard crash of the shell would otherwise orphan this process'
+      )
+      assert.match(source, /@pikku\/deploy-standalone\/runtime/)
+    })
+
+    test(`the ${runtime} entry still defaults to a fixed port outside a shell`, () => {
+      assert.match(
+        source,
+        /process\.env\.PORT \|\| '3000'/,
+        'an ordinary server deploy must keep its predictable port'
+      )
+    })
+  }
+
+  test('the environment contract is named in one place', () => {
+    assert.equal(PARENT_PID_ENV, 'PIKKU_PARENT_PID')
+    assert.equal(DATA_DIR_ENV, 'PIKKU_DATA_DIR')
+  })
+})