@pikku/deploy-standalone 0.12.12 → 0.12.17

package/dist/tauri/main-rs.d.ts

@@ -0,0 +1,31 @@
+type WindowOptions = {
+    windowTitle: string;
+    width: number;
+    height: number;
+};
+export type MainRsOptions = WindowOptions & ({
+    /** The `externalBin` base name — how `shell().sidecar(..)` finds the binary. */
+    sidecarName: string;
+    remoteUrl?: undefined;
+} | {
+    /** An already-running server the window opens against. */
+    remoteUrl: string;
+    sidecarName?: undefined;
+});
+/**
+ * The shell's whole program.
+ *
+ * Everything it does follows from one decision: the server serves the UI and
+ * the API from a single real HTTP origin, and the webview simply points at it.
+ * A `tauri://localhost` webview would break every cookie, CORS check and OAuth
+ * redirect keyed on `window.location.origin`, which is the trap this design
+ * exists to avoid.
+ *
+ * Which origin that is decides the program. A sidecar binds its port at startup,
+ * so the shell has to start it, read the port off its ready line and open the
+ * window itself. A remote url is known before a line of Rust is generated, so
+ * the window is declared in `tauri.conf.json` and nothing here has to run at
+ * all beyond keeping the app to a single instance.
+ */
+export declare const renderMainRs: (options: MainRsOptions) => string;
+export {};

package/dist/tauri/main-rs.js

