codeassembly-guidance 0.5.0 → 0.7.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/.meta/changelog.json +491 -0
- package/CHANGELOG.md +118 -0
- package/README.md +33 -4
- package/content/_partials/finding-grades.md +4 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/codeassembly-content.yaml +4 -0
- package/content/collections/recommended.md +5 -2
- package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
- package/content/guidance/rulebooks/cli-conventions.md +17 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
- package/content/guidance/shared/AGENTS.md +1 -1
- package/content/scripts/check-prose.mjs +1 -1
- package/content/scripts/describe-change.mjs +88 -88
- package/content/scripts/manage-jira-ticket.mjs +113 -113
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +38 -38
- package/content/skills/_data/action-items.md +2 -2
- package/content/skills/_data/artifact-conventions.md +20 -10
- package/content/skills/_data/concision.md +1 -1
- package/content/skills/_data/entry-points.md +37 -0
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/recommendation-gradient.md +6 -6
- package/content/skills/_data/spike-conventions.md +20 -7
- package/content/skills/_data/ticket-source-resolution.md +21 -4
- package/content/skills/_data/title-templates.md +4 -4
- package/content/skills/_partials/commit-title-rendering.md +2 -1
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/next-steps-after-plan.md +6 -5
- package/content/skills/_partials/option-format.md +8 -8
- package/content/skills/_partials/plan-template.md +5 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
- package/content/skills/_partials/split-launch-prompts.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
- package/content/skills/analyze-performance/SKILL.md +102 -0
- package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
- package/content/skills/assess-code-health/SKILL.md +16 -14
- package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
- package/content/skills/assess-usability/SKILL.md +5 -3
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +122 -122
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/convert-agent-prompt/SKILL.md +60 -0
- package/content/skills/create-commit/SKILL.md +10 -5
- package/content/skills/create-pr/SKILL.md +11 -11
- package/content/skills/create-ticket/SKILL.md +1 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
- package/content/skills/design-and-plan/SKILL.md +6 -4
- package/content/skills/implement-plan/SKILL.md +4 -29
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +36 -17
- package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
- package/content/skills/investigate-spike/SKILL.md +48 -0
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +31 -8
- package/content/skills/merge-gh-pr/SKILL.md +25 -12
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +55 -20
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +3 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
- package/content/skills/refine-plan/SKILL.md +9 -4
- package/content/skills/refine-prototype/SKILL.md +5 -5
- package/content/skills/review-branch/SKILL.md +8 -8
- package/content/skills/review-criteria/SKILL.md +4 -4
- package/content/skills/review-gh-pr/SKILL.md +1 -1
- package/content/skills/revise-prose/SKILL.md +9 -8
- package/content/skills/revise-prose/revise-prose.mjs +111 -111
- package/content/skills/save-plan/SKILL.md +2 -0
- package/content/skills/start-ticket/SKILL.md +27 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
- package/content/skills/summarize-change/SKILL.md +27 -9
- package/content/skills/testing-conventions/SKILL.md +14 -3
- package/content/skills/triage-feedback/SKILL.md +4 -0
- package/content/skills/triage-spike-findings/SKILL.md +36 -12
- package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
- package/content/skills/wrap-up/SKILL.md +4 -0
- package/content/subagents/_data/claude.yaml +3 -0
- package/content/subagents/code-health-assessor.md +4 -4
- package/content/subagents/disposition-challenger.md +3 -4
- package/content/subagents/entry-drafter.md +2 -2
- package/content/subagents/handoff-reviewer.md +1 -1
- package/content/subagents/prototype-builder.md +69 -0
- package/content/subagents/usability-assessor.md +1 -1
- package/package.json +11 -10
- package/schemas/preferences.v1.json +74 -8
- package/schemas/work-types.v1.json +1 -1
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
|
@@ -22,6 +22,11 @@ A ticket has one prototype set, in its artifact directory:
|
|
|
22
22
|
|
|
23
23
|
A later round of prototypes revises the same set: A new idea takes a new slug, and a revision of an existing prototype keeps its slug and takes the next version. The page shows the latest version of each slug.
|
|
24
24
|
|
|
25
|
+
The set title is the product's name as the developer refers to it, without a qualifier such as "chart": `Top Right`, not `Top Right chart`. Choose it before the set's first prototype is built; a later round reads it from the manifest's `title`. Every page in the set names it in its browser title, so that the developer can tell the tabs of a round apart:
|
|
26
|
+
|
|
27
|
+
- **A prototype page**: `<title>{set title} - {id} {title}</title>`, such as `Top Right - 1.1 Next item`.
|
|
28
|
+
- **The index page**: `{set title} - Prototypes`, which `render` writes.
|
|
29
|
+
|
|
25
30
|
A slug matches `[a-z0-9][a-z0-9-]{0,39}`. You choose each slug, before any prototype is built.
|
|
26
31
|
|
|
27
32
|
The helper gives each slug a number at its first registration, and every later version of the slug keeps it. A version's id is `{number}.{version}`, and it is how the developer refers to a version: Name each one to them as `{id} {title}`, such as `3.2 Catalog first`; the index card leads with the same form, and the page itself states it as the first line of its `data-demo` band. A bare number names the slug whose entries have that number, at its latest version. When the manifest does not contain an entry with that number, ask which prototype they mean rather than guess. The slug stays the key in the manifest and in the verdicts.
|
|
@@ -52,13 +57,13 @@ mktemp -d "${TMPDIR:-/tmp}/prototypes.XXXXXX"
|
|
|
52
57
|
|
|
53
58
|
### 2. Build the prototypes
|
|
54
59
|
|
|
55
|
-
Choose a slug for each prototype, resolve the ids, and choose the set's note labels, per [The set](#the-set).
|
|
60
|
+
Choose a slug for each prototype, resolve the ids, and choose the set's note labels, per [The set](#the-set). Every build meets this contract:
|
|
56
61
|
|
|
57
|
-
1. Write the page source to `{set_dir}/{slug}-v{n}.html`, with `{id} {title}` as the first line of its `data-demo` band.
|
|
62
|
+
1. Write the page source to `{set_dir}/{slug}-v{n}.html`, with the `<title>` that [The set](#the-set) states and with `{id} {title}` as the first line of its `data-demo` band.
|
|
58
63
|
2. Publish that file with the Artifact tool.
|
|
59
64
|
3. Report the artifact URL, a short title, the lens (the angle or constraint that distinguishes this prototype), the inputs on which it drew, a one-sentence description, and one line per note label as `{label}: {value}`.
|
|
60
65
|
|
|
61
|
-
Build a prototype in the main session the same way.
|
|
66
|
+
When a subagent builds a prototype, dispatch a {subagent:prototype-builder} with the dispatch block of {skill?:prepare-prototype-brief} step 5. When the session does not have a brief from that skill, first write one to the scratch directory that states what to build, the lens, the note labels, and the files that the builder may write. The builder meets the contract and checks the page in a headless browser apart from this session's. Dispatch builders one at a time, waiting for each reply, because builders that run at once share one browser. Build a prototype in the main session the same way.
|
|
62
67
|
|
|
63
68
|
### 3. Capture the screenshots
|
|
64
69
|
|
|
@@ -80,6 +85,15 @@ Stop the server once every prototype is captured.
|
|
|
80
85
|
|
|
81
86
|
The Playwright MCP attaches to the worktree's debug browser, and a call that reports a refused connection means that the browser is not running. Run `thor-chrome` from the worktree; the next call then reaches the browser without restarting the MCP. When `thor-chrome` refuses the launch with `session-unavailable`, as it can in the agent sandbox, ask the developer to run `thor-chrome` from the worktree in a terminal in the GUI login session, and wait for it rather than publishing an index without screenshots.
|
|
82
87
|
|
|
88
|
+
A Playwright call that ends in a timeout error, or that takes over 30 seconds, most likely waits on a page that hangs its renderer, and every later call queues behind it. Close that page:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
node {harness_home_dir}/skills/index-prototypes/index-prototypes.mjs probe-targets \
|
|
92
|
+
--endpoint "{endpoint from thor-chrome status --json}"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The result's `closed` lists each page that did not answer and was closed, and `answered` lists the rest. Report the prototype of each closed page as defective, leave it without a screenshot, and continue with the rest.
|
|
96
|
+
|
|
83
97
|
### 4. Register each prototype
|
|
84
98
|
|
|
85
99
|
Register each prototype in the manifest. The first registration in a set names the set with `--set-title`; a later one may rename it.
|
|
@@ -100,6 +114,8 @@ node {harness_home_dir}/skills/index-prototypes/index-prototypes.mjs register \
|
|
|
100
114
|
--screenshot "{working_dir}/.playwright-mcp/{slug}-v{n}.png"
|
|
101
115
|
```
|
|
102
116
|
|
|
117
|
+
`register` checks the source's `<title>` against the rule in [The set](#the-set). On `title-mismatch`, correct the source's `<title>` to the expected title that the message names, republish the source to the prototype's artifact URL with the Artifact tool, reading the artifact first when this session did not publish it (a builder's publish counts as another), and register again. When the artifact cannot be republished, report the prototype as defective and leave it unregistered.
|
|
118
|
+
|
|
103
119
|
Pass `--number` with the number that `resolve-ids` gave the slug. Pass one `--note` per note label, in the set's label order. Omit any optional flag that does not have a value. The result's `entry.version` must equal the `{n}` in the source's name; when it does not, the manifest already contained another version of the slug, so rename the source to match.
|
|
104
120
|
|
|
105
121
|
### 5. Describe the set
|
|
@@ -184,17 +200,20 @@ Then, in step 3, after each screenshot, pass the result's `function` to `browser
|
|
|
184
200
|
|
|
185
201
|
Every command prints one JSON object. A success has `ok: true`. A failure has `ok: false`, an `error` code, and a `message`, and the command exits 1:
|
|
186
202
|
|
|
187
|
-
| `error` | Meaning
|
|
188
|
-
| ---------------------- |
|
|
189
|
-
| `
|
|
190
|
-
| `invalid-
|
|
191
|
-
| `invalid-
|
|
192
|
-
| `invalid-
|
|
193
|
-
| `invalid-
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
| `
|
|
203
|
+
| `error` | Meaning |
|
|
204
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
205
|
+
| `endpoint-unreachable` | The browser's DevTools endpoint did not return its target list, or did not answer a close |
|
|
206
|
+
| `invalid-args` | Unknown command, a flag that this command rejects, a missing required flag, or a `--note` that is not `{label}: {value}` |
|
|
207
|
+
| `invalid-manifest` | `manifest.json` is not valid JSON or does not have the manifest layout |
|
|
208
|
+
| `invalid-slug` | The slug does not match `[a-z0-9][a-z0-9-]{0,39}` |
|
|
209
|
+
| `invalid-summary` | The summary file is not valid JSON or does not have the summary layout |
|
|
210
|
+
| `invalid-url` | The URL is not http or https |
|
|
211
|
+
| `manifest-not-found` | The set does not have a manifest yet; register a prototype first |
|
|
212
|
+
| `missing-set-title` | The set's first registration lacks `--set-title` |
|
|
213
|
+
| `not-png` | The screenshot is not a PNG file |
|
|
214
|
+
| `number-conflict` | `--number` is not a positive integer, differs from the slug's number, or belongs to another slug |
|
|
215
|
+
| `page-too-large` | The page would exceed the 16,000,000-byte artifact cap; nothing was written |
|
|
216
|
+
| `screenshot-not-found` | The screenshot path does not exist |
|
|
217
|
+
| `source-not-found` | The source path does not exist or is a directory |
|
|
218
|
+
| `summary-not-found` | The summary file does not exist |
|
|
219
|
+
| `title-mismatch` | The source's `<title>` differs from `{set title} - {id} {title}`, or the source does not have one; the message names the expected title |
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var
|
|
4
|
-
`),!0}}
|
|
3
|
+
var me=Object.defineProperty;var o=(e,t)=>me(e,"name",{value:t,configurable:!0});import{mkdir as nt,readFile as ue,writeFile as st}from"node:fs/promises";import R from"node:path";import $ from"node:process";function V(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}o(V,"isError");function x(e){try{return V(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}o(x,"describeError");import{realpathSync as F}from"node:fs";import W from"node:process";import{fileURLToPath as pe}from"node:url";function q(e,t){let r=W.argv[1];if(r===void 0)return!1;try{return F(pe(e))===F(r)}catch(s){return W.stderr.write(`${t}: warning: could not determine entry point: ${x(s)}
|
|
4
|
+
`),!0}}o(q,"isEntryPoint");function ge(e,t){return U(e)&&e.code===t}o(ge,"isErrorCode");function b(e){return ge(e,"ENOENT")}o(b,"isEnoent");function g(e){return U(e)&&!Array.isArray(e)}o(g,"isRecord");function U(e){return typeof e=="object"&&e!==null}o(U,"isObject");var D=String.raw`() => {
|
|
5
5
|
const BLOCK = 'p, li, h1, h2, h3, h4, h5, h6, td, th, dt, dd, legend, caption, figcaption, summary';
|
|
6
6
|
const INLINE = 'label, button, a, option';
|
|
7
7
|
const SKIPPED = '[data-demo], script, style, template';
|
|
@@ -50,10 +50,10 @@ var oe=Object.defineProperty;var i=(e,t)=>oe(e,"name",{value:t,configurable:!0})
|
|
|
50
50
|
strings.push(text);
|
|
51
51
|
}
|
|
52
52
|
return strings;
|
|
53
|
-
}`;function
|
|
54
|
-
`,"utf8"),await ue(s,r)}catch(n){throw await fe(s,{force:!0}),n}return r}i(k,"writeManifest");function he(e){return b(e)&&typeof e.label=="string"&&typeof e.value=="string"}i(he,"isNote");function v(e){return e===null||typeof e=="string"}i(v,"isNullableString");function be(e){return b(e)?typeof e.shared=="string"&&v(e.changes)&&Array.isArray(e.try)&&e.try.every(t=>typeof t=="string"):!1}i(be,"isSetSummary");function ye(e){return b(e)?typeof e.slug=="string"&&(e.number===void 0||typeof e.number=="number"&&Number.isSafeInteger(e.number)&&e.number>0)&&typeof e.version=="number"&&Number.isSafeInteger(e.version)&&typeof e.registeredAt=="string"&&typeof e.title=="string"&&typeof e.url=="string"&&v(e.source)&&v(e.lens)&&Array.isArray(e.inputs)&&e.inputs.every(t=>typeof t=="string")&&v(e.description)&&(e.notes===void 0||Array.isArray(e.notes)&&e.notes.every(t=>he(t)))&&v(e.shot):!1}i(ye,"isStoredEntry");function xe(e){return b(e)?typeof e.title=="string"&&(e.indexUrl===null||typeof e.indexUrl=="string")&&(e.summary===void 0||e.summary===null||be(e.summary))&&Array.isArray(e.entries)&&e.entries.every(t=>ye(t)):!1}i(xe,"isStoredManifest");function we(e){let t=new Map;for(let n of e.entries){let o=t.get(n.slug);n.number!==void 0&&(o===void 0||n.version>o.version)&&t.set(n.slug,{version:n.version,number:n.number})}let r=new Map(t.entries().map(([n,{number:o}])=>[n,o])),s=Math.max(0,...r.values());for(let n of e.entries)r.has(n.slug)||(s+=1,r.set(n.slug,s));return{...e,summary:e.summary??null,entries:e.entries.map(n=>{let o=r.get(n.slug);if(o===void 0)throw new Error(`slug "${n.slug}" was not numbered`);return{...n,number:o,notes:n.notes??[]}})}}i(we,"normalizeManifest");import ke from"node:path";function H(e,t){let r=[],s=[];for(let n=0;n<e.length;n+=1){let o=e[n];if(o===void 0)continue;if(!o.startsWith("--")){r.push(o);continue}let d=ve(o,t);if(d===null)throw new Error(`unknown flag: ${o}`);let{spec:a,inlineValue:u}=d;if(!a.takesValue){if(u!==null)throw new Error(`--${a.name} does not take a value`);s.push({name:a.name,value:null});continue}if(u!==null){s.push({name:a.name,value:u});continue}let f=e[n+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${a.name} requires a value`);s.push({name:a.name,value:f}),n+=1}return{positionals:r,flags:s}}i(H,"scanFlags");function J(e){let t={};for(let{name:r,value:s}of e)s!==null&&(t[r]=s);return t}i(J,"valueFlagMap");function ve(e,t){for(let r of t)for(let s of[r.name,...r.aliases??[]]){let n=`--${s}`;if(e===n)return{spec:r,inlineValue:null};if(e.startsWith(`${n}=`))return{spec:r,inlineValue:e.slice(n.length+1)}}return null}i(ve,"matchFlag");var P=["copy-probe","describe-set","record-index","register","render","resolve-ids"],Se=new Set(P),Ee=[{name:"description",takesValue:!0},{name:"file",takesValue:!0},{name:"inputs",takesValue:!0},{name:"lens",takesValue:!0},{name:"note",takesValue:!0},{name:"number",takesValue:!0},{name:"out",takesValue:!0},{name:"screenshot",takesValue:!0},{name:"set-dir",takesValue:!0},{name:"set-title",takesValue:!0},{name:"slug",takesValue:!0},{name:"slugs",takesValue:!0},{name:"source",takesValue:!0},{name:"title",takesValue:!0},{name:"url",takesValue:!0}],$e={"copy-probe":{required:[],optional:[]},"describe-set":{required:["file","set-dir"],optional:[]},"record-index":{required:["set-dir","url"],optional:[]},register:{required:["set-dir","slug","title","url"],optional:["description","inputs","lens","note","number","screenshot","set-title","source"]},render:{required:["out","set-dir"],optional:[]},"resolve-ids":{required:["set-dir","slugs"],optional:[]}};function X(e){let{positionals:t,flags:r}=H(e,Ee),[s,n]=t;if(s===void 0)throw new Error(`a command is required: ${P.join(", ")}`);if(!Ne(s))throw new Error(`unknown command "${s}"; expected one of ${P.join(", ")}`);if(n!==void 0)throw new Error(`unexpected argument: ${n}`);let o=r.filter(l=>l.name==="note"),d=J(r.filter(l=>l.name!=="note")),{required:a,optional:u}=$e[s];if(o.length>0&&!u.includes("note"))throw new Error(`${s} does not take --note`);for(let[l,p]of Object.entries(d)){if(!a.includes(l)&&!u.includes(l))throw new Error(`${s} does not take --${l}`);if(p==="")throw new Error(`--${l} requires a value`)}for(let l of a)if(d[l]===void 0)throw new Error(`${s} requires --${l}`);let f=o.map(l=>Me(l.value??""));return{command:s,values:d,notes:f}}i(X,"parseArgs");function M(e){return e===void 0?[]:e.split(",").map(t=>t.trim()).filter(t=>t!=="")}i(M,"parseInputs");function g(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is missing after parsing`);return r}i(g,"requireFlag");function w(e){return ke.resolve(g(e,"set-dir"))}i(w,"resolveSetDir");function Ne(e){return Se.has(e)}i(Ne,"isCommand");function Me(e){let t=e.indexOf(":"),r=t===-1?"":e.slice(0,t).trim(),s=t===-1?"":e.slice(t+1).trim();if(r===""||s==="")throw new Error(`--note "${e}" must have the form "<label>: <value>"`);return{label:r,value:s}}i(Me,"parseNote");import je from"node:path";import{copyFile as Ae,mkdir as Ie,readFile as Re}from"node:fs/promises";import C from"node:path";var Q=Buffer.from([137,80,78,71,13,10,26,10]);async function Z(e){let t;try{t=await Re(e.sourcePath)}catch(n){if(h(n))return{ok:!1,error:"screenshot-not-found",message:`the screenshot ${e.sourcePath} does not exist`};throw n}if(!t.subarray(0,Q.length).equals(Q))return{ok:!1,error:"not-png",message:`${e.sourcePath} is not a PNG file`};let r=C.join("shots",`${e.slug}-v${e.version}.png`),s=C.join(e.setDir,r);return await Ie(C.dirname(s),{recursive:!0}),await Ae(e.sourcePath,s),{ok:!0,shot:r}}i(Z,"intakeScreenshot");function T(e){try{let{protocol:t}=new URL(e);return t==="https:"||t==="http:"}catch{return!1}}i(T,"isWebUrl");async function ee(e,t,r,s){let n=g(t,"slug");if(!N(n))return c("invalid-slug",`slug "${n}" must match [a-z0-9][a-z0-9-]{0,39}`);let o=g(t,"url");if(!T(o))return c("invalid-url",`--url "${o}" is not an http or https URL`);let d=await y(e);if(d.kind==="invalid")return c("invalid-manifest",d.message);let a=d.kind==="ok"?d.manifest:null,u=t["set-title"]??a?.title;if(u===void 0)return c("missing-set-title","the first registration in a set requires --set-title");let f=Pe(a,n,t.number);if(typeof f!="number")return f;let l=j(a,n),p=null,O=t.screenshot;if(O!==void 0){let E=await Z({sourcePath:je.resolve(O),setDir:e,slug:n,version:l});if(!E.ok)return c(E.error,E.message);p=E.shot}let _={slug:n,number:f,version:l,registeredAt:s.toISOString(),title:g(t,"title"),url:o,source:t.source??null,lens:t.lens??null,inputs:M(t.inputs),description:t.description??null,notes:r,shot:p},ie={title:u,indexUrl:a?.indexUrl??null,summary:a?.summary??null,entries:[...a?.entries??[],_]};return{ok:!0,command:"register",manifestPath:await k(e,ie),entry:_}}i(ee,"register");function Pe(e,t,r){let s=Y(e,t);if(r===void 0)return s;let n=Number(r);if(!Number.isSafeInteger(n)||n<1)return c("number-conflict",`--number "${r}" must be a positive integer`);let o=e?.entries??[];if(o.some(a=>a.slug===t))return s===n?n:c("number-conflict",`slug "${t}" is number ${s}, not ${n}`);let d=o.find(a=>a.number===n);return d===void 0?n:c("number-conflict",`number ${n} belongs to slug "${d.slug}"`)}i(Pe,"resolveRegistrationNumber");var Ce="verdicts";var te=`(() => {
|
|
53
|
+
}`;function l(e,t){return{ok:!1,error:e,message:t}}o(l,"fail");import{mkdir as he,readFile as be,rename as ye,rm as xe,writeFile as we}from"node:fs/promises";import z from"node:path";import ve from"node:process";var B="manifest.json",ke=/^[a-z0-9][a-z0-9-]{0,39}$/;function w(e,t){return`${e}.${t}`}o(w,"formatId");function N(e){return ke.test(e)}o(N,"isValidSlug");function K(e){let t=new Map;for(let r of e.entries){let s=t.get(r.slug);(s===void 0||r.version>s.version)&&t.set(r.slug,r)}return t.values().toArray()}o(K,"listLatestEntries");function M(e,t){let r=e?.entries??[],s=0;for(let n of r)n.slug===t&&n.version>s&&(s=n.version);return s+1}o(M,"nextVersion");async function y(e){let t=Y(e),r;try{r=await be(t,"utf8")}catch(n){if(b(n))return{kind:"missing"};throw n}let s;try{s=JSON.parse(r)}catch{return{kind:"invalid",message:`${t} is not valid JSON`}}return Ne(s)?{kind:"ok",manifest:Pe(s)}:{kind:"invalid",message:`${t} does not have the manifest layout`}}o(y,"readManifest");function G(e,t){let r=e?.entries??[],s=new Map,n=0;for(let i of r)s.set(i.slug,i.number),n=Math.max(n,i.number);return t.map(i=>{let d=s.get(i);d===void 0&&(n+=1,d=n,s.set(i,d));let a=M(e,i);return{slug:i,number:d,version:a,id:w(d,a)}})}o(G,"resolveIds");function Y(e){return z.join(e,B)}o(Y,"resolveManifestPath");function H(e,t){let r=e?.entries??[],s=0;for(let n of r){if(n.slug===t)return n.number;s=Math.max(s,n.number)}return s+1}o(H,"resolveNumber");async function S(e,t){await he(e,{recursive:!0});let r=Y(e),s=z.join(e,`.${B}.${ve.pid}.${Date.now()}.tmp`);try{await we(s,`${JSON.stringify(t,null,2)}
|
|
54
|
+
`,"utf8"),await ye(s,r)}catch(n){throw await xe(s,{force:!0}),n}return r}o(S,"writeManifest");function Se(e){return g(e)&&typeof e.label=="string"&&typeof e.value=="string"}o(Se,"isNote");function k(e){return e===null||typeof e=="string"}o(k,"isNullableString");function Ee(e){return g(e)?typeof e.shared=="string"&&k(e.changes)&&Array.isArray(e.try)&&e.try.every(t=>typeof t=="string"):!1}o(Ee,"isSetSummary");function $e(e){return g(e)?typeof e.slug=="string"&&(e.number===void 0||typeof e.number=="number"&&Number.isSafeInteger(e.number)&&e.number>0)&&typeof e.version=="number"&&Number.isSafeInteger(e.version)&&typeof e.registeredAt=="string"&&typeof e.title=="string"&&typeof e.url=="string"&&k(e.source)&&k(e.lens)&&Array.isArray(e.inputs)&&e.inputs.every(t=>typeof t=="string")&&k(e.description)&&(e.notes===void 0||Array.isArray(e.notes)&&e.notes.every(t=>Se(t)))&&k(e.shot):!1}o($e,"isStoredEntry");function Ne(e){return g(e)?typeof e.title=="string"&&(e.indexUrl===null||typeof e.indexUrl=="string")&&(e.summary===void 0||e.summary===null||Ee(e.summary))&&Array.isArray(e.entries)&&e.entries.every(t=>$e(t)):!1}o(Ne,"isStoredManifest");function Pe(e){let t=new Map;for(let n of e.entries){let i=t.get(n.slug);n.number!==void 0&&(i===void 0||n.version>i.version)&&t.set(n.slug,{version:n.version,number:n.number})}let r=new Map(t.entries().map(([n,{number:i}])=>[n,i])),s=Math.max(0,...r.values());for(let n of e.entries)r.has(n.slug)||(s+=1,r.set(n.slug,s));return{...e,summary:e.summary??null,entries:e.entries.map(n=>{let i=r.get(n.slug);if(i===void 0)throw new Error(`slug "${n.slug}" was not numbered`);return{...n,number:i,notes:n.notes??[]}})}}o(Pe,"normalizeManifest");import Ae from"node:path";function J(e,t){let r=[],s=[];for(let n=0;n<e.length;n+=1){let i=e[n];if(i===void 0)continue;if(!i.startsWith("--")){r.push(i);continue}let d=Ie(i,t);if(d===null)throw new Error(`unknown flag: ${i}`);let{spec:a,inlineValue:c}=d;if(!a.takesValue){if(c!==null)throw new Error(`--${a.name} does not take a value`);s.push({name:a.name,value:null});continue}if(c!==null){s.push({name:a.name,value:c});continue}let f=e[n+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${a.name} requires a value`);s.push({name:a.name,value:f}),n+=1}return{positionals:r,flags:s}}o(J,"scanFlags");function X(e){let t={};for(let{name:r,value:s}of e)s!==null&&(t[r]=s);return t}o(X,"valueFlagMap");function Ie(e,t){for(let r of t)for(let s of[r.name,...r.aliases??[]]){let n=`--${s}`;if(e===n)return{spec:r,inlineValue:null};if(e.startsWith(`${n}=`))return{spec:r,inlineValue:e.slice(n.length+1)}}return null}o(Ie,"matchFlag");var T=["copy-probe","describe-set","probe-targets","record-index","register","render","resolve-ids"],Re=new Set(T),je=[{name:"description",takesValue:!0},{name:"endpoint",takesValue:!0},{name:"file",takesValue:!0},{name:"inputs",takesValue:!0},{name:"lens",takesValue:!0},{name:"note",takesValue:!0},{name:"number",takesValue:!0},{name:"out",takesValue:!0},{name:"screenshot",takesValue:!0},{name:"set-dir",takesValue:!0},{name:"set-title",takesValue:!0},{name:"slug",takesValue:!0},{name:"slugs",takesValue:!0},{name:"source",takesValue:!0},{name:"title",takesValue:!0},{name:"url",takesValue:!0}],Me={"copy-probe":{required:[],optional:[]},"describe-set":{required:["file","set-dir"],optional:[]},"probe-targets":{required:["endpoint"],optional:[]},"record-index":{required:["set-dir","url"],optional:[]},register:{required:["set-dir","slug","title","url"],optional:["description","inputs","lens","note","number","screenshot","set-title","source"]},render:{required:["out","set-dir"],optional:[]},"resolve-ids":{required:["set-dir","slugs"],optional:[]}};function Q(e){let{positionals:t,flags:r}=J(e,je),[s,n]=t;if(s===void 0)throw new Error(`a command is required: ${T.join(", ")}`);if(!Te(s))throw new Error(`unknown command "${s}"; expected one of ${T.join(", ")}`);if(n!==void 0)throw new Error(`unexpected argument: ${n}`);let i=r.filter(u=>u.name==="note"),d=X(r.filter(u=>u.name!=="note")),{required:a,optional:c}=Me[s];if(i.length>0&&!c.includes("note"))throw new Error(`${s} does not take --note`);for(let[u,h]of Object.entries(d)){if(!a.includes(u)&&!c.includes(u))throw new Error(`${s} does not take --${u}`);if(h==="")throw new Error(`--${u} requires a value`)}for(let u of a)if(d[u]===void 0)throw new Error(`${s} requires --${u}`);let f=i.map(u=>Ce(u.value??""));return{command:s,values:d,notes:f}}o(Q,"parseArgs");function P(e){return e===void 0?[]:e.split(",").map(t=>t.trim()).filter(t=>t!=="")}o(P,"parseInputs");function p(e,t){let r=e[t];if(r===void 0)throw new Error(`--${t} is missing after parsing`);return r}o(p,"requireFlag");function v(e){return Ae.resolve(p(e,"set-dir"))}o(v,"resolveSetDir");function Te(e){return Re.has(e)}o(Te,"isCommand");function Ce(e){let t=e.indexOf(":"),r=t===-1?"":e.slice(0,t).trim(),s=t===-1?"":e.slice(t+1).trim();if(r===""||s==="")throw new Error(`--note "${e}" must have the form "<label>: <value>"`);return{label:r,value:s}}o(Ce,"parseNote");import{readFile as Fe}from"node:fs/promises";import oe from"node:path";import{copyFile as Oe,mkdir as _e,readFile as Le}from"node:fs/promises";import C from"node:path";var Z=Buffer.from([137,80,78,71,13,10,26,10]);async function ee(e){let t;try{t=await Le(e.sourcePath)}catch(n){if(b(n))return{ok:!1,error:"screenshot-not-found",message:`the screenshot ${e.sourcePath} does not exist`};throw n}if(!t.subarray(0,Z.length).equals(Z))return{ok:!1,error:"not-png",message:`${e.sourcePath} is not a PNG file`};let r=C.join("shots",`${e.slug}-v${e.version}.png`),s=C.join(e.setDir,r);return await _e(C.dirname(s),{recursive:!0}),await Oe(e.sourcePath,s),{ok:!0,shot:r}}o(ee,"intakeScreenshot");var Ve={"&":"&","<":"<",">":">",""":'"',"'":"'"};function te(e){return`${e} - Prototypes`}o(te,"formatIndexTitle");function re(e,t,r,s){return se(`${e} - ${w(t,r)} ${s}`)}o(re,"formatPrototypeTitle");function ne(e){let t=e.replaceAll(/<!--[\s\S]*?-->/g,"").replaceAll(/<svg[\s>][\s\S]*?<\/svg\s*>/gi,""),r=/<title(?:\s[^>]*)?>([\s\S]*?)<\/title\s*>/i.exec(t);return r?.[1]===void 0?null:se(r[1].replaceAll(/&(?:amp|lt|gt|quot|#39);/g,s=>Ve[s]??s))}o(ne,"readPageTitle");function se(e){return e.replaceAll(/\s+/g," ").trim()}o(se,"collapseWhitespace");function E(e){try{let{protocol:t}=new URL(e);return t==="https:"||t==="http:"}catch{return!1}}o(E,"isWebUrl");async function ie(e,t,r,s){let n=p(t,"slug");if(!N(n))return l("invalid-slug",`slug "${n}" must match [a-z0-9][a-z0-9-]{0,39}`);let i=p(t,"url");if(!E(i))return l("invalid-url",`--url "${i}" is not an http or https URL`);let d=await y(e);if(d.kind==="invalid")return l("invalid-manifest",d.message);let a=d.kind==="ok"?d.manifest:null,c=t["set-title"]??a?.title;if(c===void 0)return l("missing-set-title","the first registration in a set requires --set-title");let f=Ue(a,n,t.number);if(typeof f!="number")return f;let u=M(a,n),h=p(t,"title"),O=t.source,_=await We(O,re(c,f,u,h));if(_!==null)return _;let j=await De(t.screenshot,e,n,u);if("error"in j)return j;let L={slug:n,number:f,version:u,registeredAt:s.toISOString(),title:h,url:i,source:O??null,lens:t.lens??null,inputs:P(t.inputs),description:t.description??null,notes:r,shot:j.shot},fe={title:c,indexUrl:a?.indexUrl??null,summary:a?.summary??null,entries:[...a?.entries??[],L]};return{ok:!0,command:"register",manifestPath:await S(e,fe),entry:L}}o(ie,"register");async function We(e,t){if(e===void 0)return null;let r;try{r=await Fe(oe.resolve(e),"utf8")}catch(i){if(qe(i))return l("source-not-found",`--source "${e}" is not a readable file`);throw i}let s=ne(r);if(s===t)return null;let n=s===null?"found no <title>":`found "${s}"`;return l("title-mismatch",`the source's <title> must be "${t}"; ${n}`)}o(We,"checkSourceTitle");function qe(e){return e instanceof Error&&"code"in e&&(e.code==="ENOENT"||e.code==="EISDIR")}o(qe,"isFileAbsenceError");function Ue(e,t,r){let s=H(e,t);if(r===void 0)return s;let n=Number(r);if(!Number.isSafeInteger(n)||n<1)return l("number-conflict",`--number "${r}" must be a positive integer`);let i=e?.entries??[];if(i.some(a=>a.slug===t))return s===n?n:l("number-conflict",`slug "${t}" is number ${s}, not ${n}`);let d=i.find(a=>a.number===n);return d===void 0?n:l("number-conflict",`number ${n} belongs to slug "${d.slug}"`)}o(Ue,"resolveRegistrationNumber");async function De(e,t,r,s){if(e===void 0)return{shot:null};let n=await ee({sourcePath:oe.resolve(e),setDir:t,slug:r,version:s});return n.ok?{shot:n.shot}:l(n.error,n.message)}o(De,"storeScreenshot");var ze=5e3,Be={fetch,evaluate:Ke};async function ae(e,t=Be){if(!E(e))return l("invalid-url",`--endpoint "${e}" is not an http or https URL`);let r=e.replace(/\/+$/,""),s;try{s=await(await t.fetch(`${r}/json/list`)).json()}catch{return l("endpoint-unreachable",`${r}/json/list did not return a target list`)}let n=Ge(s),i=await Promise.all(n.map(async c=>({target:c,answered:await t.evaluate(c.webSocketUrl,ze)}))),d=[],a=[];for(let{target:c,answered:f}of i){let u={id:c.id,url:c.url};if(f){d.push(u);continue}try{await t.fetch(`${r}/json/close/${encodeURIComponent(c.id)}`)}catch{return l("endpoint-unreachable",`${r}/json/close/${c.id} did not answer`)}a.push(u)}return{ok:!0,command:"probe-targets",closed:a,answered:d}}o(ae,"probeTargets");async function Ke(e,t,r=s=>new WebSocket(s)){return new Promise(s=>{let n=r(e),i=setTimeout(()=>d(!1),t);function d(a){clearTimeout(i),n.close(),s(a)}o(d,"settle"),n.addEventListener("open",()=>{n.send(JSON.stringify({id:1,method:"Runtime.evaluate",params:{expression:"1"}}))}),n.addEventListener("message",a=>{let c=Ye(a);c!==void 0&&c.id===1&&d(!c.isError)}),n.addEventListener("error",()=>d(!1))})}o(Ke,"evaluateOverWebSocket");function Ge(e){if(!Array.isArray(e))return[];let t=[];for(let r of e){if(!g(r)||r.type!=="page")continue;let{id:s,url:n,webSocketDebuggerUrl:i}=r;typeof s=="string"&&typeof i=="string"&&t.push({id:s,url:typeof n=="string"?n:"",webSocketUrl:i})}return t}o(Ge,"parsePageTargets");function Ye(e){if(typeof e.data!="string")return;let t;try{t=JSON.parse(e.data)}catch{return}if(g(t))return{id:t.id,isError:t.error!==void 0}}o(Ye,"parseReply");var He="verdicts";var de=`(() => {
|
|
55
55
|
'use strict';
|
|
56
|
-
const COLLECTION = '${
|
|
56
|
+
const COLLECTION = '${He}';
|
|
57
57
|
const grid = document.getElementById('grid');
|
|
58
58
|
const summary = document.getElementById('summary');
|
|
59
59
|
const status = document.getElementById('status');
|
|
@@ -328,14 +328,14 @@ var oe=Object.defineProperty;var i=(e,t)=>oe(e,"name",{value:t,configurable:!0})
|
|
|
328
328
|
render();
|
|
329
329
|
connect().catch(() => setStatus('Verdicts could not be loaded.'));
|
|
330
330
|
})();
|
|
331
|
-
`;var
|
|
332
|
-
`)}
|
|
333
|
-
`)}
|
|
334
|
-
:root { color-scheme: light; ${
|
|
331
|
+
`;var Je=["accent","chip","control-border","on-accent","page","reject-bg","reject-text","surface","text","text-muted","winner-bg","winner-border","winner-text"],Xe={dark:{accent:"#8cb6ff",chip:"#2a2f39","control-border":"#8790a3","on-accent":"#0b1730",page:"#111317","reject-bg":"#3f1717","reject-text":"#ffb8b8",surface:"#1b1e25",text:"#e7e9ee","text-muted":"#b0b6c3","winner-bg":"#3b2d06","winner-border":"#d9a43a","winner-text":"#ffd98a"},light:{accent:"#1d5bbf",chip:"#e9ecf1","control-border":"#6b7385","on-accent":"#ffffff",page:"#f4f5f7","reject-bg":"#fbe4e4","reject-text":"#8f1d1d",surface:"#ffffff",text:"#1b1f27","text-muted":"#4a5160","winner-bg":"#fff1c9","winner-border":"#a06c00","winner-text":"#5c3d00"}};function I(e){return Je.map(t=>`--${t}: ${Xe[e][t]};`).join(" ")}o(I,"renderTokenDeclarations");var ce=12e6,A=16e6;function le(e){let t=m(e.title),r=e.cards.length;return[`<title>${m(te(e.title))}</title>`,`<style>${tt()}</style>`,"<main>","<header>",`<h1>${t}</h1>`,...e.summary===null?[]:[rt(e.summary)],`<p class="summary" id="summary">${r} ${r===1?"prototype":"prototypes"}</p>`,"</header>",'<div class="toolbar">','<label class="toggle" id="rejected-toggle" hidden><input type="checkbox" id="show-rejected" checked> Show rejected</label>','<p class="hint" id="shortcuts" hidden>On a focused card: <kbd>\u2190</kbd> <kbd>\u2192</kbd> <kbd>\u2191</kbd> <kbd>\u2193</kbd> move between cards \xB7 <kbd>x</kbd> reject \xB7 <kbd>w</kbd> winner \xB7 <kbd>1\u20139</kbd> rank</p>','<p class="status" id="status" role="status" aria-live="polite"></p>',"</div>",'<div class="grid" id="grid">',...e.cards.map(s=>Ze(s,r)),"</div>","</main>",`<script>${de}</script>`,""].join(`
|
|
332
|
+
`)}o(le,"renderIndexPage");function m(e){return e.replaceAll("&","&").replaceAll("<","<").replaceAll(">",">").replaceAll('"',""").replaceAll("'","'")}o(m,"escapeHtml");function Qe(e){let t=Date.parse(e);if(Number.isNaN(t))return e;let r=new Date(t).toISOString();return`${r.slice(0,10)} ${r.slice(11,16)} UTC`}o(Qe,"formatTimestamp");function Ze(e,t){let{entry:r}=e,s=m(r.slug),n=m(r.title),i=m(r.url),d=`title-${s}`,a=e.shot===null?`<span class="placeholder">No screenshot for v${r.version}</span>`:`<img src="data:image/png;base64,${e.shot.toString("base64")}" alt="Screenshot of ${n}">`,c=[...r.lens===null?[]:[`<li class="chip">Lens: ${m(r.lens)}</li>`],...r.inputs.map(u=>`<li class="chip">${m(u)}</li>`)],f=Array.from({length:t},(u,h)=>`<option value="${h+1}">${h+1}</option>`);return[`<article class="card" tabindex="0" aria-labelledby="${d}" data-slug="${s}" data-number="${r.number}" data-id="${w(r.number,r.version)}" data-title="${n}" data-registered="${m(r.registeredAt)}">`,`<a class="thumb" href="${i}" target="_blank" rel="noopener" tabindex="-1" aria-hidden="true">${a}</a>`,'<div class="body">','<div class="badges" data-role="badges"></div>',`<h2 id="${d}"><a href="${i}" target="_blank" rel="noopener">${w(r.number,r.version)} ${n}</a></h2>`,`<p class="meta">${s} \xB7 ${m(Qe(r.registeredAt))}</p>`,...c.length===0?[]:[`<ul class="chips">${c.join("")}</ul>`],...r.description===null?[]:[`<p class="description">${m(r.description)}</p>`],...r.notes.length===0?[]:[et(r.notes)],'<div class="controls" data-role="controls" hidden>',`<button type="button" data-action="reject" aria-pressed="false" aria-describedby="${d}">Reject</button>`,`<label class="rank">Rank <select data-action="rank" aria-describedby="${d}"><option value="">None</option>${f.join("")}</select></label>`,`<button type="button" data-action="winner" aria-pressed="false" aria-describedby="${d}">Winner</button>`,"</div>","</div>","</article>"].join(`
|
|
333
|
+
`)}o(Ze,"renderCard");function et(e){return`<dl class="notes">${e.map(r=>`<dt>${m(r.label)}</dt><dd>${m(r.value)}</dd>`).join("")}</dl>`}o(et,"renderNotes");function tt(){return`
|
|
334
|
+
:root { color-scheme: light; ${I("light")} }
|
|
335
335
|
@media (prefers-color-scheme: dark) {
|
|
336
|
-
:root:not([data-theme="light"]) { color-scheme: dark; ${
|
|
336
|
+
:root:not([data-theme="light"]) { color-scheme: dark; ${I("dark")} }
|
|
337
337
|
}
|
|
338
|
-
:root[data-theme="dark"] { color-scheme: dark; ${
|
|
338
|
+
:root[data-theme="dark"] { color-scheme: dark; ${I("dark")} }
|
|
339
339
|
* { box-sizing: border-box; }
|
|
340
340
|
body { margin: 0; background: var(--page); color: var(--text); font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
|
|
341
341
|
main { max-width: 1280px; margin: 0 auto; padding: 24px 16px 48px; }
|
|
@@ -383,6 +383,6 @@ button, select { min-height: 32px; padding: 4px 10px; border: 1px solid var(--co
|
|
|
383
383
|
button[aria-pressed="true"] { border-color: var(--accent); background: var(--accent); color: var(--on-accent); }
|
|
384
384
|
button:disabled, select:disabled { cursor: not-allowed; }
|
|
385
385
|
@media (prefers-reduced-motion: reduce) { * { scroll-behavior: auto !important; transition: none !important; } }
|
|
386
|
-
`}
|
|
387
|
-
`),e.ok||(
|
|
388
|
-
`)
|
|
386
|
+
`}o(tt,"renderStyles");function rt(e){let t=e.try.map(s=>`<li>${m(s)}</li>`);return`<section class="set-summary" aria-label="Set summary"><dl>${[`<dt>Shared</dt><dd>${m(e.shared)}</dd>`,...e.changes===null?[]:[`<dt>Changed in this round</dt><dd>${m(e.changes)}</dd>`],...t.length===0?[]:[`<dt>Try in each</dt><dd><ol>${t.join("")}</ol></dd>`]].join("")}</dl></section>`}o(rt,"renderSummary");async function ot(){try{let e=await it({argv:$.argv.slice(2),now:new Date});$.stdout.write(`${JSON.stringify(e,null,2)}
|
|
387
|
+
`),e.ok||($.exitCode=1)}catch(e){$.stderr.write(`index-prototypes: ${x(e)}
|
|
388
|
+
`),$.exit(1)}}o(ot,"main");q(import.meta.url,"index-prototypes")&&await ot();async function it(e){let t;try{t=Q(e.argv)}catch(r){return l("invalid-args",x(r))}switch(t.command){case"copy-probe":return{ok:!0,command:"copy-probe",function:D};case"describe-set":return at(v(t.values),R.resolve(p(t.values,"file")));case"probe-targets":return ae(p(t.values,"endpoint"));case"record-index":return lt(v(t.values),p(t.values,"url"));case"register":return ie(v(t.values),t.values,t.notes,e.now);case"render":return ut(v(t.values),R.resolve(p(t.values,"out")));case"resolve-ids":return ft(v(t.values),p(t.values,"slugs"));default:{let r=t.command;throw new Error(`unhandled command: ${String(r)}`)}}}o(it,"runIndexPrototypes");async function at(e,t){let r;try{r=await ue(t,"utf8")}catch(a){if(b(a))return l("summary-not-found",`${t} does not exist`);throw a}let s;try{s=JSON.parse(r)}catch{return l("invalid-summary",`${t} is not valid JSON`)}let n=dt(s);if(typeof n=="string")return l("invalid-summary",`${t}: ${n}`);let i=await y(e);return i.kind==="missing"?l("manifest-not-found",`${e} does not contain a manifest; register a prototype first`):i.kind==="invalid"?l("invalid-manifest",i.message):{ok:!0,command:"describe-set",manifestPath:await S(e,{...i.manifest,summary:n}),summary:n}}o(at,"describeSet");function dt(e){if(!g(e))return'expected an object with "shared", "changes", and "try"';let{shared:t,changes:r,try:s}=e;if(typeof t!="string"||t.trim()==="")return'"shared" must be a non-empty string';if(r!=null&&typeof r!="string")return'"changes" must be a string or null';if(!Array.isArray(s)||s.some(i=>!(typeof i=="string"&&i.trim()!=="")))return'"try" must be a list of non-empty strings';let n=typeof r=="string"?r.trim():"";return{shared:t.trim(),changes:n===""?null:n,try:s.map(i=>i.trim())}}o(dt,"parseSummary");async function ct(e){try{return await ue(e)}catch(t){if(b(t))return null;throw t}}o(ct,"readShot");async function lt(e,t){if(!E(t))return l("invalid-url",`--url "${t}" is not an http or https URL`);let r=await y(e);return r.kind==="missing"?l("manifest-not-found",`${e} does not contain a manifest; register a prototype first`):r.kind==="invalid"?l("invalid-manifest",r.message):{ok:!0,command:"record-index",manifestPath:await S(e,{...r.manifest,indexUrl:t}),indexUrl:t}}o(lt,"recordIndex");async function ut(e,t){let r=await y(e);if(r.kind==="missing")return l("manifest-not-found",`${e} does not contain a manifest; register a prototype first`);if(r.kind==="invalid")return l("invalid-manifest",r.message);let{manifest:s}=r,n=[],i=[];for(let c of K(s)){let f=c.shot===null?null:await ct(R.join(e,c.shot));c.shot!==null&&f===null&&i.push(c.slug),n.push({entry:c,shot:f})}let d=le({title:s.title,summary:s.summary,cards:n}),a=Buffer.byteLength(d,"utf8");return a>A?l("page-too-large",`the page is ${a} bytes, over the ${A}-byte artifact cap`):(await nt(R.dirname(t),{recursive:!0}),await st(t,d,"utf8"),{ok:!0,command:"render",path:t,bytes:a,cards:n.length,title:s.title,indexUrl:s.indexUrl,missingShots:i,...a>ce&&{warning:`the page is ${a} bytes, approaching the ${A}-byte artifact cap`}})}o(ut,"render");async function ft(e,t){let r=P(t);if(r.length===0)return l("invalid-args","--slugs requires at least one slug");let s=r.find(d=>!N(d));if(s!==void 0)return l("invalid-slug",`slug "${s}" must match [a-z0-9][a-z0-9-]{0,39}`);if(new Set(r).size!==r.length)return l("invalid-args","--slugs names a slug twice");let n=await y(e);if(n.kind==="invalid")return l("invalid-manifest",n.message);let i=n.kind==="ok"?n.manifest:null;return{ok:!0,command:"resolve-ids",ids:G(i,r)}}o(ft,"resolveIdsForSlugs");export{it as runIndexPrototypes};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: investigate-spike
|
|
3
|
+
description: Carry out a spike plan's investigation steps and deliver its findings artifact, with the closing post on the ticket when no triage round follows
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Investigate spike
|
|
8
|
+
|
|
9
|
+
Carry out a spike plan, the `## Investigation steps` / `## Deliverable` shape defined in [spike conventions](../_data/spike-conventions.md). A spike produces findings rather than a diff: The run ends with a findings artifact and either the offer of the closing post or, when the findings propose work, the recommendation of the triage round that offers it, not with commits. The skill re-resolves everything it needs from the environment, so it works the same in the session that produced the plan and in a fresh one.
|
|
10
|
+
|
|
11
|
+
## Arguments
|
|
12
|
+
|
|
13
|
+
| Flag | Effect | Default |
|
|
14
|
+
| ------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------- |
|
|
15
|
+
| `--plan=<path>` | The spike plan to carry out. | Auto-resolved (see below) |
|
|
16
|
+
| `--ticket=<source>` | The spike ticket that the plan serves. Resolved per [ticket source resolution](../_data/ticket-source-resolution.md). | Auto-resolved (see below) |
|
|
17
|
+
|
|
18
|
+
## The contract
|
|
19
|
+
|
|
20
|
+
The ticket's questions to answer and decisions to enable are the contract; the plan's steps are the mechanism by which they are met. When a step turns out not to serve them, or the facts found show a better line of inquiry, the questions decide.
|
|
21
|
+
|
|
22
|
+
The plan artifact is read-only. It records what was planned, and a later reader compares it against the findings to see how the investigation departed from it.
|
|
23
|
+
|
|
24
|
+
## Process
|
|
25
|
+
|
|
26
|
+
<!-- include: ../_partials/resolve-plan-and-ticket.md / -->
|
|
27
|
+
|
|
28
|
+
5. **Work the investigation steps in order.** A step is done when its **Answered when:** condition holds, or when it is recorded as a residual unknown. Record each step's answer and its evidence as you go: the code read, the command and its output, the measurement.
|
|
29
|
+
|
|
30
|
+
Run throwaway probes and prototypes in a scratch directory created with `mktemp -d "${TMPDIR:-/tmp}/spike.XXXXXX"`, using the absolute path that the call prints. Commit nothing to the branch: A prototype worth keeping becomes a follow-up ticket, not a commit.
|
|
31
|
+
|
|
32
|
+
The timebox is the spike's effort ceiling. Judge it by the effort spent against the ceiling that the plan states, and once a step clearly exceeds it, stop the step and record what it left unanswered as a residual unknown rather than extend it.
|
|
33
|
+
|
|
34
|
+
Raise a finding that redirects the investigation, such as a false premise in a step or a question that the ticket did not ask, to the user before proceeding, rather than departing from the plan silently.
|
|
35
|
+
|
|
36
|
+
A step that names the developer as its actor is yours to carry out, unless the step has a `**Residue:**` line: Perform every part that you can, and raise the residue as the one ask that it states. It is never a step for the developer to run, and the records of a step stay yours even when the step has a residue line.
|
|
37
|
+
|
|
38
|
+
6. **Save the findings** as a ticket-level `spike-findings` artifact per {skill:save-artifact}. It contains the answer to each of the ticket's questions to answer, the recommendation on each of its decisions to enable, the residual unknowns, and the evidence behind each answer. When the investigation proposes work, list each proposal as an item that a triage can dispose of.
|
|
39
|
+
|
|
40
|
+
7. **Report** the answers and the recommendations against the ticket's questions and decisions, naming any question left unanswered and any departure from the plan, and give the artifact's path.
|
|
41
|
+
|
|
42
|
+
8. **Close** with an action-items block:
|
|
43
|
+
- When the findings propose work, recommend {skill?:triage-spike-findings} with the artifact path and the ticket, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states.
|
|
44
|
+
- Otherwise, when a ticket governs the run, offer to close it with the closing post, with the post's body shown; on consent, post it and close the ticket as that section states.
|
|
45
|
+
|
|
46
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
47
|
+
|
|
48
|
+
<!-- include: ../_partials/option-format.md / -->
|
|
@@ -21,6 +21,7 @@ The split is deliberate: The helper is narrow and mechanical; the classification
|
|
|
21
21
|
| `--domain-description` | One-line description for a domain that the write declares. Takes prose, not a path; the path comes from `--folder`. Without it the domain is declared bare. | No |
|
|
22
22
|
| `--folder` | Topic subpath beneath the assertions root (`content/assertions/`). The helper supplies the `assertions/` segment; pass the topic only. Defaults to `content/assertions/` itself. | No |
|
|
23
23
|
| `--kb` | Knowledge base name, or `@default` for the registry default. Overrides `.kb/` discovery; the registry default is reachable only via `--kb @default`. | No |
|
|
24
|
+
| `--shared` | Permit a write into a KB whose `visibility` is `shared`. See [Shared KBs](#shared-kbs). | No |
|
|
24
25
|
| `--survey` | Report the destination's shape and exit. Takes `--kb` alone; writes nothing and does not read stdin. See [step 2](#2-survey-the-destination-kb). | No |
|
|
25
26
|
| `--tags` | Comma-separated tag list. Known aliases are canonicalized at write time. | No |
|
|
26
27
|
| `--title` | The note title; also doubles as the filename. | Yes |
|
|
@@ -31,6 +32,12 @@ A value-bearing flag accepts both `--diataxis howto` and `--diataxis=howto`. The
|
|
|
31
32
|
|
|
32
33
|
By default the helper writes to the knowledge base discovered by walking up from the current directory for a `.kb/` folder. When the walk does not discover a `.kb/` and the caller does not pass `--kb`, the helper refuses to write rather than guessing a destination. `--kb <name>` names a specific entry from the merged `kb.yaml` registry and overrides discovery; `--kb @default` is the only way to reach the registry's `default_kb`. The chosen KB is shown in the proposal so that the user can redirect the write via `--kb` if it is wrong.
|
|
33
34
|
|
|
35
|
+
### Shared KBs
|
|
36
|
+
|
|
37
|
+
A KB's `.kb/config.yaml` declares its `visibility`: `shared` for a KB published to collaborators, `private` otherwise; a KB that does not declare it counts as `private`. The helper refuses a write into a `shared` KB unless the invocation passes `--shared`, because a note published in that KB's history cannot be withdrawn.
|
|
38
|
+
|
|
39
|
+
Never pass `--shared` by habit. Read the note's title, tags, and body as a collaborator would, and pass the flag only when they contain nothing unfit for that audience, such as a credential, a personal detail, or a workplace-internal fact. Otherwise, redirect the note to a private KB with `--kb <name>`, or report it uncaptured. When you cannot tell, do not pass the flag. In default mode, the user's confirmation of a proposal that names the KB as shared is the opt-in; in auto mode, the check is yours.
|
|
40
|
+
|
|
34
41
|
<!-- include: ../../_partials/kb-standard-tags.md / -->
|
|
35
42
|
|
|
36
43
|
## Runtime dependencies
|
|
@@ -74,6 +81,7 @@ It reports:
|
|
|
74
81
|
|
|
75
82
|
- `kb`: The knowledge base to which the write will resolve, by the same rules.
|
|
76
83
|
- `taxonomyPath`: The `.kb/taxonomy.yaml` from which the domains came.
|
|
84
|
+
- `visibility`: `shared` or `private`; a write into a `shared` KB needs `--shared`, per [Shared KBs](#shared-kbs).
|
|
77
85
|
- `domains`: Each declared domain with its `description`, its `provisional` flag, and the `noteCount` at or beneath it.
|
|
78
86
|
- `undeclaredFolders`: Folders containing notes outside every declared domain.
|
|
79
87
|
|
|
@@ -98,7 +106,7 @@ Write the note body. Embed cross-references inline when the reference contribute
|
|
|
98
106
|
|
|
99
107
|
### 6. Present the proposal (default mode)
|
|
100
108
|
|
|
101
|
-
In default mode, present the proposed KB, folder, Diátaxis label, title, tags, and body to the user. Name the domain that the folder matched, that domain's description, and the taxonomy file from which they came, so that the user can see what the placement was measured against. When the folder is a new domain, name it as new and propose the description that you will pass as `--domain-description`. When the survey reported an undeclared folder relevant to the choice, say so. Wait for confirmation or a redirect. In auto mode, skip this step.
|
|
109
|
+
In default mode, present the proposed KB, folder, Diátaxis label, title, tags, and body to the user. Name the domain that the folder matched, that domain's description, and the taxonomy file from which they came, so that the user can see what the placement was measured against. When the folder is a new domain, name it as new and propose the description that you will pass as `--domain-description`. When the survey reported an undeclared folder relevant to the choice, say so. When the survey reported `visibility: shared`, say that the KB is shared and that confirming the proposal writes into it with `--shared`. Wait for confirmation or a redirect. In auto mode, skip this step.
|
|
102
110
|
|
|
103
111
|
<!-- include: ../_partials/action-items.md / -->
|
|
104
112
|
|
|
@@ -110,7 +118,7 @@ Pipe the composed body to the bundled helper. A heredoc keeps multi-line bodies
|
|
|
110
118
|
cat <<'EOF' | node {harness_home_dir}/skills/kb-add/kb-add.mjs \
|
|
111
119
|
--diataxis <label> --title "<title>" \
|
|
112
120
|
[--kb <name>] [--folder <topic-subpath>] \
|
|
113
|
-
[--tags <comma,separated>] [--domain-description "<description>"] [--auto]
|
|
121
|
+
[--tags <comma,separated>] [--domain-description "<description>"] [--auto] [--shared]
|
|
114
122
|
<note body, may span multiple lines and contain any characters>
|
|
115
123
|
EOF
|
|
116
124
|
```
|
|
@@ -150,8 +158,9 @@ On `ok: false`, act on the `error` code:
|
|
|
150
158
|
- `missing-destination`: The helper did not discover a `.kb/`, and the invocation did not pass `--kb`. Ask the user where the note should go, passing `--kb <name>` for a specific KB or `--kb @default` for the registry default (or, in auto mode, fail visibly with the categorical reason).
|
|
151
159
|
- `no-default`: `--kb @default` was given but `kb.yaml` does not configure a `default_kb`. Report the message; have the user name a KB explicitly or configure a default.
|
|
152
160
|
- `readonly-kb`: The resolved KB is marked `readonly: true` in `kb.yaml`, so the write was refused. Report the message; have the user choose a writable KB with `--kb <name>`.
|
|
161
|
+
- `shared-kb`: The resolved KB is shared and the invocation did not pass `--shared`. Act per [Shared KBs](#shared-kbs).
|
|
153
162
|
- `invalid-args` / `invalid-title`: Report the helper's message and propose a corrected invocation.
|
|
154
|
-
- `invalid-config`: A survey found a malformed `.kb/config.yaml` or `.kb/taxonomy.yaml`. The message names the file; report it and have the user repair it before capturing.
|
|
163
|
+
- `invalid-config`: A survey found a malformed `.kb/config.yaml` or `.kb/taxonomy.yaml`, or a write found a malformed `.kb/config.yaml` and refused because the KB's visibility is unknown. The message names the file; report it and have the user repair it before capturing.
|
|
155
164
|
- `collision`: A note already exists at the target path. Decide whether to re-title, append the new material to the existing note (read it first, then write a follow-up edit), or abort.
|
|
156
165
|
|
|
157
166
|
## Completion
|