@pikku/deploy-standalone 0.12.11 → 0.12.13

package/src/adapter.ts

@@ -16,53 +16,92 @@
  *   compiles the bundle into a single self-contained executable via
  *   `bun build --compile`. No runtime needed on the target host.
  */
+import type { EntryGenerationContext, ProviderAdapter } from '@pikku/deploy'
+import { nodeBuiltinExternals, SERVER_READY_MARKER } from '@pikku/deploy'
 
 export type StandaloneRuntime = 'node' | 'bun'
 
-export interface StandaloneProviderAdapterOptions {
-  runtime?: StandaloneRuntime
-}
+/**
+ * Directory the built frontend is copied to, both inside the unit and beside
+ * the shipped bundle. The node entry resolves it relative to itself at runtime,
+ * so the two have to agree.
+ */
+export const STANDALONE_FRONTEND_DIR = 'frontend'
 
-type DeploymentHandler =
-  | {
-      type: 'fetch'
-      routes: Array<{ method: string; route: string; pikkuFuncId: string }>
-    }
-  | { type: 'queue'; queueName: string }
-  | { type: 'scheduled'; schedule: string; taskName: string }
+/**
+ * Module the bun entry imports its embedded assets from. It stays out of the
+ * esbuild bundle — esbuild rejects the `with { type: 'file' }` attribute the
+ * manifest is built on — and is resolved by `bun build --compile` instead.
+ */
+export const STANDALONE_FRONTEND_MANIFEST = './frontend-assets.gen.js'
 
