stikfix 1.5.0 → 1.6.1

package/dist/host/src/exe-main.js

@@ -0,0 +1,254 @@
+/**
+ * stikfix-host.exe — single-executable dispatcher (Node SEA entry).
+ *
+ * One binary multiplexes every host role by subcommand, plus a native-messaging
+ * auto-detect so the SAME exe can be registered directly as the Chrome/Edge
+ * native-messaging host (no node + .cjs wrapper needed):
+ *
+ *   stikfix-host serve   [--root <dir> ...]   → HTTP host (index.ts startHttpHost)
+ *   stikfix-host native                        → native-messaging stdio host
+ *   stikfix-host register [flags]              → non-interactive installer wiring
+ *   stikfix-host uninstall [flags]              → remove native host + launchers + config
+ *   stikfix-host doctor                        → diagnostics (stub for now)
+ *   stikfix-host --version|-v                  → print version
+ *   stikfix-host --help|-h|(no args)           → usage
+ *
+ * NATIVE AUTO-DETECT: a Chromium browser launches its native host as
+ *   stikfix-host.exe "chrome-extension://<id>/" --parent-window=<hwnd>
+ * so if the first positional looks like a chrome-extension:// origin, or any arg
+ * starts with --parent-window, we route to the native handler — never treating
+ * the origin as a subcommand.
+ *
+ * Node builtins + bundled deps only — no WXT, no Chrome imports.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { parseArgs } from 'node:util';
+import { VERSION } from './config.js';
+import { startHttpHost } from './index.js';
+import { runNativeHost } from './native-host.js';
+import { runDoctor } from './doctor.js';
+import { registerNativeHost, createLauncherFiles, registerStartup, unregisterStartup, teardownHost } from './bootstrap/register.js';
+import { STABLE_EXTENSION_ID } from './extension-id.js';
+// ---------------------------------------------------------------------------
+// Argument extraction — robust across `node script.js` and a Node SEA exe
+// ---------------------------------------------------------------------------
+/**
+ * User args, independent of how the process was started. On every path that
+ * runs this dispatcher — `node …/exe-main.js`, `node …/bundle.cjs`, and the
+ * Node SEA exe (which mirrors execPath into argv[1]) — user args begin at
+ * argv[2]. Verified against the built stikfix-host.exe.
+ */
+function getUserArgs() {
+    return process.argv.slice(2);
+}
+// ---------------------------------------------------------------------------
+// register subcommand
+// ---------------------------------------------------------------------------
+const CONFIG_DIR = join(homedir(), '.config', 'stikfix');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+/** Default notes root for the installer when --root is omitted. */
+function defaultRoot() {
+    if (process.platform === 'win32') {
+        return join(homedir(), 'Documents', 'stikfix-notes');
+    }
+    return join(homedir(), 'stikfix-notes');
+}
+async function runRegister(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            root: { type: 'string' },
+            'extension-id': { type: 'string' },
+            port: { type: 'string' },
+            startup: { type: 'boolean' },
+            'no-startup': { type: 'boolean' },
+            'host-exe': { type: 'string' },
+        },
+        strict: false,
+    });
+    const hostExe = resolve(typeof values['host-exe'] === 'string' && values['host-exe'] ? values['host-exe'] : process.execPath);
+    const root = resolve(typeof values['root'] === 'string' && values['root'] ? values['root'] : defaultRoot());
+    const extensionId = typeof values['extension-id'] === 'string' && values['extension-id']
+        ? values['extension-id']
+        : STABLE_EXTENSION_ID;
+    const port = typeof values['port'] === 'string' && values['port'] ? parseInt(values['port'], 10) : undefined;
+    const name = basename(root);
+    const notesDir = join(root, 'notes');
+    // Ensure the root exists so START_HOST's directory check passes later.
+    mkdirSync(root, { recursive: true });
+    // (a) config.json — hostExe drives START_HOST/launchers to run the exe `serve`.
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const config = {
+        root,
+        name,
+        notesDir,
+        hostEntry: hostExe,
+        nodePath: hostExe,
+        hostExe,
+    };
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { encoding: 'utf8', mode: 0o600 });
+    // (b) native-messaging manifest points DIRECTLY at the exe (self-detects native mode).
+    registerNativeHost({ extensionId, hostBinPath: hostExe, directPath: true });
+    // (c) desktop launcher runs `<exe> serve --root <root>`.
+    const launcherResult = createLauncherFiles({
+        hostEntryPath: hostExe,
+        root,
+        port,
+        hostExe,
+    });
+    // (d) Windows login autoload per flags (Windows-only; no-op elsewhere).
+    let startupRegistered = false;
+    const wantStartup = values['startup'] === true && values['no-startup'] !== true;
+    if (process.platform === 'win32') {
+        if (wantStartup) {
+            try {
+                registerStartup();
+                startupRegistered = true;
+            }
+            catch {
+                startupRegistered = false;
+            }
+        }
+        else {
+            try {
+                unregisterStartup();
+            }
+            catch {
+                // idempotent
+            }
+        }
+    }
+    console.log(JSON.stringify({
+        ok: true,
+        action: 'register',
+        hostExe,
+        root,
+        notesDir,
+        extensionId,
+        port: port ?? null,
+        configPath: CONFIG_PATH,
+        launchersWritten: launcherResult.written,
+        launcherWarnings: launcherResult.warnings,
+        startupRegistered,
+    }));
+}
+// ---------------------------------------------------------------------------
+// uninstall subcommand
+// ---------------------------------------------------------------------------
+/**
+ * Mirror bin/stikfix.ts's `uninstall` teardown exactly, via the SAME shared
+ * `teardownHost` helper (host/src/bootstrap/register.ts) — so the exe's
+ * uninstall route is equivalent: native-messaging manifest + HKCU registry
+ * keys removed, unregisterStartup() called, launcher files/config removed.
+ * Idempotent — a missing key/file is fine (teardownHost tolerates it).
+ *
+ * --extension-id / --root are accepted (teardown doesn't need either to
+ * locate the manifest/registry keys — those are derived from home + browser)
+ * and echoed back in the JSON result for operator visibility.
+ */
+async function runUninstall(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            'extension-id': { type: 'string' },
+            root: { type: 'string' },
+        },
+        strict: false,
+    });
+    const extensionId = typeof values['extension-id'] === 'string' && values['extension-id']
+        ? values['extension-id']
+        : null;
+    const root = typeof values['root'] === 'string' && values['root']
+        ? resolve(values['root'])
+        : null;
+    const result = teardownHost({});
+    console.log(JSON.stringify({
+        ok: true,
+        action: 'uninstall',
+        extensionId,
+        root,
+        manifestRemoved: result.manifestRemoved,
+        manifestError: result.manifestError ?? null,
+        startupError: result.startupError ?? null,
+        configPath: result.configPath,
+        configRemoved: result.configRemoved,
+    }));
+}
+// ---------------------------------------------------------------------------
+// usage
+// ---------------------------------------------------------------------------
+function printUsage() {
+    console.log([
+        'stikfix-host ' + VERSION,
+        '',
+        'Usage: stikfix-host <command> [options]',
+        '',
+        'Commands:',
+        '  serve [--root <dir>] [--port <n>] [--git-sync]   Start the HTTP host',
+        '  native                                           Native-messaging stdio host',
+        '  register [--root <dir>] [--extension-id <id>]    Register the native host + launchers',
+        '           [--port <n>] [--startup|--no-startup]',
+        '           [--host-exe <path>]',
+        '  uninstall [--extension-id <id>] [--root <dir>]   Remove the native host + launchers + config',
+        '  doctor                                           Print environment diagnostics',
+        '',
+        'Options:',
+        '  -v, --version                                    Print version and exit',
+        '  -h, --help                                       Print this help and exit',
+        '',
+        'Note: when launched by a Chromium browser as a native-messaging host',
+        '      (first arg chrome-extension://…, or --parent-window=…), the exe',
+        '      auto-detects native mode regardless of subcommand.',
+    ].join('\n'));
+}
+// ---------------------------------------------------------------------------
+// dispatch
+// ---------------------------------------------------------------------------
+async function main() {
+    const args = getUserArgs();
+    // NATIVE-MODE AUTO-DETECT (must be first): a Chromium browser invokes
+    //   stikfix-host.exe "chrome-extension://<id>/" --parent-window=<hwnd>
+    const first = args[0] ?? '';
+    const looksNative = /^chrome-extension:\/\//i.test(first) || args.some((a) => a.startsWith('--parent-window'));
+    if (looksNative) {
+        await runNativeHost();
+        return;
+    }
+    const cmd = args[0];
+    switch (cmd) {
+        case 'serve':
+            await startHttpHost(args.slice(1));
+            return;
+        case 'native':
+            await runNativeHost();
+            return;
+        case 'register':
+            await runRegister(args.slice(1));
+            return;
+        case 'uninstall':
+            await runUninstall(args.slice(1));
+            return;
+        case 'doctor':
+            await runDoctor(args.slice(1));
+            return;
+        case '--version':
+        case '-v':
+            console.log(VERSION);
+            return;
+        case '--help':
+        case '-h':
+        case undefined:
+            printUsage();
+            return;
+        default:
+            console.error(`stikfix-host: unknown command "${cmd}"`);
+            printUsage();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    process.exit(1);
+});