@@ -0,0 +1,213 @@
+import { SERVER_READY_MARKER } from '@pikku/deploy';
+import { DATA_DIR_ENV, PARENT_PID_ENV } from '../runtime/parent-watch.js';
+/**
+ * The shell's whole program.
+ *
+ * Everything it does follows from one decision: the server serves the UI and
+ * the API from a single real HTTP origin, and the webview simply points at it.
+ * A `tauri://localhost` webview would break every cookie, CORS check and OAuth
+ * redirect keyed on `window.location.origin`, which is the trap this design
+ * exists to avoid.
+ *
+ * Which origin that is decides the program. A sidecar binds its port at startup,
+ * so the shell has to start it, read the port off its ready line and open the
+ * window itself. A remote url is known before a line of Rust is generated, so
+ * the window is declared in `tauri.conf.json` and nothing here has to run at
+ * all beyond keeping the app to a single instance.
+ */
+export const renderMainRs = (options) => options.remoteUrl === undefined
+    ? renderSidecarMainRs(options)
+    : renderRemoteMainRs();
+const renderRemoteMainRs = () => `// Generated by \`pikku deploy apply --desktop\`. Safe to edit — the generator
+// will not overwrite this file once you have changed it.
+//
+// The window is declared in tauri.conf.json, pointed straight at the remote
+// server: its origin is known up front, so there is no port to discover and no
+// process to supervise. The webview loads that origin rather than
+// \`tauri://localhost\`, which is what keeps cookies first-party and OAuth
+// redirects working.
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+use tauri::Manager;
+
+fn main() {
+    tauri::Builder::default()
+        // A second launch should reach the window that is already open rather
+        // than start a second session against the same server.
+        .plugin(tauri_plugin_single_instance::init(|app, _argv, _cwd| {
+            if let Some(window) = app.get_webview_window("main") {
+                let _ = window.unminimize();
+                let _ = window.show();
+                let _ = window.set_focus();
+            }
+        }))
+        .run(tauri::generate_context!())
+        .expect("error while running the pikku desktop shell");
+}
+`;
+const renderSidecarMainRs = (options) => {
+    const { sidecarName, windowTitle, width, height } = options;
+    return `// Generated by \`pikku deploy apply --desktop\`. Safe to edit — the generator
+// will not overwrite this file once you have changed it.
+//
+// The webview points at the sidecar's own HTTP origin rather than at
+// \`tauri://localhost\`, so cookies are first-party, there is no CORS, and OAuth
+// redirects land where the server expects. The sidecar is the application; this
+// shell only supervises it.
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use tauri::{Manager, WebviewUrl, WebviewWindowBuilder};
+use tauri_plugin_shell::process::{CommandChild, CommandEvent};
+use tauri_plugin_shell::ShellExt;
+
+/// Printed by the sidecar once it is listening *and* its startup lifecycle has
+/// finished. The runtime's own "listening on ..." line comes earlier and is not
+/// readiness.
+const READY_PREFIX: &str = "${SERVER_READY_MARKER} on http://";
+
+/// How long to wait for the ready line before giving up. A sidecar that starts
+/// and then hangs prints nothing, so no window is ever built — and a Tauri
+/// process with no window cannot be quit from the dock or the taskbar.
+const READY_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Held so the child is not dropped while the app runs, and so a clean exit can
+/// stop it explicitly.
+struct Sidecar(Mutex<Option<CommandChild>>);
+
+fn parse_ready_port(line: &str) -> Option<u16> {
+    let rest = line.split(READY_PREFIX).nth(1)?;
+    let authority = rest.split_whitespace().next()?;
+    authority
+        .trim_end_matches('/')
+        .rsplit(':')
+        .next()?
+        .parse()
+        .ok()
+}
+
+fn main() {
+    tauri::Builder::default()
+        // A second launch must never spawn a second sidecar: that would be two
+        // SQLite writers on one file. Focus what is already running instead.
+        .plugin(tauri_plugin_single_instance::init(|app, _argv, _cwd| {
+            if let Some(window) = app.get_webview_window("main") {
+                let _ = window.unminimize();
+                let _ = window.show();
+                let _ = window.set_focus();
+            }
+        }))
+        .plugin(tauri_plugin_shell::init())
+        .setup(|app| {
+            let data_dir = app.path().app_data_dir()?;
+            std::fs::create_dir_all(&data_dir)?;
+
+            let (mut rx, child) = app
+                .shell()
+                .sidecar("${sidecarName}")?
+                // Port 0 asks the OS for a free port. Choosing one here and
+                // passing it down would race whatever binds it in between, so
+                // the sidecar binds first and reports back on its ready line.
+                .env("PORT", "0")
+                .env("HOST", "127.0.0.1")
+                // The database, uploaded content and runtime state live here
+                // and nowhere else. A double-clicked app has no meaningful
+                // working directory, so the platform's app-data path is the
+                // only sane answer — the server reads this in bootstrap.
+                .env("${DATA_DIR_ENV}", data_dir.to_string_lossy().to_string())
+                // Tauri stops the sidecar on a clean exit, but a hard crash of
+                // this process never runs that path, and an orphan would hold
+                // the database open with its data key still resident.
+                .env("${PARENT_PID_ENV}", std::process::id().to_string())
+                .spawn()?;
+
+            app.manage(Sidecar(Mutex::new(Some(child))));
+
+            let opened = Arc::new(AtomicBool::new(false));
+
+            let timeout_handle = app.handle().clone();
+            let timeout_opened = opened.clone();
+            std::thread::spawn(move || {
+                std::thread::sleep(READY_TIMEOUT);
+                if !timeout_opened.load(Ordering::SeqCst) {
+                    eprintln!(
+                        "the pikku sidecar did not become ready within {:?} — giving up",
+                        READY_TIMEOUT
+                    );
+                    timeout_handle.exit(1);
+                }
+            });
+
+            let handle = app.handle().clone();
+            tauri::async_runtime::spawn(async move {
+                while let Some(event) = rx.recv().await {
+                    let line = match event {
+                        CommandEvent::Stdout(bytes) => String::from_utf8_lossy(&bytes).into_owned(),
+                        CommandEvent::Stderr(bytes) => {
+                            eprint!("{}", String::from_utf8_lossy(&bytes));
+                            continue;
+                        }
+                        CommandEvent::Terminated(payload) => {
+                            eprintln!("pikku sidecar exited: {:?}", payload.code);
+                            if !opened.load(Ordering::SeqCst) {
+                                handle.exit(1);
+                            }
+                            break;
+                        }
+                        _ => continue,
+                    };
+                    print!("{}", line);
+
+                    if opened.load(Ordering::SeqCst) {
+                        continue;
+                    }
+                    if let Some(port) = parse_ready_port(&line) {
+                        let url = format!("http://127.0.0.1:{}", port);
+                        match url.parse() {
+                            Ok(parsed) => {
+                                let built = WebviewWindowBuilder::new(
+                                    &handle,
+                                    "main",
+                                    WebviewUrl::External(parsed),
+                                )
+                                .title("${windowTitle}")
+                                .inner_size(${width}.0, ${height}.0)
+                                .build();
+                                match built {
+                                    Ok(_) => opened.store(true, Ordering::SeqCst),
+                                    Err(err) => {
+                                        eprintln!("could not open the window: {}", err);
+                                        handle.exit(1);
+                                    }
+                                }
+                            }
+                            Err(err) => {
+                                eprintln!("the sidecar reported an unusable url: {}", err);
+                                handle.exit(1);
+                            }
+                        }
+                    }
+                }
+            });
+
+            Ok(())
+        })
+        .on_window_event(|window, event| {
+            if let tauri::WindowEvent::Destroyed = event {
+                if let Some(sidecar) = window.app_handle().try_state::<Sidecar>() {
+                    if let Ok(mut guard) = sidecar.0.lock() {
+                        if let Some(child) = guard.take() {
+                            let _ = child.kill();
+                        }
+                    }
+                }
+            }
+        })
+        .run(tauri::generate_context!())
+        .expect("error while running the pikku desktop shell");
+}
+`;
+};

