@brmbh/tack 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# tack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Point at your running site, say what should change, and hand it to your coding agent.
+
+`tack` puts a local proxy in front of your dev server and adds a small toolbar
+to every page. Click an element to comment on it, or click any text and retype
+it in place. Each note stores the page, a verified CSS selector, the element's
+text and HTML, and the **source file:line it most likely comes from**. Your
+agent (Claude Code, Cursor, Codex…) reads the notes, changes the code, and
+resolves them. The pin leaves the page once it's done; the note and the agent's answer stay in the list (`L` → All).
+
+Nothing gets installed in your project, and it works with any framework: static
+HTML, Vite, Next, Astro, WordPress, PHP. It runs only on your machine.
+
+## Install
+
+**Which agent:** the coding agent that works **in your project folder**, the one that can read and
+change your files and knows your codebase (Claude Code, Codex, Cursor, Gemini CLI, Copilot,
+opened in that folder). Not a browser chat like claude.ai or ChatGPT: it can't see your code, so
+it can't act on the notes. Tack points; that agent finds the right place in your code or CMS.
+
+**With your agent:** paste this into it, in your project.
+
+```text
+Set me up to use Tack in this project. Run `npx -y @brmbh/tack@latest init` in the project root;
+it installs the tack skill for this agent. Read the installed skill (.claude/skills/tack/SKILL.md
+or .agents/skills/tack/SKILL.md), then start a tack session on my dev server and give me the URL.
+```
+
+**From the command line**, like any other tool:
+
+```bash
+npx @brmbh/tack init                         # in your project: installs the agent skill
+npx @brmbh/tack --target http://localhost:3000
+npm i -g @brmbh/tack                         # optional: a `tack` command everywhere
+```
+
+Needs Node 18+ for `npx`, nothing else: tack ships as a standalone binary for macOS (arm64, x64),
+Linux (x64, arm64) and Windows (x64). `tack init` writes the skill to `.claude/skills/tack/`
+(Claude Code) and `.agents/skills/tack/` (Codex, Cursor, Gemini CLI, GitHub Copilot, Amp, Cline
+and others). `--global` puts it in your home folder instead. Then tell your agent
+"start tack", and later "do the tack notes".
+
+## Use
+
+```bash
+tack --target http://localhost:3000        # → http://localhost:7777
+```
+
+Open the printed URL and browse as usual.
+
+| Key | |
+|---|---|
+| `C` | Comment mode: click an element and type. Select text first to quote it. |
+| `E` | Edit mode: click text, retype it, `Enter` saves (`Shift+Enter` = newline), `Esc` cancels. |
+| `L` | Feedback list (all pages). Copy button = Markdown for any agent. |
+| `H` | Show/hide pins. |
+| `Esc` | Leave the current mode. |
+
+Pins show open notes only (black). A dot on a pin means the agent asked a question. Done notes leave the canvas and stay in the list (`L` → All), with the agent's answer.
+
+## Hand it to your agent
+
+Feedback is written to `<project>/.tack/`, as `notes.json` (the source of truth) and `FEEDBACK.md`
+(readable by anything). Three ways for an agent to pick it up:
+
+1. **Skill** (Claude Code, Codex, Cursor and every agent that reads `.agents/skills`): run
+   `tack init` in the project, or `tack init --global`, then tell the agent "do the tack notes".
+2. **MCP**: `claude mcp add tack -- tack mcp` (without a global install:
+   `claude mcp add tack -- npx -y @brmbh/tack mcp`). Tools: `tack_list`, `tack_get`,
+   `tack_resolve`, `tack_reply`.
+3. **CLI** (any agent that can run shell commands):
+   ```bash
+   tack list --md
+   tack resolve 3 -m "Shortened the lead, index.html:1370"
+   tack reply 4 -m "Bolder as in weight 700, or bigger?"
+   ```
+
+Commit `.tack/` if you want the review history in git, or add it to `.gitignore`.
+
+## Console bridge
+
+The proxy also sees what the page does, so the agent doesn't have to ask you to open DevTools.
+A tiny script at the top of `<head>` captures `console.*`, uncaught errors (with
+`file:line:col`), unhandled rejections, failed `fetch` calls and broken images/scripts. The
+proxy adds upstream 4xx/5xx responses and **missing files that the dev server answered with
+its HTML fallback** (Vite serves `index.html` with status 200 for any unknown path, so a
+missing `.json` or `.png` looks like success). Everything goes to `.tack/console.jsonl`.
+
+```bash
+tack logs --md                        # last 50 entries
+tack logs --level problems --since 5m # errors, warnings, network, proxy
+tack logs --page /pricing/ --md
+```
+
+MCP: `tack_console`. Every new note also carries the problems from **its own page load**,
+with repeats collapsed. `tack --verbose` prints every proxied request.
+
+## AI suggestions (optional)
+
+In edit mode (`E`), the popover has **Suggest**: say what the new versions should do (or leave it
+empty) and tack streams a few versions of the text. Pick one, it appears on the page, `Enter`
+saves it as a normal edit note for your agent.
+
+Any model, your own key, via the [Vercel AI SDK](https://ai-sdk.dev). Set it up in the
+overlay: the **gear icon** opens AI settings. Pick where the model runs (any OpenAI-compatible
+endpoint such as Ollama Cloud, OpenRouter, LM Studio or a local Ollama, or the Vercel AI
+Gateway), paste your key, name the model, **Save & test connection**.
+
+The key is stored on your computer in `~/.config/tack/settings.json` (mode 600), for all
+projects. Never in the project, never in the browser; the overlay can write it but only ever
+reads back `••••` plus the last four characters. Environment variables win over the file:
+
+```bash
+TACK_BASE_URL=https://ollama.com/v1 TACK_API_KEY=… TACK_MODEL=minimax-m3:cloud   # OpenAI-compatible
+AI_GATEWAY_API_KEY=… TACK_MODEL=anthropic/claude-sonnet-5.5                     # AI Gateway
+```
+
+Models without JSON-schema output answer in plain lines, which tack parses as they stream.
+
+The model gets the element, its page, the source around the likely file:line and your
+`AGENTS.md` / `CLAUDE.md` / `README.md`, and can **read** more itself (list, search, read files
+in the project). Point it at notes outside the repo with `.tack/config.json`:
+
+```json
+{ "knowledge": ["~/notes/my-project"] }
+```
+
+It never writes files, and refuses `.env*`, keys and `.git/`. What it reads is sent to the
+model provider you chose.
+
+**Security.** tack listens on `127.0.0.1` only and answers only requests addressed to
+`localhost` / `127.0.0.1` (a foreign site re-resolved to your machine, "DNS rebinding", gets
+`421`). Every write to its API must come from tack's own pages, or from a tool without a
+browser such as the CLI, and be JSON, so other sites open in your browser can't change
+settings or spend your tokens. The key file is plain text with mode 600, like `~/.npmrc`:
+any program running as your user can read it. Prefer the env vars if you keep keys in a
+secrets manager. `--host 0.0.0.0` turns the host check off (you're exposing tack on purpose).
+
+## Options
+
+```
+--target <url>   dev server to proxy (required)
+--port <n>       proxy port (default 7777)
+--dir <path>     project root: where .tack/ lives and source hints are searched (default cwd)
+--store <path>   put notes somewhere else
+--host <addr>    bind address (default 127.0.0.1)
+```
+
+## How it works
+
+- **Proxy** (`src/server.ts`): forwards every request to the target, injects
+  `/__tack/overlay.js` into HTML responses, rewrites absolute links to the dev server so
+  you stay inside the proxy, strips CSP headers, and pipes websockets through so hot
+  reload keeps working.
+- **Same origin**: the proxy serves the page from its own address, so the overlay can
+  read the real DOM, which a screenshot tool can't. Selectors come from the actual
+  element and are checked for uniqueness when the note is captured.
+- **Overlay** (`overlay/overlay.ts`): vanilla TypeScript in a shadow root, bundled by
+  Bun when requested (prebuilt into the release binary). The site's CSS can't reach it.
+- **Source hints** (`src/hints.ts`): a deterministic text search over the project
+  (git-tracked files, minus build output). It still matches when text is wrapped across
+  lines, contains HTML entities or smart quotes, or is split by inline tags. It falls
+  back to `id`, then class names.
+- **MCP** (`src/mcp.ts`): about 100 lines of JSON-RPC over stdio, no SDK.
+- **Stable targets**: clicks on anonymous wrappers inside a heading or paragraph (split-text
+  lines and words, styling spans) snap to the heading/paragraph. Runtime classes
+  (`is-*`, `split-*`, `line`, `word`…) never go into selectors, and a pin is only drawn if the
+  element's tag and text still match. Otherwise tack looks for the element by text.
+- **Redirects** pass through with their `Location` (rewritten when it points back at the
+  target). If the target's root redirects to another host at startup (apex → `www`,
+  http → https), tack proxies the final host instead. A later redirect to another host
+  (e.g. a locale subdomain) leaves the proxy; tack prints and logs the `--target` to use.
+- **One tack per project**: starting tack again for the same project with another `--target`
+  switches the running proxy (same port, notes kept) instead of starting a second one.
+  Tools can do the same with `POST /__tack/api/target {"target": "…"}`.
+- **For tools on the page**: `window.__tack` carries `version` and `contract` (the page-event
+  contract version); `/__tack/api/status` reports both. Nothing is added to `<html>` and the
+  console bridge removes its own `<script>`, so SSR hydration (React, Next) sees the server's markup.
+- **Revalidation**: conditional request headers are stripped, so every request gets a full
+  response. A passed-through 304 had turned into an empty 200 (a broken web manifest).
+
+## Develop
+
+```bash
+bun install
+bun test
+bunx tsc --noEmit
+```
+
+Requires [Bun](https://bun.sh) ≥ 1.2 to develop; users get a compiled binary.
+
+## Release
+
+```bash
+# bump "version" in package.json, commit
+bun run release --dry-run   # checks, build of all 5 binaries, smoke test of this platform
+bun run release             # the same, then publish (platform packages first), wait for npm, tag vX.Y.Z
+```
+
+Run it in a real terminal: with a passkey, npm confirms each package in the browser
+(`--auth-type=web`). A granular npm token with publish rights on `@brmbh/tack*` and 2FA bypass
+(in `NPM_TOKEN` or `~/.npmrc`) skips the confirmations. CI (`release-smoke`) builds and
+smoke-tests every platform on its own runner on each push.

package/bin/tack.cjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Runs the tack binary that npm installed for this platform (@brmbh/tack-<os>-<arch>).
+const { spawn } = require('node:child_process')
+
+const os = process.platform === 'win32' ? 'windows' : process.platform
+const name = `@brmbh/tack-${os}-${process.arch}`
+let bin
+try {
+	bin = require.resolve(`${name}/bin/tack${process.platform === 'win32' ? '.exe' : ''}`)
+} catch {
+	console.error(`tack: no binary for ${process.platform}-${process.arch} (${name} is not installed).`)
+	console.error('Supported: macOS arm64/x64, Linux x64/arm64, Windows x64. If yours is one, reinstall without --no-optional.')
+	process.exit(1)
+}
+
+const child = spawn(bin, process.argv.slice(2), { stdio: 'inherit' })
+// The proxy runs until stopped: hand stop signals to it instead of orphaning it.
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => child.kill(sig))
+child.on('error', (err) => {
+	console.error(`tack: could not start ${bin}: ${err.message}`)
+	process.exit(1)
+})
+child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))

package/package.json

@@ -1,6 +1,35 @@
 {
-  "name": "@brmbh/tack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@brmbh/tack",
+	"version": "0.1.1",
+	"description": "Point at your running site, comment or edit text in place, and hand the feedback to your coding agent.",
+	"license": "UNLICENSED",
+	"homepage": "https://github.com/brmbh/tack",
+	"author": "Jan Brombach",
+	"keywords": [
+		"feedback",
+		"coding-agent",
+		"claude-code",
+		"cursor",
+		"codex",
+		"proxy",
+		"review",
+		"skills"
+	],
+	"bin": {
+		"tack": "bin/tack.cjs"
+	},
+	"files": [
+		"bin",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"optionalDependencies": {
+		"@brmbh/tack-darwin-arm64": "0.1.1",
+		"@brmbh/tack-darwin-x64": "0.1.1",
+		"@brmbh/tack-linux-x64": "0.1.1",
+		"@brmbh/tack-linux-arm64": "0.1.1",
+		"@brmbh/tack-windows-x64": "0.1.1"
+	}
+}