@pikku/deploy-standalone 0.12.12 → 0.12.13

package/knowledge/decisions/a-remote-desktop-shell-bundles-nothing.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: A remote desktop shell bundles nothing
+description: --desktop-url produces a window onto an already-deployed server — no sidecar, no binary, no bun requirement — with the window declared in tauri.conf.json rather than opened from Rust
+tags: [tauri, desktop, standalone, remote]
+---
+
+# A remote desktop shell bundles nothing
+
+`pikku deploy apply --desktop-url https://app.example.com` generates the same
+`src-tauri/` crate as the sidecar shell, minus everything that exists to run a
+server: no `externalBin`, no `tauri-plugin-shell`, no binary copied into
+`binaries/`, and no `--runtime bun` requirement, because there is nothing to
+compile. The app is a window onto a server someone else's deploy already put on
+the internet.
+
+The window is **declared in `tauri.conf.json`**, not built from Rust. That is
+the whole difference in the generated program. A sidecar binds its port at
+launch, so its origin is unknown until it says so and only Rust can open the
+window; a remote url is known before a line of Rust is written, so `main.rs`
+keeps nothing but the single-instance plugin.
+
+The origin rule from
+[the sidecar shell](the-desktop-shell-runs-the-server-as-a-sidecar.md) is
+unchanged and is why this mode is worth having at all: the webview loads the
+real `https://` origin, so cookies are first-party, there is no CORS, and OAuth
+redirects land where the server expects. A shell that instead bundled the
+frontend and served it from `tauri://localhost` would break every one of those
+— which is exactly what "remote origin only" rules out.
+
+The url is validated as `http:` or `https:` at generate time. Anything else
+builds a crate that fails at runtime, in a window with no address bar to
+diagnose it from.
+
+**What this rules out:** bundling the frontend into the shell, a shell that
+falls back to a local server when the remote is unreachable, and mixing the two
+modes — a binary and a url together is refused rather than silently shipping a
+sidecar nothing starts.

package/knowledge/decisions/deploy-consumes-a-built-frontend.md

@@ -0,0 +1,33 @@
+---
+type: decision
+title: Deploy consumes a built frontend, it does not build one
+description: pikku reads an already-built client directory named by the frontend config key; running the frontend's build command is the project's job
+tags: [frontend, deploy, standalone, cli]
+---
+
+# Deploy consumes a built frontend, it does not build one
+
+`frontend` in `pikku.config.json` names a **directory of built output** —
+`{ dir: './web/dist', urlPrefix: '/', spaFallback: true }` — not a project to
+build. `pikku deploy` reads that directory. It does not run `vite build`, does
+not shell out to a package manager, and fails with a plain error if the
+directory is absent rather than trying to produce it.
+
+Building the frontend would mean pikku deciding which package manager runs,
+which script name means "build", which workspace the frontend lives in, what
+environment variables it needs, and what to do when that build fails inside a
+deploy. Every one of those is a project-level answer that pikku would be
+guessing at, and guessing wrong is worse than not trying: a deploy that
+silently rebuilds can ship output that differs from what the project's own CI
+verified. `yarn build && pikku deploy` states the order explicitly and keeps the
+two steps independently debuggable.
+
+The ordering constraint that this creates is real and worth naming. The bun path
+embeds assets by generating a manifest of static imports, which means the build
+sequence is fixed: **frontend build → manifest generation → server bundle →
+`bun build --compile`**. A frontend that has not been built yet cannot be
+enumerated, so there is no arrangement in which pikku could usefully build it
+later.
+
+**What this rules out:** a `frontend.build` command in the config, and any
+deploy step that invokes a package manager on the user's behalf.