package/dist/tauri/next-steps.d.ts

@@ -0,0 +1,15 @@
+export type TauriNextStepsOptions = {
+    /** Absolute path of the generated crate. */
+    shellDir: string;
+    /** Whether a Rust toolchain answered when the triple was resolved. */
+    hasRust: boolean;
+};
+/**
+ * What to say once the crate and its sidecar are on disk.
+ *
+ * Generation is pure Node — it writes files and copies a binary — so `--desktop`
+ * succeeds perfectly well on a machine that cannot build the result. Saying so
+ * here is the difference between a known prerequisite and a cargo error at the
+ * point someone least expects one.
+ */
+export declare const renderTauriNextSteps: ({ shellDir, hasRust, }: TauriNextStepsOptions) => string[];

package/dist/tauri/next-steps.js

@@ -0,0 +1,16 @@
+const PREREQUISITES = 'https://tauri.app/start/prerequisites/';
+/**
+ * What to say once the crate and its sidecar are on disk.
+ *
+ * Generation is pure Node — it writes files and copies a binary — so `--desktop`
+ * succeeds perfectly well on a machine that cannot build the result. Saying so
+ * here is the difference between a known prerequisite and a cargo error at the
+ * point someone least expects one.
+ */
+export const renderTauriNextSteps = ({ shellDir, hasRust, }) => {
+    const lines = [`  Next: cd ${shellDir} && npx tauri build`];
+    if (!hasRust) {
+        lines.push(`  That step needs a Rust toolchain, and none answered here — see ${PREREQUISITES}.`, '  The crate and its sidecar are complete, so another machine can build them as they are.');
+    }
+    return lines;
+};

package/dist/tauri/target-triple.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Rust target triples, and the file name Tauri's `externalBin` resolves a
+ * sidecar by.
+ *
+ * Tauri appends the *compile* target's triple to every `externalBin` path and
+ * looks the result up on disk, so a binary dropped in as plain `binaries/app`
+ * is silently invisible to the bundler. This is the one detail that makes an
+ * otherwise correct shell fail at build time with "binary not found".
+ */
+export type HostPlatform = NodeJS.Platform;
+export type HostArch = string;
+/** Pull the `host:` line out of `rustc -vV` output. */
+export declare const parseRustcHost: (output: string) => string | undefined;
+export type HostTargetTripleOptions = {
+    platform?: HostPlatform;
+    arch?: HostArch;
+    /** Raw `rustc -vV` output, when the toolchain was reachable. */
+    rustcVersionVerbose?: string;
+};
+/**
+ * The triple the shell will be built for.
+ *
+ * `rustc -vV` wins when it is available: it is the toolchain that will link the
+ * shell, and it knows things the Node platform pair cannot express — a musl
+ * host, or a Node process running under Rosetta on an arm64 Mac.
+ */
+export declare const hostTargetTriple: (options?: HostTargetTripleOptions) => string;
+/** `binaries/<name>-<triple>[.exe]`, exactly as `externalBin` looks it up. */
+export declare const sidecarFileName: (baseName: string, targetTriple: string) => string;