-interface DeploymentUnit {
-  name: string
-  role: string
-  functionIds: string[]
-  services: Array<{ capability: string; sourceServiceName: string }>
-  dependsOn: string[]
-  handlers: DeploymentHandler[]
-  tags: string[]
+/**
+ * Lines every standalone entry ends with, whatever the runtime.
+ *
+ * The ready line is the handshake a parent process — `pikku dev --spawn`, or
+ * the desktop shell that runs this binary as a sidecar — blocks on. It carries
+ * `server.port` rather than the requested port because a shell passes `PORT=0`:
+ * picking a free port in the parent and handing it down races anything else
+ * that binds it in between, so the server binds first and reports back.
+ */
+const sidecarHandshakeLines = (): string[] => [
+  `  watchParentProcess()`,
+  `  console.log(\`${SERVER_READY_MARKER} on http://\${hostname}:\${server.port}\`)`,
+]
+
+const SIDECAR_RUNTIME_IMPORT = `import { watchParentProcess } from '@pikku/deploy-standalone/runtime'`
+
+/**
+ * `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
+ * cases rustc knows better about (musl, Rosetta) are the ones where a Rust
+ * toolchain is present anyway.
+ */
+const rustcHostOutput = async (): Promise<string | undefined> => {
+  try {
+    const { execFileSync } = await import('node:child_process')
+    return execFileSync('rustc', ['-vV'], { encoding: 'utf-8', stdio: 'pipe' })
+  } catch {
+    return undefined
+  }
 }
 
-interface EntryGenerationContext {
-  unit: DeploymentUnit
-  unitDir: string
-  bootstrapPath: string
-  configImport: string
-  configVar: string
-  servicesImport: string
-  servicesVar: string
-  singletonServicesImport: string
-  servicesType: string
-  mcpImport: string
-  mcpServerOption: string
+export interface StandaloneProviderAdapterOptions {
+  runtime?: StandaloneRuntime
+  /**
+   * Generate a desktop shell (Tauri) around the compiled binary. Requires the
+   * `bun` runtime — the shell ships the binary as a sidecar, and only that
+   * runtime produces one. A shell pointed at {@link desktopUrl} ships no binary
+   * and so has no such requirement.
+   */
+  desktop?: boolean
+  /** Project root. The shell crate is written to `<projectDir>/src-tauri`. */
+  projectDir?: string
+  /** Bundle identifier for the shell. Derived from the app name when absent. */
+  desktopIdentifier?: string
+  /**
+   * An already-deployed server for the shell to open, instead of bundling one.
+   * The window is a webview onto that origin and nothing else is shipped.
+   */
+  desktopUrl?: string
 }
 
-export class StandaloneProviderAdapter {
+export class StandaloneProviderAdapter implements ProviderAdapter {
   readonly name = 'standalone'
   readonly deployDirName = 'standalone'
   readonly singleUnit = true
   readonly runtime: StandaloneRuntime
+  readonly desktop: boolean
+  readonly projectDir?: string
+  readonly desktopIdentifier?: string
+  readonly desktopUrl?: string
 
   constructor(options: StandaloneProviderAdapterOptions = {}) {
     this.runtime = options.runtime ?? 'node'
+    this.desktop = options.desktop ?? Boolean(options.desktopUrl)
+    this.projectDir = options.projectDir
+    this.desktopIdentifier = options.desktopIdentifier
+    this.desktopUrl = options.desktopUrl
   }
 
   generateEntrySource(ctx: EntryGenerationContext): string {
@@ -77,12 +116,19 @@ export class StandaloneProviderAdapter {
       `// Generated standalone entry — all functions in one process`,
       `import { LocalEventHubService } from '@pikku/core/channel/local'`,
       `import { ConsoleLogger, InMemoryQueueService, InMemoryTriggerService, InMemoryWorkflowService } from '@pikku/core/services'`,
-      `import { pikkuState } from '@pikku/core/ecosystem'`,
-      `import { wireAgentScorerQueueWorkers } from '@pikku/core/ecosystem/agent-scorer'`,
+      `import { pikkuState } from '@pikku/core/state'`,
+      `import { wireAgentScorerQueueWorkers } from '@pikku/core/agent-scorer'`,
       `import { InMemorySchedulerService } from '@pikku/schedule'`,
       `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
+        ? [
+            `import { dirname as __pikkuDirname, join as __pikkuJoin } from 'node:path'`,
+            `import { fileURLToPath as __pikkuFileURLToPath } from 'node:url'`,
+          ]
+        : []),
       ``,
       ctx.configImport,
       ctx.servicesImport,
@@ -114,9 +160,21 @@ export class StandaloneProviderAdapter {
       `  })`,
       `  pikkuState(null, 'package', 'singletonServices', singletonServices)`,
       ``,
+      ...(ctx.frontend
+        ? [
+            // Resolved from the running bundle rather than baked in at build
+            // time, so the distributable stays movable.
+            `  const staticMounts = [{`,
+            `    urlPrefix: '${ctx.frontend.urlPrefix}',`,
+            `    directory: __pikkuJoin(__pikkuDirname(__pikkuFileURLToPath(import.meta.url)), '${STANDALONE_FRONTEND_DIR}'),`,
+            `    spaFallback: ${ctx.frontend.spaFallback},`,
+            `  }]`,
+            ``,
+          ]
+        : []),
       `  const wss = new WebSocketServer({ noServer: true, maxPayload: DEFAULT_WS_MAX_PAYLOAD })`,
       `  const server = new PikkuNodeHTTPServer(`,
-      `    { ...config, port, hostname },`,
+      `    { ...config, port, hostname${ctx.frontend ? ', staticMounts' : ''} },`,
       `    logger,`,
       `    {`,
       `      ${ctx.mcpServerOption}configureServer: (httpServer) => {`,
@@ -129,6 +187,7 @@ export class StandaloneProviderAdapter {
       `  await triggerService.start()`,
       `  server.enableExitOnSignals()`,
       `  await server.start()`,
+      ...sidecarHandshakeLines(),
       `}`,
       ``,
       `main().catch((err) => {`,
@@ -143,10 +202,14 @@ export class StandaloneProviderAdapter {
     return [
       `// Generated standalone entry (bun runtime) — all functions in one process`,
       `import { ConsoleLogger, InMemoryQueueService, InMemoryTriggerService, InMemoryWorkflowService } from '@pikku/core/services'`,
-      `import { pikkuState } from '@pikku/core/ecosystem'`,
-      `import { wireAgentScorerQueueWorkers } from '@pikku/core/ecosystem/agent-scorer'`,
+      SIDECAR_RUNTIME_IMPORT,
+      `import { pikkuState } from '@pikku/core/state'`,
+      `import { wireAgentScorerQueueWorkers } from '@pikku/core/agent-scorer'`,
       `import { InMemorySchedulerService } from '@pikku/schedule'`,
       `import { PikkuBunServer, BunEventHubService } from '@pikku/bun-server'`,
+      ...(ctx.frontend
+        ? [`import { frontendAssets } from '${STANDALONE_FRONTEND_MANIFEST}'`]
+        : []),
       ``,
       ctx.configImport,
       ctx.servicesImport,
@@ -178,12 +241,26 @@ export class StandaloneProviderAdapter {
       `  })`,
       `  pikkuState(null, 'package', 'singletonServices', singletonServices)`,
       ``,
-      `  const server = new PikkuBunServer({ ...config, port, hostname }, logger, { ${ctx.mcpServerOption}eventHub })`,
+      ...(ctx.frontend
+        ? [
+            // A compiled binary has no directory to read: every file was
+            // embedded, and the map is the only way back to it.
+            `  const staticMounts = [{`,
+            `    urlPrefix: '${ctx.frontend.urlPrefix}',`,
+            `    directory: '',`,
+            `    spaFallback: ${ctx.frontend.spaFallback},`,
+            `    assets: frontendAssets,`,
+            `  }]`,
+            ``,
+          ]
+        : []),
+      `  const server = new PikkuBunServer({ ...config, port, hostname${ctx.frontend ? ', staticMounts' : ''} }, logger, { ${ctx.mcpServerOption}eventHub })`,
       `  await server.init()`,
       `  await schedulerService.start()`,
       `  await triggerService.start()`,
       `  server.enableExitOnSignals()`,
       `  await server.start()`,
+      ...sidecarHandshakeLines(),
       `}`,
       ``,
       `main().catch((err) => {`,
@@ -207,33 +284,12 @@ export class StandaloneProviderAdapter {
   }
 
   getExternals(): string[] {
-    const externals = [
-      'node:*',
-      'child_process',
-      'crypto',
-      'fs',
-      'http',
-      'https',
-      'net',
-      'os',
-      'path',
-      'stream',
-      'url',
-      'util',
-      'zlib',
-      'events',
-      'buffer',
-      'querystring',
-      'tls',
-      'dns',
-      'dgram',
-      'cluster',
-      'worker_threads',
-    ]
+    const externals = nodeBuiltinExternals()
     if (this.runtime === 'bun') {
       // Bun-native builtins are provided by the runtime and resolved by
       // `bun build --compile` — leave them as imports rather than inlining.
       externals.push('bun', 'bun:*', 'bun:sqlite', 'bun:ffi')
+      externals.push(STANDALONE_FRONTEND_MANIFEST)
     }
     return externals
   }
@@ -248,8 +304,37 @@ export class StandaloneProviderAdapter {
     onProgress?: (step: string, detail: string) => void
   }) {
     const { buildDir, logger } = options
+
+    // Checked before anything expensive runs: a `--desktop` deploy that cannot
+    // produce a shell should say so now, not after a bun compile.
+    if (this.desktop) {
+      if (!this.desktopUrl && this.runtime !== 'bun') {
+        return {
+          success: false,
+          errors: [
+            {
+              step: 'desktop',
+              error: `A desktop shell ships the server as a sidecar binary, which only the bun runtime produces. Re-run with --runtime bun (got '${this.runtime}').`,
+            },
+          ],
+        }
+      }
+      if (!this.projectDir) {
+        return {
+          success: false,
+          errors: [
+            {
+              step: 'desktop',
+              error:
+                'No project directory was supplied, so there is nowhere to write src-tauri/.',
+            },
+          ],
+        }
+      }
+    }
+
     const { join, dirname } = await import('node:path')
-    const { readdir, writeFile, copyFile, mkdir } =
+    const { cp, readdir, writeFile, copyFile, mkdir } =
       await import('node:fs/promises')
     const { existsSync } = await import('node:fs')
 
@@ -282,6 +367,22 @@ export class StandaloneProviderAdapter {
     }
     logger.info(`Bundle: ${join(outDir, 'bundle.js')}`)
 
+    // --- 2a. Frontend, when the build produced one ---
+    // Both runtimes need it here rather than only in the build directory: node
+    // resolves the mount relative to the shipped bundle, and `bun build
+    // --compile` follows the manifest import out of the copy it is given.
+    const frontendDir = join(unitDir, STANDALONE_FRONTEND_DIR)
+    if (existsSync(frontendDir)) {
+      await cp(frontendDir, join(outDir, STANDALONE_FRONTEND_DIR), {
+        recursive: true,
+      })
+      const manifestName = STANDALONE_FRONTEND_MANIFEST.replace('./', '')
+      if (existsSync(join(unitDir, manifestName))) {
+        await copyFile(join(unitDir, manifestName), join(outDir, manifestName))
+      }
+      logger.info(`Frontend: ${join(outDir, STANDALONE_FRONTEND_DIR)}`)
+    }
+
     // --- 2b. bun runtime: compile the bundle into a self-contained binary ---
     if (this.runtime === 'bun') {
       const { execFileSync } = await import('node:child_process')
@@ -313,6 +414,58 @@ export class StandaloneProviderAdapter {
       }
     }
 
+    // --- 2c. desktop: wrap the server in a shell, or point one at a remote ---
+    let targetTriple: string | undefined
+    if (this.desktop && this.projectDir) {
+      const { generateTauriShell, tauriBundleIdentifier } =
+        await import('./tauri/generate.js')
+      const { hostTargetTriple } = await import('./tauri/target-triple.js')
+      const { renderTauriNextSteps } = await import('./tauri/next-steps.js')
+      try {
+        const rustcVersionVerbose = await rustcHostOutput()
+        targetTriple = hostTargetTriple({ rustcVersionVerbose })
+        const shell = await generateTauriShell({
+          projectDir: this.projectDir,
+          appName,
+          identifier: this.desktopIdentifier ?? tauriBundleIdentifier(appName),
+          targetTriple,
+          ...(this.desktopUrl
+            ? { remoteUrl: this.desktopUrl }
+            : { binaryPath: join(outDir, appName) }),
+        })
+        logger.info(`Desktop shell: ${shell.dir} (${shell.targetTriple})`)
+        if (shell.written.length) {
+          logger.info(`  wrote ${shell.written.join(', ')}`)
+        }
+        if (shell.preserved.length) {
+          logger.info(
+            `  kept your edits, not regenerated: ${shell.preserved.join(', ')}`
+          )
+        }
+        if (shell.sidecar) {
+          logger.info(`  sidecar: binaries/${shell.sidecar.fileName}`)
+        } else {
+          logger.info(`  window opens: ${this.desktopUrl}`)
+        }
+        for (const line of renderTauriNextSteps({
+          shellDir: shell.dir,
+          hasRust: rustcVersionVerbose !== undefined,
+        })) {
+          logger.info(line)
+        }
+      } catch (e: unknown) {
+        return {
+          success: false,
+          errors: [
+            {
+              step: 'desktop',
+              error: e instanceof Error ? e.message : String(e),
+            },
+          ],
+        }
+      }
+    }
+
     // --- 3. config/ — empty template with .env example ---
     const configDir = join(outDir, 'config')
     await mkdir(configDir, { recursive: true })
@@ -341,9 +494,10 @@ export class StandaloneProviderAdapter {
 
     return {
       success: true,
-      workersDeployed: [{ name: appName }],
+      workersDeployed: [appName],
       resourcesCreated: [],
       errors: [],
+      targetTriple,
     }
   }
 }

package/src/desktop-deploy.test.ts

@@ -0,0 +1,167 @@
+import { after, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { StandaloneProviderAdapter } from './adapter.js'
+import { sidecarFileName } from './tauri/target-triple.js'
+
+const tempDirs: string[] = []
+
+after(() => {
+  for (const dir of tempDirs) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+const silentLogger = { info: () => {}, error: () => {} }
+
+const builtUnit = async () => {
+  const buildDir = await mkdtemp(join(tmpdir(), 'pikku-desktop-deploy-'))
+  tempDirs.push(buildDir)
+  const unitDir = join(buildDir, 'shop')
+  await mkdir(unitDir, { recursive: true })
+  await writeFile(join(unitDir, 'bundle.js'), 'console.log("bundle")\n')
+
+  const projectDir = await mkdtemp(join(tmpdir(), 'pikku-desktop-project-'))
+  tempDirs.push(projectDir)
+  return { buildDir, projectDir, outDir: join(buildDir, 'shop-dist') }
+}
+
+describe('deploying a standalone unit as a desktop shell', () => {
+  test('refuses without the bun runtime, since there is no binary to ship', async () => {
+    const { buildDir, projectDir } = await builtUnit()
+
+    const result = await new StandaloneProviderAdapter({
+      runtime: 'node',
+      desktop: true,
+      projectDir,
+    }).deploy({ buildDir, logger: silentLogger })
+
+    assert.equal(result.success, false)
+    assert.match(result.errors[0]!.error, /bun/)
+  })
+
+  test('refuses when it was not told where the project lives', async () => {
+    const { buildDir } = await builtUnit()
+
+    const result = await new StandaloneProviderAdapter({
+      runtime: 'bun',
+      desktop: true,
+    }).deploy({ buildDir, logger: silentLogger })
+
+    assert.equal(result.success, false)
+    assert.match(result.errors[0]!.error, /project/i)
+  })
+
+  test('generates the shell around the compiled binary', async () => {
+    const { buildDir, projectDir, outDir } = await builtUnit()
+
+    const result = await new StandaloneProviderAdapter({
+      runtime: 'bun',
+      desktop: true,
+      projectDir,
+    }).deploy({ buildDir, logger: silentLogger })
+
+    assert.deepEqual(result.errors, [])
+    assert.equal(result.success, true)
+
+    const shellDir = join(projectDir, 'src-tauri')
+    const conf = JSON.parse(
+      await readFile(join(shellDir, 'tauri.conf.json'), 'utf-8')
+    )
+    assert.equal(conf.productName, 'shop')
+    assert.equal(conf.identifier, 'com.shop.desktop')
+    assert.deepEqual(conf.bundle.externalBin, ['binaries/shop'])
+
+    // The sidecar must be the binary the compile step actually produced, under
+    // the triple-suffixed name externalBin resolves.
+    const compiled = await readFile(join(outDir, 'shop'))
+    const shipped = await readFile(
+      join(shellDir, 'binaries', sidecarFileName('shop', result.targetTriple!))
+    )
+    assert.ok(compiled.equals(shipped))
+    assert.notEqual(
+      (
+        await stat(
+          join(
+            shellDir,
+            'binaries',
+            sidecarFileName('shop', result.targetTriple!)
+          )
+        )
+      ).mode & 0o111,
+      0
+    )
+  })
+
+  test('takes an explicit bundle identifier over the derived one', async () => {
+    const { buildDir, projectDir } = await builtUnit()
+
+    await new StandaloneProviderAdapter({
+      runtime: 'bun',
+      desktop: true,
+      projectDir,
+      desktopIdentifier: 'com.acme.pos',
+    }).deploy({ buildDir, logger: silentLogger })
+
+    const conf = JSON.parse(
+      await readFile(join(projectDir, 'src-tauri', 'tauri.conf.json'), 'utf-8')
+    )
+    assert.equal(conf.identifier, 'com.acme.pos')
+  })
+
+  test('points a remote shell at the url, with no runtime requirement', async () => {
+    const { buildDir, projectDir } = await builtUnit()
+
+    // Nothing is bundled, so there is no binary to compile and no reason to
+    // insist on bun — the node runtime has to be allowed through here.
+    const result = await new StandaloneProviderAdapter({
+      runtime: 'node',
+      desktop: true,
+      desktopUrl: 'https://shop.example.com',
+      projectDir,
+    }).deploy({ buildDir, logger: silentLogger })
+
+    assert.deepEqual(result.errors, [])
+    assert.equal(result.success, true)
+
+    const shellDir = join(projectDir, 'src-tauri')
+    const conf = JSON.parse(
+      await readFile(join(shellDir, 'tauri.conf.json'), 'utf-8')
+    )
+    assert.equal(conf.bundle.externalBin, undefined)
+    assert.equal(conf.app.windows[0].url, 'https://shop.example.com')
+    await assert.rejects(
+      () => stat(join(shellDir, 'binaries')),
+      'a remote shell ships no sidecar'
+    )
+  })
+
+  test('refuses a url that is not http(s)', async () => {
+    const { buildDir, projectDir } = await builtUnit()
+
+    const result = await new StandaloneProviderAdapter({
+      runtime: 'node',
+      desktop: true,
+      desktopUrl: 'file:///etc/passwd',
+      projectDir,
+    }).deploy({ buildDir, logger: silentLogger })
+
+    assert.equal(result.success, false)
+    assert.match(result.errors[0]!.error, /http/i)
+  })
+
+  test('a plain standalone deploy generates no shell at all', async () => {
+    const { buildDir, projectDir } = await builtUnit()
+
+    await new StandaloneProviderAdapter({
+      runtime: 'bun',
+      projectDir,
+    }).deploy({ buildDir, logger: silentLogger })
+
+    await assert.rejects(() => stat(join(projectDir, 'src-tauri')))
+  })
+})

package/src/index.ts

@@ -16,9 +16,7 @@ import {
 } from './adapter.js'
 
 export { StandaloneProviderAdapter }
-export type {
-  StandaloneProviderAdapterOptions,
-} from './adapter.js'
+export type { StandaloneProviderAdapterOptions } from './adapter.js'
 
 export const createAdapter = (options?: StandaloneProviderAdapterOptions) =>
   new StandaloneProviderAdapter(options)

package/src/runtime/index.ts

@@ -0,0 +1,13 @@
+/**
+ * `@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'

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 })
+    }
+  })
+})