@staff0rd/assist 0.881.0 → 0.883.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -44,9 +44,10 @@ The user guide is a static site built from JSON pages in `docs/guide/pages/` and
44
44
 
45
45
  - **Add a page** — add `docs/guide/pages/<id>.json` with `id`, `title`, `group` (a nav group from `src/docs/docsPageSchema.ts`), `order`, `covers` and `sections` (`heading`, `markdown`, optional `screenshots`). `covers` lists the inventory ids the page documents (`cli:<command path>`, `claude:<name>`, `config:<key>`, `route:<path>`); delete each one from `src/docs/pendingUserDocumentation.ts`. Unknown keys, unknown ids and missing screenshots fail the build.
46
46
  - **Coverage report** — `npx tsx src/docs/docsCoverage.ts --report` lists the commands, skills, config keys and routes still pending documentation, by area. `verify:docs-coverage` fails when an item is neither covered nor pending, or is both.
47
- - **Screenshots** — each screenshot declares a `route`, and optionally `viewport` (default 1280×800), `theme`, `waitFor` and `crop` selectors, and `setup` steps run before capture: `{ "assist": [args] }` runs an assist command in the sandbox, `{ "run": "<name>" }` starts a run session from `docs/guide/capture/assist.yml`. Without a `theme`, it is captured as `<file>` (light) and `<file>-dark.png`, and the site shows the one matching the reader's colour scheme.
47
+ - **Screenshots** — each screenshot declares a `route`, and optionally `viewport` (default 1280×800), `theme`, `waitFor` and `crop` selectors, and `setup` steps run before capture: `{ "assist": [args] }` runs an assist command in the sandbox, `{ "run": "<name>" }` starts a run session from `docs/guide/capture/assist.yml`. Without a `theme`, it is captured as `<file>` (light) and `<file>-dark.png`, and the site shows the one matching the reader's colour scheme. A `{{screenshot:<file>}}` line in the section's markdown places the screenshot there; otherwise it follows the section's text.
48
48
  - **Recapture** — `npm run docs:capture [-- <file.png>...] [--skip-build] [--keep-home]` builds assist, starts a throwaway Postgres container (Docker required), clones `staff0rd/sandbox` into a temporary `HOME`, runs the real daemon and web server there on a free port, captures the screenshots with Playwright (`npx playwright install chromium` once) and tears everything down. Commit the changed PNGs.
49
49
  - **Preview** — `npm run docs:build [-- --base <path>]` renders the site into `.docs-site/`, and `npm run docs:preview` builds and serves it on port 4173.
