stikfix 1.3.1 → 1.5.0

package/README.md

@@ -115,6 +115,32 @@ cp /path/to/stikfix/skill/SKILL.md .claude/skills/review-notes/SKILL.md
 
 Run it on a clean directory and it just says "no unread notes." Safe to fire any time.
 
+## Git-sync mode (optional)
+
+By default stikfix is purely local: notes land in `notes/` and nothing else
+happens. **Git-sync mode** is an opt-in, per-project mode for working across
+more than one computer — capture a note on your laptop, `git pull` on your
+desktop, and your agent sees it there.
+
+- **Enable it** with the **"Sync notes to git"** toggle in the extension
+  popup for that project, or set it as a machine-level default by launching
+  the host with the `--git-sync` flag.
+- **Requirements:** the project must be a git repository with a configured
+  remote you can push to. stikfix uses your machine's existing git auth
+  (SSH key / credential manager) — it never stores or handles a token itself.
+- **What it does:** after writing a captured note (and any screenshot PNGs)
+  to disk, the host runs `git add`, `git commit`, and `git push` — all
+  pathspec-limited to `notes/`, so it only ever commits notes and never
+  touches your code changes.
+- **Multi-computer workflow:** capture notes on machine A → they're pushed
+  automatically → `git pull` on machine B → your AI agent (via the
+  `review-notes` skill) sees them. The skill also pulls before reading and
+  pushes its own frontmatter updates (`status: resolved`, `reply`, etc.) back
+  up — see [`skill/SKILL.md`](skill/SKILL.md).
+- **Repo size:** screenshots are committed as PNGs alongside their notes, so
+  the repo will grow over time with review history — something to be aware
+  of on long-lived projects.
+
 ## Demo
 
 ![stikfix demo](docs/demo-placeholder.png)

package/dist/host/src/config.js

@@ -67,6 +67,21 @@ export function resolveConfigValues(values, env = process.env) {
     const token = values['token'] ??
         env['STIKFIX_TOKEN'] ??
         env['npm_config_token'];
+    // git-sync — flag (boolean) > STIKFIX_GIT_SYNC > npm_config_git_sync.
+    // Presence of --git-sync (boolean true), or env value '1'/'true', enables it.
+    // Returned under the same 'git-sync' key so it survives the double resolution
+    // (index.ts resolves once, resolveConfig resolves again).
+    const gitSyncFlag = values['git-sync'];
+    let gitSync;
+    if (typeof gitSyncFlag === 'boolean') {
+        gitSync = gitSyncFlag;
+    }
+    else {
+        const gitSyncEnv = env['STIKFIX_GIT_SYNC'] ?? env['npm_config_git_sync'];
+        if (gitSyncEnv !== undefined) {
+            gitSync = gitSyncEnv === '1' || gitSyncEnv.toLowerCase() === 'true';
+        }
+    }
     return {
         root,
         origin: origins,
@@ -74,6 +89,7 @@ export function resolveConfigValues(values, env = process.env) {
         'notes-dir': notesDir,
         port,
         token,
+        'git-sync': gitSync,
     };
 }
 // ---------------------------------------------------------------------------
@@ -110,7 +126,9 @@ export function resolveConfig(values) {
     }
     // D-07 token resolution order (npm_config_token handled in resolveConfigValues)
     const token = v['token'] ?? randomUUID();
-    return { root, notesDir, name, origins, port, token };
+    // git-sync default false (opt-in). resolveConfigValues resolved the three tiers.
+    const gitSync = v['git-sync'] ?? false;
+    return { root, notesDir, name, origins, port, token, gitSync };
 }
 // ---------------------------------------------------------------------------
 // ensureNotesDir (HOST-12)

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();
+}

package/dist/host/src/index.js

@@ -28,6 +28,7 @@ const { values: rawValues } = parseArgs({
         'notes-dir': { type: 'string' },
         port: { type: 'string' },
         token: { type: 'string' },
+        'git-sync': { type: 'boolean' },
     },
     strict: false,
 });

package/dist/host/src/server.js