package/dist/tauri/target-triple.js

@@ -0,0 +1,42 @@
+/**
+ * Rust target triples, and the file name Tauri's `externalBin` resolves a
+ * sidecar by.
+ *
+ * Tauri appends the *compile* target's triple to every `externalBin` path and
+ * looks the result up on disk, so a binary dropped in as plain `binaries/app`
+ * is silently invisible to the bundler. This is the one detail that makes an
+ * otherwise correct shell fail at build time with "binary not found".
+ */
+const TRIPLES = {
+    'darwin:arm64': 'aarch64-apple-darwin',
+    'darwin:x64': 'x86_64-apple-darwin',
+    'linux:arm64': 'aarch64-unknown-linux-gnu',
+    'linux:x64': 'x86_64-unknown-linux-gnu',
+    'win32:arm64': 'aarch64-pc-windows-msvc',
+    'win32:x64': 'x86_64-pc-windows-msvc',
+};
+/** Pull the `host:` line out of `rustc -vV` output. */
+export const parseRustcHost = (output) => /^host:\s*(\S+)$/m.exec(output)?.[1];
+/**
+ * The triple the shell will be built for.
+ *
+ * `rustc -vV` wins when it is available: it is the toolchain that will link the
+ * shell, and it knows things the Node platform pair cannot express — a musl
+ * host, or a Node process running under Rosetta on an arm64 Mac.
+ */
+export const hostTargetTriple = (options = {}) => {
+    const fromRustc = options.rustcVersionVerbose
+        ? parseRustcHost(options.rustcVersionVerbose)
+        : undefined;
+    if (fromRustc)
+        return fromRustc;
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const triple = TRIPLES[`${platform}:${arch}`];
+    if (!triple) {
+        throw new Error(`No known Rust target triple for ${platform}/${arch}. Install a Rust toolchain so \`rustc -vV\` can report its host, or pass the triple explicitly.`);
+    }
+    return triple;
+};
+/** `binaries/<name>-<triple>[.exe]`, exactly as `externalBin` looks it up. */
+export const sidecarFileName = (baseName, targetTriple) => `${baseName}-${targetTriple}${targetTriple.includes('windows') ? '.exe' : ''}`;

package/knowledge/decisions/a-pikku-server-serves-a-static-frontend.md

@@ -0,0 +1,36 @@
+---
+type: decision
+title: A pikku server serves a static frontend, not a rendered one
+description: The frontend is TanStack Start built to static output and served through a static mount; pikku never runs a framework renderer in-process
+tags: [frontend, tanstack, static-mounts, standalone]
+---
+
+# A pikku server serves a static frontend, not a rendered one
+
+The frontend story is one framework — **TanStack Start** — and one output shape:
+static HTML, JS and CSS on disk, served through the same `StaticMount`
+machinery that already serves the console. Next.js is out of scope, and so is
+running any framework's server renderer inside the pikku process.
+
+Both halves of that are deliberate, and for the same reason. Hosting a renderer
+means owning that framework's server contract: its request/response adapter, its
+streaming model, its middleware ordering, its version skew. It couples a pikku
+release to a frontend framework release, and it multiplies by every runtime we
+support — the node server, the bun server, and every serverless adapter would
+each need their own integration. A directory of files needs none of that, and
+what it costs the app is per-request server rendering, which a local-first
+desktop app was never going to use.
+
+The capability is not standalone-specific. `pikku serve` and `pikku dev` mount a
+frontend the same way, because a server that can serve its own UI is useful long
+before anyone wraps it in Tauri — it is the difference between one origin and
+two, which is also the difference between first-party cookies and a CORS
+configuration. Standalone is the case that makes it *feel* like an app; it is
+not the case that justifies the feature.
+
+Dev does not use a mount at all. Vite serves the frontend and proxies `/api` to
+pikku, exactly as `packages/console/vite.config.ts` already does — HMR is the
+whole point of dev, and a static mount cannot offer it.
+
+**What this rules out:** a Next.js integration, an in-process SSR or streaming
+handler, and a frontend capability that only exists inside `pikku deploy`.

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.