package/dist/host/src/index.js

@@ -12,136 +12,174 @@
 import { writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
 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';
 import { startTray } from './tray.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' },
-        'git-sync': { type: 'boolean' },
-    },
-    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);
+/**
+ * Start the HTTP host. Extracted from the former top-level module body so the
+ * single-executable dispatcher (exe-main.ts) can call it as `serve`, while
+ * `node dist/host/src/index.js` keeps running it via the direct-entry guard at
+ * the bottom of this file. Behavior is byte-for-byte identical to the previous
+ * top-level code — the only change is that argv is passed in (defaulting to
+ * process.argv.slice(2)) instead of being read from the global process.argv.
+ */
+export async function startHttpHost(argv = process.argv.slice(2)) {
+    // -------------------------------------------------------------------------
+    // CLI parsing (preserve Phase 1 stub options block — HOST-13)
+    // -------------------------------------------------------------------------
+    const { values: rawValues } = parseArgs({
+        args: argv,
+        options: {
+            root: { type: 'string' },
+            origin: { type: 'string', multiple: true },
+            name: { type: 'string' },
+            'notes-dir': { type: 'string' },
+            port: { type: 'string' },
+            token: { type: 'string' },
+            'git-sync': { type: 'boolean' },
+        },
+        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
         }
-        // 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;
+    // -------------------------------------------------------------------------
+    // 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,
+    }));
+    // -------------------------------------------------------------------------
+    // Windows system-tray indicator (best-effort, cosmetic, win32-only)
+    // -------------------------------------------------------------------------
+    // Only reached on genuine startup — the single-instance guard above exits(0)
+    // before here, so a second instance never spawns a duplicate tray.
+    const tray = startTray({
+        port: boundPort,
+        root: cfg.root,
+        name: cfg.name,
+        notesDir: cfg.notesDir,
+        hostPid: process.pid,
+    });
+    // Kill the tray child when the host shuts down so a dead host has no tray.
+    // (No prior signal handling existed here; these are additive.)
+    let shuttingDown = false;
+    function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        try {
+            tray?.kill();
         }