package/knowledge/decisions/desktop-builds-are-unsigned-and-never-update-themselves.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: Desktop builds are unsigned and never update themselves
+description: Code signing, notarization and auto-update are deliberately absent from the first version of the Tauri shell — a known limitation, not an oversight
+tags: [tauri, desktop, limitations, distribution]
+---
+
+# Desktop builds are unsigned and never update themselves
+
+The generated shell has no signing pipeline and no updater. Both were left out
+on purpose, and both need building before anything is distributed to people who
+did not compile it themselves.
+
+What this means in practice today:
+
+- **macOS Gatekeeper will refuse the app on first launch.** An unsigned,
+  un-notarized `.app` downloaded from anywhere gets quarantined; the user has to
+  right-click → Open, or clear the quarantine attribute by hand. This is
+  accepted for now.
+- **Windows SmartScreen shows an unknown-publisher warning** for the same reason.
+- **There is no update path.** A shipped build stays the version it was. Tauri's
+  updater plugin is not wired in, no update endpoint exists, and — relevant
+  later — the updater requires signing keys, so the two gaps have to be closed
+  together rather than in either order.
+
+Signing is not something the generator can quietly grow, because it needs
+secrets the build machine has to hold: an Apple Developer ID certificate plus an
+app-specific password or API key for notarization, and an Authenticode
+certificate on Windows. That is CI configuration and key custody, not code
+generation, which is why it is a separate piece of work rather than a flag.
+
+**What this rules out for now:** distributing a build to end users without
+telling them how to get past Gatekeeper, and any claim that a shipped desktop
+app can be patched after release.

package/knowledge/decisions/index.md

@@ -0,0 +1,19 @@
+---
+type: overview
+title: Decisions
+description: What "a standalone unit with a UI" does and does not mean, and what a double-clickable build of it is
+---
+
+# Decisions
+
+<!-- pikku:knowledge-index -->
+
+- [A remote desktop shell bundles nothing](a-remote-desktop-shell-bundles-nothing.md) — --desktop-url produces a window onto an already-deployed server — no sidecar, no binary, no bun requirement — with the window declared in tauri.conf.json rather than opened from Rust
+- [A pikku server serves a static frontend, not a rendered one](a-pikku-server-serves-a-static-frontend.md) — The frontend is TanStack Start built to static output and served through a static mount; pikku never runs a framework renderer in-process
+- [Deploy consumes a built frontend, it does not build one](deploy-consumes-a-built-frontend.md) — pikku reads an already-built client directory named by the frontend config key; running the frontend's build command is the project's job
+- [Desktop builds are unsigned and never update themselves](desktop-builds-are-unsigned-and-never-update-themselves.md) — Code signing, notarization and auto-update are deliberately absent from the first version of the Tauri shell — a known limitation, not an oversight
+- [Standalone assets are embedded in the bun binary](standalone-assets-are-embedded-in-the-bun-binary.md) — A generated manifest of `with { type: 'file' }` imports puts the frontend inside the compiled binary; the imports must be static literals, which fixes the build order
+- [The desktop shell runs the server as a sidecar, not embedded](the-desktop-shell-runs-the-server-as-a-sidecar.md) — Tauri spawns the compiled pikku binary and points the webview at its HTTP origin, so cookies, CORS and OAuth behave exactly as they do in a browser
+- [The sidecar reports its port; the shell never picks one](the-sidecar-reports-its-port-the-shell-never-picks-one.md) — The server binds :0 and prints the port it got on the ready line; Rust blocks on that line rather than choosing a free port and passing it down
+
+<!-- /pikku:knowledge-index -->

package/knowledge/decisions/standalone-assets-are-embedded-in-the-bun-binary.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: Standalone assets are embedded in the bun binary
+description: A generated manifest of `with { type: 'file' }` imports puts the frontend inside the compiled binary; the imports must be static literals, which fixes the build order
+tags: [frontend, standalone, bun, assets]
+---
+
+# Standalone assets are embedded in the bun binary
+
+On the bun runtime the frontend ships **inside** the compiled binary rather than
+beside it. `bun build --compile` embeds any module imported with
+`with { type: 'file' }`, and `Bun.file()` reads the embedded path back at
+runtime. That is what makes the artifact a single file you can hand someone,
+which was the whole premise of the feature.
+
+This was verified rather than assumed: a test binary was compiled, its `assets/`
+directory and entry source deleted from disk, and the binary then served both
+`/` and a hashed asset correctly, with `Bun.embeddedFiles` reporting both files.
+Two things fell out of that check. Content types are inferred by `Bun.file` for
+free, so the bun path needs no MIME table of its own. And the binary is large —
+around 64MB for a trivial app — because the bun runtime is in there; that is the
+cost of the single-file property, not a bug to optimize away.
+
+The constraint that shapes the code is that **`with { type: 'file' }` cannot be
+dynamic**. There is no way to embed a directory, or to build the import list at
+runtime; each file needs its own literal `import` statement. So a generated
+manifest module enumerates them, and generating it requires the built frontend
+to already exist — see
+[deploy consumes a built frontend](deploy-consumes-a-built-frontend.md).
+
+Because assets live in the binary on one runtime and on disk on another,
+`StaticMount` carries an optional `assets: Record<string, string>` map. A mount
+with `assets` resolves keys through it; a mount without one resolves them against
+`directory`. One mount type, one pipeline, and the node path stays exactly as it
+was.
+
+**What this rules out:** shipping the frontend as a sibling directory next to the
+binary, a runtime-assembled embed list, and a second static-serving code path for
+embedded assets.

