npm - @pikku/deploy-standalone - Versions diffs - 0.12.12 → 0.12.13 - Mend

@pikku/deploy-standalone 0.12.12 → 0.12.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/CHANGELOG.md +41 -0
package/dist/adapter.d.ts +34 -0
package/dist/adapter.js +184 -4
package/dist/runtime/index.d.ts +9 -0
package/dist/runtime/index.js +8 -0
package/dist/runtime/parent-watch.d.ts +45 -0
package/dist/runtime/parent-watch.js +87 -0
package/dist/tauri/generate.d.ts +45 -0
package/dist/tauri/generate.js +230 -0
package/dist/tauri/icon.d.ts +1 -0
package/dist/tauri/icon.js +54 -0
package/dist/tauri/main-rs.d.ts +31 -0
package/dist/tauri/main-rs.js +213 -0
package/dist/tauri/next-steps.d.ts +15 -0
package/dist/tauri/next-steps.js +16 -0
package/dist/tauri/target-triple.d.ts +29 -0
package/dist/tauri/target-triple.js +42 -0
package/knowledge/decisions/a-pikku-server-serves-a-static-frontend.md +36 -0
package/knowledge/decisions/a-remote-desktop-shell-bundles-nothing.md +38 -0
package/knowledge/decisions/deploy-consumes-a-built-frontend.md +33 -0
package/knowledge/decisions/desktop-builds-are-unsigned-and-never-update-themselves.md +34 -0
package/knowledge/decisions/index.md +19 -0
package/knowledge/decisions/standalone-assets-are-embedded-in-the-bun-binary.md +39 -0
package/knowledge/decisions/the-desktop-shell-runs-the-server-as-a-sidecar.md +51 -0
package/knowledge/decisions/the-sidecar-reports-its-port-the-shell-never-picks-one.md +44 -0
package/knowledge/index.md +22 -0
package/package.json +6 -4
package/src/adapter.test.ts +186 -0
package/src/adapter.ts +210 -4
package/src/desktop-deploy.test.ts +167 -0
package/src/runtime/index.ts +13 -0
package/src/runtime/parent-watch.process.test.ts +112 -0
package/src/runtime/parent-watch.test.ts +148 -0
package/src/runtime/parent-watch.ts +115 -0
package/src/sidecar-entry.test.ts +89 -0
package/src/tauri/generate.test.ts +401 -0
package/src/tauri/generate.ts +327 -0
package/src/tauri/icon.test.ts +63 -0
package/src/tauri/icon.ts +62 -0
package/src/tauri/main-rs.rustfmt.test.ts +86 -0
package/src/tauri/main-rs.ts +241 -0
package/src/tauri/next-steps.test.ts +38 -0
package/src/tauri/next-steps.ts +30 -0
package/src/tauri/target-triple.test.ts +84 -0
package/src/tauri/target-triple.ts +65 -0
package/tsconfig.tsbuildinfo +1 -1

package/dist/tauri/generate.js ADDED Viewed

