Tooling: CMDR_INSTANCE_ID primitive (P1/6)

- New apps/desktop/scripts/instance-id.js: pure helpers (sanitizer, instance derivation, identifier / productName / app-data-dir composition, --worktree flag extractor). Vitest-tested in scripts/instance-id.test.js (29 cases).
- Rewrite tauri-wrapper.js around the new helpers. It resolves CMDR_INSTANCE_ID (existing env wins, then --worktree-derived dev-<slug>, then "dev" in dev mode, else unset for prod), computes CMDR_DATA_DIR to match Tauri's app_data_dir() for the same identifier, and writes a fresh tauri.instance.json under $TMPDIR/cmdr-tauri-instance-<rand>/ that it passes via -c <abs path>. Cleanup on exit / SIGINT / SIGTERM; /tmp self-prune is the load-bearing fallback.
- The generated config also flips withGlobalTauri to true and points the updater at a dead URL (https://localhost.invalid/no-updater) so non-prod instances never phone home.
- pnpm dev --worktree foo -- --features virtual-mtp parses correctly: the wrapper extracts the slug before --, leaves --features through to Tauri.
- Worktree slug sanitization: lowercase ASCII [a-z0-9-]+, runs of dashes collapsed, trimmed, max 32 chars, retrim after slice. Rejects empty input with a descriptive error (thrown in Node before any Rust process spawns).
- Force CMDR_SECRET_STORE=file for any non-prod instance (preserves no-Keychain-dialog dev UX).
- Delete apps/desktop/src-tauri/tauri.dev.json: replaced by the wrapper-generated file.
- config.rs: extract data_dir_from_env helper so the CMDR_DATA_DIR branch of resolved_app_data_dir is unit-testable without a Tauri mock runtime. Empty CMDR_DATA_DIR is now treated as unset (falls through to Tauri default) instead of silently landing in cwd-equivalent paths.
- Vitest config includes scripts/**/*.test.js so the new wrapper tests run.
- Doc sweep: AGENTS.md Debugging, CONTRIBUTING.md MTP example, apps/desktop/CLAUDE.md Running, docs/security.md withGlobalTauri, apps/desktop/src-tauri/src/config.rs comment, apps/desktop/src-tauri/src/mtp/CLAUDE.md virtual-mtp recipe.
- Prod path bit-for-bit identical: pnpm build skips instance composition entirely, so canonical tauri.conf.json governs the bundle and identifier stays com.veszelovszki.cmdr.

Author: vdavid

AGENTS.md

@@ -151,12 +151,15 @@ Three cadences. Pick the one that matches where you are in the work, not the one
 
 ## Debugging
 
-- **Data dirs (dev and prod are separate!)**: Prod: `~/Library/Application Support/com.veszelovszki.cmdr/`, Dev:
-  `~/Library/Application Support/com.veszelovszki.cmdr-dev/`. The split has two prongs that converge on the same path:
-  (1) `tauri.dev.json` overrides `identifier` to `com.veszelovszki.cmdr-dev` so Tauri's own `app_data_dir()` (and
-  anything keyed off it, e.g. `tauri-plugin-store`'s `settings.json`) lands in the dev path; (2) `tauri-wrapper.js` sets
-  `CMDR_DATA_DIR` to the same path so `src-tauri/src/config.rs::data_dir()` and direct file I/O (crash reports, logs,
-  the file-backed secret store) all agree without round-tripping through Tauri's API.
+- **Data dirs (prod, dev, and dev-per-worktree are separate!)**: Prod:
+  `~/Library/Application Support/com.veszelovszki.cmdr/`. Dev (plain `pnpm dev`):
+  `~/Library/Application Support/com.veszelovszki.cmdr-dev/`. A per-worktree dev session started with
+  `pnpm dev --worktree foo` lives at `~/Library/Application Support/com.veszelovszki.cmdr-dev-foo/`. The wrapper
+  (`apps/desktop/scripts/tauri-wrapper.js`) resolves `CMDR_INSTANCE_ID` from flags and env, writes a fresh
+  `tauri.instance.json` under `$TMPDIR` with the matching identifier (so Tauri's own `app_data_dir()` lands on the right
+  path), and exports `CMDR_DATA_DIR` to the same path so direct file I/O (crash reports, logs, file-backed secret store)
+  agrees without round-tripping through Tauri's API. See
+  [`docs/specs/instance-isolation-plan.md`](docs/specs/instance-isolation-plan.md) for the full design.
 - **Logging**: Frontend and backend logs appear together in terminal and in the log dir (dev: `<CMDR_DATA_DIR>/logs/`,
   prod: `~/Library/Logs/com.veszelovszki.cmdr/`). **Read [docs/tooling/logging.md](docs/tooling/logging.md) before using
   `RUST_LOG`**: it has copy-paste recipes for every subsystem. Key gotcha: the Rust library target is `cmdr_lib`, not

CONTRIBUTING.md

@@ -59,9 +59,13 @@ This starts both the Svelte frontend and the Rust backend with hot reload.
 To test with a virtual MTP device (simulated Android phone):
 
 ```bash
-cd apps/desktop && pnpm tauri dev -c src-tauri/tauri.dev.json --features virtual-mtp
+pnpm dev -- --features virtual-mtp
 ```
 
+This still flows through `apps/desktop/scripts/tauri-wrapper.js`, which generates the per-instance config (bundle
+identifier, `CMDR_DATA_DIR`, file-backed secret store) on the fly. Pass `--worktree <slug>` first to isolate a
+worktree's data dir from your main dev session: `pnpm dev --worktree foo -- --features virtual-mtp`.
+
 ## Debug window
 
 In dev mode, press **Cmd+D** to open a debug window. This window is only available in dev builds and provides:

apps/desktop/CLAUDE.md

@@ -10,9 +10,16 @@ the full subsystem map. Feature-level docs live in colocated `CLAUDE.md` files n
 Run from repo root: `pnpm dev` (start) and `pnpm build` (release build). Don't `cd` here just to run the app.
 
 If you've already `cd`d into `apps/desktop/`, `pnpm tauri dev` is equivalent; both paths invoke
-`scripts/tauri-wrapper.js`, which sets `CMDR_DATA_DIR` and injects `tauri.dev.json`. The wrapper is the single source of
-truth for dev/prod path separation; bypassing it (raw `cargo tauri dev`, raw `cargo build`) gives you the wrong data dir
-or a binary with no embedded frontend.
+`scripts/tauri-wrapper.js`, which resolves `CMDR_INSTANCE_ID` (from `--worktree <slug>` or the existing env, else
+`"dev"`), composes `CMDR_DATA_DIR` to match, and writes a fresh `tauri.instance.json` under `$TMPDIR` that overrides the
+bundle identifier and `productName` for this instance. The wrapper is the single source of truth for dev / prod path
+separation; bypassing it (raw `cargo tauri dev`, raw `cargo build`) gives you the wrong data dir or a binary with no
+embedded frontend.
+
+To run two dev sessions side-by-side from different worktrees without colliding on `settings.json`, ports, or the Dock
+label, pass `--worktree <slug>`: `pnpm dev --worktree my-feature`. The slug is sanitized to lowercase ASCII (max 32
+chars) and feeds into both the bundle identifier (`com.veszelovszki.cmdr-dev-my-feature`) and the data dir. See
+[`docs/specs/instance-isolation-plan.md`](../../docs/specs/instance-isolation-plan.md) for the full design.
 
 ## Structure
 

apps/desktop/scripts/instance-id.js

@@ -0,0 +1,202 @@
+// Pure helpers for the CMDR_INSTANCE_ID primitive. Kept side-effect-free so vitest can
+// exercise them without spawning Tauri. See docs/specs/instance-isolation-plan.md for the
+// full design.
+//
+// One env var (CMDR_INSTANCE_ID) drives every per-instance suffix the wrapper composes:
+//   - prod (pnpm build):            unset
+//   - pnpm dev (no --worktree):     "dev"
+//   - pnpm dev --worktree foo:      "dev-<sanitized slug>"
+//   - E2E checker (set externally): preserved as-is
+//
+// The wrapper derives CMDR_DATA_DIR, bundle identifier, productName, and (in later phases)
+// Vite port + MCP ports from this single string.
+
+import { join } from 'path'
+
+const PROD_IDENTIFIER = 'com.veszelovszki.cmdr'
+const PROD_PRODUCT_NAME = 'Cmdr'
+const MAX_SLUG_LEN = 32
+
+/**
+ * Sanitize a --worktree slug to lowercase ASCII [a-z0-9-], collapsed dashes, trimmed, max 32 chars.
+ * The wrapper does NOT validate the slug against the actual worktree directory name. The user
+ * picks their own slug; this just makes sure the result is safe for a CFBundleIdentifier.
+ *
+ * Returns the sanitized slug, or null if the input collapses to empty (caller throws).
+ *
+ * @param {unknown} raw
+ * @returns {string|null}
+ */
+export function sanitizeWorktreeSlug(raw) {
+  if (typeof raw !== 'string') return null
+  // Lowercase, replace any non-[a-z0-9-] with '-', collapse runs, trim leading/trailing '-'.
+  const cleaned = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, MAX_SLUG_LEN)
+    .replace(/-+$/, '') // re-trim in case slice cut mid-run
+  return cleaned.length > 0 ? cleaned : null
+}
+
+/**
+ * Derive CMDR_INSTANCE_ID for a dev or prod invocation.
+ *
+ * Precedence:
+ *   1. existing env (caller responsible for setting, e.g. the E2E checker)
+ *   2. --worktree <slug> in dev mode → "dev-<sanitized>"
+ *   3. dev mode with no flag → "dev"
+ *   4. prod / anything else → null (caller leaves the env unset)
+ *
+ * @param {object} opts
+ * @param {boolean} opts.isDev
+ * @param {string|undefined} opts.envInstanceId  the current value of CMDR_INSTANCE_ID, if any
+ * @param {string|null|undefined} opts.worktreeSlug  raw --worktree argument (pre-sanitization)
+ * @returns {string|null}
+ */
+export function resolveInstanceId({ isDev, envInstanceId, worktreeSlug }) {
+  if (envInstanceId && envInstanceId.length > 0) return envInstanceId
+  if (!isDev) return null
+  if (worktreeSlug != null) {
+    const slug = sanitizeWorktreeSlug(worktreeSlug)
+    if (slug === null) {
+      throw new Error(
+        `--worktree must be 1-${MAX_SLUG_LEN} alphanumeric or dash characters after sanitization (got: ${JSON.stringify(worktreeSlug)})`,
+      )
+    }
+    return `dev-${slug}`
+  }
+  return 'dev'
+}
+
+/**
+ * Compute the Tauri-equivalent app_data_dir for an identifier on this OS. Mirrors the
+ * platform branches in resolved_app_data_dir on the Rust side and the legacy block this
+ * file replaces in tauri-wrapper.js.
+ *
+ * @param {object} opts
+ * @param {string} opts.identifier  e.g. com.veszelovszki.cmdr-dev
+ * @param {NodeJS.Platform} opts.platform
+ * @param {string} opts.home  homedir()
+ * @param {string|undefined} opts.xdgDataHome  process.env.XDG_DATA_HOME
+ * @returns {string}
+ */
+export function computeAppDataDir({ identifier, platform, home, xdgDataHome }) {
+  if (platform === 'darwin') {
+    return join(home, 'Library', 'Application Support', identifier)
+  }
+  const base = xdgDataHome && xdgDataHome.length > 0 ? xdgDataHome : join(home, '.local', 'share')
+  return join(base, identifier)
+}
+
+/**
+ * Compose the bundle identifier from an instance ID. Unset → prod default.
+ *
+ * @param {string|null} instanceId
+ * @returns {string}
+ */
+export function bundleIdentifier(instanceId) {
+  return instanceId ? `${PROD_IDENTIFIER}-${instanceId}` : PROD_IDENTIFIER
+}
+
+/**
+ * Compose the Dock / process label (productName) from an instance ID. Unset → "Cmdr".
+ *
+ * @param {string|null} instanceId
+ * @returns {string}
+ */
+export function productName(instanceId) {
+  return instanceId ? `Cmdr (${instanceId})` : PROD_PRODUCT_NAME
+}
+
+/**
+ * Pull a --worktree value out of an argv array, returning { slug, rest }.
+ * - Honors the `--` separator: anything after it is left as-is for Tauri.
+ * - Recognizes `--worktree foo` and `--worktree=foo`.
+ * - Removes the consumed tokens from the returned `rest`.
+ *
+ * @param {string[]} argv
+ * @returns {{ slug: string|null, rest: string[] }}
+ */
+export function extractWorktreeFlag(argv) {
+  const sepIdx = argv.indexOf('--')
+  const beforeSep = sepIdx >= 0 ? argv.slice(0, sepIdx) : argv.slice()
+  const afterSep = sepIdx >= 0 ? argv.slice(sepIdx) : []
+
+  let slug = null
+  const kept = []
+  for (let i = 0; i < beforeSep.length; i++) {
+    const a = beforeSep[i]
+    if (a === '--worktree') {
+      slug = beforeSep[i + 1] ?? null
+      i += 1 // skip the value
+      continue
+    }
+    if (a.startsWith('--worktree=')) {
+      slug = a.slice('--worktree='.length)
+      continue
+    }
+    kept.push(a)
+  }
+  return { slug, rest: [...kept, ...afterSep] }
+}
+
+/**
+ * @typedef {{
+ *   $schema: string,
+ *   productName: string,
+ *   identifier: string,
+ *   app: { withGlobalTauri: boolean },
+ *   plugins: { updater: { endpoints: string[] } },
+ * }} InstanceConfig
+ */
+
+/**
+ * Build the Tauri config payload that the wrapper writes to disk and passes via -c.
+ *
+ * For prod (instanceId null), returns null: the wrapper omits -c entirely so canonical
+ * tauri.conf.json governs the build.
+ *
+ * @param {string|null} instanceId
+ * @returns {InstanceConfig|null}
+ */
+export function buildInstanceConfig(instanceId) {
+  if (!instanceId) return null
+  return {
+    $schema: 'https://schema.tauri.app/config/2',
+    productName: productName(instanceId),
+    identifier: bundleIdentifier(instanceId),
+    app: {
+      withGlobalTauri: true,
+    },
+    plugins: {
+      updater: {
+        // Dead URL so non-prod instances never phone home accidentally. P4 will replace
+        // this with a real per-instance stub when the Vite dev port also lands here.
+        endpoints: ['https://localhost.invalid/no-updater'],
+      },
+    },
+  }
+}
+
+/**
+ * Convenience for tests + the wrapper: from an instance ID, compute the (identifier, data dir,
+ * config payload) triple in one place so the precedence rules can't drift.
+ *
+ * @param {object} opts
+ * @param {string|null} opts.instanceId
+ * @param {NodeJS.Platform} opts.platform
+ * @param {string} opts.home
+ * @param {string|undefined} opts.xdgDataHome
+ * @returns {{ identifier: string, dataDir: string, config: InstanceConfig|null }}
+ */
+export function deriveInstance({ instanceId, platform, home, xdgDataHome }) {
+  const identifier = bundleIdentifier(instanceId)
+  const dataDir = computeAppDataDir({ identifier, platform, home, xdgDataHome })
+  const config = buildInstanceConfig(instanceId)
+  return { identifier, dataDir, config }
+}
+
+// Re-export the platform default for callers that need to detect "no override".
+export const PRODUCTION_IDENTIFIER = PROD_IDENTIFIER