@@ -16,6 +16,7 @@ import { withSerialLock, getNextSerial } from './serial.js';
 import { writeNote } from './write-note.js';
 import { listAnnotations, editNote, deleteNote } from './read-note.js';
 import { validateChosenFolder } from './validate-folder.js';
+import { isGitRepo, getLastGitSyncStatus, gitSyncNote } from './git-sync.js';
 // ---------------------------------------------------------------------------
 // Per-request notes-dir resolution (D-04 — targetDir support)
 // ---------------------------------------------------------------------------
@@ -81,7 +82,7 @@ function setPreflightHeaders(req, res) {
 // ---------------------------------------------------------------------------
 // Route handlers
 // ---------------------------------------------------------------------------
-function handleStatus(req, res, cfg) {
+async function handleStatus(req, res, cfg) {
     setCorsHeaders(req, res);
     const body = JSON.stringify({
         app: 'stikfix',
@@ -90,6 +91,10 @@ function handleStatus(req, res, cfg) {
         root: cfg.root,
         notesDir: cfg.notesDir,
         origins: cfg.origins,
+        // git-sync surface (shared contract): is cfg.root a git work tree, and the
+        // result of the most recent git-sync attempt (null if none yet).
+        gitRepo: await isGitRepo(cfg.root),
+        gitSyncStatus: getLastGitSyncStatus(),
     });
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(body);
@@ -162,12 +167,21 @@ async function handleAnnotation(req, res, cfg) {
     //    Writes are confined to <notesDir> (= cfg.notesDir OR <validated targetDir>/notes).
     //    targetDir is NOT persisted into the note frontmatter (routing-only field).
     try {
+        let serialNum = 0;
         const { file, serial } = await withSerialLock(async () => {
-            const serialNum = getNextSerial(notesDir);
+            serialNum = getNextSerial(notesDir);
             return writeNote(notesDir, payload, serialNum);
         });
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ ok: true, file, serial }));
+        // git-sync (opt-in) — AFTER the 200 is sent, outside withSerialLock, and
+        // fire-and-forget so Send stays instant. Runs iff the CLI/machine default
+        // (cfg.gitSync) OR the per-send flag (payload.gitSync) is true. Its own queue
+        // serializes concurrent notes; .catch-guarded so it can never crash the host.
+        const doSync = cfg.gitSync === true || payload.gitSync === true;
+        if (doSync) {
+            void gitSyncNote({ root: cfg.root, notesDir, serial: serialNum }).catch(() => { });
+        }
     }
     catch (e) {
         // CR-02: propagate statusCode from write-phase errors (e.g. bad screenshot → 400)
@@ -384,7 +398,13 @@ export function createHostServer(cfg) {
             return;
         }
         if (method === 'GET' && path === '/status') {
-            handleStatus(req, res, cfg);
+            handleStatus(req, res, cfg).catch((e) => {
+                if (!res.headersSent) {
+                    setCorsHeaders(req, res);
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: String(e) }));
+                }
+            });
             return;
         }
         if (method === 'POST' && path === '/annotation') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stikfix",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Pin sticky notes on any page — your AI reads them.",
   "license": "MIT",
   "author": "Omer Nesher <omernesher@gmail.com>",
@@ -50,7 +50,7 @@
     "test:lib": "tsc -p tsconfig.lib.json && node --test \"dist/lib/lib/test/**/*.test.js\"",
     "test": "tsc -p tsconfig.host.json && node --test \"dist/host/test/**/*.test.js\"",
     "check": "tsc --noEmit && tsc --noEmit -p tsconfig.host.json && node scripts/clean-room-check.mjs && node scripts/host-smoke-test.mjs && npm run test:lib && npm test",
-    "postinstall": "node -e \"try{require.resolve('wxt')}catch(e){process.exit(0)}\" && wxt prepare"
+    "postinstall": "node -e \"try{require.resolve('wxt');require('node:child_process').execSync('wxt prepare',{stdio:'inherit'})}catch(e){}\""
   },
   "devDependencies": {
     "@medv/finder": "4.0.2",