@pikku/deploy-standalone 0.12.11 → 0.12.13

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @pikku/deploy-standalone
 
+## 0.12.13
+
+### Patch Changes
+
+- 80eb5c0: Generate a desktop shell from `pikku deploy apply --desktop`
+
+  `pikku deploy apply --provider standalone --runtime bun --desktop` now emits a
+  `src-tauri/` crate that ships the compiled binary as a sidecar and opens a
+  window on the server's own HTTP origin, so cookies, CORS and OAuth behave
+  exactly as they do in a browser. Regeneration is idempotent and leaves an
+  edited file alone rather than overwriting it.
+
+  `--desktop-url https://app.example.com` builds the other shape: a shell that
+  points at an already-deployed server. Nothing is bundled — no sidecar, no
+  binary, and so no bun runtime to compile one — and the window is declared in
+  `tauri.conf.json` rather than opened from Rust, because the origin is known up
+  front. The url can also live in `pikku.config.json` as `deploy.desktop.url`,
+  alongside `deploy.desktop.identifier`.
+
+  Supporting changes: `SERVER_READY_MARKER` moved to `@pikku/deploy` (the CLI
+  re-exports it from its old path), both HTTP runtimes expose the port they
+  actually bound so `--port 0` reports a real port, and the generated server
+  entry exits when its parent process goes away.
+
+- 80eb5c0: feat: serve a built frontend from the pikku server's own origin
+
+  A new `frontend` key in `pikku.config.json` names a directory of built
+  frontend output. `pikku serve` mounts it, and `pikku deploy` ships it inside
+  the distributable — into a directory beside the bundle for the node runtime,
+  and embedded in the binary for a `bun build --compile` standalone. `pikku dev`
+  deliberately ignores it and says so, because the frontend's own dev server owns
+  that job.
+
+  Pikku reads the frontend's output and never builds it, so an unbuilt directory
+  fails with a message that says which build to run rather than booting a server
+  that answers every page with a 404.
+
+- Updated dependencies [80eb5c0]
+- Updated dependencies [80eb5c0]
+  - @pikku/deploy@0.12.2
+
+## 0.12.12
+
+### Patch Changes
+
+- 32616af: Give the deploy pipeline one shared contract instead of a copy per adapter
+
+  `DeploymentManifest`, `DeploymentUnit`, `EntryGenerationContext` and
+  `ProviderAdapter` were hand-copied into eleven source files across the four
+  provider adapters and the CLI — three copies inside `@pikku/deploy-cloudflare`
+  alone. Nothing compared the copies, so they had already drifted: several typed
+  `role` as a bare `string`, and none carried the manifest's addon-scoping fields.
+
+  They now live in a new zero-dependency `@pikku/deploy` package that every
+  adapter and the CLI import, and each adapter declares `implements
+ProviderAdapter` so the compiler checks it against the contract it claims to
+  satisfy. That check immediately caught a real disagreement: the deploy result's
+  `workersDeployed` and `resourcesCreated` were `string[]` from Cloudflare — the
+  shape the result file and the generated SDK types already record — but
+  `Array<{ name: string }>` from the standalone adapter. Both are now `string[]`.
+
+  The Lambda and Azure adapters also derived their esbuild externals from a
+  hand-written list of 25 node builtins, so anything outside it (`async_hooks`,
+  `perf_hooks`, `timers`, `http2`, …) was bundled instead of resolved from the
+  runtime. They now use `nodeBuiltinExternals()`, which reads `builtinModules`
+  from the running Node and cannot fall behind it.
+
+- Updated dependencies [32616af]
+  - @pikku/deploy@0.12.1
+
 ## 0.12.11
 
 ### Patch Changes

package/dist/adapter.d.ts

@@ -16,55 +16,48 @@
  *   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';
 export type StandaloneRuntime = 'node' | 'bun';
