stikfix 1.2.0

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

@@ -0,0 +1,100 @@
+/**
+ * Native messaging stdio framing for stikfix.
+ * Implements the Chrome native messaging wire protocol:
+ *   4-byte UInt32LE JSON byte length + UTF-8 JSON body.
+ *
+ * ONB-02: framing must be lossless and chunk-safe.
+ * Pitfall 2: ALL stdout writes MUST use Buffer (never string) to avoid
+ *   Windows text-mode \n→\r\n corruption of the binary length field.
+ *
+ * Node builtins only — no WXT, no Chrome imports.
+ */
+// ---------------------------------------------------------------------------
+// encodeNativeMessage
+// ---------------------------------------------------------------------------
+/**
+ * Encode a message object into the Chrome native messaging wire format:
+ * [4 bytes: UInt32LE JSON byte length][N bytes: UTF-8 JSON]
+ *
+ * Returns a single Buffer containing both header and body (one alloc).
+ */
+export function encodeNativeMessage(msg) {
+    const json = JSON.stringify(msg);
+    const body = Buffer.from(json, 'utf8');
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(body.length, 0);
+    return Buffer.concat([header, body]);
+}
+// ---------------------------------------------------------------------------
+// decodeNativeMessages
+// ---------------------------------------------------------------------------
+/**
+ * Decode zero or more complete native-messaging frames from `buf`.
+ *
+ * Returns:
+ *   - `messages`: array of decoded objects for all complete frames found
+ *   - `rest`: the unconsumed tail of `buf` (may be empty or a partial frame)
+ *
+ * Malformed JSON frames are swallowed (the buffer is advanced past them
+ * so a bad frame does not stall the reader — RESEARCH Pattern 2).
+ */
+export function decodeNativeMessages(buf) {
+    const messages = [];
+    let pos = 0;
+    while (buf.length - pos >= 4) {
+        const msgLen = buf.readUInt32LE(pos);
+        if (buf.length - pos < 4 + msgLen) {
+            // Frame is incomplete — stop here, return remainder
+            break;
+        }
+        const jsonSlice = buf.slice(pos + 4, pos + 4 + msgLen).toString('utf8');
+        pos += 4 + msgLen;
+        try {
+            messages.push(JSON.parse(jsonSlice));
+        }
+        catch {
+            // Malformed JSON — swallow and continue (do not stall reader)
+        }
+    }
+    return { messages, rest: pos > 0 ? buf.slice(pos) : buf };
+}
+// ---------------------------------------------------------------------------
+// sendNativeMessage
+// ---------------------------------------------------------------------------
+/**
+ * Write one native message to `out` (defaults to process.stdout).
+ *
+ * CRITICAL (Pitfall 2): writes the combined header+body as a single Buffer
+ * via Buffer.concat — NEVER passes a string to out.write(). On Windows,
+ * string writes go through text-mode I/O which translates \n → \r\n and
+ * corrupts the binary length prefix.
+ */
+export function sendNativeMessage(msg, out = process.stdout) {
+    out.write(encodeNativeMessage(msg));
+}
+// ---------------------------------------------------------------------------
+// readNativeMessages
+// ---------------------------------------------------------------------------
+/**
+ * Attach to `inp` (defaults to process.stdin) and call `onMessage` for each
+ * fully decoded native-messaging frame received.
+ *
+ * Accumulates chunks into a module-local Buffer, draining complete frames via
+ * decodeNativeMessages after every data event.  Calls process.exit(0) when
+ * stdin closes (per Chrome native messaging lifecycle — 'end' = Chrome closed
+ * the pipe, native host should terminate).
+ */
+export function readNativeMessages(onMessage, inp = process.stdin) {
+    let buf = Buffer.alloc(0);
+    inp.on('data', (chunk) => {
+        buf = Buffer.concat([buf, chunk]);
+        const { messages, rest } = decodeNativeMessages(buf);
+        buf = Buffer.from(rest);
+        for (const msg of messages) {
+            onMessage(msg);
+        }
+    });
+    inp.on('end', () => {
+        process.exit(0);
+    });
+}