50
+ - **Feedback** — run `npm run docs:preview` from an assist session (in the background) and open the preview in Firefox with the [assist browser extension](#docs-feedback) installed. Select text on a page, press the assist icon next to the selection, type a prompt and press **Enter**: it arrives in that session as a user prompt naming the page id, section heading and source JSON file, with the selected text quoted.
50
51
 
51
52
  ## Claude Commands
52
53
 
@@ -571,7 +572,7 @@ A restart kills every managed session's pty, which also kills any background tas
571
572
 
572
573
  ## assist browser extension
573
574
 
574
- `assist extension` prints the directory to load unpacked. The extension is a Manifest V3 content script scoped to `https://github.com/*`, plus a background script and an options page, built by `npm run build` from `src/commands/extension/` into `extension/content.js`, `background.js` and `options.js` (gitignored). It adds an **Outline criteria** toggle to the markdown toolbar of an issue's body editor and the new-issue form, re-attaching after client-side navigation; pressing it hides the textarea and mounts the same `AcceptanceCriteriaOutline` control the web preview panel uses, in a shadow root with its own emotion cache and MUI theme. A body whose acceptance criteria are bullets, checkboxes or prose gets a **Convert to outline** button instead, and a body with no acceptance criteria heading gets **Add acceptance criteria**. Each edit is written back through `writeAcceptanceCriteria` into the textarea and dispatched as an `input` event, so GitHub's own Save pushes it.
575
+ `assist extension` prints the directory to load unpacked. The extension is a Manifest V3 content script scoped to `https://github.com/*`, a [docs feedback](#docs-feedback) content script on `localhost`, plus a background script and an options page, built by `npm run build` from `src/commands/extension/` into `extension/content.js`, `docs.js`, `background.js` and `options.js` (gitignored). It adds an **Outline criteria** toggle to the markdown toolbar of an issue's body editor and the new-issue form, re-attaching after client-side navigation; pressing it hides the textarea and mounts the same `AcceptanceCriteriaOutline` control the web preview panel uses, in a shadow root with its own emotion cache and MUI theme. A body whose acceptance criteria are bullets, checkboxes or prose gets a **Convert to outline** button instead, and a body with no acceptance criteria heading gets **Add acceptance criteria**. Each edit is written back through `writeAcceptanceCriteria` into the textarea and dispatched as an `input` event, so GitHub's own Save pushes it.
575
576
 
576
577
  1. Run `assist extension` — it prints the extension directory. Under WSL it copies the extension to `C:\tools\extension` and prints that Windows path instead; re-run and reload the extension after a rebuild.
577
578
  2. Load the unpacked extension:
@@ -587,6 +588,10 @@ On a PR page the header button opens a menu mirroring the web app's PR dialog in
587
588
 
588
589
  Sending is Firefox-only (it relies on the `browser.*` promise APIs). The web server URL is set on the extension's options page (**about:addons** → the extension → **Options**) and defaults to `http://localhost:3100`. `host_permissions` covers any port on `localhost` and `127.0.0.1`; another host relies on the endpoint's CORS.
589
590
 
591
+ ### Docs feedback
592
+
593
+ `npm run docs:preview` stamps each page with `<meta name="assist-docs-page">` (the page id) and, when run inside an assist session, `<meta name="assist-session-id">` (`$ASSIST_SESSION_ID`), and marks each section with `data-docs-heading` and `data-docs-source` (its JSON file); `docs:build` output carries none of these. The `docs.js` content script runs on any `localhost` / `127.0.0.1` page but only activates on one with the page meta. Selecting text inside a section shows a small assist icon by the selection; pressing it opens the same prompt popover, and **Enter** sends a non-empty prompt. The background script POSTs `{ sessionId, pageId, heading, source, selection, prompt }` to `POST /api/sessions/docs-feedback`, which asks the daemon (`type-prompt`) to paste the prompt into that session and submit it. A toast reports success, or a 404 when the preview had no session or the session is missing or ended.
594
+
590
595
  ### Permanent Firefox install
591
596
 
592
597
  Firefox release and beta only install signed add-ons, so a permanent install means having Mozilla sign the package. Signing uses AMO's **unlisted** (self-distribution) channel: Mozilla signs the `.xpi` and hands it back, with no public store listing and no human review queue.
@@ -1 +1 @@
1
- "use strict";(()=>{function a(){return globalThis.browser?.storage?.local}function u(s){let e;try{e=new URL(s.trim())}catch{return}if(!(e.protocol!=="http:"&&e.protocol!=="https:"))return e.origin}var f="http://localhost:3100",g="serverUrl";async function d(){let e=(await a()?.get(g).catch(()=>{}))?.[g];return typeof e=="string"&&u(e)||f}function p(s){let{type:e,url:r,args:t}=s??{};return e==="assist-send"&&typeof r=="string"&&(t===void 0||Array.isArray(t)&&t.every(o=>typeof o=="string"))}function l(){return globalThis.browser?.runtime}async function c(s,{url:e,instructions:r,args:t}){let[o,m]=t?["review-from-github",{url:e,args:t}]:["from-github",{url:e,instructions:r}],n;try{n=await fetch(`${s}/api/sessions/${o}`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(m)})}catch{return{ok:!1,message:`assist web server unreachable at ${s}`}}let i=await n.json().catch(()=>({}));return n.ok?{ok:!0,message:`assist session started in ${i.cwd}`}:{ok:!1,message:i.error??`assist web server returned ${n.status}`}}function S(){l()?.onMessage.addListener(s=>{if(p(s))return d().then(e=>c(e,s))})}S();})();
1
+ "use strict";(()=>{function d(e){let{type:s,pageId:n,prompt:t}=e??{};return s==="assist-docs-feedback"&&typeof n=="string"&&typeof t=="string"}async function r(e,s,n){let t;try{t=await fetch(`${e}${s}`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(n)})}catch{return{ok:!1,message:`assist web server unreachable at ${e}`}}let o=await t.json().catch(()=>({}));return t.ok?{ok:!0,data:o}:{ok:!1,message:o.error??`assist web server returned ${t.status}`}}async function c(e,{type:s,...n}){let t=await r(e,"/api/sessions/docs-feedback",n);return t.ok?{ok:!0,message:t.data.message??"Sent to the docs session"}:t}function p(){return globalThis.browser?.storage?.local}function u(e){let s;try{s=new URL(e.trim())}catch{return}if(!(s.protocol!=="http:"&&s.protocol!=="https:"))return s.origin}var y="http://localhost:3100",g="serverUrl";async function a(){let s=(await p()?.get(g).catch(()=>{}))?.[g];return typeof s=="string"&&u(s)||y}function m(e){let{type:s,url:n,args:t}=e??{};return s==="assist-send"&&typeof n=="string"&&(t===void 0||Array.isArray(t)&&t.every(o=>typeof o=="string"))}function f(){return globalThis.browser?.runtime}async function l(e,{url:s,instructions:n,args:t}){let[o,k]=t?["review-from-github",{url:s,args:t}]:["from-github",{url:s,instructions:n}],i=await r(e,`/api/sessions/${o}`,k);return i.ok?{ok:!0,message:`assist session started in ${i.data.cwd}`}:i}function b(){f()?.onMessage.addListener(e=>{if(m(e))return a().then(s=>l(s,e));if(d(e))return a().then(s=>c(s,e))})}b();})();