@@ -0,0 +1,230 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { renderPlaceholderIcon } from './icon.js';
+import { renderMainRs } from './main-rs.js';
+import { hostTargetTriple, sidecarFileName } from './target-triple.js';
+/** Directory the shell crate is generated into, relative to the project root. */
+export const TAURI_SHELL_DIR = 'src-tauri';
+/**
+ * Records the bytes this generator last wrote for each file, so a regenerate
+ * can tell "unchanged since we wrote it" from "the user has taken this over".
+ * Without it the only options are to clobber edits or to never update anything.
+ */
+const MANIFEST_FILE = '.pikku-shell.json';
+const ICON_SIZE = 512;
+const hash = (content) => createHash('sha256').update(content).digest('hex');
+const readManifest = async (shellDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(join(shellDir, MANIFEST_FILE), 'utf-8'));
+        if (parsed && typeof parsed === 'object' && parsed.files)
+            return parsed;
+    }
+    catch {
+        // A missing or unreadable manifest means every existing file is the user's.
+    }
+    return { version: 1, files: {} };
+};
+/**
+ * A crate name, a file name and a bundle identifier segment all reject the same
+ * things, so one rule covers them.
+ */
+const slug = (raw) => raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+/**
+ * A reverse-DNS identifier for the bundle.
+ *
+ * A scoped package already names its org, so `@acme/shop` becomes
+ * `com.acme.shop`. An unscoped name has no org to borrow, and `com.shop.app`
+ * is not an option — macOS rejects an identifier ending in `.app`.
+ */
+export const tauriBundleIdentifier = (packageName) => {
+    const scoped = /^@([^/]+)\/(.+)$/.exec(packageName);
+    if (scoped) {
+        return `com.${slug(scoped[1])}.${slug(scoped[2])}`;
+    }
+    return `com.${slug(packageName)}.desktop`;
+};
+const renderConfig = (options) => JSON.stringify({
+    $schema: 'https://schema.tauri.app/config/2',
+    productName: options.appName,
+    version: options.version,
+    identifier: options.identifier,
+    build: {
+        // The real UI is served by the sidecar over HTTP; the window is pointed
+        // at it from Rust once the port is known. Tauri still requires a
+        // frontend directory to exist, so a placeholder page stands in.
+        frontendDist: 'ui',
+    },
+    app: {
+        // A sidecar's origin is not known until it reports its port, so its
+        // window is built from Rust and this stays deliberately empty. A remote
+        // url is known here, and a declared window is the whole program.
+        windows: options.remoteUrl
+            ? [
+                {
+                    label: 'main',
+                    url: options.remoteUrl,
+                    title: options.windowTitle,
+                    width: options.width,
+                    height: options.height,
+                },
+            ]
+            : [],
+        security: { csp: null },
+    },
+    bundle: {
+        active: true,
+        targets: 'all',
+        icon: ['icons/icon.png'],
+        ...(options.remoteUrl
+            ? {}
+            : { externalBin: [`binaries/${options.appName}`] }),
+    },
+}, null, 2) + '\n';
+const renderCargoToml = (options) => `[package]
+name = "${options.crateName}"
+version = "${options.version}"
+edition = "2021"
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+[dependencies]
+tauri = { version = "2", features = [] }
+${options.remoteUrl ? '' : 'tauri-plugin-shell = "2"\n'}tauri-plugin-single-instance = "2"
+[profile.release]
+panic = "abort"
+codegen-units = 1
+lto = true
+strip = true
+`;
+const PLACEHOLDER_UI = `<!doctype html>
+<meta charset="utf-8" />
+<title>Starting…</title>
+<p>Starting…</p>
+`;
+const CAPABILITIES = JSON.stringify({
+    $schema: '../gen/schemas/desktop-schema.json',
+    identifier: 'default',
+    description: 'Baseline permissions for the pikku desktop shell.',
+    windows: ['main'],
+    permissions: ['core:default'],
+}, null, 2);
+const GITIGNORE = `/target
+/binaries
+/gen
+`;
+/**
+ * A webview can only open an http(s) origin, and everything the shell exists to
+ * preserve — first-party cookies, CORS, OAuth redirects — is keyed on it. A
+ * `file:` or custom-scheme url would build fine and then fail at runtime.
+ */
+const normalizeRemoteUrl = (raw) => {
+    const trimmed = raw.trim();
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`"${raw}" is not a url the desktop shell could open.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`The desktop shell opens an http or https url; "${raw}" is ${parsed.protocol.replace(':', '')}.`);
+    }
+    return trimmed;
+};
+export const generateTauriShell = async (options) => {
+    const appName = options.appName;
+    if (!appName || slug(appName) !== appName) {
+        throw new Error(`"${appName}" is not a usable app name for a Tauri shell — use lowercase letters, digits and dashes (got the slug "${slug(appName)}").`);
+    }
+    const remoteUrl = options.remoteUrl
+        ? normalizeRemoteUrl(options.remoteUrl)
+        : undefined;
+    if (remoteUrl && options.binaryPath) {
+        throw new Error('A remote desktop shell runs no server of its own, so there is no sidecar to install the binary as. Drop either the url or the binary.');
+    }
+    const version = options.version ?? '0.1.0';
+    const windowTitle = options.windowTitle ?? appName;
+    const width = options.width ?? 1200;
+    const height = options.height ?? 800;
+    const targetTriple = options.targetTriple ?? hostTargetTriple();
+    const shellDir = join(options.projectDir, TAURI_SHELL_DIR);
+    const files = [
+        [
+            'tauri.conf.json',
+            renderConfig({
+                appName,
+                identifier: options.identifier,
+                version,
+                windowTitle,
+                width,
+                height,
+                remoteUrl,
+            }),
+        ],
+        [
+            'Cargo.toml',
+            renderCargoToml({ crateName: `${appName}-shell`, version, remoteUrl }),
+        ],
+        ['build.rs', 'fn main() {\n    tauri_build::build()\n}\n'],
+        [
+            'src/main.rs',
+            renderMainRs(remoteUrl
+                ? { remoteUrl, windowTitle, width, height }
+                : { sidecarName: appName, windowTitle, width, height }),
+        ],
+        ['ui/index.html', PLACEHOLDER_UI],
+        ['capabilities/default.json', CAPABILITIES],
+        ['icons/icon.png', renderPlaceholderIcon(ICON_SIZE)],
+        ['.gitignore', GITIGNORE],
+    ];
+    const manifest = await readManifest(shellDir);
+    const written = [];
+    const preserved = [];
+    for (const [relativePath, content] of files) {
+        const target = join(shellDir, relativePath);
+        const nextHash = hash(content);
+        let existing;
+        try {
+            existing = await readFile(target);
+        }
+        catch {
+            existing = undefined;
+        }
+        if (existing) {
+            const currentHash = hash(existing);
+            if (currentHash === nextHash) {
+                manifest.files[relativePath] = nextHash;
+                continue;
+            }
+            if (manifest.files[relativePath] !== currentHash) {
+                preserved.push(relativePath);
+                continue;
+            }
+        }
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+        manifest.files[relativePath] = nextHash;
+        written.push(relativePath);
+    }
+    let sidecar;
+    if (options.binaryPath) {
+        // Build output rather than source: always replaced, never diffed against
+        // the manifest, and gitignored.
+        const binary = await readFile(options.binaryPath);
+        const fileName = sidecarFileName(appName, targetTriple);
+        const target = join(shellDir, 'binaries', fileName);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, binary);
+        await chmod(target, 0o755);
+        sidecar = { fileName, path: target };
+    }
+    await mkdir(shellDir, { recursive: true });
+    await writeFile(join(shellDir, MANIFEST_FILE), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    return { dir: shellDir, written, preserved, targetTriple, sidecar };
+};

package/dist/tauri/icon.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export declare const renderPlaceholderIcon: (size: number) => Buffer;

package/dist/tauri/icon.js ADDED Viewed

@@ -0,0 +1,54 @@
+import { crc32, deflateSync } from 'node:zlib';
+/**
+ * A valid, deliberately plain app icon.
+ *
+ * Tauri's bundler refuses to package without one, so a generated shell has to
+ * ship something rather than leaving the first `tauri build` to fail on a
+ * missing file. Encoding it here keeps the generator free of binary fixtures
+ * and of an image dependency; `npx tauri icon <your-icon.png>` replaces it with
+ * the full platform set the moment a project has real artwork.
+ */
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const chunk = (type, data) => {
+    const typeAndData = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(typeAndData) >>> 0);
+    return Buffer.concat([length, typeAndData, crc]);
+};
+/** A flat slate square — recognisably a placeholder, and legible at any size. */
+const FILL = [0x2f, 0x36, 0x40, 0xff];
+export const renderPlaceholderIcon = (size) => {
+    if (!Number.isInteger(size) || size <= 0) {
+        throw new Error(`Icon size must be a positive integer, got ${size}`);
+    }
+    const stride = 1 + size * 4;
+    const raw = Buffer.alloc(size * stride);
+    for (let y = 0; y < size; y++) {
+        const rowStart = y * stride;
+        // Filter type 0 (None) — no prediction, so the row is its own pixels.
+        raw[rowStart] = 0;
+        for (let x = 0; x < size; x++) {
+            const px = rowStart + 1 + x * 4;
+            raw[px] = FILL[0];
+            raw[px + 1] = FILL[1];
+            raw[px + 2] = FILL[2];
+            raw[px + 3] = FILL[3];
+        }
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(size, 0);
+    ihdr.writeUInt32BE(size, 4);
+    ihdr.writeUInt8(8, 8);
+    ihdr.writeUInt8(6, 9);
+    ihdr.writeUInt8(0, 10);
+    ihdr.writeUInt8(0, 11);
+    ihdr.writeUInt8(0, 12);
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        chunk('IHDR', ihdr),
+        chunk('IDAT', deflateSync(raw, { level: 9 })),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+};

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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`.