@lovinka/vitrinka 1.1.0

package/README.md

@@ -0,0 +1,142 @@
+# @lovinka/vitrinka
+
+The [vitrinka](https://github.com/lefteq/vitrinka) client — one package, two bins:
+
+- **`vitrinka`** — the CLI: capture screenshots into `.screenshots/`, build a
+  self-contained gallery, publish artifact **sets**, scaffold interactive
+  artifacts, and arm the annotation-board `watch` monitor.
+- **`vitrinka-mcp`** — the MCP server: lets any MCP-aware AI browse artifact sets
+  and drive the annotation-board **work queue** (pick up an annotation → fix the
+  app → attach the after-shot → reply) without touching the web UI.
+
+Both share the same token / operator / base-url / actor-encoding conventions,
+single-sourced in `src/lib/` (previously duplicated between the CLI and the MCP
+server — the latin-1 `X-Board-Actor` encoding bug once had to be fixed in three
+places). The MCP server is a thin, **stateless** stdio process: every tool call
+becomes one HTTPS request against the deployed vitrinka Go server.
+
+## Install
+
+```bash
+# both bins on PATH
+npm i -g @lovinka/vitrinka
+
+# register the MCP server (Claude Code, user scope) — no global install needed
+claude mcp add --scope user vitrinka -- npx -y --package=@lovinka/vitrinka vitrinka-mcp
+```
+
+For Claude Desktop or any other MCP client, add the equivalent entry by hand:
+
+```json
+{
+  "mcpServers": {
+    "vitrinka": {
+      "command": "npx",
+      "args": ["-y", "--package=@lovinka/vitrinka", "vitrinka-mcp"],
+      "env": {
+        "VITRINKA_BASE_URL": "https://vitrinka.lovinka.com",
+        "VITRINKA_TOKEN": "…"
+      }
+    }
+  }
+}
+```
+
+vitrinka is reachable over the WireGuard mesh — bring the VPN up (or point
+`VITRINKA_BASE_URL` at any reachable host) before use.
+
+## Configuration (env)
+
+| Var | Default | Purpose |
+|---|---|---|
+| `VITRINKA_URL` / `VITRINKA_BASE_URL` | `https://vitrinka.lovinka.com` | vitrinka server base URL. `VITRINKA_URL` wins, then `VITRINKA_BASE_URL`; the CLI's `--base` flag overrides both. |
+| `VITRINKA_TOKEN` | — | Bearer write token. Falls back to `~/.config/vitrinka/token`. Required only by the **mutating** tools; read tools work unauthenticated. |
+| `VITRINKA_OPERATOR` | — | Operator persona name. Falls back to `~/.config/vitrinka/operator` (written by `install.sh` onboarding). When set, write calls carry `X-Board-Actor: <name>` so the board credits the operator's machine — agent-authored content (`reply`, `attach_after`) keeps its explicit `claude` attribution. |
+
+## MCP tools
+
+**Artifacts library**
+
+- `list_projects` — all projects (name, branch/set counts, last update).
+- `list_sets` — a project's (or one branch's) artifact sets, newest first.
+- `get_set` — one set's metadata + full file list + share URL.
+- `rename_set` — set/clear a set's custom URL-addressable name. *(write)*
+- `update_set` — edit a set's custom name and/or human title. *(write)*
+
+**Annotation-board work queue**
+
+- `list_boards` — the annotation boards (canvases over screenshot sets).
+- `ask_board` — post a first-class multiple-choice question on a board. *(write)*
+- `scrape_board` — read a whole board as one structured testing digest.
+- `wait_for_work` — **block** (long-poll) until annotation work exists.
+- `list_work` — the agent queue (FIFO); filter by status / board / project+branch.
+- `get_annotation` — one annotation's full brief.
+- `get_capsule` — one annotation's compact markdown work brief.
+- `set_status` — move an annotation through its lifecycle. *(write)*
+- `reply` — post a reply into an annotation's thread as `claude`. *(write)*
+- `attach_after` — attach the "after" proof shot to an annotation. *(write)*
+- `highlight` — draw an ink rectangle on an annotation's card (live via SSE). *(write)*
+
+Agent loop: `list_work` → `set_status working` → fix the app → push a new set
+(`vitrinka snap`/push) → `attach_after` → `reply` → `set_status in_review`.
+**Only the user resolves** (accepts in the board UI) — never set status
+`resolved` yourself.
+
+## Unattended worker
+
+When no listening Claude session is open, the fallback worker long-polls the
+queue and spawns one `claude -p` per annotation:
+
+```bash
+vitrinka-mcp work --repo ~/Documents/Work/FixIt [--board <slug>] [--grace 8]
+```
+
+## Local development
+
+```bash
+cd pkg
+npm install
+npm run build        # tsc → dist/ (rewrites .ts import specifiers to .js on emit)
+npm test             # node --test tests/  (spawns the server/worker over real stdio + unit-tests src/lib)
+npm run typecheck
+node dist/cli.js help        # CLI
+node dist/bin-mcp.js         # MCP server over stdio (Ctrl-C to stop)
+```
+
+The source (`src/*.ts`, `src/lib/*.ts`) is dependency-free, erasable TypeScript
+(node builtins + global `fetch` only) and runs directly under Node 24 via type
+stripping — that is how a repo checkout registers the MCP server:
+
+```bash
+claude mcp add --scope user vitrinka -- node <repo>/mcp/server.ts   # shim → pkg/src/mcp.ts
+```
+
+The published `dist/` is plain ESM and runs on Node ≥ 20.
+
+## Release (Lovinka org)
+
+```bash
+npm login                     # as the lovinka npm org
+cd pkg
+npm publish --access public   # prepublishOnly runs the build
+```
+
+`files` is a whitelist (`dist` + `README.md`), so `npm pack --dry-run` should
+list only the compiled output — verify before publishing.
+
+### Deprecating the old MCP-only package
+
+`@lovinka/vitrinka-mcp` (the previous MCP-only package) is superseded by this
+unified package. After `@lovinka/vitrinka` is published, deprecate it:
+
+```bash
+npm deprecate @lovinka/vitrinka-mcp "moved to @lovinka/vitrinka (vitrinka-mcp bin)"
+```
+
+Existing `npx -y @lovinka/vitrinka-mcp` registrations keep resolving (deprecation
+only prints a warning); migrate them to
+`npx -y --package=@lovinka/vitrinka vitrinka-mcp` at leisure.
+
+## License
+
+MIT