package/knowledge/decisions/the-desktop-shell-runs-the-server-as-a-sidecar.md

@@ -0,0 +1,51 @@
+---
+type: decision
+title: The desktop shell runs the server as a sidecar, not embedded
+description: Tauri spawns the compiled pikku binary and points the webview at its HTTP origin, so cookies, CORS and OAuth behave exactly as they do in a browser
+tags: [tauri, desktop, standalone, bun]
+---
+
+# The desktop shell runs the server as a sidecar, not embedded
+
+`pikku deploy apply --provider standalone --runtime bun --desktop` generates a
+`src-tauri/` crate that ships the compiled binary as an `externalBin`, spawns it
+at launch, and opens a window at `http://127.0.0.1:<port>`. The server serves
+both the API and the built frontend, so **the UI and the API share one real HTTP
+origin**.
+
+That single property is the whole reason for the design. A webview loaded from
+`tauri://localhost` is a different origin from the server it talks to, and
+everything keyed on `window.location.origin` breaks: cookies stop being
+first-party, every request needs CORS, better-auth needs special-casing, and
+OAuth redirects have nowhere valid to land. Pointing the webview at the server's
+own origin means none of that is true — the app is the same app it is on the
+web, and no auth code knows it is running on a desktop.
+
+The user never writes Rust. `main.rs`, `tauri.conf.json`, `Cargo.toml`,
+`build.rs`, a placeholder icon and a placeholder frontend directory are all
+generated, with the product name and bundle identifier taken from the project
+rather than hardcoded. Regenerating is idempotent, and a file the user has since
+edited is left alone and reported rather than overwritten — the generator
+records a hash of what it wrote, which is the only way to tell "unchanged since
+we wrote it" from "the user has taken this over".
+
+Two supporting rules fall out of running a real server process:
+
+- **Single instance is load-bearing.** `tauri-plugin-single-instance` focuses the
+  existing window instead of launching again. Two shells would mean two
+  sidecars: two SQLite writers on one file.
+- **The sidecar must not outlive the shell.** Tauri stops it on a clean exit, but
+  a hard crash never runs that path, and an orphan holds the database open. The
+  shell passes its pid down as
+  `PIKKU_PARENT_PID` and the server polls it, exiting when the parent is gone.
+  With no such variable set — a terminal, a container — the watch is inert.
+
+The shell also resolves the platform's app-data directory and passes it as
+`PIKKU_DATA_DIR`. A double-clicked app has no meaningful working directory, so
+that variable is where the SQLite file, uploaded content and runtime state live;
+the server reads it in bootstrap, which is the one place `process.env` is
+allowed.
+
+**What this rules out:** linking the server into the Rust binary, serving the UI
+from `tauri://localhost` or a custom protocol, a second auth path for desktop
+builds, and any design where two windows can be open at once.

package/knowledge/decisions/the-sidecar-reports-its-port-the-shell-never-picks-one.md