+/**
+ * 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 declare const STANDALONE_FRONTEND_DIR = "frontend";
+/**
+ * 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 declare const STANDALONE_FRONTEND_MANIFEST = "./frontend-assets.gen.js";
 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;
 }
-type DeploymentHandler = {
-    type: 'fetch';
-    routes: Array<{
-        method: string;
-        route: string;
-        pikkuFuncId: string;
-    }>;
-} | {
-    type: 'queue';
-    queueName: string;
-} | {
-    type: 'scheduled';
-    schedule: string;
-    taskName: string;
-};
-interface DeploymentUnit {
-    name: string;
-    role: string;
-    functionIds: string[];
-    services: Array<{
-        capability: string;
-        sourceServiceName: string;
-    }>;
-    dependsOn: string[];
-    handlers: DeploymentHandler[];
-    tags: string[];
-}
-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 declare class StandaloneProviderAdapter {
+export declare 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);
     generateEntrySource(ctx: EntryGenerationContext): string;
     private generateNodeEntrySource;
@@ -89,13 +82,12 @@ export declare class StandaloneProviderAdapter {
         }[];
         workersDeployed?: undefined;
         resourcesCreated?: undefined;
+        targetTriple?: undefined;
     } | {
         success: boolean;
-        workersDeployed: {
-            name: string;
-        }[];
+        workersDeployed: string[];
         resourcesCreated: never[];
         errors: never[];
+        targetTriple: string | undefined;
     }>;
 }
-export {};

package/dist/adapter.js

@@ -1,28 +1,60 @@
+import { nodeBuiltinExternals, SERVER_READY_MARKER } from '@pikku/deploy';
 /**
- * Standalone provider adapter for the Pikku deploy pipeline.
- *
- * Produces a self-contained distributable directory:
- *
- *   {app-name}/
- *   ├── bundle.js            # esbuild bundle (all deps inlined)
- *   ├── config/              # user config (env, secrets, etc.)
- *
- * Two runtimes, selected via `--runtime`:
+ * 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';
+/**
+ * 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';
+/**
+ * Lines every standalone entry ends with, whatever the runtime.
  *
- * - `node` (default): uses `@pikku/node-http-server` (pure JS, node:http) —
- *   the same server `pikku dev` and the container deploy entry use, so all
- *   three share one HTTP path. Ships `bundle.js`; run with `node bundle.js`.
- * - `bun`: uses `@pikku/bun-server` (Bun.serve, native WebSockets) and
- *   compiles the bundle into a single self-contained executable via
- *   `bun build --compile`. No runtime needed on the target host.
+ * 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 = () => [
+    `  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 () => {
+    try {
+        const { execFileSync } = await import('node:child_process');
+        return execFileSync('rustc', ['-vV'], { encoding: 'utf-8', stdio: 'pipe' });
+    }
+    catch {
+        return undefined;
+    }
+};
 export class StandaloneProviderAdapter {
     name = 'standalone';
     deployDirName = 'standalone';
     singleUnit = true;
     runtime;
+    desktop;
+    projectDir;
+    desktopIdentifier;
+    desktopUrl;
     constructor(options = {}) {
         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) {
         if (this.runtime === 'bun') {
@@ -35,12 +67,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,
@@ -72,9 +111,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) => {`,
@@ -87,6 +138,7 @@ export class StandaloneProviderAdapter {
             `  await triggerService.start()`,
             `  server.enableExitOnSignals()`,
             `  await server.start()`,
+            ...sidecarHandshakeLines(),
             `}`,
             ``,
             `main().catch((err) => {`,
@@ -100,10 +152,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,
@@ -135,12 +191,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) => {`,
@@ -160,33 +230,12 @@ export class StandaloneProviderAdapter {
         return new Map();
     }
     getExternals() {
-        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;
     }
@@ -195,8 +244,34 @@ export class StandaloneProviderAdapter {
     }
     async deploy(options) {
         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 } = await import('node:fs/promises');
+        const { cp, readdir, writeFile, copyFile, mkdir } = await import('node:fs/promises');
         const { existsSync } = await import('node:fs');
         // Find the unit dir with the bundle
         const entries = await readdir(buildDir);
@@ -218,6 +293,21 @@ export class StandaloneProviderAdapter {
             await copyFile(join(unitDir, 'bundle.js.map'), join(outDir, 'bundle.js.map'));
         }
         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');
@@ -245,6 +335,56 @@ export class StandaloneProviderAdapter {
                 };
             }
         }
+        // --- 2c. desktop: wrap the server in a shell, or point one at a remote ---
+        let targetTriple;
+        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) {
+                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 });
@@ -264,9 +404,10 @@ export class StandaloneProviderAdapter {
         logger.info(`Output: ${outDir}`);
         return {
             success: true,
-            workersDeployed: [{ name: appName }],
+            workersDeployed: [appName],
             resourcesCreated: [],
             errors: [],
+            targetTriple,
         };
     }
 }

package/dist/index.d.ts

@@ -11,5 +11,5 @@
  */
 import { StandaloneProviderAdapter, type StandaloneProviderAdapterOptions } from './adapter.js';
 export { StandaloneProviderAdapter };
-export type { StandaloneProviderAdapterOptions, } from './adapter.js';
+export type { StandaloneProviderAdapterOptions } from './adapter.js';
 export declare const createAdapter: (options?: StandaloneProviderAdapterOptions) => StandaloneProviderAdapter;

package/dist/runtime/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@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/dist/runtime/index.js

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

package/dist/runtime/parent-watch.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Environment variable a desktop shell uses to tell its sidecar which process
+ * it must not outlive.
+ */
+export declare 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 declare 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;
+};
+/**
+ * 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 declare const watchParentProcess: (options?: ParentWatchOptions) => ParentWatch;

package/dist/runtime/parent-watch.js

@@ -0,0 +1,87 @@
+/**
+ * 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';
+/**
+ * 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) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+};
+const parsePid = (raw) => {
+    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 = {}) => {
+    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;
+    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,
+    };
+};