package/dist/bin-mcp.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// index.ts — the npm bin entry (`vitrinka-mcp`). A thin dispatcher over the two
+// runnable modules that ship in this package:
+//
+//   vitrinka-mcp            Start the stdio MCP server (default) — server.ts.
+//   vitrinka-mcp work …     Run the unattended annotation worker — work.ts
+//                           (needs --repo <app dir>; see `work --help` usage).
+//
+// Both modules self-run on import (they set up their own stdio / poll loop), so
+// this file only needs to pick one and hand off. Kept dependency-free and
+// erasable, exactly like server.ts / work.ts.
+const sub = process.argv[2];
+if (sub === '--help' || sub === '-h') {
+    process.stdout.write('vitrinka-mcp — Model Context Protocol server for vitrinka\n\n' +
+        'USAGE\n' +
+        '  vitrinka-mcp            Start the MCP server over stdio (default).\n' +
+        '  vitrinka-mcp work …     Run the unattended annotation worker (--repo <dir>).\n\n' +
+        'ENV\n' +
+        '  VITRINKA_BASE_URL  default https://vitrinka.lovinka.com\n' +
+        '  VITRINKA_TOKEN     bearer token; falls back to ~/.config/vitrinka/token\n' +
+        '                     (required only by mutating tools; reads work without it)\n\n' +
+        'REGISTER (Claude Code, user scope)\n' +
+        '  claude mcp add --scope user vitrinka -- npx -y --package=@lovinka/vitrinka vitrinka-mcp\n');
+    process.exit(0);
+}
+if (sub === 'work') {
+    await import("./work.js");
+}
+else {
+    await import("./mcp.js");
+}
+export {};
+//# sourceMappingURL=bin-mcp.js.map

package/dist/bin-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-mcp.js","sourceRoot":"","sources":["../src/bin-mcp.ts"],"names":[],"mappings":";AACA,gFAAgF;AAChF,8CAA8C;AAC9C,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,8CAA8C;AAE9C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE5B,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+DAA+D;QAC7D,SAAS;QACT,wEAAwE;QACxE,oFAAoF;QACpF,OAAO;QACP,6DAA6D;QAC7D,6EAA6E;QAC7E,mFAAmF;QACnF,sCAAsC;QACtC,6FAA6F,CAChG,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;IACnB,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;AAC5B,CAAC;KAAM,CAAC;IACN,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC"}