@@ -0,0 +1,44 @@
+---
+type: decision
+title: The sidecar reports its port; the shell never picks one
+description: The server binds :0 and prints the port it got on the ready line; Rust blocks on that line rather than choosing a free port and passing it down
+tags: [tauri, desktop, ports, server-ready]
+---
+
+# The sidecar reports its port; the shell never picks one
+
+The shell starts the sidecar with `PORT=0`, reads its stdout until the ready
+line appears, parses the port out of it, and only then creates the window.
+
+The obvious alternative — have Rust find a free port and pass it down — has a
+race with no fix: between the check that a port is free and the sidecar's bind,
+anything on the machine can take it. Binding first and reporting back is the
+only ordering with no window in it.
+
+The line it waits for is the existing readiness marker:
+
+```
+pikku: ready on http://127.0.0.1:53422
+```
+
+`SERVER_READY_MARKER` now lives in `@pikku/deploy` rather than in the CLI,
+because the two ends of the handshake are built by different packages: the CLI
+waits on it for `pikku dev --spawn`, and the standalone provider's generated
+entry prints it from inside the shipped binary. The CLI re-exports it from its
+old path, so nothing that imported it had to change. A second copy of the string
+would have drifted the first time either side touched it.
+
+Making the line true required a real bound port to report. `--port 0` used to
+print `:0`, because both `serve` and `dev` logged the *requested* port. Both
+runtimes now expose the port they actually bound —
+`PikkuNodeHTTPServer.port` reads `server.address()`, `PikkuBunServer.port`
+already had it — `DevServerInstance` carries it, and every URL announced after
+`start()` is built from it.
+
+Note that `listening on …` is still **not** readiness. It is printed inside
+`server.start()`, before the project's `afterStart` has run, so a parent that
+treats it as ready races whatever the project seeds there.
+
+**What this rules out:** a fixed default port for desktop builds, port
+allocation in Rust, a handshake over a file or a socket instead of stdout, and
+treating the runtime's own `listening on …` line as ready.

package/knowledge/index.md

@@ -0,0 +1,22 @@
+---
+type: overview
+title: Knowledge
+description: How a standalone unit comes to contain a frontend as well as a server, and how it becomes a double-clickable desktop app
+---
+
+# Knowledge
+
+A standalone unit is meant to be one artifact you can hand someone: a binary
+that, when run, is the whole application. Adding a UI to that picture forces
+three questions — what kind of frontend, who builds it, and where the files
+live at runtime — and the answers are less obvious than they look.
+
+Wrapping that binary in a window forces a second set: who starts the server,
+how the window learns the port it bound, who holds the passphrase, and what
+happens to the server when the window goes away.
+
+These notes record the answers and the constraints that produced them.
+
+<!-- pikku:knowledge-index -->
+- [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
+<!-- /pikku:knowledge-index -->

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@pikku/deploy-standalone",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "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"
+    "tsc": "tsc --noEmit",
+    "test": "node --test --import tsx src/*.test.ts"
   },
   "devDependencies": {
     "typescript": "^6.0.3"
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/index.js",
+    "./runtime": "./dist/runtime/index.js"
   },
   "license": "MIT",
   "dependencies": {
-    "@pikku/deploy": "^0.12.1"
+    "@pikku/deploy": "^0.12.2"
   }
 }

package/src/adapter.test.ts