-        // else: empty file — keep freshly generated UUID from resolveConfig
+        catch { /* best-effort */ }
+        server.close(() => process.exit(0));
+        // Fallback: exit even if server.close hangs on lingering connections.
+        setTimeout(() => process.exit(0), 1000).unref();
+        void signal;
     }
-    // else: no existing file — keep freshly generated UUID from resolveConfig
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    // Belt-and-suspenders: also reap the tray on plain process exit.
+    process.on('exit', () => { try {
+        tray?.kill();
+    }
+    catch { /* best-effort */ } });
+    // Server runs indefinitely (Pitfall 2 — no process.exit here)
 }
-// 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}`);
+function isBundled() {
+    try {
+        return typeof __STIKFIX_BUNDLED__ !== 'undefined' && __STIKFIX_BUNDLED__ === true;
+    }
+    catch {
+        return false;
+    }
 }
-// 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,
-}));
-// ---------------------------------------------------------------------------
-// Windows system-tray indicator (best-effort, cosmetic, win32-only)
-// ---------------------------------------------------------------------------
-// Only reached on genuine startup — the single-instance guard above exits(0)
-// before here, so a second instance never spawns a duplicate tray.
-const tray = startTray({
-    port: boundPort,
-    root: cfg.root,
-    name: cfg.name,
-    notesDir: cfg.notesDir,
-    hostPid: process.pid,
-});
-// Kill the tray child when the host shuts down so a dead host has no tray.
-// (No prior signal handling existed here; these are additive.)
-let shuttingDown = false;
-function shutdown(signal) {
-    if (shuttingDown)
-        return;
-    shuttingDown = true;
+function isDirectEntry() {
+    // In the single-executable bundle, exe-main.ts dispatches explicitly — this
+    // guard must never fire there (it would double-start the host).
+    if (isBundled())
+        return false;
     try {
-        tray?.kill();
+        return import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
+    }
+    catch {
+        return false;
     }
-    catch { /* best-effort */ }
-    server.close(() => process.exit(0));
-    // Fallback: exit even if server.close hangs on lingering connections.
-    setTimeout(() => process.exit(0), 1000).unref();
-    void signal;
 }
-process.on('SIGINT', () => shutdown('SIGINT'));
-process.on('SIGTERM', () => shutdown('SIGTERM'));
-// Belt-and-suspenders: also reap the tray on plain process exit.
-process.on('exit', () => { try {
-    tray?.kill();
+if (isDirectEntry()) {
+    startHttpHost().catch((err) => {
+        console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+        process.exit(1);
+    });
 }
-catch { /* best-effort */ } });
-// Server runs indefinitely (Pitfall 2 — no process.exit here)