stikfix 1.3.2 → 1.6.0

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/git-sync.js

@@ -0,0 +1,146 @@
+/**
+ * Opt-in git-sync for stikfix-host.
+ *
+ * When git-sync is enabled, after a note's .md + screenshots are written AND the
+ * HTTP 200 is already sent, the host commits ONLY the notes/ folder and pushes —
+ * non-blocking, so Send stays instant. Default (git-sync OFF) = no git calls at all;
+ * this module is never even imported into the hot path unless a sync is requested
+ * (server.ts fires gitSyncNote only when doSync is true) and isGitRepo is only
+ * queried by /status.
+ *
+ * Security invariant (matches host/src/folder-picker.ts and
+ * host/src/bootstrap/register.ts): ALL shell-outs go through
+ * execFile('git', [argArray], { cwd: root }) — NEVER exec, NEVER shell:true, and
+ * NEVER string-interpolate user input into a command. Arg arrays only. The commit
+ * message is a fixed `stikfix: note NNNN` (NNNN = digits) passed as a single arg
+ * element, so command injection is impossible.
+ *
+ * Node builtins only — no WXT, no Chrome imports.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+/** Per-root cache of "is this a git work tree" — repo status is stable per session. */
+const gitRepoCache = new Map();
+/** Result of the most recent git-sync attempt (null until the first attempt). */
+let lastStatus = null;
+/**
+ * Serialize all git operations through a promise-chain queue (mutex): each
+ * gitSyncNote call chains after the previous so concurrent notes never race git.
+ * Never rejects — the chain always continues.
+ */
+let gitQueue = Promise.resolve();
+// ---------------------------------------------------------------------------
+// isGitRepo — cached "is <root> inside a git work tree"
+// ---------------------------------------------------------------------------
+/**
+ * Return true iff `git rev-parse --is-inside-work-tree` (cwd=root) exits 0 and
+ * prints "true". Cached per-root (repo status doesn't change during a session)
+ * so /status calls are cheap.
+ */
+export async function isGitRepo(root, execFileFn = execFileAsync) {
+    const cached = gitRepoCache.get(root);
+    if (cached !== undefined)
+        return cached;
+    let result = false;
+    try {
+        const { stdout } = await execFileFn('git', ['rev-parse', '--is-inside-work-tree'], { cwd: root });
+        result = stdout.trim() === 'true';
+    }
+    catch {
+        result = false;
+    }
+    gitRepoCache.set(root, result);
+    return result;
+}
+// ---------------------------------------------------------------------------
+// getLastGitSyncStatus — read the most recent attempt (for /status)
+// ---------------------------------------------------------------------------
+export function getLastGitSyncStatus() {
+    return lastStatus;
+}
+// ---------------------------------------------------------------------------
+// gitSyncNote — commit ONLY notes/ and push (queued, never rejects)
+// ---------------------------------------------------------------------------
+/**
+ * Heuristic: did this git error mean "there was nothing to commit"? git commit
+ * exits 1 with a clean tree and prints "nothing to commit" / "no changes added".
+ */
+function isNothingToCommit(err) {
+    const e = err;
+    const text = `${e.stdout ?? ''}\n${e.stderr ?? ''}\n${e.message ?? ''}`.toLowerCase();
+    return (text.includes('nothing to commit') ||
+        text.includes('no changes added to commit') ||
+        text.includes('nothing added to commit'));
+}
+/**
+ * Sync a single note to git: add → commit (pathspec-limited to notes/) → push.
+ *
+ * Behavior:
+ *  1. Not a git repo → record {ok:false, error:'not a git repository'} and return
+ *     (does NOT throw).
+ *  2. `git add -- <notesDir>` — stage only the note files.
+ *  3. `git commit -m "stikfix: note <NNNN>" -- <notesDir>` — pathspec-limited so it
+ *     commits ONLY notes/, never the owner's other staged/unstaged code. A
+ *     "nothing to commit" exit is treated as OK/no-op, not an error.
+ *  4. `git push` — uses the current branch's upstream. On push failure (no upstream,
+ *     non-fast-forward, …) the error is recorded but NO automatic pull/rebase is
+ *     attempted (never mutate the owner's branch beyond adding the note commit).
+ *     The commit is already local and safe.
+ *  5. Full success → record {ok:true}.
+ *
+ * Serialized through a module-level queue; catches ALL errors internally so it can
+ * be fired non-awaited without ever crashing the host.
+ */
+export function gitSyncNote(args) {
+    const { root, notesDir, serial } = args;
+    const run = args.execFileFn ?? execFileAsync;
+    // Chain onto the queue; the wrapped body never rejects.
+    const next = gitQueue.then(async () => {
+        try {
+            if (!(await isGitRepo(root, run))) {
+                lastStatus = { ok: false, error: 'not a git repository', at: Date.now() };
+                return;
+            }
+            // Stage only the notes dir (absolute path is fine with cwd=root).
+            await run('git', ['add', '--', notesDir], { cwd: root });
+            // Pathspec-limited commit — fixed message, NNNN = zero-padded serial digits.
+            const message = `stikfix: note ${String(serial).padStart(4, '0')}`;
+            try {
+                await run('git', ['commit', '-m', message, '--', notesDir], { cwd: root });
+            }
+            catch (commitErr) {
+                if (isNothingToCommit(commitErr)) {
+                    // Note path already committed — treat as success/no-op.
+                    lastStatus = { ok: true, at: Date.now() };
+                    return;
+                }
+                throw commitErr;
+            }
+            // Push to the current branch's upstream. On failure, record but do NOT
+            // pull/rebase — the commit is already local and safe.
+            await run('git', ['push'], { cwd: root });
+            lastStatus = { ok: true, at: Date.now() };
+        }
+        catch (err) {
+            const e = err;
+            const detail = (e.stderr && e.stderr.trim()) || e.message || String(err);
+            lastStatus = { ok: false, error: detail, at: Date.now() };
+        }
+    });
+    // Keep the queue alive even if something unexpected escapes (it shouldn't).
+    gitQueue = next.catch(() => { });
+    return next;
+}
+// ---------------------------------------------------------------------------
+// Test-only reset — clear module state between unit tests
+// ---------------------------------------------------------------------------
+/** @internal Reset cache/status/queue. Used by unit tests only. */
+export function __resetGitSyncStateForTests() {
+    gitRepoCache.clear();
+    lastStatus = null;
+    gitQueue = Promise.resolve();
+}