stikfix 1.2.0

package/dist/host/src/config.js

@@ -0,0 +1,147 @@
+/**
+ * Config resolution for stikfix-host.
+ * D-07: token resolution order --token -> STIKFIX_TOKEN -> crypto.randomUUID()
+ * D-09: ensureNotesDir creates notesDir + .gitkeep (HOST-12)
+ * D-10: resolveConfig rejects notesDir outside root (HOST-09)
+ * Pattern 11: VERSION read from package.json at runtime via import.meta.url
+ * Windows-PowerShell compat: npm 11.x on Windows strips unknown flags and exposes
+ *   them as process.env.npm_config_<key>. resolveConfig accepts all three sources
+ *   with precedence: parsed flag > STIKFIX_* env > npm_config_* env.
+ */
+import { readFileSync, mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { resolve, join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { isInsideDir } from './security.js';
+// ---------------------------------------------------------------------------
+// VERSION — read from package.json at runtime (Pattern 11)
+// dist/host/src/config.js → ../../../package.json
+// ---------------------------------------------------------------------------
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const _pkg = JSON.parse(readFileSync(join(__dirname, '../../../package.json'), 'utf8'));
+export const VERSION = _pkg.version;
+// ---------------------------------------------------------------------------
+// resolveConfigValues — three-tier env resolution (exported for testing)
+// ---------------------------------------------------------------------------
+/**
+ * Merge parsed CLI flags with env-variable fallbacks.
+ *
+ * Precedence (first defined wins) per key:
+ *   1. Real parsed flag  (values.root, values.origin, …)         — git bash / macOS / Linux
+ *   2. STIKFIX_* env   (STIKFIX_ROOT, STIKFIX_ORIGINS, …) — explicit env override
+ *   3. npm_config_* env  (npm_config_root, npm_config_origin, …) — npm-on-Windows PowerShell
+ *
+ * Callers must not assume root is present — resolveConfig validates below.
+ */
+export function resolveConfigValues(values, env = process.env) {
+    // root
+    const root = values['root'] ??
+        env['STIKFIX_ROOT'] ??
+        env['npm_config_root'];
+    // origin / origins — flag: string[] (multiple:true); env: comma-separated string
+    const originFlag = values['origin'];
+    let origins;
+    if (originFlag !== undefined && originFlag.length > 0) {
+        origins = originFlag;
+    }
+    else {
+        const originsEnv = env['STIKFIX_ORIGINS'] ??
+            env['npm_config_origin'];
+        if (originsEnv !== undefined && originsEnv !== '') {
+            origins = originsEnv.split(',').map((s) => s.trim()).filter(Boolean);
+        }
+    }
+    // name
+    const name = values['name'] ??
+        env['STIKFIX_NAME'] ??
+        env['npm_config_name'];
+    // notes-dir
+    const notesDir = values['notes-dir'] ??
+        env['STIKFIX_NOTES_DIR'] ??
+        env['npm_config_notes_dir'];
+    // port
+    const port = values['port'] ??
+        env['STIKFIX_PORT'] ??
+        env['npm_config_port'];
+    // token — D-07 (STIKFIX_TOKEN already documented in PRD §8.1)
+    const token = values['token'] ??
+        env['STIKFIX_TOKEN'] ??
+        env['npm_config_token'];
+    return {
+        root,
+        origin: origins,
+        name,
+        'notes-dir': notesDir,
+        port,
+        token,
+    };
+}
+// ---------------------------------------------------------------------------
+// resolveConfig
+// ---------------------------------------------------------------------------
+/**
+ * Resolve CLI parseArgs values into a validated Config.
+ * Applies three-tier env resolution via resolveConfigValues before validation.
+ * Throws if notesDir resolves outside root (D-10).
+ */
+export function resolveConfig(values) {
+    const v = resolveConfigValues(values);
+    if (typeof v['root'] !== 'string' || !v['root']) {
+        throw new Error('--root is required');
+    }
+    const root = resolve(v['root']);
+    const name = v['name'] ?? basename(root);
+    // origins: resolved by resolveConfigValues, fallback to []
+    const origins = v['origin'] ?? [];
+    const notesDirRaw = v['notes-dir'];
+    const notesDir = resolve(notesDirRaw ?? join(root, 'notes'));
+    // D-10: notesDir must be inside root
+    if (!isInsideDir(root, notesDir)) {
+        throw new Error(`--notes-dir must be inside --root.\n  root:     ${root}\n  notesDir: ${notesDir}`);
+    }
+    const portStr = v['port'];
+    let port;
+    if (portStr !== undefined) {
+        // WR-05: validate port — Number('abc') → NaN, Number('0x10') → 16, etc.
+        port = Number(portStr);
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new Error(`--port must be an integer 1-65535, got: ${portStr}`);
+        }
+    }
+    // D-07 token resolution order (npm_config_token handled in resolveConfigValues)
+    const token = v['token'] ?? randomUUID();
+    return { root, notesDir, name, origins, port, token };
+}
+// ---------------------------------------------------------------------------
+// ensureNotesDir (HOST-12)
+// ---------------------------------------------------------------------------
+/**
+ * Create notesDir (recursively) if it does not exist.
+ * Write a .gitkeep file if absent so the empty dir is tracked by git.
+ */
+export function ensureNotesDir(notesDir) {
+    mkdirSync(notesDir, { recursive: true });
+    const gitkeep = join(notesDir, '.gitkeep');
+    if (!existsSync(gitkeep)) {
+        writeFileSync(gitkeep, '');
+    }
+}
+// ---------------------------------------------------------------------------
+// writeTokenFile (HOST-12)
+// ---------------------------------------------------------------------------
+/**
+ * Write the resolved token to <root>/.stikfix-token for developer convenience.
+ * The file is already gitignored (verified in Phase 1).
+ *
+ * The token is a credential, so the file is created owner-only (mode 0o600).
+ * Any pre-existing file is removed first so a prior, looser-permissioned inode
+ * (e.g. 0o644) is not reused. POSIX mode bits are honored on macOS/Linux; on
+ * Windows they are largely ignored by the filesystem, which is acceptable.
+ */
+export function writeTokenFile(root, token) {
+    const tokenPath = join(root, '.stikfix-token');
+    if (existsSync(tokenPath)) {
+        rmSync(tokenPath, { force: true });
+    }
+    writeFileSync(tokenPath, token, { encoding: 'utf8', mode: 0o600 });
+}

package/dist/host/src/extension-id.js

@@ -0,0 +1,49 @@
+/**
+ * deriveExtensionId — deterministic Chrome extension ID derivation from a
+ * base64-encoded SPKI/DER public key (the same value used in manifest.json `key`).
+ *
+ * Algorithm (Phase 9 / RESEARCH Pattern 3):
+ *   1. Base64-decode the manifest `key` field to get DER bytes.
+ *   2. SHA-256 hash the DER bytes.
+ *   3. Take the first 16 bytes (= first 32 hex nibbles).
+ *   4. Map each nibble 0-f to the letter a-p  (0→a, 1→b, … 9→j, a→k, … f→p).
+ *
+ * This matches how Chrome computes the extension ID from the key field.
+ * [VERIFIED: developer.chrome.com/docs/extensions/reference/manifest/key]
+ *
+ * Node builtins only — no WXT, no Chrome imports.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * The stable extension ID derived from the committed public key in wxt.config.ts.
+ * Generated during Phase 9 bootstrapping (2026-06-05).
+ * Private key is at .keys/stikfix-extension.pem (gitignored).
+ *
+ * If you regenerate the keypair, update wxt.config.ts `key` field AND this constant.
+ */
+export const STABLE_EXTENSION_ID = 'ccdfmbhdcafhmnnnfjpbhgebfkfgjgca';
+/**
+ * The base64 SPKI/DER public key matching STABLE_EXTENSION_ID.
+ * Committed in wxt.config.ts `key` field and stored in .keys/manifest-key.txt.
+ */
+export const MANIFEST_PUBLIC_KEY = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1RFrtpIlsiHwm21+ISi8v5381HQeJq2pw4lgbvqQ2a6o2uZ6H1uHfT+1xRy2msqHzXMOJOhwfAKuwBoebATIFDcms132Msz11DJPHUgoVX29sh9PWxUN5aJ/KovtPgIXoEDTKg/QtV+C9Hza0bcdncqymi9xBw5De/rRn/ZQdkXx2ZFiIm6AuHE0Q4dJrSPLqRLEFxP7mf+/SNPQ0LGDYsWUBbDLz8ksMU0VrrDDtRbDSPhBglxNzVYv00MYpwPEHijBCG9wQ57a34tDuA2/TFvNSwpbkWIYiGe6GyN5DvVHdIZgHcmTxSoY43Xu8EAvX+isRp3DdK8j3tAx1C/wIwIDAQAB';
+/**
+ * Derive the Chrome extension ID from a base64-encoded SPKI/DER public key.
+ *
+ * @param publicKeyBase64 - Base64-encoded DER/SPKI public key (the manifest `key` value).
+ * @returns 32-character lowercase extension ID using the a-p alphabet.
+ *
+ * @example
+ * const id = deriveExtensionId(MANIFEST_PUBLIC_KEY);
+ * // → 'ccdfmbhdcafhmnnnfjpbhgebfkfgjgca'
+ */
+export function deriveExtensionId(publicKeyBase64) {
+    const derBytes = Buffer.from(publicKeyBase64, 'base64');
+    const hash = createHash('sha256').update(derBytes).digest('hex');
+    // Take first 32 hex nibbles (16 bytes) and map 0-f → a-p
+    return hash
+        .slice(0, 32)
+        .split('')
+        .map((c) => String.fromCharCode('a'.charCodeAt(0) + parseInt(c, 16)))
+        .join('');
+}

package/dist/host/src/folder-picker.js

@@ -0,0 +1,142 @@
+/**
+ * OS native folder-picker dialog for stikfix (D-04).
+ * Spawns the OS dialog binary via execFile (NEVER exec, NEVER shell:true).
+ * Arguments are a static array — no user-supplied strings interpolated into
+ * shell command context (T-09-01 / RESEARCH Pattern 5).
+ *
+ * Node builtins only — no WXT, no Chrome imports.
+ */
+import { execFile } from 'node:child_process';
+/**
+ * Build the command + argument array for the OS folder-picker dialog.
+ *
+ * Security contract (T-09-01):
+ * - Uses execFile (not exec) — no shell spawned
+ * - The `title` is the only variable input; it is escaped for safe use in
+ *   the dialog command but never allows shell metacharacters to pass through
+ * - No user-controlled input (origin, username, path) is interpolated into
+ *   the command string beyond the developer-static dialog title
+ *
+ * @param plat - NodeJS.Platform override for testing
+ * @param title - Static dialog title (developer-controlled)
+ */
+export function buildPickerArgs(plat = process.platform, title = 'Choose folder') {
+    switch (plat) {
+        case 'win32': {
+            // PowerShell FolderBrowserDialog — fixed arg array, no shell interpolation.
+            // Single-quote escape: replace ' with '' (PowerShell string literal escape).
+            // Title is developer-controlled (static label) — not user/origin input.
+            const safeTitle = title.replace(/'/g, "''");
+            return {
+                cmd: 'powershell.exe',
+                args: [
+                    '-NoProfile',
+                    '-NonInteractive',
+                    '-OutputFormat',
+                    'Text',
+                    '-Command',
+                    `Add-Type -AssemblyName System.Windows.Forms;` +
+                        `$owner = New-Object System.Windows.Forms.Form;` +
+                        `$owner.TopMost = $true; $owner.ShowInTaskbar = $false;` +
+                        `$owner.Opacity = 0; $owner.Show(); $owner.Activate();` +
+                        `$d = New-Object System.Windows.Forms.FolderBrowserDialog;` +
+                        `$d.Description = '${safeTitle}';` +
+                        `$null = $d.ShowDialog($owner);` +
+                        `$owner.Dispose();` +
+                        `$d.SelectedPath`,
+                ],
+            };
+        }
+        case 'darwin': {
+            // osascript choose folder — fixed arg array
+            return {
+                cmd: 'osascript',
+                args: ['-e', `choose folder with prompt "Choose a project folder"`],
+            };
+        }
+        case 'linux':
+        default: {
+            // zenity (GNOME primary), kdialog fallback handled at runtime in pickFolder
+            return {
+                cmd: 'zenity',
+                args: ['--file-selection', '--directory', `--title=${title}`],
+            };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// pickFolder — invoke the OS dialog and return the chosen path
+// ---------------------------------------------------------------------------
+/**
+ * Open a native OS folder-picker dialog and return the chosen absolute path,
+ * or null if the user cancels, the dialog binary is not available, or the
+ * timeout (120 s) is exceeded.
+ *
+ * Uses execFile (not exec) with a static argument array — T-09-01.
+ * The returned path should be validated with isInsideDir before use.
+ *
+ * @param title - Dialog title (developer-static label, not user-controlled)
+ * @param plat  - Platform override for testing
+ */
+export async function pickFolder(title = 'Choose a project folder', plat = process.platform) {
+    if (plat === 'darwin') {
+        // osascript returns an HFS+ alias path; convert to POSIX
+        return new Promise((resolve) => {
+            const { args } = buildPickerArgs('darwin', title);
+            execFile('osascript', args, { timeout: 120_000 }, (err, stdout) => {
+                if (err || !stdout.trim()) {
+                    resolve(null);
+                    return;
+                }
+                const raw = stdout.trim();
+                // Convert alias to POSIX path via second osascript call
+                execFile('osascript', ['-e', `POSIX path of (${raw})`], {}, (e2, out2) => {
+                    resolve(e2 ? null : out2.trim() || null);
+                });
+            });
+        });
+    }
+    if (plat === 'win32') {
+        const { cmd, args } = buildPickerArgs('win32', title);
+        return new Promise((resolve) => {
+            execFile(cmd, args, { timeout: 120_000 }, (err, stdout) => {
+                resolve(err ? null : stdout.trim() || null);
+            });
+        });
+    }
+    // Linux: try zenity first, then kdialog
+    const zenityResult = await tryLinuxPicker('zenity', title);
+    if (zenityResult !== undefined)
+        return zenityResult;
+    const kdialogResult = await tryLinuxPicker('kdialog', title);
+    if (kdialogResult !== undefined)
+        return kdialogResult;
+    // Headless fallback: return null (native host falls back to --root config)
+    return null;
+}
+/**
+ * Try a Linux folder-picker tool.
+ * Returns the path string if successful, null if user cancelled,
+ * undefined if the tool is not found.
+ */
+function tryLinuxPicker(tool, title) {
+    return new Promise((resolve) => {
+        const args = tool === 'zenity'
+            ? ['--file-selection', '--directory', `--title=${title}`]
+            : ['--getexistingdirectory', '/home'];
+        execFile(tool, args, { timeout: 120_000 }, (err, stdout) => {
+            if (err) {
+                // Distinguish "not found" (ENOENT) from "user cancelled" (non-zero exit)
+                const e = err;
+                if (e.code === 'ENOENT') {
+                    resolve(undefined); // tool not installed — try next
+                }
+                else {
+                    resolve(null); // user cancelled or dialog error
+                }
+                return;
+            }
+            resolve(stdout.trim() || null);
+        });
+    });
+}

package/dist/host/src/index.js

@@ -0,0 +1,110 @@
+/**
+ * stikfix-host CLI entry point.
+ * D-08/HOST-01/HOST-02/HOST-03: bind 127.0.0.1 only; honor --port or scan 39240-39260
+ * D-07/HOST-12: writeTokenFile to <root>/.stikfix-token
+ * Startup JSON line: {app,name,root,port,token,notesDir,origins}
+ * Pattern 1: bind-or-fail loop (EADDRINUSE -> retry next port)
+ * WR-06: bindServer/tryListen extracted to bind.ts; removeAllListeners between attempts
+ * Pitfall 2: server runs indefinitely (smoke test uses spawn+readline, not spawnSync)
+ * FIX-SI: single-instance guard — probeExistingHost (probe.ts) reads .stikfix-port + probes /status
+ * FIX-TP: token persistence — reuse .stikfix-token across restarts if no explicit token
+ */
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { resolveConfig, resolveConfigValues, ensureNotesDir, writeTokenFile } from './config.js';
+import { createHostServer } from './server.js';
+import { bindServer, BIND_HOST } from './bind.js';
+import { probeExistingHost } from './probe.js';
+// ---------------------------------------------------------------------------
+// CLI parsing (preserve Phase 1 stub options block — HOST-13)
+// ---------------------------------------------------------------------------
+const { values: rawValues } = parseArgs({
+    options: {
+        root: { type: 'string' },
+        origin: { type: 'string', multiple: true },
+        name: { type: 'string' },
+        'notes-dir': { type: 'string' },
+        port: { type: 'string' },
+        token: { type: 'string' },
+    },
+    strict: false,
+});
+// Apply three-tier env resolution (flag > STIKFIX_* > npm_config_*) so that
+// `npm run host -- --root <dir>` works in Windows PowerShell, where npm 11.x
+// intercepts unknown flags and re-exposes them as npm_config_<key> env vars.
+const values = resolveConfigValues(rawValues);
+if (!values['root']) {
+    console.error('stikfix-host: --root is required');
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// Config resolution + filesystem setup
+// ---------------------------------------------------------------------------
+const cfg = resolveConfig(values);
+ensureNotesDir(cfg.notesDir);
+// ---------------------------------------------------------------------------
+// FIX-SI: Single-instance guard — BEFORE any file mutation
+// ---------------------------------------------------------------------------
+const portFilePath = join(cfg.root, '.stikfix-port');
+if (existsSync(portFilePath)) {
+    const portStr = readFileSync(portFilePath, 'utf8').trim();
+    const existingPort = Number(portStr);
+    if (Number.isInteger(existingPort) && existingPort > 0 && existingPort <= 65535) {
+        const live = await probeExistingHost(cfg.root, existingPort);
+        if (live !== null) {
+            console.log(`stikfix-host: already running for ${cfg.root} on port ${live.port} — not starting a second instance.`);
+            process.exit(0);
+        }
+        // else: stale port file — continue with normal startup
+    }
+}
+// ---------------------------------------------------------------------------
+// FIX-TP: Token persistence — reuse existing token if no explicit token given
+// ---------------------------------------------------------------------------
+// An "explicit" token is one supplied via --token / STIKFIX_TOKEN / npm_config_token.
+// resolveConfig already resolved these; if none was supplied, randomUUID() was called.
+// We detect the "no explicit token" case by checking the raw resolved values BEFORE
+// randomUUID was applied.
+const rawToken = values['token'] ??
+    (process.env['STIKFIX_TOKEN']) ??
+    (process.env['npm_config_token']);
+const tokenFilePath = join(cfg.root, '.stikfix-token');
+let finalToken = cfg.token;
+if (!rawToken) {
+    // No explicit token provided — try to reuse existing token file
+    if (existsSync(tokenFilePath)) {
+        const existing = readFileSync(tokenFilePath, 'utf8').trim();
+        if (existing.length > 0) {
+            finalToken = existing;
+        }
+        // else: empty file — keep freshly generated UUID from resolveConfig
+    }
+    // else: no existing file — keep freshly generated UUID from resolveConfig
+}
+// Write the final token (idempotent — fixes perms to 0o600 via writeTokenFile)
+writeTokenFile(cfg.root, finalToken);
+// ---------------------------------------------------------------------------
+// Port discovery — bind-or-fail loop on 127.0.0.1 (Pattern 1 / D-08)
+// ---------------------------------------------------------------------------
+const server = createHostServer({ ...cfg, token: finalToken });
+const boundPort = await bindServer(server, cfg.port);
+// Safety assertion: binding must be 127.0.0.1 (T-02-bind)
+const addr = server.address();
+if (addr.address !== BIND_HOST) {
+    throw new Error(`FATAL: server bound to ${addr.address} instead of ${BIND_HOST}`);
+}
+// Publish bound port to disk so the native host can read it without a port scan
+// (RESEARCH Open Question 2 / A5). Mode 0o600 alongside existing token file.
+writeFileSync(join(cfg.root, '.stikfix-port'), String(boundPort), { encoding: 'utf8', mode: 0o600 });
+// Startup JSON line — read by smoke test via readline (Pattern 12)
+console.log(JSON.stringify({
+    app: 'stikfix',
+    name: cfg.name,
+    root: cfg.root,
+    port: boundPort,
+    token: finalToken,
+    notesDir: cfg.notesDir,
+    origins: cfg.origins,
+}));
+// Server runs indefinitely (Pitfall 2 — no process.exit here)

package/dist/host/src/native-host.js

@@ -0,0 +1,143 @@
+/**
+ * stikfix native-messaging host entry point.
+ *
+ * Chrome spawns this process via the registered native-messaging manifest
+ * (com.stikfix.host). It responds to GET_TOKEN with { type:'TOKEN', ... }
+ * from disk-backed files, then exits (sendNativeMessage one-shot — Pitfall 3).
+ *
+ * ONB-02: Reads the token from <root>/.stikfix-token and delivers it to the SW.
+ * ONB-04: Chrome spawns this on demand; no persistent process or HTTP server.
+ *
+ * Security:
+ *  T-09-07: MUST NOT call createHostServer, bindServer, or listen on any port.
+ *  T-09-09: Token read from disk file (mode 0o600), sent only over native messaging.
+ *
+ * Node builtins only — no WXT, no Chrome imports.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { sendNativeMessage, readNativeMessages } from './native-msg.js';
+import { pickFolder } from './folder-picker.js';
+import { validateChosenFolder } from './validate-folder.js';
+// Re-export so existing importers (native-host.test.ts) keep working unchanged
+// after the validation logic moved to validate-folder.ts (single source of truth).
+export { validateChosenFolder };
+// ---------------------------------------------------------------------------
+// Config + token/port resolution
+// ---------------------------------------------------------------------------
+const CONFIG_PATH = join(homedir(), '.config', 'stikfix', 'config.json');
+// ---------------------------------------------------------------------------
+// PICK_FOLDER handler — open the OS dialog, validate, respond, exit (Pitfall 8)
+// Folder validation lives in validate-folder.ts (shared with the HTTP server).
+// ---------------------------------------------------------------------------
+/**
+ * Handle a PICK_FOLDER native message: open the OS folder dialog, validate the
+ * chosen path, send a FOLDER_PICKED frame echoing the origin, then exit(0).
+ *
+ * Pitfall 8: Chrome spawns a FRESH process per sendNativeMessage, so PICK_FOLDER
+ * is handled per-spawn entirely separately from GET_TOKEN — the blocking folder
+ * dialog can never delay a token fetch (which is a different spawn).
+ *
+ * `pickFn` is injectable so tests can stub the OS dialog.
+ */
+export async function handlePickFolder(origin, pickFn = pickFolder, plat = process.platform, out) {
+    let chosen;
+    try {
+        chosen = await pickFn('Choose a folder for ' + (origin ?? 'this site'));
+    }
+    catch {
+        // Dialog spawn error — never crash; respond with null (no silent drop).
+        chosen = null;
+    }
+    const folder = validateChosenFolder(chosen, plat);
+    if (out) {
+        sendNativeMessage({ type: 'FOLDER_PICKED', origin, folder }, out);
+    }
+    else {
+        sendNativeMessage({ type: 'FOLDER_PICKED', origin, folder });
+    }
+}
+// ---------------------------------------------------------------------------
+// Message dispatch — handle one message and exit (Pitfall 3)
+// ---------------------------------------------------------------------------
+/**
+ * Native-host entry point. Reads config from disk (required), then dispatches
+ * the single inbound native message and exits. The token/port are read LAZILY
+ * inside the GET_TOKEN branch only — PICK_FOLDER does not need them.
+ *
+ * Kept as a function (not top-level side effects) so the pure helpers above
+ * (validateChosenFolder / handlePickFolder) can be imported by unit tests
+ * WITHOUT triggering a config read + process.exit on import.
+ */
+export function main() {
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+    }
+    catch {
+        // Config missing — respond with a structured error so the SW gets {ok:false}
+        // rather than Chrome reporting "native host exited unexpectedly"
+        sendNativeMessage({ type: 'ERROR', error: 'Config not found. Run: npx stikfix init' });
+        process.exit(1);
+    }
+    // NOTE: the token (and optional port) are read LAZILY inside the GET_TOKEN
+    // branch below — NOT upfront. PICK_FOLDER does not need the token, so reading
+    // it here would wrongly fail the folder dialog whenever .stikfix-token is
+    // absent (e.g. host never started). Config is the only upfront requirement.
+    readNativeMessages((msg) => {
+        const m = msg;
+        if (m.type === 'GET_TOKEN') {
+            // Token is required ONLY for GET_TOKEN — read it lazily here.
+            let token;
+            try {
+                token = readFileSync(join(cfg.root, '.stikfix-token'), 'utf8').trim();
+            }
+            catch {
+                sendNativeMessage({ type: 'ERROR', error: '.stikfix-token not found. Start the host first.' });
+                process.exit(1);
+            }
+            // Port is optional — read if present; SW falls back to port scan (A5 fallback)
+            let port;
+            try {
+                const raw = readFileSync(join(cfg.root, '.stikfix-port'), 'utf8').trim();
+                const parsed = parseInt(raw, 10);
+                if (!isNaN(parsed)) {
+                    port = parsed;
+                }
+            }
+            catch {
+                // .stikfix-port absent is OK — SW re-probes (A5)
+            }
+            // Send token + port (if known) + host identity, then exit (one-shot)
+            sendNativeMessage({
+                type: 'TOKEN',
+                token,
+                port,
+                name: cfg.name,
+                notesDir: cfg.notesDir,
+            });
+            process.exit(0);
+        }
+        if (m.type === 'PICK_FOLDER') {
+            // PICK_FOLDER is a SEPARATE spawn from GET_TOKEN (Pitfall 8) — the dialog
+            // never blocks a token fetch. It does NOT require the token (read lazily
+            // for GET_TOKEN only), so it works even before the host has ever started.
+            // Open the dialog, validate, respond, exit.
+            handlePickFolder(m.origin).then(() => process.exit(0), () => process.exit(0));
+            return;
+        }
+        // Unknown message type — exit cleanly (Chrome expects process to exit)
+        process.exit(0);
+    });
+}
+// Run only when invoked as the entry point (esbuild CJS bundle), never on import.
+// In the esbuild CJS bundle (stikfix-native.cjs), `require`/`module` are CJS
+// scope locals and `require.main === module` is true when run directly. The
+// node:test compile path emits ESM where these are undefined at runtime — the
+// `typeof` guards keep main() from running on import there.
+if (typeof require !== 'undefined' &&
+    typeof module !== 'undefined' &&
+    require.main === module) {
+    main();
+}