punchlist-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manassarn Manoonchai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# punchlist
+
+Click-to-edit for any running web app, driven by any coding agent.
+
+A local proxy sits in front of your dev server and injects a picker into every HTML page. You walk through the app (desktop or phone, also over Tailscale), mark the spots that need a change, and send them as one batch - a punch list. Your coding agent pulls the batch with a shell command, edits the source, and reports back; the browser shows the result as a toast.
+
+Nothing in your app changes. It works in front of Rails (Turbo), SvelteKit/Vite, React, Vue and static servers.
+
+## Use
+
+With the skill installed, ask your agent: `/punchlist 5173` (or "let me click the element I want changed").
+
+By hand:
+
+```bash
+node scripts/punchlist-axi.mjs start --target 5173      # proxy runs in the background, prints the link
+node scripts/punchlist-axi.mjs wait                     # blocks until you press Send
+node scripts/punchlist-axi.mjs done r1 "1: made it blue"
+node scripts/punchlist-axi.mjs stop
+```
+
+Open the printed link (its token sets an access cookie). In the page: press ◎ (Alt+Shift+E), tap an element or drag a box, write a note, repeat, then press **Send**. With ◎ off, selecting text shows an Annotate button. ⏸ (Alt+Shift+P) pauses animations. 🗒 lists your notes; notes survive reloads until sent.
+
+Phone access: `tailscale serve --bg <port>`, then open the HTTPS link that `start` prints. Never use `tailscale funnel`: anyone who reaches the proxy can make your agent edit code.
+
+Optional: `node scripts/punchlist-axi.mjs setup hooks` adds a SessionStart hook to Claude Code, Codex and OpenCode, so new agent sessions see the proxies running for their directory (`--project` for the repo config, `--remove` to undo).
+
+`node scripts/punchlist-axi.mjs --help` is the full guide for agents.
+
+## Source hints
+
+Each note carries hints that point the agent at the source:
+
+- **Svelte 5 dev**: `file:line:col`
+- **Rails**: the template chain, if `config.action_view.annotate_rendered_view_with_filenames = true` is set in development
+- **React**: component names (and `_debugSource` on React 18 and older)
+- **Vue 3**: component file
+
+## Open in your editor
+
+When the hint names a file, the note panel shows **↗ Open**. The proxy opens that file (at the line, when the hint has one) in the editor on the machine where the proxy runs, so it also works when you tap on a phone. It uses [launch-editor](https://github.com/vitejs/launch-editor): it finds a running editor (VS Code, Cursor, Zed, JetBrains, Sublime...), or set `LAUNCH_EDITOR` (or `EDITOR`) in the shell that runs `start`. Only files inside the directory you started the proxy from can be opened.
+
+When the hints name no file (only a component name, or nothing), the panel shows **🔎 Locate** instead. It sends a small request to your agent, which finds the file and opens it with `done <id> --open <file>[:line]`. This works with any framework, but it takes the agent's time and needs a `wait` running.
+
+## Known limits
+
+- HTML is buffered before injection, so streamed HTML arrives all at once.
+- Absolute dev-server URLs inside JS bundles are not rewritten (HTML only).
+- Pages in cross-origin iframes cannot be picked.
+- In annotate mode, touch scrolling is blocked on phones; turn ◎ off to scroll.
+- One queue per proxy, no per-user attribution.
+
+## Develop
+
+```bash
+pnpm install && pnpm test   # pnpm version comes from package.json "packageManager"
+```

package/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: punchlist
+description: Click-to-edit for any running web app. Starts a local proxy in front of the user's dev server that injects an element picker, so the user can tap any element in a real browser (desktop or phone, also over Tailscale), type what should change, and you receive the element's selector, HTML, styles and source-file hints and edit the code. Use this whenever the user wants to point at UI and have it changed, says things like "let me click the element", "visual edit", "inspect and fix", "จิ้ม element แล้วแก้", or wants to tweak a page from their phone - even if they don't name this skill. Works with any server (Rails, SvelteKit, Vite, Next, static) with no changes to the app.
+metadata:
+  argument-hint: <dev server port or URL>
+---
+
+# punchlist
+
+punchlist runs a proxy in the background in front of the user's dev server. The user annotates elements in the browser and presses Send; you pull the batch with a blocking command, edit the source, and report back. Nothing in the user's app changes.
+
+## Current guidance lives in the CLI
+
+Do not follow workflow details from memory or from this file. Read the source of truth first:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/punchlist-axi.mjs" --help
+```
+
+Then start the proxy. It returns at once and prints the link for the user and the next command to run:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/punchlist-axi.mjs" start --target <port|url>
+```
+
+Do not wrap `start` in `nohup` or `&`; it already runs the proxy in the background.
+
+**Paste the full link from the `start` output into your reply text.** The user does not see command output, and "I'll share the link" without the URL leaves them stuck. Then run `wait` as the `start` output says (as a background command, so new notes reach you without the user asking), and follow the instructions it prints.
+
+## Request
+
+$ARGUMENTS
+
+If the request above is non-empty, it names the dev server (port or URL) - read `--help`, then start the proxy for it. If it is empty, find the dev server port as `--help` describes.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "punchlist-axi",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Click-to-edit for any running web app: a proxy injects a picker, your coding agent pulls the batch of notes and edits the source.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/narze/punchlist-axi.git"
+  },
+  "homepage": "https://github.com/narze/punchlist-axi#readme",
+  "bin": {
+    "punchlist-axi": "scripts/punchlist-axi.mjs"
+  },
+  "files": [
+    "scripts/punchlist-axi.mjs",
+    "scripts/punchlist-cli.mjs",
+    "scripts/client.js",
+    "SKILL.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "esbuild src/cli.mjs --bundle --platform=node --format=esm --target=node18 --banner:js='#!/usr/bin/env node\n// Generated from src/ by `pnpm build` - do not edit.\nimport { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=scripts/punchlist-cli.mjs && esbuild src/punchlist-axi.mjs --bundle --platform=node --format=esm --target=node18 --banner:js='#!/usr/bin/env node\n// Generated from src/ by `pnpm build` - do not edit.' --external:./punchlist-cli.mjs --outfile=scripts/punchlist-axi.mjs",
+    "pretest": "pnpm run --silent build",
+    "test": "node test/cli.test.mjs && node test/proxy.test.mjs && node test/client.test.mjs && node test/drag.test.mjs"
+  },
+  "devDependencies": {
+    "axi-sdk-js": "^0.1.13",
+    "esbuild": "^0.28.2",
+    "jsdom": "^24.0.0",
+    "launch-editor": "^2.14.2"
+  },
+  "packageManager": "pnpm@12.11.2"
+}