code2app 0.1.0

package/docs/LOCAL_APPS.md

@@ -0,0 +1,116 @@
+# Packaging a CLI as a native app
+
+Remote mode wraps a website. Local mode wraps something that has no website at all — a
+command-line tool — and turns it into an installable GUI app that needs no runtime on the user's
+machine. `packages/about-system-info/native` is the worked example: the `about-system` CLI, a
+Node program, shipped as a `.msi` / `.dmg` / `.AppImage` that a user who has never installed Node
+can double-click.
+
+## The three pieces
+
+```
+  ┌──────────────────────────┐
+  │ dist/index.html          │   the app's entire UI, bundled into the binary
+  │   invoke("sidecar_output")│
+  └───────────┬──────────────┘
+              │ Tauri IPC
+  ┌───────────▼──────────────┐
+  │ src-tauri/src/lib.rs     │   sidecar_output: fixed args, bundled-content-only
+  │   shell().sidecar(NAME)  │
+  └───────────┬──────────────┘
+              │ spawn + capture stdout
+  ┌───────────▼──────────────┐
+  │ src-tauri/binaries/      │   the CLI, compiled to one self-contained executable
+  │   <name>-<target triple> │   per platform, bundled into the installer
+  └──────────────────────────┘
+```
+
+1. **The frontend** replaces `dist/index.html`. It's plain bundled content, so it can use
+   `window.__TAURI__.core.invoke` directly (the profile sets `withGlobalTauri`) with no build step
+   and no npm dependency.
+2. **The bridge** is `sidecar_output`, defined in `src-tauri/src/lib.rs` and available to any
+   local-mode app for free. It runs the bundled binary with the profile's fixed `sidecar.args` and
+   returns its stdout as a string.
+3. **The binary** is whatever compiles your CLI into one file. For a Node/TypeScript CLI,
+   `bun build --compile` does it; Go and Rust CLIs are already single files; Python needs
+   PyInstaller or similar. It must land at `src-tauri/binaries/<name>-<rust target triple>` —
+   Tauri appends the triple itself so one installer per platform picks up the right build.
+   `scripts/build-sidecar.mjs` runs your build command and puts the result there under the right
+   name; `npm run build:sidecar` calls it, and the `predev`/`prebuild:desktop` hooks call it too,
+   so the binary is never a step you have to remember.
+
+## Configuring it
+
+```jsonc
+{
+  "mode": "local",
+  // and no "url" — local mode loads dist/
+  "sidecar": {
+    "name": "about-system",                    // the binary's base name
+    "args": ["--json"],                        // the fixed argv it is always run with
+    "build": "bun build --compile src/cli.ts --outfile {out}",
+    "buildCwd": ".."                           // where to run that command, relative to the app dir
+  }
+}
+```
+
+`{out}` is the only substitution `build-sidecar.mjs` makes — it expands to the full path, target
+triple and `.exe` suffix included, that Tauri will look for. The build command owns everything
+else, so the wrapper never has to know what language the CLI is written in. A `build` without
+`{out}` is rejected by profile validation rather than quietly producing a binary in the wrong
+place.
+
+`configure` turns that into `bundle.externalBin: ["binaries/about-system"]` plus the Rust
+constants. `tauri build` then **fails** if no binary exists for the platform being built, which is
+the behavior you want: a silently sidecar-less installer would ship a GUI that can't load anything.
+
+## Why the arguments are fixed
+
+`sidecar_output` takes no parameters. The frontend asks for "the output this app is built around";
+it can't choose the argument list. A command that forwarded arbitrary argv to a bundled executable
+would be a process spawner reachable from page content, and in a remote-mode app that page is a
+website.
+
+It also refuses to run unless the calling window is showing bundled content (`tauri://localhost`,
+or `http://tauri.localhost` on Windows). Tauri does already reject app-defined commands from a
+remote origin unless a capability explicitly grants them, so that check is a second line of
+defense — but it's the line that survives someone adding the command to `capabilities/remote.json`
+without thinking it through.
+
+If your app genuinely needs several different invocations, add them as separate commands with
+separate fixed argument lists rather than opening up the one.
+
+**One gotcha if you add your own ACL manifest.** Tauri skips the ACL for app-defined commands
+called from local content *only while the app has no `src-tauri/permissions/` directory of its
+own*. Create one — for any reason — and every app command, `sidecar_output` included, starts
+needing an explicit entry in `capabilities/default.json`, and the app fails with "not allowed by
+ACL" until it gets one.
+
+## Getting the target triple right
+
+Tauri resolves `binaries/<name>` to `binaries/<name>-<triple>` using the *Rust* target triple, not
+Node's `process.platform`. Read it from the toolchain rather than mapping it by hand:
+
+```bash
+rustc -vV | sed -n 's/^host: //p'   # e.g. x86_64-unknown-linux-gnu, aarch64-apple-darwin
+```
+
+`scripts/build-sidecar.mjs` does exactly this: it reads the host triple from the toolchain,
+compiles the CLI, names the output accordingly, and marks it executable.
+
+macOS universal builds (`--target universal-apple-darwin`) need **both**
+`<name>-x86_64-apple-darwin` and `<name>-aarch64-apple-darwin` present, since the sidecar isn't
+lipo'd for you.
+
+## Offline, updates, and size
+
+A local-mode app has no network dependency at all, which is the main reason to choose it. The
+tradeoffs:
+
+- **Size.** A compiled Node CLI is 50–100 MB before the Tauri binary. Nothing about that is
+  avoidable if you want a runtime-free install; a Go or Rust CLI is a fraction of it.
+- **Updates.** There's no server to change, so shipping a fix means shipping a new installer.
+  Tauri's updater (see `BUILDING.md`) is the answer if you want that to be automatic.
+- **Permissions.** The CLI runs with the user's own privileges, exactly as it would in their
+  terminal. If it reads system state, the app reads system state; if it needs elevation, the app
+  needs elevation.