package/dist/host/src/probe.js

@@ -0,0 +1,62 @@
+/**
+ * Single-instance guard probe helper (FIX-SI).
+ *
+ * Extracted into its own module so tests can import probeExistingHost
+ * without triggering the top-level CLI code in index.ts.
+ *
+ * Builtins only: node:http, node:path. No new dependencies.
+ */
+import * as http from 'node:http';
+import { resolve as resolvePath } from 'node:path';
+import { BIND_HOST } from './bind.js';
+/**
+ * Probe an existing host instance on the given port.
+ *
+ * Returns { port } if a live stikfix-host is running for the same root,
+ * or null if the port is stale / belongs to something else / unreachable.
+ *
+ * Bounded by a 700 ms timeout. Uses node:http only (builtins, no new deps).
+ */
+export function probeExistingHost(root, port) {
+    return new Promise((resolve) => {
+        const options = {
+            hostname: BIND_HOST,
+            port,
+            path: '/status',
+            method: 'GET',
+        };
+        const req = http.request(options, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                if (res.statusCode !== 200) {
+                    resolve(null);
+                    return;
+                }
+                try {
+                    const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                    if (body['app'] === 'stikfix' &&
+                        typeof body['root'] === 'string' &&
+                        resolvePath(body['root']) === resolvePath(root)) {
+                        resolve({ port });
+                    }
+                    else {
+                        resolve(null);
+                    }
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        // Bounded timeout: destroy socket and resolve null
+        req.setTimeout(700, () => {
+            req.destroy();
+            resolve(null);
+        });
+        req.on('error', () => {
+            resolve(null);
+        });
+        req.end();
+    });
+}

package/dist/host/src/read-note.js

@@ -0,0 +1,175 @@
+/**
+ * Note read/list/edit/delete service for stikfix-host.
+ * HOST-14/15/16: resolveSerialFile, listAnnotations, editNote, deleteNote
+ *
+ * matchesUrlPath is IMPORTED from lib/pin-position.ts (single source of truth —
+ * do NOT redefine inline; lib/pin-position.ts is the authoritative implementation).
+ *
+ * All file operations are path-confined via isInsideDir from security.ts (T-06-02).
+ * Throws {statusCode:404} when serial doesn't resolve (D-06).
+ * Throws {statusCode:403} when resolved path fails isInsideDir guard.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { readFile, writeFile, rm, readdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
+import { isInsideDir } from './security.js';
+import { matchesUrlPath } from '../../lib/pin-position.js';
+// ---------------------------------------------------------------------------
+// resolveSerialFile — find a note file by its leading 4-digit serial
+// ---------------------------------------------------------------------------
+/**
+ * Find the note file whose name starts with `<serial>-` in `notesDir`.
+ * Matches both *.md and *.read.md (the serial prefix predicate handles both).
+ * Returns the absolute path to the file, or null when no match.
+ *
+ * Pattern: readdirSync + startsWith filter (serial.ts:27-36 analog).
+ * Does NOT call getNextSerial / withSerialLock — read-only resolution (Pitfall 7).
+ */
+export function resolveSerialFile(notesDir, serial) {
+    const files = readdirSync(notesDir);
+    // Must end in .md or .read.md — avoids matching sibling +N.png files (RESEARCH.md Pitfall 5)
+    const match = files.find(f => f.startsWith(serial + '-') && (f.endsWith('.md') || f.endsWith('.read.md')));
+    return match ? join(notesDir, match) : null;
+}
+// ---------------------------------------------------------------------------
+// listAnnotations — list all notes whose URL path matches the given page URL
+// ---------------------------------------------------------------------------
+/**
+ * Read all *.md files in notesDir, parse their YAML frontmatter, and return a
+ * PinDescriptor for each note whose `url` pathname matches `pageUrl` (D-02).
+ *
+ * When `opts.allUrls` is true the per-note URL-path match is skipped, so notes
+ * from ALL pages are returned (project-wide listing). A note still needs a
+ * string `url` field to be included. The read/.read.md exclusion and the
+ * `status === 'read'` skip apply identically in both modes — read notes are
+ * never returned regardless of `allUrls`.
+ *
+ * Serial is extracted from filename.slice(0,4) — NEVER from fm['id'] which loses
+ * zero-padding (RESEARCH.md Pitfall 7).
+ *
+ * CANONICAL: reads fm['note_position'] into the note_position descriptor field —
+ * the SAME key that buildFrontmatter writes AND the extension consumer reads off
+ * the wire. Do NOT use alternative key names (a mismatch breaks free-pin placement).
+ * Also maps fm['reply'] → reply and fm['fixed_in'] → fixedIn (snake_case → camelCase).
+ */
+export function listAnnotations(notesDir, pageUrl, opts) {
+    // Read notes must not produce pins. The review-notes skill marks a note done
+    // two ways (belt-and-suspenders): it renames the file to `*.read.md` AND sets
+    // `status: read` in the frontmatter. Exclude both here so a marked-read note's
+    // pin disappears on the next refresh. The filename check is the robust primary
+    // signal (works even if the frontmatter status is stale or missing).
+    const files = readdirSync(notesDir).filter(f => f.endsWith('.md') && (opts?.includeDone || !f.endsWith('.read.md')));
+    const pins = [];
+    for (const file of files) {
+        const serial = file.slice(0, 4); // leading 4-digit serial from filename
+        const content = readFileSync(join(notesDir, file), 'utf8');
+        // Extract YAML frontmatter block
+        const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!fmMatch)
+            continue;
+        const fm = yamlParse(fmMatch[1]);
+        // Skip notes explicitly marked read in frontmatter (secondary signal —
+        // catches an in-place status flip that did not rename the file).
+        if (!opts?.includeDone && fm['status'] === 'read')
+            continue;
+        // Skip notes without a string url field
+        if (typeof fm['url'] !== 'string')
+            continue;
+        // D-02: path-only URL match (query string ignored). Skipped for project-wide
+        // listing (opts.allUrls) so notes from every page are returned.
+        if (!opts?.allUrls && !matchesUrlPath(fm['url'], pageUrl))
+            continue;
+        // Extract first line of body as text
+        const bodyStart = content.indexOf('\n---', 3) + 4; // skip closing ---\n
+        const text = content.slice(bodyStart).trim().split('\n')[0] ?? '';
+        pins.push({
+            serial,
+            mode: fm['mode'] ?? 'free',
+            status: fm['status'] ?? 'unread',
+            url: fm['url'],
+            text,
+            selector: typeof fm['selector'] === 'string' ? fm['selector'] : undefined,
+            rect: fm['rect'],
+            // CANONICAL KEY: note_position — D-03 (same name on disk, descriptor, and wire)
+            note_position: fm['note_position'],
+            screenshots: Array.isArray(fm['screenshots']) ? fm['screenshots'] : [],
+            reply: typeof fm['reply'] === 'string' ? fm['reply'] : undefined,
+            fixedIn: typeof fm['fixed_in'] === 'string' ? fm['fixed_in'] : undefined,
+        });
+    }
+    return pins;
+}
+// ---------------------------------------------------------------------------
+// editNote — overwrite note body in place; set status:unread; preserve frontmatter+screenshots
+// ---------------------------------------------------------------------------
+/**
+ * Rewrite the note body for the given serial. Preserves the YAML frontmatter block
+ * (with status updated to 'unread') and any existing ### Screenshots section.
+ *
+ * Throws {statusCode:404} when serial doesn't resolve.
+ * Throws {statusCode:403} when resolved path fails isInsideDir guard (T-06-02).
+ *
+ * D-04: editing an already-read note re-marks it unread (you changed it).
+ */
+export async function editNote(notesDir, serial, newComment) {
+    const mdPath = resolveSerialFile(notesDir, serial);
+    if (!mdPath) {
+        throw Object.assign(new Error('not found'), { statusCode: 404 });
+    }
+    if (!isInsideDir(notesDir, mdPath)) {
+        throw Object.assign(new Error('forbidden'), { statusCode: 403 });
+    }
+    const content = await readFile(mdPath, 'utf8');
+    // Extract the complete frontmatter block (including --- delimiters)
+    const fmMatch = content.match(/^(---\n[\s\S]*?\n---)\n/);
+    if (!fmMatch) {
+        throw Object.assign(new Error('malformed note: no frontmatter'), { statusCode: 400 });
+    }
+    // Re-parse frontmatter to update status
+    const rawFm = fmMatch[1].replace(/^---\n/, '').replace(/\n---$/, '');
+    const fm = yamlParse(rawFm);
+    fm['status'] = 'unread';
+    const newFmBlock = '---\n' + yamlStringify(fm) + '---\n';
+    // Extract existing body after frontmatter
+    const bodyAfterFm = content.slice(fmMatch[0].length);
+    // Preserve the ### Screenshots section if present (D-04 — preserve screenshots)
+    const screenshotSection = bodyAfterFm.match(/(### Screenshots[\s\S]*)$/)?.[1] ?? '';
+    const newBody = newComment + '\n' + (screenshotSection ? '\n' + screenshotSection : '');
+    await writeFile(mdPath, newFmBlock + newBody, 'utf8');
+}
+// ---------------------------------------------------------------------------
+// deleteNote — remove the .md file and any +N.png screenshots
+// ---------------------------------------------------------------------------
+/**
+ * Hard-delete the note file and its associated screenshot PNGs.
+ * Base name stripping handles both *.md and *.read.md (Pitfall 5 / RESEARCH.md).
+ *
+ * Throws {statusCode:404} when serial doesn't resolve.
+ * Throws {statusCode:403} when resolved path fails isInsideDir guard (T-06-02).
+ *
+ * Every rm is guarded by isInsideDir — no path traversal (T-06-01/02).
+ */
+export async function deleteNote(notesDir, serial) {
+    const mdPath = resolveSerialFile(notesDir, serial);
+    if (!mdPath) {
+        throw Object.assign(new Error('not found'), { statusCode: 404 });
+    }
+    if (!isInsideDir(notesDir, mdPath)) {
+        throw Object.assign(new Error('forbidden'), { statusCode: 403 });
+    }
+    // Strip both .md and .read.md extensions to get the base name for PNG glob (Pitfall 5)
+    const base = basename(mdPath).replace(/\.read\.md$|\.md$/, '');
+    // Remove the .md file
+    await rm(mdPath);
+    // Find and remove associated +N.png screenshots
+    const dirEntries = await readdir(notesDir);
+    const pngs = dirEntries.filter(f => f.startsWith(base + '+') && f.endsWith('.png'));
+    for (const png of pngs) {
+        const pngPath = join(notesDir, png);
+        // isInsideDir guard on every rm — non-negotiable (T-06-02)
+        if (isInsideDir(notesDir, pngPath)) {
+            await rm(pngPath);
+        }
+    }
+}

package/dist/host/src/security.js

@@ -0,0 +1,76 @@
+/**
+ * Security helpers for stikfix-host.
+ * D-04: readBody with 12 MB hard cap
+ * D-06/HOST-05: checkToken with crypto.timingSafeEqual
+ * D-10/HOST-09: isInsideDir path-traversal guard (Windows-correct with path.sep)
+ */
+import { timingSafeEqual } from 'node:crypto';
+import { resolve, sep } from 'node:path';
+const MAX_BODY = 12 * 1024 * 1024; // 12 MB hard cap (D-04)
+// ---------------------------------------------------------------------------
+// Token auth (HOST-05, T-02-auth, T-02-timing)
+// ---------------------------------------------------------------------------
+/**
+ * Validate X-Stikfix-Token header using constant-time comparison.
+ * Returns false if header is missing, not a string, or wrong length/value.
+ */
+export function checkToken(req, expectedToken) {
+    const provided = req.headers['x-stikfix-token'];
+    if (typeof provided !== 'string')
+        return false;
+    // Compare UTF-8 byte lengths — timingSafeEqual requires equal-length buffers (Pattern 5)
+    // Using Buffer.from(...,'utf8') avoids a RangeError when multibyte chars make
+    // UTF-16 .length equal but UTF-8 byte length differ (CR-01).
+    const a = Buffer.from(provided, 'utf8');
+    const b = Buffer.from(expectedToken, 'utf8');
+    if (a.length !== b.length)
+        return false; // byte-length guard
+    return timingSafeEqual(a, b);
+}
+// ---------------------------------------------------------------------------
+// Body size cap (HOST-11, T-02-dos)
+// ---------------------------------------------------------------------------
+/**
+ * Accumulate request body as a string with a hard 12 MB cap.
+ * Calls req.destroy() + rejects with statusCode 413 if cap is exceeded (Pattern 3).
+ */
+export function readBody(req) {
+    return new Promise((resolve2, reject) => {
+        const chunks = [];
+        let total = 0;
+        let rejected = false;
+        req.on('data', (chunk) => {
+            if (rejected)
+                return;
+            total += chunk.length;
+            if (total > MAX_BODY) {
+                rejected = true;
+                req.destroy();
+                reject(Object.assign(new Error('Payload Too Large'), { statusCode: 413 }));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (!rejected)
+                resolve2(Buffer.concat(chunks).toString('utf8'));
+        });
+        req.on('error', (err) => {
+            if (!rejected)
+                reject(err);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Path-traversal guard (HOST-09, T-02-traversal)
+// ---------------------------------------------------------------------------
+/**
+ * Return true if `target` resolves to `root` itself or a path strictly inside it.
+ * Uses path.sep to prevent the /rootfoo-prefix bypass (Pitfall 4, Pattern 6).
+ */
+export function isInsideDir(root, target) {
+    const resolvedRoot = resolve(root);
+    const resolvedTarget = resolve(target);
+    return resolvedTarget === resolvedRoot ||
+        resolvedTarget.startsWith(resolvedRoot + sep);
+}

package/dist/host/src/serial.js

@@ -0,0 +1,32 @@
+/**
+ * Serial assignment + in-process promise-queue mutex.
+ * D-03: All writes serialize through withSerialLock; no file-system locking needed.
+ */
+import { readdirSync } from 'node:fs';
+// Module-level queue — forces all locked operations to execute sequentially.
+let queue = Promise.resolve();
+/**
+ * Execute `fn` exclusively — all concurrent callers queue behind the previous call.
+ * A throwing `fn` does not poison the queue (errors are swallowed on the tail).
+ */
+export function withSerialLock(fn) {
+    const result = queue.then(fn);
+    // Swallow errors on the queue tail so a failed write does not block future writes.
+    queue = result.then(() => undefined, () => undefined);
+    return result;
+}
+/**
+ * Scan `notesDir` for files matching /^\d{4}-/ (both *.md and *.read.md),
+ * return max(serial) + 1. Returns 1 for an empty directory.
+ * Must be called inside withSerialLock to avoid concurrent scan race (Pitfall 3).
+ */
+export function getNextSerial(notesDir) {
+    const files = readdirSync(notesDir);
+    const serials = files
+        .map(f => f.match(/^(\d{4})-/))
+        .filter((m) => m !== null)
+        .map(m => parseInt(m[1], 10));
+    // IN-02: use reduce instead of spread to avoid call-stack limit on large dirs
+    const max = serials.length > 0 ? serials.reduce((a, b) => Math.max(a, b), 0) : 0;
+    return max + 1;
+}