@@ -0,0 +1,186 @@
+import { after, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { existsSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { StandaloneProviderAdapter } from './adapter.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 withFrontend = {
+  ...(baseContext as object),
+  frontend: { urlPrefix: '/', spaFallback: true },
+} as never
+
+describe('StandaloneProviderAdapter frontend serving', () => {
+  test('a node entry without a frontend mounts nothing', () => {
+    const source = new StandaloneProviderAdapter({
+      runtime: 'node',
+    }).generateEntrySource(baseContext)
+
+    assert.doesNotMatch(source, /staticMounts/)
+  })
+
+  test('a bun entry without a frontend imports no asset manifest', () => {
+    const source = new StandaloneProviderAdapter({
+      runtime: 'bun',
+    }).generateEntrySource(baseContext)
+
+    assert.doesNotMatch(source, /frontend-assets/)
+    assert.doesNotMatch(source, /staticMounts/)
+  })
+
+  test('a node entry serves the frontend from a directory beside the bundle', () => {
+    const source = new StandaloneProviderAdapter({
+      runtime: 'node',
+    }).generateEntrySource(withFrontend)
+
+    assert.match(source, /staticMounts/)
+    assert.match(
+      source,
+      /import\.meta\.url/,
+      'the directory must be resolved from the running bundle, not the build machine'
+    )
+    assert.doesNotMatch(
+      source,
+      /assets:/,
+      'node reads the copied directory rather than an embed map'
+    )
+  })
+
+  test('a bun entry serves the frontend from the embedded asset map', () => {
+    const source = new StandaloneProviderAdapter({
+      runtime: 'bun',
+    }).generateEntrySource(withFrontend)
+
+    assert.match(source, /from '\.\/frontend-assets\.gen\.js'/)
+    assert.match(source, /assets:/)
+    assert.doesNotMatch(
+      source,
+      /import\.meta\.url/,
+      'an embedded asset has no directory to resolve'
+    )
+  })
+
+  test('the mount carries the configured prefix and fallback', () => {
+    const source = new StandaloneProviderAdapter({
+      runtime: 'bun',
+    }).generateEntrySource({
+      ...(baseContext as object),
+      frontend: { urlPrefix: '/app', spaFallback: false },
+    } as never)
+
+    assert.match(source, /urlPrefix: '\/app'/)
+    assert.match(source, /spaFallback: false/)
+  })
+
+  test('bun externalises the asset manifest so esbuild never parses it', () => {
+    // esbuild rejects `with { type: 'file' }` outright; the manifest has to
+    // survive to the `bun build --compile` step untouched.
+    const externals = new StandaloneProviderAdapter({
+      runtime: 'bun',
+    }).getExternals()
+
+    assert.ok(externals.includes('./frontend-assets.gen.js'))
+  })
+
+  test('the node runtime has no manifest to externalise', () => {
+    const externals = new StandaloneProviderAdapter({
+      runtime: 'node',
+    }).getExternals()
+
+    assert.ok(!externals.includes('./frontend-assets.gen.js'))
+  })
+})
+
+describe('StandaloneProviderAdapter deploy output', () => {
+  const tempDirs: string[] = []
+
+  after(() => {
+    for (const dir of tempDirs) {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  const builtUnit = async (options: { withFrontend: boolean }) => {
+    const buildDir = await mkdtemp(join(tmpdir(), 'pikku-standalone-'))
+    tempDirs.push(buildDir)
+    const unitDir = join(buildDir, 'app')
+    await mkdir(unitDir, { recursive: true })
+    await writeFile(join(unitDir, 'bundle.js'), 'console.log("bundle")')
+    if (options.withFrontend) {
+      await mkdir(join(unitDir, 'frontend', 'assets'), { recursive: true })
+      await writeFile(
+        join(unitDir, 'frontend', 'index.html'),
+        '<!doctype html>'
+      )
+      await writeFile(join(unitDir, 'frontend', 'assets', 'app.js'), 'app')
+      await writeFile(
+        join(unitDir, 'frontend-assets.gen.js'),
+        'export const frontendAssets = {}\n'
+      )
+    }
+    return { buildDir, outDir: join(buildDir, 'app-dist') }
+  }
+
+  const silentLogger = { info: () => {}, error: () => {} }
+
+  test('ships the frontend beside the bundle', async () => {
+    // The node entry resolves its mount directory relative to itself, so the
+    // copy has to land in the distributable, not just in the build directory.
+    const { buildDir, outDir } = await builtUnit({ withFrontend: true })
+
+    const result = await new StandaloneProviderAdapter({
+      runtime: 'node',
+    }).deploy({ buildDir, logger: silentLogger })
+
+    assert.equal(result.success, true)
+    assert.equal(
+      await readFile(join(outDir, 'frontend', 'assets', 'app.js'), 'utf-8'),
+      'app'
+    )
+  })
+
+  test('ships the asset manifest the compile step still has to resolve', async () => {
+    // `bun build --compile` follows the import out of the copied bundle, so the
+    // manifest has to sit next to it — it was excluded from the esbuild output
+    // precisely so it would still be a real file at this point.
+    const { buildDir, outDir } = await builtUnit({ withFrontend: true })
+
+    await new StandaloneProviderAdapter({ runtime: 'node' }).deploy({
+      buildDir,
+      logger: silentLogger,
+    })
+
+    assert.match(
+      await readFile(join(outDir, 'frontend-assets.gen.js'), 'utf-8'),
+      /frontendAssets/
+    )
+  })
+
+  test('a project without a frontend copies nothing extra', async () => {
+    const { buildDir, outDir } = await builtUnit({ withFrontend: false })
+
+    const result = await new StandaloneProviderAdapter({
+      runtime: 'node',
+    }).deploy({ buildDir, logger: silentLogger })
+
+    assert.equal(result.success, true)
+    assert.equal(existsSync(join(outDir, 'frontend')), false)
+    assert.equal(existsSync(join(outDir, 'frontend-assets.gen.js')), false)
+  })
+})