package/docs/MOBILE.md

@@ -0,0 +1,78 @@
+# Android + iOS
+
+The Rust core (`src-tauri/`) is already mobile-ready: `lib.rs`'s `run()` is gated with
+`#[cfg_attr(mobile, tauri::mobile_entry_point)]`, the crate builds as a `staticlib`/`cdylib` for
+FFI, and every desktop-only plugin (single-instance, updater, global-shortcut) is behind
+`#[cfg(not(any(target_os = "android", target_os = "ios")))]`. What's missing is the generated
+native project each platform needs around that core — and generating it needs host tooling this
+package can't assume you have (an Android SDK/NDK install, or a Mac with Xcode), so it isn't
+run automatically. Do it once per machine you build mobile from:
+
+```bash
+npm run android:init   # writes src-tauri/gen/android
+npm run ios:init       # writes src-tauri/gen/apple  (macOS host only)
+```
+
+Both read `src-tauri/tauri.conf.json` (already configured for the active profile — see
+`../profiles/README.md`) to set the package name / bundle id, deep-link scheme, and icons, so run
+`npm run configure` first if you've changed profiles.
+
+## Android
+
+**Requirements** (from the [Tauri mobile prerequisites](https://v2.tauri.app/start/prerequisites/)):
+- Android SDK + **NDK r28 or newer**. NDK ≥28 builds 16KB-page-aligned native libraries, which
+  Google Play now requires for new apps/updates targeting recent devices — an older NDK needs a
+  manual linker workaround this wrapper doesn't set up for you.
+- `ANDROID_HOME` and `NDK_HOME` environment variables pointing at your SDK/NDK install.
+- The Android Rust targets: `rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android`.
+- Minimum supported OS: **API 24** (set via the profile's `android.minSdkVersion`);
+  Google Play itself now requires new/updated apps to **target** API 36 — see
+  `APP_STORES.md`.
+
+```bash
+npm run android:dev      # runs on a connected device/emulator with hot reload
+npm run android:build    # release build; add --apk for a plain APK instead of the .aab Play wants
+```
+
+## iOS
+
+**Requirements**: a macOS host with full **Xcode** installed (not just the Command Line Tools),
+and the iOS Rust targets: `rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim`.
+
+```bash
+npm run ios:dev
+npm run ios:build -- --export-method app-store-connect   # or ad-hoc / development / enterprise
+```
+
+`ios:build` produces an unsigned/ad-hoc `.ipa` unless you've set up a signing identity and
+provisioning profile in `src-tauri/gen/apple`'s Xcode project first (`npm run ios:init` opens it
+for you to configure once) — see `APP_STORES.md` for what App Store distribution needs
+beyond that, including the "minimum functionality" review risk a webview-wrapper app like this one
+should expect on iOS specifically.
+
+## Should `gen/android` / `gen/apple` be committed?
+
+The scaffold's `.gitignore` excludes them by default, since a freshly generated tree matches
+`tauri.conf.json` exactly and re-running `init` reproduces it. If you hand-edit anything inside
+`gen/` directly (native permissions, a custom Gradle/Xcode build step, manual signing config),
+commit that tree instead — Tauri's mobile tooling is built to have `gen/` checked in and patched
+in place for exactly that case, and future `init`/`build` runs preserve local edits rather than
+clobbering them.
+
+## Sidecars don't apply here
+
+A local-mode app that bundles a CLI (`LOCAL_APPS.md`) has no mobile build: neither Android nor iOS
+lets an app spawn a bundled executable, so `bundle.externalBin` is desktop-only. Packaging that
+kind of app for mobile means reimplementing what the CLI does as a Tauri mobile plugin, which is a
+different project. Remote-mode apps have no such limit.
+
+## CI
+
+Android builds on any Linux runner once the SDK/NDK are installed — `android-actions/setup-android`
+plus `rustup target add` for the four Android targets is the usual recipe — and
+`tauri-apps/tauri-action` can build the `.aab` from there. Sign it with an upload key held as
+repository secrets; skip the signing step when they're absent so forks still get an unsigned build.
+
+iOS needs a `macos-*` runner with Xcode plus a distribution certificate and provisioning profile in
+secrets. Whether to wire that up is a decision for whoever holds the Apple Developer account, not
+something to default to for every copy of this wrapper.

package/docs/OAUTH.md

@@ -0,0 +1,76 @@
+# Why login needs a deep link, and how it works
+
+This applies to **remote-mode** apps only, and only to ones whose wrapped site has a login. A
+profile with no `deepLinkScheme` compiles none of this into the app's behavior — local-mode apps
+(`LOCAL_APPS.md`) never need it.
+
+Google (and most OAuth providers) refuse to run their login flow inside an embedded webview —
+Tauri's WebView2/WKWebView/WebKitGTK included. Loading the site and clicking "Continue with Google"
+straight inside the wrapper's window either fails outright or gets flagged as insecure. So sign-in
+has to happen in the user's actual default browser, and the resulting session has to be handed back
+to the wrapper's window afterward — those are two different cookie jars that can't otherwise see
+each other's session.
+
+## The three steps
+
+```
+ Wrapper window                System browser                  Wrapper window
+   (the site)                    (the site)                      (the site)
+┌────────────────┐            ┌──────────────────┐            ┌────────────────┐
+│ login UI        │  opener    │ /login            │            │ /auth/         │
+│ "Continue in    │ ────────► │  → Google OAuth    │            │  native-callback│
+│  your browser"  │  plugin    │  → /auth/          │  deep      │  verifies token │
+│                 │            │    native-complete │  link      │  → session      │
+│                 │            │  generates token,  │ ─────────► │    cookie set   │
+│                 │            │  redirects to      │ myapp://   │  → redirect "/" │
+│                 │            │  myapp://...       │            │                 │
+└────────────────┘            └──────────────────┘            └────────────────┘
+      step 1                        step 2                          step 3
+```
+
+1. **The site's login page** detects it's running inside the wrapper — check for the
+   `window.__TAURI__` global the wrapper injects (the profile sets `withGlobalTauri`, and
+   `capabilities/remote.json` is what makes the opener plugin reachable from the site's origin) —
+   and, instead of rendering the normal social/magic-link buttons, renders one "Continue in your
+   browser" button. Clicking it calls the wrapper's opener plugin (`plugin:opener|open_url`) to
+   open `https://<your-site>/login?callbackURL=/auth/native-complete` in the OS default browser.
+2. The user signs in normally there — whichever provider they pick; none of this page's code needs
+   to know which. Once a session cookie exists, the browser lands on **`/auth/native-complete`**.
+   That page generates a **single-use, short-lived token bound to that session** and redirects the
+   browser to `<scheme>://auth-callback?token=<token>`. The custom scheme (registered by the
+   wrapper from the profile's `deepLinkScheme`) hands the OS back to the installed app.
+3. `src-tauri/src/lib.rs`'s `on_open_url` handler catches that deep link and navigates the
+   wrapper's own window to **`https://<your-site>/auth/native-callback?token=<token>`** — the same
+   origin the window already had loaded, so this is same-origin from here on. That page spends the
+   token against the site's verify endpoint, which sets a session cookie scoped to *this* window's
+   cookie jar, then redirects to `/`. The wrapper's window is now signed in.
+
+## Why the Rust side doesn't call the verify endpoint directly
+
+A verify endpoint is normally a **POST** expecting a JSON body — not something a plain window
+navigation (a GET) can hit. Routing through `/auth/native-callback`'s own client-side `fetch` is
+what actually performs that POST, and doing it from a page already loaded at the site's own origin
+is what makes the resulting `Set-Cookie` land in the right cookie jar with no CORS complications —
+a cross-origin fetch from a `tauri://localhost` asset page would need those, a same-origin one
+doesn't.
+
+## Windows/Linux: why `tauri-plugin-single-instance` is in `Cargo.toml`
+
+Clicking a `<scheme>://` link while the app is already running launches a **second OS process** on
+Windows and Linux instead of delivering the URL to the running one — `on_open_url` alone doesn't
+fire for the already-running instance there. `tauri-plugin-single-instance` intercepts that second
+launch and forwards its argv (which contains the deep-link URL) to `handle_deep_link()` in the
+first, already-running process instead, and focuses its window. macOS doesn't need this —
+`on_open_url` fires correctly there without it.
+
+## What the wrapped site has to provide
+
+Everything above is generic except the page routes — `/login`, `/auth/native-complete`,
+`/auth/native-callback` — which have to exist on whatever the profile's `url` points at. Any auth
+stack with a one-time-token generate/verify pair will do;
+[better-auth's one-time-token plugin](https://better-auth.com/docs/plugins/one-time-token) is one
+ready-made option. The deep-link and Rust-side handoff mechanics in `src-tauri/` don't change
+either way.
+
+`debate/debate-ai.com`'s `apps/debate-native-wrapper` — the wrapper this package was generalized
+from — is a full worked implementation of both halves if you want a reference.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "code2app",
+  "version": "0.1.0",
+  "description": "Tauri scaffold that packages a website or a bundled CLI as a native desktop + mobile app, configured from a single JSON profile",
+  "type": "module",
+  "author": "vtempest",
+  "license": "rights.institute/prosper",
+  "bin": {
+    "native-app-wrapper": "bin/cli.js"
+  },
+  "scripts": {
+    "init": "node bin/cli.js init",
+    "configure": "node bin/cli.js configure",
+    "icons": "node scripts/generate-icons.mjs",
+    "icons:placeholder": "node scripts/generate-placeholder-icons.mjs",
+    "build:sidecar": "node scripts/build-sidecar.mjs",
+    "predev": "node bin/cli.js configure",
+    "dev": "tauri dev",
+    "prebuild:desktop": "node bin/cli.js configure",
+    "build:desktop": "tauri build",
+    "android:init": "tauri android init",
+    "preandroid:dev": "node bin/cli.js configure",
+    "android:dev": "tauri android dev",
+    "preandroid:build": "node bin/cli.js configure",
+    "android:build": "tauri android build",
+    "ios:init": "tauri ios init",
+    "preios:dev": "node bin/cli.js configure",
+    "ios:dev": "tauri ios dev",
+    "preios:build": "node bin/cli.js configure",
+    "ios:build": "tauri ios build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "tauri",
+    "desktop-app",
+    "webview",
+    "app-wrapper",
+    "windows",
+    "macos",
+    "linux",
+    "android",
+    "ios",
+    "sidecar"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenSourceAGI/dev-tools-starter-agent.git",
+    "directory": "packages/native-app-wrapper"
+  },
+  "homepage": "https://github.com/OpenSourceAGI/dev-tools-starter-agent/tree/master/packages/native-app-wrapper",
+  "devDependencies": {
+    "@tauri-apps/cli": "^2",
+    "@vitest/coverage-v8": "^4.1.0",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "@tauri-apps/api": "^2",
+    "@tauri-apps/plugin-deep-link": "^2",
+    "@tauri-apps/plugin-opener": "^2",
+    "@tauri-apps/plugin-process": "^2",
+    "@tauri-apps/plugin-shell": "^2",
+    "@tauri-apps/plugin-updater": "^2"
+  }
+}

package/profiles/README.md

@@ -0,0 +1,56 @@
+# Profiles
+
+A profile is the one JSON file you edit to say what app this wrapper is. Everything else —
+`src-tauri/tauri.conf.json`, the Rust constants, the remote capability's origin scope, the icon
+set — is generated from it by `node bin/cli.js configure`, so the profile is the only place an app
+identity is written down.
+
+Copy `example.json`, fill it in, and either drop it in this folder or hand it straight to
+`node bin/cli.js init <dir> --profile-file <path>` to scaffold a standalone copy of the wrapper
+around it.
+
+## Fields
+
+| Field | Meaning |
+|---|---|
+| `appName` / `productName` | Display name used in window titles, installers, and store listings. `productName` defaults to `appName`. |
+| `identifier` | Reverse-DNS app id (e.g. `com.example.app`). Used as the Tauri `identifier`, the Android `applicationId`, and the iOS bundle id unless overridden under `android`/`ios`. Changing this after a store release changes the app's identity — don't. |
+| `version` | Semantic version written into `tauri.conf.json`. Bump this to trigger a new store/release version. |
+| `mode` | `"remote"` (default) loads `url` in the main window; `"local"` bundles `dist/` as the app's frontend. See below. |
+| `url` | **Remote mode only, required.** The site the wrapper loads. Must be HTTPS (`http://localhost` is allowed for local dev). Setting it in local mode is an error rather than a silently ignored field. |
+| `sidecar` | **Local mode only.** `{ "name", "args", "build", "buildCwd" }` — a CLI bundled next to the app binary and exposed to the bundled frontend through the `sidecar_output` command. `args` is the fixed argument list it's always run with (default: none); `build` is the command that compiles it, with `{out}` standing in for the path Tauri expects. See `../docs/LOCAL_APPS.md`. |
+| `deepLinkScheme` | Optional custom URL scheme (e.g. `exampleapp` → `exampleapp://...`) registered with the OS so the site's OAuth login page can hand a session back to the app window. Omit it and the whole deep-link path compiles out of the app's behavior. See `../docs/OAUTH.md`. |
+| `trustedOrigins` | Origins allowed to use the scoped Tauri IPC bridge — keep this to exactly the domains you control. `capabilities/remote.json` is generated from this list; leave it empty (or omit it) and the wrapper loads no remote capability at all, which is what a local-mode app wants. |
+| `iconSource` | Path (relative to the profile file) to a single square PNG, at least 1024x1024, used to generate every platform's icon set via `npm run icons`. |
+| `placeholderIcon` | `{ "background": ["#top", "#bottom"], "accent": "#fg" }` — colors for the generated stand-in icon set (`node bin/cli.js icons`), used until you have real artwork. |
+| `copyright` / `publisher` / `category` / `shortDescription` / `longDescription` | Metadata surfaced in installers and store listings. `category` should match the target store's taxonomy (e.g. Apple's `public.app-category.*`, Microsoft Store, Google Play categories — see `../docs/APP_STORES.md`). |
+| `window` | Initial window size/behavior. `fullscreen: true` opens the app in true OS fullscreen (no window chrome); users can leave it with the in-app fullscreen toggle (F11 / Ctrl+Shift+F). |
+| `updater` | Optional `{ "pubkey", "endpoints": [...] }` — turns on `tauri-plugin-updater`. Leave it out and the plugin isn't registered at all; see `../docs/BUILDING.md` for why an "off" updater config is a crash rather than a disabled feature. |
+| `macos` | `{ "minimumSystemVersion": "10.15" }`. |
+| `android` / `ios` | Mobile-specific overrides (package name, minimum OS version). Omit both if the app is desktop-only. |
+
+## Remote vs. local mode
+
+**Remote** is for packaging a website: the window loads the live site, `dist/` stays an unused
+placeholder, and the app is useless offline — exactly like a browser tab pointed at the same URL.
+The wrapper's added value is OS-level: an icon, an installer, a deep-link login handoff.
+
+**Local** is for packaging something that isn't a website: the window loads `dist/index.html`, the
+app ships everything it needs, and it works with no network. Pair it with a `sidecar` when the data
+comes from a CLI you already have — the bundled binary runs on demand and the frontend renders its
+output.
+
+The two modes are mutually exclusive by validation, not by convention: a local profile with a `url`
+and a remote profile with a `sidecar` are both rejected by `scripts/profile.mjs` rather than
+half-working.
+
+## Regenerating
+
+```bash
+node bin/cli.js configure          # tauri.conf.json + generated_config.rs + capabilities/remote.json
+node bin/cli.js icons              # placeholder icon set from placeholderIcon's colors
+npm run icons                      # real icon set from iconSource, via the Tauri CLI
+```
+
+A directory with exactly one profile (what `init` produces) needs no `--profile` flag. This package
+itself keeps only `example.json`, so its own scripts fall back to that.

package/profiles/example.json

@@ -0,0 +1,37 @@
+{
+  "_comment": "Copy this file to profiles/<your-app>.json and fill in every field, or scaffold a fresh copy of the wrapper somewhere else with `node bin/cli.js init <dir> --profile-file <your-profile.json>`. JSON has no comments, so field docs live in profiles/README.md.",
+
+  "appName": "Example App",
+  "productName": "Example App",
+  "identifier": "com.example.app",
+  "version": "0.1.0",
+  "mode": "remote",
+  "url": "https://example.com",
+  "deepLinkScheme": "exampleapp",
+  "iconSource": "../assets/icon-source.png",
+  "placeholderIcon": {
+    "background": ["#1e293b", "#0b1220"],
+    "accent": "#f8fafc"
+  },
+  "copyright": "Example, Inc.",
+  "category": "Productivity",
+  "shortDescription": "One-line description shown in store listings.",
+  "trustedOrigins": ["https://example.com", "https://*.example.com"],
+  "window": {
+    "title": "Example App",
+    "width": 1280,
+    "height": 800,
+    "minWidth": 480,
+    "minHeight": 480,
+    "fullscreen": false,
+    "resizable": true
+  },
+  "android": {
+    "packageName": "com.example.app",
+    "minSdkVersion": 24
+  },
+  "ios": {
+    "bundleId": "com.example.app",
+    "minimumSystemVersion": "14.0"
+  }
+}

package/scripts/build-sidecar.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Compiles the profile's sidecar CLI into src-tauri/binaries/<name>-<target triple>,
+// which is where Tauri's `bundle.externalBin` looks for it.
+//
+// The triple is read from the installed Rust toolchain rather than mapped from
+// process.platform: Tauri appends the *Rust* target triple, and getting it from
+// the toolchain is the only way the name can't disagree with what the bundler
+// then searches for. A mismatch shows up as "binary not found" at bundle time,
+// after the whole Rust build has already run.
+
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { loadProfile, resolveProfileName } from "./profile.mjs";
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function hostTargetTriple() {
+  const verbose = execFileSync("rustc", ["-vV"], { encoding: "utf8" });
+  const match = /^host:\s*(\S+)$/m.exec(verbose);
+  if (!match) throw new Error("could not read the host target triple from `rustc -vV`");
+  return match[1];
+}
+
+export function buildSidecar(rootDir, profile) {
+  if (!profile.sidecar) {
+    return { skipped: "the profile bundles no sidecar" };
+  }
+  if (!profile.sidecar.build) {
+    throw new Error(
+      `profiles/${profile.name}.json's sidecar has no "build" command, so there is nothing to ` +
+        "compile. Add one (see docs/LOCAL_APPS.md) or drop the binary into src-tauri/binaries/ yourself.",
+    );
+  }
+
+  const triple = hostTargetTriple();
+  const suffix = triple.includes("windows") ? ".exe" : "";
+  const outDir = path.join(rootDir, "src-tauri", "binaries");
+  const outPath = path.join(outDir, `${profile.sidecar.name}-${triple}${suffix}`);
+  mkdirSync(outDir, { recursive: true });
+
+  // {out} is the only substitution: the build command owns everything else about
+  // how the CLI is compiled, so this script never has to know the language or
+  // bundler involved.
+  const command = profile.sidecar.build.replaceAll("{out}", outPath);
+  const cwd = path.resolve(rootDir, profile.sidecar.buildCwd ?? ".");
+
+  console.log(`[native-app-wrapper] building sidecar for ${triple}`);
+  console.log(`  ${command}`);
+  console.log(`  (in ${cwd})`);
+
+  const result = spawnSync(command, { cwd, stdio: "inherit", shell: true });
+  if (result.status !== 0) {
+    throw new Error(`sidecar build command failed with exit code ${result.status}`);
+  }
+  if (!existsSync(outPath)) {
+    throw new Error(
+      `sidecar build command succeeded but wrote nothing to ${outPath} — the command must honor {out}`,
+    );
+  }
+  if (!suffix) chmodSync(outPath, 0o755);
+
+  return { outPath: path.relative(rootDir, outPath), triple };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const profile = loadProfile(rootDir, resolveProfileName(rootDir));
+  try {
+    const result = buildSidecar(rootDir, profile);
+    if (result.skipped) {
+      console.log(`[native-app-wrapper] nothing to build: ${result.skipped}`);
+    } else {
+      console.log(`[native-app-wrapper] wrote ${result.outPath}`);
+    }
+  } catch (error) {
+    console.error(`[native-app-wrapper] ${error.message}`);
+    process.exit(1);
+  }
+}