Compare commits

..
10 Commits
226 changed files with 14014 additions and 5284 deletions

No files matched your search

@@ -3,10 +3,10 @@
Key design points: Key design points:
- **First-run Welcome.** The first dashboard a person sees (after the wake-up finishes) opens `#welcome-modal`. Any close (button, Esc, backdrop) saves `looks.welcomeSeen: true` to `looks.json`, which survives "Back to default". Help's first tab has a **Show the welcome again** link (`data-action="welcome"`). Logic: `maybeWelcome()` / `openWelcome()` in `screens/help-dialog.js`. - **First-run Welcome.** The first dashboard a person sees (after the wake-up finishes) opens `#welcome-modal`. Any close (button, Esc, backdrop) saves `looks.welcomeSeen: true` to `looks.json`, which survives "Reset this tab". The four columns teach Pick a card, Answer then Send, Watch the terminal (the in-app wording names the terminal panel) and Get help; the session meter's one-time tip lives in the meter popover (`looks.meterTipSeen`). `looks.skillLaunched` is set by the first skill launch from this machine (`launchSkill()`) and, like `welcomeSeen`, is never reset: until it is set the dashboard holds the role line and draws Learning "Not set up" at the bottom, and after it one quiet line offers the two optional extras. Help's first tab has a **Show the welcome again** link (`data-action="welcome"`). Logic: `maybeWelcome()` / `openWelcome()` in `screens/help-dialog.js`.
- **Top-bar icons.** `#btn-looks` (gear) opens `#looks-modal`, titled User Preferences (see User Preferences below). `#btn-feedback` (megaphone) is a plain link to `https://github.com/jparkerweb/plan2code/issues/new/choose`, backed by `.github/ISSUE_TEMPLATE/bug.yml` and `idea.yml` (`config.yml` sets `blank_issues_enabled: false`). `DEFAULT_ACCENT` in `palette.js` is `ocean`. - **Top-bar icons.** `#btn-looks` (gear) opens `#looks-modal`, titled User Preferences (see User Preferences below). `#btn-feedback` (megaphone) is a plain link to `https://github.com/jparkerweb/plan2code/issues/new/choose`, backed by `.github/ISSUE_TEMPLATE/bug.yml` and `idea.yml` (`config.yml` sets `blank_issues_enabled: false`). `DEFAULT_ACCENT` in `palette.js` is `ocean`.
- **Version in Help.** `GET /version` reads `version.json` beside `server.mjs`, falling back to `../../version.json` for a run from `src/` (the `/version` route in `routes.mjs`). `renderHelpVersion()` in `screens/help-dialog.js` fills `#help-version`. `computeExpectedSkills()` in `install.js` injects the root `version.json` into every `references/web-console/`, so a version bump changes every skill. - **Version in Help.** `GET /version` reads `version.json` beside `server.mjs`, falling back to `../../version.json` for a run from `src/` (the `/version` route in `routes.mjs`). `renderHelpVersion()` in `screens/help-dialog.js` fills `#help-version`. `computeExpectedSkills()` in `install.js` injects the root `version.json` into every `references/web-console/`, so a version bump changes every skill.
- **User Preferences is four tabs in a side list.** Appearance (Theme, Card width, Highlight color, Role), Agents & models, System (Cleanup, and Desktop app inside the app only) and Sounds & activities (Sounds, Activities), a sideways strip below 720 px. The tabs are the static `<section class="prefs-panel">` panels in `#looks-modal`, each fieldset in exactly one (its `data-section`, listed in `PREFS_TABS`), wired by the shared `public/tabs.js` (`wireTabs()`, the same helper Help uses: `helpKeyTarget()` re-exports its `tabKeyTarget()`). `public/prefs.js` is the pure part: `PREFS_TABS`, `prefsOpenTab()` (the gear and the dashboard's Set up preferences both open Appearance; nothing is remembered between opens) and `prefsResetScope()` (Back to default resets only the shown tab's looks keys, and is hidden on Agents & models and System). `screens/prefs-dialog.js` owns `openPrefs(tab)`, the one way in, the Saved mark and the unsaved prompt; `screens/looks.js` keeps the look and sound controls, which save to `looks.json` as they change; `screens/agents-view.js` mounts the Agents & models tab, a master-detail split over today's `models.json` and `agents.json` (formats unchanged) whose per-agent form has its own Save and Discard: Save sends the last saved list with only that form's draft swapped in, so another form's half-typed edit is never written. The split's components live under `screens/agents/` (data, list editor, summary, form); the mount owns all state and every fetch and hands them one `ctx`. - **User Preferences is four tabs in a side list.** Appearance (Theme, Card width, Highlight color, Role), Agents & models, System (Cleanup, and Desktop app inside the app only) and Sounds & activities (Sounds, Activities), a sideways strip below 720 px. The tabs are the static `<section class="prefs-panel">` panels in `#looks-modal`, each fieldset in exactly one (its `data-section`, listed in `PREFS_TABS`), wired by the shared `public/tabs.js` (`wireTabs()`, the same helper Help uses: `helpKeyTarget()` re-exports its `tabKeyTarget()`). `public/prefs.js` is the pure part: `PREFS_TABS`, `prefsOpenTab()` (the gear and the dashboard's Set up preferences both open Appearance; nothing is remembered between opens) and `prefsResetScope()` (Reset this tab, with an "Reset. Undo" mark for eight seconds, resets only the shown tab's looks keys, and is hidden on Agents & models and System). `screens/prefs-dialog.js` owns `openPrefs(tab)`, the one way in, the Saved mark and the unsaved prompt; `screens/looks.js` keeps the look and sound controls, which save to `looks.json` as they change; `screens/agents-view.js` mounts the Agents & models tab, a master-detail split over today's `models.json` and `agents.json` (formats unchanged) whose per-agent form has its own Save and Discard: Save sends the last saved list with only that form's draft swapped in, so another form's half-typed edit is never written. The split's components live under `screens/agents/` (data, list editor, summary, form); the mount owns all state and every fetch and hands them one `ctx`.
- **Models in User Preferences.** `GET` / `POST /models` in `routes.mjs` read the shipped `~/.plan2code/bin/models.json` and read/write the user's `~/.plan2code/models.json` (`SHIPPED_MODELS_FILE` / `USER_MODELS_FILE` in `files.mjs`), edited from each built-in agent's form on the Agents & models tab. `PLAN2CODE_MODELS_DIR` relocates both for tests. The launcher reads the same two files for its model menu. - **Models in User Preferences.** `GET` / `POST /models` in `routes.mjs` read the shipped `~/.plan2code/bin/models.json` and read/write the user's `~/.plan2code/models.json` (`SHIPPED_MODELS_FILE` / `USER_MODELS_FILE` in `files.mjs`), edited from each built-in agent's form on the Agents & models tab. `PLAN2CODE_MODELS_DIR` relocates both for tests. The launcher reads the same two files for its model menu.
- **The wait is bounded.** `wait --seconds 240` exits `0` (answers), `10` (still waiting, `message: "Waiting on your answer in the web console"` to relay), `20` (server gone, resume it) or `30` (canceled). The agent loops. Nothing blocks for the whole time a person takes. - **The wait is bounded.** `wait --seconds 240` exits `0` (answers), `10` (still waiting, `message: "Waiting on your answer in the web console"` to relay), `20` (server gone, resume it) or `30` (canceled). The agent loops. Nothing blocks for the whole time a person takes.
- **A turn is one command, and the CLI does the bookkeeping.** Agent speed is model round trips and typed tokens, not the console (`bench-web-console.mjs --roundtrip`: Send→agent ~70 ms, post→page ~180 ms), so the CLI absorbs every step with one right answer: `consume()` marks the agent `working` when it hands over a submit (`markWorking()`), and `wait` hands the turn back (`markWaiting()`) when it starts with an open question, a finish, or on the dashboard or git board; `post --wait <N>` posts and waits in one process; `settle: true | [ids]` (`settleItems()` in `patches.mjs`) records the latest send's cards as answered from their `submitted`; a new or reopened question with no stated status sets `waiting` and waiting drops `quietMinutes` (`settleAgent()`); a doc whose content changed with no `version` moves up one (`mergeDocs()`); a chat reply with no `id` is `r<re>`; doc blocks with `file` (and `select: "tasks"`, doc-level `refresh: true`) are read from the worktree by `resolveDocFiles()` before the merge, refusing paths outside it; and a hop (`__launch`, `__dashboard`, `__commit`, `__pickup`) comes with `resume` (the exact `open --resume` command) and `skillFile` (`hopFor()`), a pick-up also with `handoffFile`. The wait loop's health check runs beside the 50 ms polling instead of blocking it, and is aborted on exit. `help <topic>` prints any contract file; `help topics` lists them. `token` defaults to the option key in the page's `tokenFor()`, and nothing reads `fallbackText`, so the contract no longer asks for either. - **A turn is one command, and the CLI does the bookkeeping.** Agent speed is model round trips and typed tokens, not the console (`bench-web-console.mjs --roundtrip`: Send→agent ~70 ms, post→page ~180 ms), so the CLI absorbs every step with one right answer: `consume()` marks the agent `working` when it hands over a submit (`markWorking()`), and `wait` hands the turn back (`markWaiting()`) when it starts with an open question, a finish, or on the dashboard or git board; `post --wait <N>` posts and waits in one process; `settle: true | [ids]` (`settleItems()` in `patches.mjs`) records the latest send's cards as answered from their `submitted`; a new or reopened question with no stated status sets `waiting` and waiting drops `quietMinutes` (`settleAgent()`); a doc whose content changed with no `version` moves up one (`mergeDocs()`); a chat reply with no `id` is `r<re>`; doc blocks with `file` (and `select: "tasks"`, doc-level `refresh: true`) are read from the worktree by `resolveDocFiles()` before the merge, refusing paths outside it; and a hop (`__launch`, `__dashboard`, `__commit`, `__pickup`) comes with `resume` (the exact `open --resume` command) and `skillFile` (`hopFor()`), a pick-up also with `handoffFile`. The wait loop's health check runs beside the 50 ms polling instead of blocking it, and is aborted on exit. `help <topic>` prints any contract file; `help topics` lists them. `token` defaults to the option key in the page's `tokenFor()`, and nothing reads `fallbackText`, so the contract no longer asks for either.
@@ -53,15 +53,16 @@ Key design points:
- **Back to the dashboard is the same kind of post-finish request.** A finish with `finish.dashboard: true` shows the button; a press arrives as `{ "i": "__dashboard", "type": "dashboard" }`, and the agent runs `open --resume <sid> --no-open --workflow dashboard` then posts `"finish": null` with a fresh `menu`. The agent waits ~10 minutes after the finish for it (alongside `__review` / `__done` on a quick task); after that the page swaps the button for the `/plan2code` command. `finish.command` is optional — without one the page shows the "All done" line — and `validate()` rejects a `<placeholder>` command and a non-boolean `dashboard`. The session-level actions are therefore `__brief`, `__stop`, `__launch`, `__review`, `__done` and `__dashboard`; a new post-finish button should copy this precedent. - **Back to the dashboard is the same kind of post-finish request.** A finish with `finish.dashboard: true` shows the button; a press arrives as `{ "i": "__dashboard", "type": "dashboard" }`, and the agent runs `open --resume <sid> --no-open --workflow dashboard` then posts `"finish": null` with a fresh `menu`. The agent waits ~10 minutes after the finish for it (alongside `__review` / `__done` on a quick task); after that the page swaps the button for the `/plan2code` command. `finish.command` is optional — without one the page shows the "All done" line — and `validate()` rejects a `<placeholder>` command and a non-boolean `dashboard`. The session-level actions are therefore `__brief`, `__stop`, `__launch`, `__review`, `__done` and `__dashboard`; a new post-finish button should copy this precedent.
- **Continue here, Update CHANGELOG first and Ask prompt blocks.** Three small additions on the same pattern. **Continue here** is page-only: `continueOffer(fin)` (`public/answers.js`) reads `finish.command`, and when it starts with a Plan2Code skill (and the finish is not a pause) `screens/ending.js` draws a button beside the Next step block, hidden when the session meter is red; the press is the dashboard's own `{ "i": "__launch", ... }` through `sendAfterBuild("launch", offer)`, so the agent writes nothing new (`startsClean()` cleans the page for the hop, except out of Git and into Review; a same-skill next step keeps the workflow, so the agent posts `"finish": null`). **Update CHANGELOG first** is `finish.changelog: true`, accepted by `validate()` only on `quick-task` and `finalize` (a paused finish is exempt from that check and the page ignores the flag), and it belongs with `commit: true`; the press is `__changelog`, a `HOP_ACTIONS` entry in `cmd-post-wait.mjs` that resumes as `changelog`, whose "Commit this now?" yes carries on to Git. **Ask prompt blocks** are contract only (`console-chat.md` → Prompts to carry away): the page already draws a Copy button on every fenced block. - **Continue here, Update CHANGELOG first and Ask prompt blocks.** Three small additions on the same pattern. **Continue here** is page-only: `continueOffer(fin)` (`public/answers.js`) reads `finish.command`, and when it starts with a Plan2Code skill (and the finish is not a pause) `screens/ending.js` draws a button beside the Next step block, hidden when the session meter is red; the press is the dashboard's own `{ "i": "__launch", ... }` through `sendAfterBuild("launch", offer)`, so the agent writes nothing new (`startsClean()` cleans the page for the hop, except out of Git and into Review; a same-skill next step keeps the workflow, so the agent posts `"finish": null`). **Update CHANGELOG first** is `finish.changelog: true`, accepted by `validate()` only on `quick-task` and `finalize` (a paused finish is exempt from that check and the page ignores the flag), and it belongs with `commit: true`; the press is `__changelog`, a `HOP_ACTIONS` entry in `cmd-post-wait.mjs` that resumes as `changelog`, whose "Commit this now?" yes carries on to Git. **Ask prompt blocks** are contract only (`console-chat.md` → Prompts to carry away): the page already draws a Copy button on every fenced block.
- **`__dashboard` also arrives mid-workflow.** A left-pointing triangle (`#btn-home`, filled with `--accent`) sits left of Stop session on every non-dashboard page. Its state comes from the pure `homeButtonState()` in `answers.js`: hidden on the dashboard, on a finish and during a stop, and otherwise gated by the same `turnGate()` Stop now uses (the person's turn, unless the agent has gone adrift). The confirm (`#home-modal`) reuses `stopWarning()`, and the submit carries the staged answers plus `__dashboard`, with `HOME_REPLY`. With no finish on the page, the agent treats it as a stop that lands on the menu: it saves its place as for `__stop`, then resumes as the dashboard with `"finish": null` + `menu`, with no finish and no stop in between (console-stop.md → "Back to the dashboard, mid-workflow"; building.md for builds). `local.homeward` drives Planny's "Saving your place and opening the dashboard…" line until the through-the-dashboard reset clears it. - **`__dashboard` also arrives mid-workflow.** A left-pointing triangle (`#btn-home`, filled with `--accent`) sits left of Stop session on every non-dashboard page. Its state comes from the pure `homeButtonState()` in `answers.js`: hidden on the dashboard, on a finish and during a stop, and otherwise gated by the same `turnGate()` Stop now uses (the person's turn, unless the agent has gone adrift). The confirm (`#home-modal`) reuses `stopWarning()`, and the submit carries the staged answers plus `__dashboard`, with `HOME_REPLY`. With no finish on the page, the agent treats it as a stop that lands on the menu: it saves its place as for `__stop`, then resumes as the dashboard with `"finish": null` + `menu`, with no finish and no stop in between (console-stop.md → "Back to the dashboard, mid-workflow"; building.md for builds). `local.homeward` drives Planny's "Saving your place and opening the dashboard…" line until the through-the-dashboard reset clears it.
- **Handoffs live outside every repo, in `~/.plan2code/handoffs/`, and the console owns them** (`handoffs.mjs`; the console ships in every skill, so the Stop flow, the Handoff skill and the dashboard all reach it through `console.mjs`). `handoff new --workflow <w> --skill <s> [--spec specs/<x>] [--title <t>] [--from-stop]` claims one for this checkout and prints `{ ok, id, path, meta }` (exit 2 bad usage, 3 a bad value). Off the dashboard the Stop modal offers **Stop with a handoff** (`#stop-handoff`, suggested) above **Just stop and save** (`#stop-go`); the first sends `__stop` with `handoff: true` and `STOP_HANDOFF_REPLY`, and `wait` adds `handoffSkill` (the built Handoff skill's `SKILL.md`, `handoffFor()`); console-stop.md gives the order (answers, save, `handoff new --from-stop`, write, paused finish naming the file, `stop`). On a dashboard, `cmdOpen()` adds `scan.handoffs` (`listHandoffs(worktree)`) and `scan.handoffsDir` after `scanProject()`, which stays handoff-free because `specs.mjs list` shares it. The picker draws them as dashed `.spec-chip.is-handoff` chips after the specs (`specSel = "handoff:<id>"`); a picked one replaces the skill cards with `renderHandoffPreview()`: **Pick it up here**, **Read it all** (`GET /handoff?id=`, served only for an id in the dashboard's own `state.scan.handoffs`), **Copy for a new conversation** (`handoffCopyText()`) and **Delete** (`openHandoffDelete()`, one step). Pick it up sends `{ "i": "__pickup", "type": "pickup", "handoff": <id> }`; `HOP_ACTIONS.pickup` (`pickupHop()`) reads the stored `.json` only, never the page, and falls back to Quick Task with `fallback: true` when the record, its skill or its spec is gone, or the Handoff skill wrote it (resuming that skill would only write another handoff); `markPickedUp()` stamps `usedAt` as the hop is printed, so the next scan drops the chip. Delete sends `__delete` with `handoff` in place of `spec`, and the agent runs `delete-handoff --handoff <id>` (`removeHandoff()`, exit 3 on a refusal, nothing touched). `open` sweeps handoffs untouched for 30 days (`staleHandoffs()`, the `.json`'s mtime, else the `.md`'s), picked up or not, and reports them in `swept.handoffs`; Cleanup never lists the folder (`KEPT_PLAN2CODE_ENTRIES`). - **Handoffs live outside every repo, in `~/.plan2code/handoffs/`, and the console owns them** (`handoffs.mjs`; the console ships in every skill, so the Stop flow, the Handoff skill and the dashboard all reach it through `console.mjs`). `handoff new --workflow <w> --skill <s> [--spec specs/<x>] [--title <t>] [--from-stop]` claims one for this checkout and prints `{ ok, id, path, meta }` (exit 2 bad usage, 3 a bad value). Off the dashboard the Stop modal offers **Stop with a handoff** (`#stop-handoff`, suggested) above **Just stop and save** (`#stop-go`); the first sends `__stop` with `handoff: true` and `STOP_HANDOFF_REPLY`, and `wait` adds `handoffSkill` (the built Handoff skill's `SKILL.md`, `handoffFor()`); console-stop.md gives the order (answers, save, `handoff new --from-stop`, write, paused finish naming the file, `stop`). On a dashboard, `cmdOpen()` adds `scan.handoffs` (`listHandoffs(worktree)`) and `scan.handoffsDir` after `scanProject()`, which stays handoff-free because `specs.mjs list` shares it. The picker draws them as dashed `.spec-chip.is-handoff` chips after the specs (`specSel = "handoff:<id>"`); a picked one replaces the skill cards with `renderHandoffPreview()`: **Pick it up here**, **Read it all** (`GET /handoff?id=`, served only for an id in the dashboard's own `state.scan.handoffs`), **Copy for a new conversation** (`handoffCopyText()`) and **Delete** (`openHandoffDelete()`, one step). Pick it up sends `{ "i": "__pickup", "type": "pickup", "handoff": <id> }`; `HOP_ACTIONS.pickup` (`pickupHop()`) reads the stored `.json` only, never the page, and falls back to Quick task with `fallback: true` when the record, its skill or its spec is gone, or the Handoff skill wrote it (resuming that skill would only write another handoff); `markPickedUp()` stamps `usedAt` as the hop is printed, so the next scan drops the chip. Delete sends `__delete` with `handoff` in place of `spec`, and the agent runs `delete-handoff --handoff <id>` (`removeHandoff()`, exit 3 on a refusal, nothing touched). `open` sweeps handoffs untouched for 30 days (`staleHandoffs()`, the `.json`'s mtime, else the `.md`'s), picked up or not, and reports them in `swept.handoffs`; Cleanup never lists the folder (`KEPT_PLAN2CODE_ENTRIES`).
- **Notebook: the person's, one per folder, in `~/.plan2code/notepads/`, in named tabs, and the agent's only when the person sends a tab.** `notepads.mjs` is the store's one owner (`PLAN2CODE_NOTEPADS_DIR` moves it for tests). The folder is the session's worktree, else its project (`notepadRoot()` in `routes.mjs`), keyed `<folder-name>-<12 hex>` by `notepadKey()` (the hash over `foldKey()`, so case-only path differences match on Windows and macOS, and two worktrees get two notepads). **Layout:** `meta.json` (`{ v: 2, folder, created }`), `tabs.json` (`{ v: 1, order: [id], last, tabs: { id: { name, created, sent? } } }`, the index and the only place order and the last tab live) and, per tab, `tabs/<id>/note.md` with `tabs/<id>/images/<uuid>.jpg` and `<uuid>.thumb.jpg`; a tab id is 12 hex. Every write takes the folder's `notepad.lock`; a read never creates a file, so only the person's edits age a notepad. A delete removes the tab from the index first, then its folder, and the next write sweeps away a tab folder the index no longer names (a delete that crashed half way). **Migration:** the first shape (`v: 1`, one `note.md` and `images/` at the top) reads as one virtual tab, Notes, with the fixed id `LEGACY_TAB_ID`, and a read writes nothing; the first write moves the files into `tabs/<LEGACY_TAB_ID>/` and writes `tabs.json` last, so a crash in the middle is finished by the next write and never loses a file. A `tabs.json` that does not hold up is set aside as `tabs.json.corrupt` and rebuilt from the tab folders. **Routes:** twelve, placed after `/upload` in `ROUTES` (the shape test pins the order): `GET /notepad[?tab=<id>]` (`{ tabs, last, tab: { id, text, savedAt, images } }`, with the tab's `text`, `savedAt` and `images` repeated at the top), `POST /notepad/text?tab=` (`{ text }`, 1 MB, 413 `too-long`), `POST /notepad/image?tab=` and `POST /notepad/thumb?id=<uuid>&tab=` (raw `image/jpeg` the page re-encoded with `reencode()`, 4 MB, 200 pictures per tab: 415 `not-jpeg`, 413 `too-large`, 409 `too-many`), `POST /notepad/image/delete?tab=` (`{ id }`), `POST /notepad/tab` (`{ name }`), `/notepad/tab/rename` (`{ id, name }`), `/notepad/tab/delete` (`{ id }`), `/notepad/tab/order` (`{ order }`, every id once) `/notepad/tab/last` (`{ id }`) and `/notepad/tab/sent` (`{ id, workflow, spec? }`, `markTabSent()`: sets `sent: { workflow, spec?, at }` on the tab, replacing an earlier one; `workflow` one of `pathfinder`, `plan`, `quick-task`, `revise-plan`, `spec` matching `^specs/[A-Za-z0-9._-]+$`, else 400 `bad-sent`), and `GET /notepad/images/<tab>/<uuid>[.thumb].jpg` (matched on the raw request line like `/uploads/`, served through `imagePath()`'s realpath containment, `no-store`). A text or picture request with no `?tab` means the last tab used (and makes Notes when there is none), so an unchanged client keeps working. The ten POSTs are origin-checked, and every refusal is a `NotepadError` turned into `{ error }` (`bad-name`, `duplicate-name`, `too-many-tabs`, `no-such-tab` beside the picture and text codes). None of them writes to the session folder or `events.ndjson`, and `console.mjs` and the `cmd-*.mjs` files never import `notepads.mjs` (a source test pins it; `sessions.mjs` loads it lazily for Cleanup only, listing and removing whole notepads), so nothing in a notepad reaches `state.json` or anything `wait` prints except a tab the person sends (see **Send to a skill**). **The editor, and the CSP.** CodeMirror 6 replaced OverType 2.6.1 after a spike (typing at 200 KB measured about 24 ms a key against about 99 ms, and real heading sizes): `public/vendor/codemirror.esm.js` is one minified file (about 500 KB) made by the dev-only `scripts/vendor-codemirror.mjs` from `scripts/vendor-codemirror-lock.json`, never installed in the repo, and loaded by a dynamic import only when the Notebook first opens. CodeMirror writes its rules as a `<style>` element, which `style-src 'self'` refuses, so the editor lives in the open shadow root of `.notepad-cm-host` where it adopts them as a constructed stylesheet, and its own look is `public/notepad-editor.css`, a `<link>` inside the root. Custom properties inherit across the boundary, so both themes work; page tests reach the editor with Playwright's CSS locators (they pierce open shadow roots) and read its text from `EditorView.findFromDOM()`, since lines the cursor is not on draw without their Markdown marks. CodeMirror's own rules win a tie in specificity (they are adopted after the linked sheet), so `notepad-editor.css` writes `div.cm-editor .cm-scroller` for the few it overrides. `scripts/test-web-console-page-notepad.mjs` fails on any `securitypolicyviolation` with the notepad open. **Upgrading CodeMirror:** change a version in `scripts/vendor-codemirror.mjs`, run `node scripts/vendor-codemirror.mjs --update-lock` (npm and network; it installs in a temp folder), update the sha256 in the files-table row, then run the two notepad test files. **Tabs on the page:** `screens/notepaLine truncated - **Notebook: the person's, one per folder, in `~/.plan2code/notepads/`, in named tabs, and the agent's only when the person sends a tab.** `notepads.mjs` is the store's one owner (`PLAN2CODE_NOTEPADS_DIR` moves it for tests). The folder is the session's worktree, else its project (`notepadRoot()` in `routes.mjs`), keyed `<folder-name>-<12 hex>` by `notepadKey()` (the hash over `foldKey()`, so case-only path differences match on Windows and macOS, and two worktrees get two notepads). **Layout:** `meta.json` (`{ v: 2, folder, created }`), `tabs.json` (`{ v: 1, order: [id], last, tabs: { id: { name, created, sent? } } }`, the index and the only place order and the last tab live) and, per tab, `tabs/<id>/note.md` with `tabs/<id>/images/<uuid>.jpg` and `<uuid>.thumb.jpg`; a tab id is 12 hex. Every write takes the folder's `notepad.lock`; a read never creates a file, so only the person's edits age a notepad. A delete removes the tab from the index first, then its folder, and the next write sweeps away a tab folder the index no longer names (a delete that crashed half way). **Migration:** the first shape (`v: 1`, one `note.md` and `images/` at the top) reads as one virtual tab, Notes, with the fixed id `LEGACY_TAB_ID`, and a read writes nothing; the first write moves the files into `tabs/<LEGACY_TAB_ID>/` and writes `tabs.json` last, so a crash in the middle is finished by the next write and never loses a file. A `tabs.json` that does not hold up is set aside as `tabs.json.corrupt` and rebuilt from the tab folders. **Routes:** twelve, placed after `/upload` in `ROUTES` (the shape test pins the order): `GET /notepad[?tab=<id>]` (`{ tabs, last, tab: { id, text, savedAt, images } }`, with the tab's `text`, `savedAt` and `images` repeated at the top), `POST /notepad/text?tab=` (`{ text }`, 1 MB, 413 `too-long`), `POST /notepad/image?tab=` and `POST /notepad/thumb?id=<uuid>&tab=` (raw `image/jpeg` the page re-encoded with `reencode()`, 4 MB, 200 pictures per tab: 415 `not-jpeg`, 413 `too-large`, 409 `too-many`), `POST /notepad/image/delete?tab=` (`{ id }`), `POST /notepad/tab` (`{ name }`), `/notepad/tab/rename` (`{ id, name }`), `/notepad/tab/delete` (`{ id }`), `/notepad/tab/order` (`{ order }`, every id once) `/notepad/tab/last` (`{ id }`) and `/notepad/tab/sent` (`{ id, workflow, spec? }`, `markTabSent()`: sets `sent: { workflow, spec?, at }` on the tab, replacing an earlier one; `workflow` one of `pathfinder`, `plan`, `quick-task`, `revise-plan`, `spec` matching `^specs/[A-Za-z0-9._-]+$`, else 400 `bad-sent`), and `GET /notepad/images/<tab>/<uuid>[.thumb].jpg` (matched on the raw request line like `/uploads/`, served through `imagePath()`'s realpath containment, `no-store`). A text or picture request with no `?tab` means the last tab used (and makes Notes when there is none), so an unchanged client keeps working. The ten POSTs are origin-checked, and every refusal is a `NotepadError` turned into `{ error }` (`bad-name`, `duplicate-name`, `too-many-tabs`, `no-such-tab` beside the picture and text codes). None of them writes to the session folder or `events.ndjson`, and `console.mjs` and the `cmd-*.mjs` files never import `notepads.mjs` (a source test pins it; `sessions.mjs` loads it lazily for Cleanup only, listing and removing whole notepads), so nothing in a notepad reaches `state.json` or anything `wait` prints except a tab the person sends (see **Send to a skill**). **The editor, and the CSP.** CodeMirror 6 replaced OverType 2.6.1 after a spike (typing at 200 KB measured about 24 ms a key against about 99 ms, and real heading sizes): `public/vendor/codemirror.esm.js` is one minified file (about 500 KB) made by the dev-only `scripts/vendor-codemirror.mjs` from `scripts/vendor-codemirror-lock.json`, never installed in the repo, and loaded by a dynamic import only when the Notebook first opens. CodeMirror writes its rules as a `<style>` element, which `style-src 'self'` refuses, so the editor lives in the open shadow root of `.notepad-cm-host` where it adopts them as a constructed stylesheet, and its own look is `public/notepad-editor.css`, a `<link>` inside the root. Custom properties inherit across the boundary, so both themes work; page tests reach the editor with Playwright's CSS locators (they pierce open shadow roots) and read its text from `EditorView.findFromDOM()`, since lines the cursor is not on draw without their Markdown marks. CodeMirror's own rules win a tie in specificity (they are adopted after the linked sheet), so `notepad-editor.css` writes `div.cm-editor .cm-scroller` for the few it overrides. `scripts/test-web-console-page-notepad.mjs` fails on any `securitypolicyviolation` with the notepad open. **Upgrading CodeMirror:** change a version in `scripts/vendor-codemirror.mjs`, run `node scripts/vendor-codemirror.mjs --update-lock` (npm and network; it installs in a temp folder), update the sha256 in the files-table row, then run the two notepad test files. **Tabs on the page:** `screens/notepaLine truncated
- **A Bug fixed spec deletes in one step.** Its chip shows a visible **Delete** (`.spec-chip-del-label`) instead of the hover ✕, `openDeleteConfirm()` gives it a fixed-bug warning and a **Delete it** button, and `deleteStep()` sends `__delete` on the first press, with no name to type. `chipDetail()` drops the scan's repeated "bug fixed" detail under the label. - **A Bug fixed spec deletes in one step.** Its chip shows a visible **Delete** (`.spec-chip-del-label`) instead of the hover ✕, `openDeleteConfirm()` gives it a fixed-bug warning and a **Delete it** button, and `deleteStep()` sends `__delete` on the first press, with no name to type. `chipDetail()` drops the scan's repeated "bug fixed" detail under the label.
- **The Quick question chat is a second, append-only channel beside the card slot.** The page's **Ask** tab (always last, every workflow, still there after a finish) posts to `POST /chat` (a message, or `{ reset: true }` for New conversation) and `POST /chat/decision` (Approve / Decline on an edit the agent proposed). The server is the only writer of `<sid>/chat.ndjson` (one JSON line per `message` / `decision` / `reset`, each with a `seq`; `appendChat()` in `inbox.mjs`); `console.mjs` is the only writer of `<sid>/chat-cursor.json` (the last seq handed over, advanced only after printing) and of the agent's replies in `state.json` → `chat.replies` (merged by `id`, checked by `validateChat()`: real `re`, proposal paths outside the running `specs/<idea>/`). The server never writes chat into `state.json` — `post` read-modify-writes it under `withStateLock()` — and `stateFrame()` merges inbox and replies into the frame's `chat` block (`conversation`, `messages`, `typed`, `limit`, `offline`) in memory. `/chat` never checks `pendingResult()`, so neither channel can block the other. `wait` keeps its exit codes 0/10/20/30: exit 0 gains `chat` (or is `type: "chat"` with no actions), and the instant `console.mjs chat` answers 0/10/20 without touching `result.json`, which builds run after every task. Guards: 10 typed messages per conversation (`409 limit`), 4,000 characters (`400 too-long`), own uploads only, of the right kind (`400 image`, `400 file`), `409 offline` when `chatOffline()` says no agent is there, `409 stale` for an old conversation. A hop through the dashboard keeps the conversation: `switchWorkflow()` carries `chat.replies` across and the page keeps its Ask state, so only New conversation appends a `reset` after the opening one. A lone reset never ends a `wait` slice (`deliverableChat()`); it rides along with the next message. - **The Quick question chat is a second, append-only channel beside the card slot.** The page's **Ask** tab (always last, every workflow, still there after a finish) posts to `POST /chat` (a message, or `{ reset: true }` for New conversation) and `POST /chat/decision` (Approve / Decline on an edit the agent proposed). The server is the only writer of `<sid>/chat.ndjson` (one JSON line per `message` / `decision` / `reset`, each with a `seq`; `appendChat()` in `inbox.mjs`); `console.mjs` is the only writer of `<sid>/chat-cursor.json` (the last seq handed over, advanced only after printing) and of the agent's replies in `state.json` → `chat.replies` (merged by `id`, checked by `validateChat()`: real `re`, proposal paths outside the running `specs/<idea>/`). The server never writes chat into `state.json` — `post` read-modify-writes it under `withStateLock()` — and `stateFrame()` merges inbox and replies into the frame's `chat` block (`conversation`, `messages`, `typed`, `limit`, `offline`) in memory. `/chat` never checks `pendingResult()`, so neither channel can block the other. `wait` keeps its exit codes 0/10/20/30: exit 0 gains `chat` (or is `type: "chat"` with no actions), and the instant `console.mjs chat` answers 0/10/20 without touching `result.json`, which builds run after every task. Guards: 10 typed messages per conversation (`409 limit`), 4,000 characters (`400 too-long`), own uploads only, of the right kind (`400 image`, `400 file`), `409 offline` when `chatOffline()` says no agent is there, `409 stale` for an old conversation. A hop through the dashboard keeps the conversation: `switchWorkflow()` carries `chat.replies` across and the page keeps its Ask state, so only New conversation appends a `reset` after the opening one. A lone reset never ends a `wait` slice (`deliverableChat()`); it rides along with the next message.
- **A loop stop leads with why and what to do next, in two places.** `evidence_markdown` in `loop_driver.rs` opens the report doc with a `> [!CAUTION]` box (the reason, then the stop line) and a `> [!TIP]` box (the advice); `render.js` draws a blockquote that opens with either marker as a colored `md-alert` and hides the marker. The stop card shows the same two as `.loop-why` and `.loop-advice` from `loopEnd.advice`. The advice is the failed phase's own `loopOutcome.nextStep` (one line, 300 characters, optional, only for a `failed` report that refused the phase), else `stop_advice()`'s words for the cause. `failed_words` puts the reason before the agent's summary, since a failed report's summary often reads like success. - **A loop stop leads with why and what to do next, in two places.** `evidence_markdown` in `loop_driver.rs` opens the report doc with a `> [!CAUTION]` box (the reason, then the stop line) and a `> [!TIP]` box (the advice); `render.js` draws a blockquote that opens with either marker as a colored `md-alert` and hides the marker. The stop card shows the same two as `.loop-why` and `.loop-advice` from `loopEnd.advice`. The advice is the failed phase's own `loopOutcome.nextStep` (one line, 300 characters, optional, only for a `failed` report that refused the phase), else `stop_advice()`'s words for the cause. `failed_words` puts the reason before the agent's summary, since a failed report's summary often reads like success.
- **`validate()` in `patches.mjs` enforces four workflow rules mechanically**: max three open required questions, no internal vocabulary in a title, one recommended option, and no loop markers or metrics-scraper bait. - **`validate()` in `patches.mjs` enforces four workflow rules mechanically**: max three open required questions, no internal vocabulary in a title, one recommended option, and no loop markers or metrics-scraper bait.
- **The palette is written twice for dark, and that duplication is the mechanism.** `@media (prefers-color-scheme: dark) :root:not([data-theme="light"])` follows the system; `:root[data-theme="dark"]` is the explicit choice from the colors panel. Drop the `:not()` and a system-dark browser overrides someone who asked for light. A chosen accent is applied as an inline custom property on `:root` (CSSOM, which the CSP allows), and the default is applied by REMOVING that override so the stylesheet's own per-theme values win. The server's `data-looks-accent` stand-in only lasts until `applyLooks()` runs, which removes it first thing — left on, its rule would beat "Back to default". - **The palette is written twice for dark, and that duplication is the mechanism.** `@media (prefers-color-scheme: dark) :root:not([data-theme="light"])` follows the system; `:root[data-theme="dark"]` is the explicit choice from the colors panel. Drop the `:not()` and a system-dark browser overrides someone who asked for light. A chosen accent is applied as an inline custom property on `:root` (CSSOM, which the CSP allows), and the default is applied by REMOVING that override so the stylesheet's own per-theme values win. The server's `data-looks-accent` stand-in only lasts until `applyLooks()` runs, which removes it first thing — left on, its rule would beat "Reset this tab".
- **Help is in the page, built on first open.** The **?** button (`#btn-about`) opens `<dialog id="help-modal">`, which replaced the old "What this page is" About dialog. Its 22 panels and their icon sheet are hand-written HTML and SVG in `<template id="help-content">` in `index.html` (after `#start-poses`), cloned into `#help-panels` the first time **?** is pressed (except the dashboard topic's card list: `buildHelp()` fills its `.help-cards` from `SKILL_CATALOG` and `CATALOG_GROUPS` at that moment, in the dashboard's order), so first load builds nothing and Help still reads fully once the server is gone. `help.js` supplies the tab list and rules, `screens/help-dialog.js` the wiring (tab buttons, roving focus, `renderAbout()` for the live connection line on tab 1, `lightDismiss()`, and a Ctrl/⌘+Enter guard scoped to this dialog). SVG is styled by class and CSS variables only — a `style=` attribute is dropped by the CSP, and a test fails on one — and every number the prose quotes sits in a `data-fact` span a test checks against the constant it comes from. - **Help is in the page, built on first open.** The **?** button (`#btn-about`) opens `<dialog id="help-modal">`, which replaced the old "What this page is" About dialog. Its 23 panels (in four groups, with a filter box above the tab list) and their icon sheet are hand-written HTML and SVG in `<template id="help-content">` in `index.html` (after `#start-poses`), cloned into `#help-panels` the first time **?** is pressed (except the dashboard topic's card list: `buildHelp()` fills its `.help-cards` from `SKILL_CATALOG` and `CATALOG_GROUPS` at that moment, in the dashboard's order), so first load builds nothing and Help still reads fully once the server is gone. `help.js` supplies the tab list and rules, `screens/help-dialog.js` the wiring (tab buttons, roving focus, `renderAbout()` for the live connection line on tab 1, `lightDismiss()`, and a Ctrl/⌘+Enter guard scoped to this dialog). SVG is styled by class and CSS variables only — a `style=` attribute is dropped by the CSP, and a test fails on one — and every number the prose quotes sits in a `data-fact` span a test checks against the constant it comes from.
- **Stuck sessions are explained twice, in Help and on the status line.** `stuck` ("When something looks stuck") is the second tab in `HELP_TABS`; its panel opens with a `help-callout` ("Check this first": Plan2Code often waits for a permission in the terminal, which the page cannot see) and four You see / Likely cause / Do this rows before the diagram. The quiet and Not running status lines carry a "What to check" button (`openHelpOn("stuck")`) inside the existing `role="status"` element, so it exists only while the symptom shows. Every finished and paused screen gets a "Before you close this" panel from `renderCloseGuide()` in `renderHandoff()` (Safe to close, Start fresh, Carry on). Tests in `scripts/test-web-console-source.mjs` check the tab order, the callout and rows, and the `renderCloseGuide` call. - **Stuck sessions are explained twice, in Help and on the status line.** `stuck` ("When something looks stuck") is the second tab in `HELP_TABS`; its panel opens with a `help-callout` ("Check this first": Plan2Code often waits for a permission in the terminal, which the page cannot see) and four You see / Likely cause / Do this rows before the diagram. The quiet and Not running status lines carry a "What to check" button (`openHelpOn("stuck")`) inside the existing `role="status"` element, so it exists only while the symptom shows. Every finished and paused screen gets a "Before you close this" panel from `renderCloseGuide()` in `renderHandoff()` (Safe to close, Start fresh, Carry on). Tests in `scripts/test-web-console-source.mjs` check the tab order, the callout and rows, and the `renderCloseGuide` call.
- **Starting ticks are staged by the page, never answered by the server.** A `multi` row with `ticked: true` is seeded into the person's staged answer once (`seedStaged`, marked in `page.local.seeded`); an `answer` on the item would settle the card before anyone saw it, and a staged answer already flows through Send, drafts, the settled record and the reply words.
- **Markdown is rendered to DOM nodes, never to an HTML string** (`public/render.js`), so agent-authored text that quotes a hostile source cannot execute. Only `marked.lexer()` is used. - **Markdown is rendered to DOM nodes, never to an HTML string** (`public/render.js`), so agent-authored text that quotes a hostile source cannot execute. Only `marked.lexer()` is used.
Tests: `npm test` runs, in order, `validate-char-count.js`, `install.js --build-skills`, `parse-check.mjs`, `check-skill-table.mjs`, then one `node --test` over the skill-script tests (`test-skill-scripts.mjs`, `test-script-*.mjs`, `test-git-repo.mjs`), `test-launcher.mjs`, `test-getting-started.mjs` and the web console's `test-web-console-*.mjs`, so they run in parallel, one process each. The console tests are split by area (`-session`, `-lifecycle`, `-logic`, `-server`, `-chat`, `-chat-stress`, `-workspace`, `-subagents`, `-concurrency`, `-source`, `-shape`, `-git`, `-git-board`, `-qa`, `-speed`, `-hardening`, `-embed`, `-handoffs`, `-in-app`, `-loop`, `-notepad`, `-pointers`, `-skills`, `-spec-states`, `-state`, `-tones`), plus the `-page-*` browser suites and the per-game `-activities*` suites. Their shared setup is `scripts/web-console-test-helpers.mjs`: importing it gives the file its own console home (so `workspaces.json`, `subagents.json`, `looks.json` and sessions never collide across files) and registers the `stop --all` cleanup. `-session` and `-lifecycle` each run an ordered chain of tests on one session of their own; everything else opens a session per test. A new test goes in the file for its area, after the tests it depends on. The parse check exists because `node --check` parses a `.js` file as a CommonJS script and has already let a browser-fatal string literal through; it imports each shipped module as a real ES module instead. They live in `scripts/`, not `src/web-console/`, because everything under the latter ships into every skill. Tests: `npm test` runs, in order, `validate-char-count.js`, `install.js --build-skills`, `parse-check.mjs`, `check-skill-table.mjs`, then one `node --test` over the skill-script tests (`test-skill-scripts.mjs`, `test-script-*.mjs`, `test-git-repo.mjs`), `test-launcher.mjs`, `test-getting-started.mjs` and the web console's `test-web-console-*.mjs`, so they run in parallel, one process each. The console tests are split by area (`-session`, `-lifecycle`, `-logic`, `-server`, `-chat`, `-chat-stress`, `-workspace`, `-subagents`, `-concurrency`, `-source`, `-shape`, `-git`, `-git-board`, `-qa`, `-speed`, `-hardening`, `-embed`, `-handoffs`, `-in-app`, `-loop`, `-notepad`, `-pointers`, `-skills`, `-spec-states`, `-state`, `-tones`), plus the `-page-*` browser suites and the per-game `-activities*` suites. Their shared setup is `scripts/web-console-test-helpers.mjs`: importing it gives the file its own console home (so `workspaces.json`, `subagents.json`, `looks.json` and sessions never collide across files) and registers the `stop --all` cleanup. `-session` and `-lifecycle` each run an ordered chain of tests on one session of their own; everything else opens a session per test. A new test goes in the file for its area, after the tests it depends on. The parse check exists because `node --check` parses a `.js` file as a CommonJS script and has already let a browser-fatal string literal through; it imports each shipped module as a real ES module instead. They live in `scripts/`, not `src/web-console/`, because everything under the latter ships into every skill.
@@ -27,15 +27,15 @@ One row per file under `src/web-console/public/` (the games and their sound are
| `public/state.js` | the page's shared state (`page.S` the server's truth, `page.local` what is staged) and the `redraw()` / save hooks every screen calls; defines only | | `public/state.js` | the page's shared state (`page.S` the server's truth, `page.local` what is staged) and the `redraw()` / save hooks every screen calls; defines only |
| `public/uploads.js` | pictures and documents attached to a note: chips, trays, re-encoding, upload, retry, and the page's shared full-screen picture preview (`openPicview`, the `#picview` dialog every thumbnail opens) | | `public/uploads.js` | pictures and documents attached to a note: chips, trays, re-encoding, upload, retry, and the page's shared full-screen picture preview (`openPicview`, the `#picview` dialog every thumbnail opens) |
| `public/screens/ask.js` | the Ask chat, the Subagents tab, and attaching files to notes | | `public/screens/ask.js` | the Ask chat, the Subagents tab, and attaching files to notes |
| `public/screens/cards.js` | question cards: every kind (one builder per kind in `BUILDERS`), the pager, settled and in-flight records. The `lessons` kind's builder is `buildLessons()`: the approval card for noted lessons, one row per waiting item (`lessonRow()`) decided on its own with the words its type takes, the choices kept as a draft (`lessons-<id>`) until Send, or the first ask's three answers when the card carries `firstAsk`; on the dashboard it is drawn in the Lessons to review dialog (`renderLessonsDialog()` in `screens/learning-row.js`) | | `public/screens/cards.js` | question cards: every kind (one builder per kind in `BUILDERS`), the pager, settled and in-flight records. The `lessons` kind's builder is `buildLessons()`: the approval card for noted lessons, one row per waiting item (`lessonRow()`) decided on its own with the words its type takes, the choices kept as a draft (`lessons-<id>`) until Send, or the first ask's three answers when the card carries `firstAsk`; a `suggested` map (row id to one of that row's choices, checked in `lessonsProblems()` in `patches.mjs`) draws a dashed `is-suggested` ring on those buttons without picking them; on the dashboard it is drawn in the Lessons to review dialog (`renderLessonsDialog()` in `screens/learning-row.js`). A `multi` option may carry `ticked: true` (the row starts ticked the first time the card shows, never on a `locked` row) and `tag` (1 to 16 characters, drawn as a neutral `.pill.tag` beside the label and read in the checkbox's accessible name after the `k: text`); on a card with a ticked row, unticking the last box (or pressing a lit preset off) stages `ks: []`, an answer that reads `none`, where other cards stage nothing. |
| `public/screens/cleanup.js` | User Preferences' Cleanup section, on the System tab | | `public/screens/cleanup.js` | User Preferences' Cleanup section, on the System tab |
| `public/screens/core.js` | the core every screen sits inside: connection, the render loop, the page chrome and Send; the only file that imports the screens, and only `app.js` imports it | | `public/screens/core.js` | the core every screen sits inside: connection, the render loop, the page chrome and Send; the only file that imports the screens, and only `app.js` imports it |
| `public/screens/dashboard.js` | the dashboard: cards, the spec picker, handoff chips, delete, the first-open wake-up, and Learning's waiting banner (`learningBanner()`: the line from `learningBannerText()` and a **Review** button sending `__learning` `review`, last of the banners), which places Learning's row through `hooks.renderLearningRow` | | `public/screens/dashboard.js` | the dashboard: cards, the spec picker, handoff chips, delete, the first-open wake-up, and Learning's waiting banner (`learningBanner()`: the line from `learningBannerText()` and a **Review** button sending `__learning` `review`, last of the banners), which places Learning's row through `hooks.renderLearningRow` |
| `public/screens/learning-row.js` | Learning's row on the dashboard (`renderLearningRow(scan, position)`): four states in two places (under the picker while not set up, off or paused; after the last card group while on), Pause for me posting `/learning/pause` with no agent, More, Open the lessons and the Remove confirm, plus `renderLessonsDialog()`, the Lessons to review dialog that draws an open `lessons` card over the menu; the agent-run controls send `__learning` through `hooks.sendLearning` and gray out under `learningBlocked()` | | `public/screens/learning-row.js` | Learning's row on the dashboard (`renderLearningRow(scan, position)`): four states in two places (under the picker while not set up, off or paused; after the last card group while on), Pause for me posting `/learning/pause` with no agent, More, Open the lessons and the Remove confirm, plus `renderLessonsDialog()`, the Lessons to review dialog that draws an open `lessons` card over the menu; the agent-run controls send `__learning` through `hooks.sendLearning` and gray out under `learningBlocked()` |
| `public/screens/loop-setup.js` | the Implementation Loop's setup screen on the dashboard (app only): the fields, their defaults and read-only facts, the Start checks, and the request to the app. The **Strength per phase** field (`strengthField`) is a grid: four headed columns (Match my session, Thrifty, Balanced, Best; level 0 to 3) and one `radiogroup` row per phase left, one radio per column (`#loop-strength-<n>-<word>`, `match` for Match my session; an unmapped word's radio is disabled and its header says "(not mapped)"), the cell's dot (`strengthBars`) over the hidden radio, and the model the pick becomes at the row's end. **Set all to** stays a select (`#loop-strength-all`, blank again after use). `drawStrengthLine(grid)` draws the grid's SVG from the checked nodes' measured positions, never from state: a very light dashed `line.col` per column and a thick square-step `path.step` from each row's node to the next (one path fewer than rows, none under two rows or with the toggle off). It redraws on the window's resize, a `ResizeObserver` on the grid (Preferences' page width), fonts loading and every redraw of the section, and stops once the grid is gone. The colors are the `--lvl-0` to `--lvl-3` tokens (`--lvl-0` is the neutral gray of Match my session); tests wait for the drawn state before reading the line. The page locks while `state.loop.driving` is set (`loopDriving()` in `selectors.js`) until the app posts `loopEnd`; Activities, Notebook, Help and Preferences stay usable. `loopEnd.can` accepts `ask` (`LOOP_CAN` in `patches.mjs`); the app adds it first to every stop that offers `resume`, and the stopped screen's **Ask a question** wakes an ordinary agent on the same session | | `public/screens/loop-setup.js` | the Implementation Loop's setup screen on the dashboard (app only): the fields, their defaults and read-only facts, the Start checks, and the request to the app. The **Strength per phase** field (`strengthField`) is a grid: four headed columns (Match my session, Thrifty, Balanced, Best; level 0 to 3) and one `radiogroup` row per phase left, one radio per column (`#loop-strength-<n>-<word>`, `match` for Match my session; an unmapped word's radio is disabled and its header says "(not mapped)"), the cell's dot (`strengthBars`) over the hidden radio, and the model the pick becomes at the row's end. **Set all to** stays a select (`#loop-strength-all`, blank again after use). **Suggest for me** (`#loop-strength-suggest`, right of it) sends a no-hop `__loopSuggest` (`id`, `spec`, `phases`, the mapped `strengths`) to the dashboard agent and grays the field under `.loop-suggest-overlay` (`.is-suggesting`, `aria-busy`); the agent posts `loopSuggest` (`{ id, spec, picks: [{ n, strength, why }] }`, checked by `loopSuggestProblems` in `patches.mjs`), and the page applies only the answer whose `id` and `spec` match its own request, mapped words only, with each `why` as a `.loop-strength-why` line that a hand change or Set all to clears; `SUGGEST_WAIT_MS` (two minutes) gives the field back with a note when nobody answers. The dashboard skill answers it under "A strength suggestion arrives". `drawStrengthLine(grid)` draws the grid's SVG from the checked nodes' measured positions, never from state: a very light dashed `line.col` per column and a thick square-step `path.step` from each row's node to the next (one path fewer than rows, none under two rows or with the toggle off). It redraws on the window's resize, a `ResizeObserver` on the grid (Preferences' page width), fonts loading and every redraw of the section, and stops once the grid is gone. The colors are the `--lvl-0` to `--lvl-3` tokens (`--lvl-0` is the neutral gray of Match my session); tests wait for the drawn state before reading the line. The page locks while `state.loop.driving` is set (`loopDriving()` in `selectors.js`) until the app posts `loopEnd`; Activities, Notebook, Help and Preferences stay usable. `loopEnd.can` accepts `ask` (`LOOP_CAN` in `patches.mjs`); the app adds it first to every stop that offers `resume`, and the stopped screen's **Ask a question** wakes an ordinary agent on the same session |
| `public/screens/docs.js` | documents: tabs, blocks, print and download, and the brief button | | `public/screens/docs.js` | documents: tabs, blocks, print and download, and the brief button |
| `public/screens/ending.js` | how a session ends: the finished screen, its offers, Stop and the way home; a Diagnose finish whose `doc` is saved shows that file whole as a Bug report box with Copy report (the raw Markdown), above Next step | | `public/screens/ending.js` | how a session ends: the finished screen, its offers, Stop and the way home; a Diagnose finish whose `doc` is saved shows that file whole as a Bug report box with Copy report (the raw Markdown), above Next step |
| `public/screens/git-host.js` | hosts the git board: tabs, panels and what each click sends | | `public/screens/git-host.js` | hosts the git board: the tools fold-out (`board.tools`, saved with the board), tabs, panels and what each click sends |
| `public/screens/help-dialog.js` | the Help dialog and the first-run Welcome (named so it is never confused with the pure help.js). Help reads right in both modes: a phrase that differs under the desktop app carries its app wording in `data-app` (swapped in by `renderAppWording()`), and a paragraph that differs is a `.for-browser` / `.for-app` sibling pair, switched by `:root.in-app` (set in `core.js` from `page.inApp`, rule in `help.css`). The older `render*Help()` functions patch a few ids the same way. `scripts/test-web-console-page-help.mjs` sweeps every topic's visible text in each mode for the other mode's wording | | `public/screens/help-dialog.js` | the Help dialog and the first-run Welcome (named so it is never confused with the pure help.js). Help reads right in both modes: a phrase that differs under the desktop app carries its app wording in `data-app` (swapped in by `renderAppWording()`), and a paragraph that differs is a `.for-browser` / `.for-app` sibling pair, switched by `:root.in-app` (set in `core.js` from `page.inApp`, rule in `help.css`). The older `render*Help()` functions patch a few ids the same way. `scripts/test-web-console-page-help.mjs` sweeps every topic's visible text in each mode for the other mode's wording |
| `public/screens/looks.js` | User Preferences: the look and sound controls, which save as they change | | `public/screens/looks.js` | User Preferences: the look and sound controls, which save as they change |
| `public/screens/agents-view.js` | the agents view's mount, state and server calls, serving both User Preferences' Agents & models tab and the setup page. Preferences draws a roster of agent cards with the picked agent's form in a side drawer (`data-av="drawer"`, hidden while no form is open, the roster `inert` behind it) and the Add agent chooser (`data-av="chooser"`); the setup page keeps a master-detail split, the pickable list on the left and the picked entry's state (or the same form) in the right pane. Picking a card or row is the navigation; a dirty form asks the dialog's unsaved prompt first. Each form edits a draft; Save sends the saved list with only that draft swapped in (`POST /models` or `POST /agents`), Discard drops it. `hasUnsaved`, `saveOpen` and `discardOpen` feed the dialog's unsaved prompt. `mountAgentsView(container, {mode, forCli, onStart})` hands its renderers one `ctx` (state plus callbacks); `mode: "prefs"` draws the agent cards with Found / Not found on PATH badges and the model each strength uses, `openChooser` / `startNew(template)` (the starter templates are an opt-in there, not a list section) and `closeDrawer` (Esc, the scrim and Close go through it, so a dirty draft asks first), `mode: "setup"` draws the pick list (found / outside-PATH / missing states, install lines, Use it from here, templates, Start) inside a caller-supplied container | | `public/screens/agents-view.js` | the agents view's mount, state and server calls, serving both User Preferences' Agents & models tab and the setup page. Preferences draws a roster of agent cards with the picked agent's form in a side drawer (`data-av="drawer"`, hidden while no form is open, the roster `inert` behind it) and the Add agent chooser (`data-av="chooser"`); the setup page keeps a master-detail split, the pickable list on the left and the picked entry's state (or the same form) in the right pane. Picking a card or row is the navigation; a dirty form asks the dialog's unsaved prompt first. Each form edits a draft; Save sends the saved list with only that draft swapped in (`POST /models` or `POST /agents`), Discard drops it. `hasUnsaved`, `saveOpen` and `discardOpen` feed the dialog's unsaved prompt. `mountAgentsView(container, {mode, forCli, onStart})` hands its renderers one `ctx` (state plus callbacks); `mode: "prefs"` draws the agent cards with Found / Not found on PATH badges and the model each strength uses, `openChooser` / `startNew(template)` (the starter templates are an opt-in there, not a list section) and `closeDrawer` (Esc, the scrim and Close go through it, so a dirty draft asks first), `mode: "setup"` draws the pick list (found / outside-PATH / missing states, install lines, Use it from here, templates, Start) inside a caller-supplied container |
@@ -46,7 +46,7 @@ One row per file under `src/web-console/public/` (the games and their sound are
| `public/screens/agents/agents-strengths.js` | the strengths panel of an agent's form: `strengthsPanel(ctx, agentId, draft, { models, hasEffort })` returns the In the loop box (the model each of Thrifty, Balanced and Best resolves to, an effort select for Claude and Codex, Reset or a "default" tag) and `pills(id, label)`, the three toggle buttons each model row carries (one pressed per word; tapping the pick again clears it only where nothing ships for the word). Changed rows only are kept in `ctx.strengthDrafts` for the form's Save; `wordChip` is the colored word the cards use too | | `public/screens/agents/agents-strengths.js` | the strengths panel of an agent's form: `strengthsPanel(ctx, agentId, draft, { models, hasEffort })` returns the In the loop box (the model each of Thrifty, Balanced and Best resolves to, an effort select for Claude and Codex, Reset or a "default" tag) and `pills(id, label)`, the three toggle buttons each model row carries (one pressed per word; tapping the pick again clears it only where nothing ships for the word). Changed rows only are kept in `ctx.strengthDrafts` for the form's Save; `wordChip` is the colored word the cards use too |
| `public/strengths.js` | the loop's strength rule, shared by the page and the server: `resolveStrengths` and `nextStrength`, held to `scripts/fixtures/strength-cases.json` (the Rust twin is in `models.rs`) | | `public/strengths.js` | the loop's strength rule, shared by the page and the server: `resolveStrengths` and `nextStrength`, held to `scripts/fixtures/strength-cases.json` (the Rust twin is in `models.rs`) |
| `public/screens/setup.js` | the agent-less setup screen (`workflow === "setup"`, opened by `plan2code` or the app when no agent can run): the "No agent yet" headline, Planny's setup pose, the agent list from `mountAgentsView` in setup mode, Check again, and the "Starting <Label>..." pane after a Start send (`{i:"__start"}` via `/submit`). `setupMoved(url)` disarms the 2-minute no-page notice once the `move` event lands | | `public/screens/setup.js` | the agent-less setup screen (`workflow === "setup"`, opened by `plan2code` or the app when no agent can run): the "No agent yet" headline, Planny's setup pose, the agent list from `mountAgentsView` in setup mode, Check again, and the "Starting <Label>..." pane after a Start send (`{i:"__start"}` via `/submit`). `setupMoved(url)` disarms the 2-minute no-page notice once the `move` event lands |
| `public/screens/prefs-dialog.js` | User Preferences as a dialog: its four tabs (wired by `tabs.js` from `PREFS_TABS`), `openPrefs(tab)` (the one way in, loading Agents & models each time), the fading Saved mark beside a fieldset (`markSaved`), Back to default for the tab on screen, and `confirmUnsaved()`, the in-dialog Save / Discard / Keep editing prompt before Close, Esc, a backdrop click, a tab switch or picking another agent leaves an unsaved agent edit. Other screens reach it through `hooks` | | `public/screens/prefs-dialog.js` | User Preferences as a dialog: its four tabs (wired by `tabs.js` from `PREFS_TABS`), `openPrefs(tab)` (the one way in, loading Agents & models each time), the fading Saved mark beside a fieldset (`markSaved`), Reset this tab for the tab on screen, and `confirmUnsaved()`, the in-dialog Keep editing / Discard / Save prompt (focus on Keep editing) before Close, Esc, a backdrop click, a tab switch or picking another agent leaves an unsaved agent edit. Other screens reach it through `hooks` |
| `public/screens/starting.js` | the launching, starting and waiting screens, with Planny's poses | | `public/screens/starting.js` | the launching, starting and waiting screens, with Planny's poses |
| `public/screens/workspace.js` | the read-only Workspace of extra folders, and @mentions | | `public/screens/workspace.js` | the read-only Workspace of extra folders, and @mentions |
| `public/styles/ask.css` | The Ask pane and its Quick question chat | | `public/styles/ask.css` | The Ask pane and its Quick question chat |
@@ -66,18 +66,18 @@ One row per file under `src/web-console/public/` (the games and their sound are
| `public/styles/responsive.css` | Print, then the narrow-window rules: last, so its overrides come after everything they override | | `public/styles/responsive.css` | Print, then the narrow-window rules: last, so its overrides come after everything they override |
| `public/styles/shell.css` | The page shell: banner, top bar and meter, layout, sidebar, aside, footer, waiting and arrival | | `public/styles/shell.css` | The page shell: banner, top bar and meter, layout, sidebar, aside, footer, waiting and arrival |
| `public/styles/tokens.css` | Colors, type, sizes and the light and dark themes: the variables every other file reads | | `public/styles/tokens.css` | Colors, type, sizes and the light and dark themes: the variables every other file reads |
| `public/help.js` | the Help dialog's PURE rules: `HELP_TABS` (22 tabs: ids, order, labels, diagram flags; every tab uses the chosen highlight color; Implementation Loop sits right after Watching a build, The git board right after it, and Activities right after Ask a quick question), `helpTabFor()` (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, the Subagents tab → Helpers (subagents), a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a git session → The git board, a build, else What this page is) and `helpKeyTarget()` (roving arrow keys, Home, End, wrapping; a re-export of `tabs.js`'s `tabKeyTarget`). No module-scope DOM, so `node --test` covers it | | `public/help.js` | the Help dialog's PURE rules: `HELP_TABS` (23 tabs: ids, order, labels, diagram flags; `HELP_GROUPS` and `helpGroupStart()` name the four group headings, Start here, Working in a session, Tools and Reference, each a run of neighbors so grouping never moves a tab; every tab uses the chosen highlight color; Implementation Loop sits right after Watching a build, The git board right after it, and Activities right after Ask a quick question), `helpTabFor()` (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, the Subagents tab → Subagents, a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a git session → The git board, a build, else What this page is) and `helpKeyTarget()` (roving arrow keys, Home, End, wrapping; a re-export of `tabs.js`'s `tabKeyTarget`). No module-scope DOM, so `node --test` covers it |
| `public/tabs.js` | the WAI-ARIA tabs shared by Help and User Preferences: `wireTabs()` (buttons and panel links, roving tabindex, automatic activation, `aria-orientation` switching at 720 px, an optional `beforeSelect` guard) and the pure `tabKeyTarget()` | | `public/tabs.js` | the WAI-ARIA tabs shared by Help and User Preferences: `wireTabs()` (buttons and panel links, roving tabindex, automatic activation, `aria-orientation` switching at 720 px, an optional `beforeSelect` guard) and the pure `tabKeyTarget()` |
| `public/prefs.js` | User Preferences' PURE rules: `PREFS_TABS` (Appearance, Agents & models, System, Sounds & activities, with hints and the sections each holds), `prefsOpenTab()` and `prefsResetScope()` (the looks keys Back to default resets per tab, or null) | | `public/prefs.js` | User Preferences' PURE rules: `PREFS_TABS` (Appearance, Agents & models, System, Sounds & activities, with hints and the sections each holds), `prefsOpenTab()` and `prefsResetScope()` (the looks keys Reset this tab resets per tab, or null) |
| `public/git-board.js` | PURE, one import (`pr-url.js`): the git board's rules from a `state.git` snapshot: branch order and the Remote only fold at `REMOTE_FOLD` 50, whether a new branch name is free, which buttons show and are enabled, whether the board still waits on the agent (`boardAwaiting()`: from a click until the agent's next post, not just until `wait` collects it), the plain sentence each click sends as `reply`, the "Last refreshed" line, which files start ticked in the commit dialog, the pull-request link, and the current branch's page on its host (`boardBranchLink()`, null until the branch is pushed under its own name); the next step (ten rules, `nextStep()`), the tab that owns it, per-tab badges (`tabBadges()`), the busy mode and per-control gate (`busyMode()`, `controlAllowed()`), the tab to show (`pickTab()`), and the create-panel sources and clean-up groups. `app.js` only renders what it says | | `public/git-board.js` | PURE, one import (`pr-url.js`): the git board's rules from a `state.git` snapshot: branch order and the Remote only fold at `REMOTE_FOLD` 50, whether a new branch name is free, which buttons show and are enabled, whether the board still waits on the agent (`boardAwaiting()`: from a click until the agent's next post, not just until `wait` collects it), the plain sentence each click sends as `reply`, the "Last refreshed" line, which files start ticked in the commit dialog, the pull-request link, and the current branch's page on its host (`boardBranchLink()`, null until the branch is pushed under its own name); the next step (ten rules, `nextStep()`), the tab that owns it, where it sits on the Save, Share, Review, Tidy path (`PATH_STOPS`, `boardPath()`), whether the task card carries the commit table (`cardShowsFiles()`), per-tab badges (`tabBadges()`), the busy mode and per-control gate (`busyMode()`, `controlAllowed()`), the tab to show (`pickTab()`), and the create-panel sources and clean-up groups. `app.js` only renders what it says |
| `public/git-board-view.js` | No DOM access of its own: `drawGitBoard(ctx)` draws the tabbed board (header, whose branch name is a link to the branch on its host once pushed, tab strip with Done with git, the card slot, step strip, Changes / Branches / Sync) from the helpers it is handed (`el`, `md`, `copyButton`), every control through one gate; `screens/git-host.js` hosts it, and `scripts/test-web-console-git-board.mjs` drives it with a recording fake `el` | | `public/git-board-view.js` | No DOM access of its own: `drawGitBoard(ctx)` draws the guided board (header with Done with git, whose branch name is a link to the branch on its host once pushed; the path; the card slot; the task card, which holds the commit table on a Save stop and the operation mid-rebase; the **All branches and tools** fold-out with the Changes / Branches / Sync tabs) from the helpers it is handed (`el`, `md`, `copyButton`), every control through one gate; `screens/git-host.js` hosts it, and `scripts/test-web-console-git-board.mjs` drives it with a recording fake `el` |
| `public/pr-url.js` | PURE, no imports: `prUrl()`, the "open a pull request" link for the GitHub, GitLab, Azure DevOps and Bitbucket shapes (`null` for an unknown kind, no web address, or a non-https result), and `branchUrl()`, the branch's own page on the same four hosts under the same rules. `git-repo.mjs` re-exports `prUrl()`, and the board's base picker rebuilds the link in the browser with the same code | | `public/pr-url.js` | PURE, no imports: `prUrl()`, the "open a pull request" link for the GitHub, GitLab, Azure DevOps and Bitbucket shapes (`null` for an unknown kind, no web address, or a non-https result), and `branchUrl()`, the branch's own page on the same four hosts under the same rules. `git-repo.mjs` re-exports `prUrl()`, and the board's base picker rebuilds the link in the browser with the same code |
| `public/workspace.js` | PURE, no imports: the Workspace's name rules (`nameProblem()`, `NAME_MAX`, `defaultName()`, `freeName()` for the `-2` suggestion), the footer label and its width tiers (`footerLabel()`, `FOOTER_TIERS`) and `changeLine()`, the `Workspace: …` reply line an agent is handed per change. Imported by the server, `cmd-chat.mjs`, `cmd-post-wait.mjs`, `workspace.mjs` and the page | | `public/workspace.js` | PURE, no imports: the Workspace's name rules (`nameProblem()`, `NAME_MAX`, `defaultName()`, `freeName()` for the `-2` suggestion), the footer label and its width tiers (`footerLabel()`, `FOOTER_TIERS`) and `changeLine()`, the `Workspace: …` reply line an agent is handed per change. Imported by the server, `cmd-chat.mjs`, `cmd-post-wait.mjs`, `workspace.mjs` and the page |
| `public/meter.js` | PURE, imports only `skills.js`: the session meter. `WEIGHTS` (the events that are not a skill's own launch, merged with each skill's `weight` from `skills.js`; its keys are also `RUN_EVENTS`, the `run` events `post` accepts), `LAUNCH_COUNTED` (workflows whose launch itself scores), the built-phase sizing (`TASK_EVENTS`, the keys of `TASK_BONUS`: `implement-phase` +0 and `implement-review-phase` +1; `isTaskCount()` accepts a whole `tasks` from 1 to `MAX_TASKS` 999; `runPoints()` scores such a run `ceil(tasks / TASKS_PER_POINT)` (3) plus its bonus, and any other run its `WEIGHTS` value), `ANSWERS_PER_POINT` 2 (`answer` entries score per skill run, `floor(count / 2)`), `breakdownFrom()` (the click-the-ring list: one row per scoring entry plus one answers row per skill run), `pointsFrom()` (the count, its sum, folded from `ledger.ndjson` and deduplicated by id, never stored), `levelFor()` with `YELLOW_AT` 5 / `RED_AT` 10, `ringFraction()` (full at `RING_FULL` 15), `WORDS`, `tooltipFor()`, `RED_BANNER` and `meterView()` | | `public/meter.js` | PURE, imports only `skills.js`: the session meter. `WEIGHTS` (the events that are not a skill's own launch, merged with each skill's `weight` from `skills.js`; its keys are also `RUN_EVENTS`, the `run` events `post` accepts), `LAUNCH_COUNTED` (workflows whose launch itself scores), the built-phase sizing (`TASK_EVENTS`, the keys of `TASK_BONUS`: `implement-phase` +0 and `implement-review-phase` +1; `isTaskCount()` accepts a whole `tasks` from 1 to `MAX_TASKS` 999; `runPoints()` scores such a run `ceil(tasks / TASKS_PER_POINT)` (3) plus its bonus, and any other run its `WEIGHTS` value), `ANSWERS_PER_POINT` 2 (`answer` entries score per skill run, `floor(count / 2)`), `breakdownFrom()` (the click-the-ring list: one row per scoring entry plus one answers row per skill run), `pointsFrom()` (the count, its sum, folded from `ledger.ndjson` and deduplicated by id, never stored), `levelFor()` with `YELLOW_AT` 5 / `RED_AT` 10, `ringFraction()` (full at `RING_FULL` 15), `WORDS`, `tooltipFor()`, `RED_BANNER` and `meterView()` |
| `public/mentions.js` | PURE, no imports: the `@name` popover's logic — `mentionAt()` finds an `@partial` at the caret, `matchNames()` filters the workspace names, `applyMention()` splices a pick in and returns the new caret. Used by the Ask box, notes and text answers | | `public/mentions.js` | PURE, no imports: the `@name` popover's logic — `mentionAt()` finds an `@partial` at the caret, `matchNames()` filters the workspace names, `applyMention()` splices a pick in and returns the new caret. Used by the Ask box, notes and text answers |
| `public/favicon.js` | The tab icon's status bar. `faviconState({ mood, spin })` (PURE) maps the call `renderStatus()` makes for Planny's line to `busy` (the spinning ring), `ready` (`point`), `attention` (`adrift`, `gone`, or `work` without the ring — the stale line) or `plain` (`done`, `happy`); a finished screen gets no special case, so one still offering a press points and lights `ready` (the desktop app's taskbar dot follows), a stranded press is `attention`, and only all done or paused is `plain`; `faviconSvg()` is `FAVICON_BODY` (kept equal to `favicon.svg` by a test) plus a bar along the bottom edge in the `FAVICON_COLORS` color (busy dashed on a white strip, so the states differ by pattern; the rest solid); `setFavicon()` swaps both `<link rel=icon>` hrefs only on a change — the SVG as a data URL, the PNG link drawn through a canvas. Called from `say()` in `renderStatus()`, which runs every second | | `public/favicon.js` | The tab icon's status bar. `faviconState({ mood, spin })` (PURE) maps the call `renderStatus()` makes for Planny's line to `busy` (the spinning ring), `ready` (`point`), `attention` (`adrift`, `gone`, or `work` without the ring — the stale line) or `plain` (`done`, `happy`); a finished screen gets no special case, so one still offering a press points and lights `ready` (the desktop app's taskbar dot follows), a stranded press is `attention`, and only all done or paused is `plain`; `faviconSvg()` is `FAVICON_BODY` (kept equal to `favicon.svg` by a test) plus a bar along the bottom edge in the `FAVICON_COLORS` color (busy dashed on a white strip, so the states differ by pattern; the rest solid); `setFavicon()` swaps both `<link rel=icon>` hrefs only on a change — the SVG as a data URL, the PNG link drawn through a canvas. Called from `say()` in `renderStatus()`, which runs every second |
| `public/continue-button.js` | The one control that wakes a quiet agent. `continueButton(label, cls)` is a button asking the app for `agent-continue` (held off 4 s after a press); `reconnectOffer(cls)` is that button labeled **Reconnect to agent** under the app and, in a browser, a line telling the person to type `continue` in their terminal. Used by the status line (`screens/core.js`: the dashboard's quiet, launch-saved and way-home-saved lines), the Ask tab (`screens/ask.js`, left of Send while the red no-agent line shows) and the saved-and-waiting launch screen (`screens/starting.js`, app only; a browser reads the hint). | | `public/continue-button.js` | The one control that wakes a quiet agent. `continueButton(label, cls)` is a button asking the app for `agent-continue` (held off 4 s after a press); `reconnectOffer(cls)` is that button labeled **Reconnect to agent** under the app and, in a browser, a line telling the person to type `continue` in their terminal. Used by the status line (`screens/core.js`: the dashboard's quiet, launch-saved and way-home-saved lines), the Ask tab (`screens/ask.js`, left of Send while the red no-agent line shows) and the saved-and-waiting launch screen (`screens/starting.js`, app only; a browser reads the hint). |
| `public/app-bridge.js` | The messages the page posts to the desktop app that frames it. `framed()` is true inside a frame; `tellApp(kind, extra)` posts `{ plan2code: kind }`, a named request with no free text: `looks` (the highlight's dark shades, from `applyLooks()`, for the app bar's buttons), `agent-continue` (the in-app **continue** button on the Not running line: the app types the keystrokes `continueKeys()` in `plan2code-app/ui/meter.js` names into the agent's terminal, `continue` and Enter, then under Claude Code its send-now chord ctrl+x ctrl+s, so a word queued behind a stuck turn is delivered), `terminal-open` (the in-app **terminal** button, shown in place of the word in every What to check line while the app's terminal panel is collapsed: the app presses the panel's own Collapse/View button, and only when collapsed; the app tells the page the panel's state with `terminal-state` `{ collapsed }` on the page's `console-ready` and on every change, heard through `onAppMessage` into `page.terminalCollapsed`), `new-session` (the meter popover's New Session: the app presses its own bar button, confirm and all) and `activities-full` (`{ on }`, an Activities game going in or out of full screen: the app lays the console's frame over its bar and terminal and puts the window in full screen, and out of it only if it put it there; `taskbarSwitch()` checks the boolean, and the window permissions are in `capabilities/default.json`). Nothing outside a frame | | `public/app-bridge.js` | The messages the page posts to the desktop app that frames it. `framed()` is true inside a frame; `tellApp(kind, extra)` posts `{ plan2code: kind }`, a named request with no free text: `looks` (from `applyLooks()`: the resolved `theme`, `"light"` or `"dark"`, and both highlight shade sets, `light` and `dark`, four `#rrggbb` each, plus `accent`, the dark set, for a shell that predates the theme; the app validates it with `looksFromMessage()` in `plan2code-app/ui/meter.js`, sets `data-theme` and the accent properties on its root, themes its terminal and the OS title bar, and keeps both for the next launch, which `ui/theme-early.js` paints before the first frame; the page also sends it again when the system theme flips under a System choice), `agent-continue` (the in-app **continue** button on the Not running line: the app types the keystrokes `continueKeys()` in `plan2code-app/ui/meter.js` names into the agent's terminal, `continue` and Enter, then under Claude Code its send-now chord ctrl+x ctrl+s, so a word queued behind a stuck turn is delivered), `terminal-open` (the in-app **terminal** button, shown in place of the word in every What to check line while the app's terminal panel is collapsed: the app presses the panel's own Collapse/View button, and only when collapsed; the app tells the page the panel's state with `terminal-state` `{ collapsed }` on the page's `console-ready` and on every change, heard through `onAppMessage` into `page.terminalCollapsed`), `new-session` (the meter popover's New Session: the app presses its own bar button, confirm and all) and `activities-full` (`{ on }`, an Activities game going in or out of full screen: the app lays the console's frame over its bar and terminal and puts the window in full screen, and out of it only if it put it there; `taskbarSwitch()` checks the boolean, and the window permissions are in `capabilities/default.json`). Nothing outside a frame |
| `public/subagents.js` | PURE, no imports: the Subagents switch. `SUBAGENT_WORKFLOWS` / `offered()` (the opt-in table, one entry per non-null `subagents` field in `skills.js`, each with its default instruction), `cleanSetting()` (`{ on, instruction, max, strength }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20, `strength` not one of `STRENGTHS`; `strength` is `balanced`, `thrifty`, `best` or `session`, missing reads as `balanced`, saved per project and skill in each `subagents.json` entry and sent as a `Helper strength:` line in the "on" block), `FRAME_LINES`, `blockFor(setting, told)` (the `Subagents:` lines and `subagents` field an agent is owed, given the session setting and its cursor; never says "off" to an agent not told "on"), `checkHelper()` / `checkHelpers()` (the `helpers` house rule) and the page's view rules `showSwitch()`, `switchLabel()`, `helperRows()`, `showTab()`, `CHECKIN_LINE`. Imported by the server, the `cmd-*.mjs` files, `patches.mjs`, `settings.mjs`, the page and the tests; in `SERVABLE` and preloaded | | `public/subagents.js` | PURE, no imports: the Subagents switch. `SUBAGENT_WORKFLOWS` / `offered()` (the opt-in table, one entry per non-null `subagents` field in `skills.js`, each with its default instruction), `cleanSetting()` (`{ on, instruction, max, strength }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20, `strength` not one of `STRENGTHS`; `strength` is `balanced`, `thrifty`, `best` or `session`, missing reads as `balanced`, saved per project and skill in each `subagents.json` entry and sent as a `Helper strength:` line in the "on" block), `FRAME_LINES`, `blockFor(setting, told)` (the `Subagents:` lines and `subagents` field an agent is owed, given the session setting and its cursor; never says "off" to an agent not told "on"), `checkHelper()` / `checkHelpers()` (the `helpers` house rule) and the page's view rules `showSwitch()`, `switchLabel()`, `helperRows()`, `showTab()`, `CHECKIN_LINE`. Imported by the server, the `cmd-*.mjs` files, `patches.mjs`, `settings.mjs`, the page and the tests; in `SERVABLE` and preloaded |
| `public/notepad.js` | PURE, no imports: the Notebook's rules. `SAVE_DEBOUNCE_MS` 800, `RETRY_STEPS_MS` (1 s up to 30 s), `NOTE_MAX_BYTES` / `NOTEPAD_MAX_IMAGES` / `TAB_NAME_MAX` / `NOTEPAD_MAX_TABS` / `IMAGE_ID_RE` / `TAB_ID_RE` (kept equal to `notepads.mjs` by a test), `noteBytes()`, the save-state reducer `nextSave(state, event)` from `SAVE_START` (states `idle`, `pending`, `saving`, `saved`, `failed`, `too-long`; it returns the timer to arm), `saveStatus()` (the status line's words), `unsaved()` (what `beforeunload` asks on), `keepsText()` (unsaved or too long: a reopen never replaces the editor's text then), `tabSwitch()` (whether leaving a tab must save it first), `NOT_LOADED`, `EDITOR_NOT_LOADED`, `errorSentence()` (one sentence per `/notepad` refusal, else a lost connection), the tab rules `cleanTabName()`, `nameTaken()`, `tabNameProblem()`, `moveTab()`, `dropTab()` and the two-confirm delete `nextDelete()` / `DELETE_STAGES`, and `step()` (wrapping through the pictures) | | `public/notepad.js` | PURE, no imports: the Notebook's rules. `SAVE_DEBOUNCE_MS` 800, `RETRY_STEPS_MS` (1 s up to 30 s), `NOTE_MAX_BYTES` / `NOTEPAD_MAX_IMAGES` / `TAB_NAME_MAX` / `NOTEPAD_MAX_TABS` / `IMAGE_ID_RE` / `TAB_ID_RE` (kept equal to `notepads.mjs` by a test), `noteBytes()`, the save-state reducer `nextSave(state, event)` from `SAVE_START` (states `idle`, `pending`, `saving`, `saved`, `failed`, `too-long`; it returns the timer to arm), `saveStatus()` (the status line's words), `unsaved()` (what `beforeunload` asks on), `keepsText()` (unsaved or too long: a reopen never replaces the editor's text then), `tabSwitch()` (whether leaving a tab must save it first), `NOT_LOADED`, `EDITOR_NOT_LOADED`, `errorSentence()` (one sentence per `/notepad` refusal, else a lost connection), the tab rules `cleanTabName()`, `nameTaken()`, `tabNameProblem()`, `moveTab()`, `dropTab()` and the two-confirm delete `nextDelete()` / `DELETE_STAGES`, and `step()` (wrapping through the pictures) |
| `public/screens/notepad.js` | the Notebook: `#btn-notepad` in the top bar on every screen (disabled while the server is gone, `renderNotepadButton()` in the render pass), `#notepad-modal`, the one CodeMirror editor (made on first open by a dynamic import of `notepad-editor.js`), the page's view of the notepad as `{ tabs, activeId }`, the name form (New tab and Rename, never `window.prompt`), the in-modal two-step delete, and autosave through `nextSave()` to `POST /notepad/text?tab=<id>`, flushed on close, when the page is hidden and before a switch. The editor stays read-only until the first read lands, so nothing typed into an empty editor is saved over a note. **Every save and every picture is bound to the tab it was made in**: `saveTab` is fixed when the change is made, a picture entry carries its `tab`, and a switch waits for the save (`settled()`), stays put with "Not saved yet, so staying on this tab." when it cannot, and drops a deleted tab's unsaved text without sending it | | `public/screens/notepad.js` | the Notebook: `#btn-notepad` in the top bar on every screen (disabled while the server is gone, `renderNotepadButton()` in the render pass), `#notepad-modal`, the one CodeMirror editor (made on first open by a dynamic import of `notepad-editor.js`), the page's view of the notepad as `{ tabs, activeId }`, the name form (New tab and Rename, never `window.prompt`), the in-modal two-step delete, and autosave through `nextSave()` to `POST /notepad/text?tab=<id>`, flushed on close, when the page is hidden and before a switch. The editor stays read-only until the first read lands, so nothing typed into an empty editor is saved over a note. **Every save and every picture is bound to the tab it was made in**: `saveTab` is fixed when the change is made, a picture entry carries its `tab`, and a switch waits for the save (`settled()`), stays put with "Not saved yet, so staying on this tab." when it cannot, and drops a deleted tab's unsaved text without sending it |
@@ -87,7 +87,7 @@ One row per file under `src/web-console/public/` (the games and their sound are
| `public/vendor/codemirror.esm.js` | CodeMirror 6 (state, view, language, commands, lang-markdown, MIT), bundled into one minified ES module by `scripts/vendor-codemirror.mjs` (sha256 `4ff96d58fc1a5497eb933426bd2d160d2fb0cf490de8bb9302c304096c71c1d4`, the six top-level versions in the script and the file's header comment, everything they pull in pinned by `scripts/vendor-codemirror-lock.json` and installed with `npm ci`, so the same lock gives the same bytes). Never edited by hand: change a version in the script and run `node scripts/vendor-codemirror.mjs --update-lock` (needs npm and network; the packages install in a temp folder, never in the repo), or without the flag to rebuild from the lock | | `public/vendor/codemirror.esm.js` | CodeMirror 6 (state, view, language, commands, lang-markdown, MIT), bundled into one minified ES module by `scripts/vendor-codemirror.mjs` (sha256 `4ff96d58fc1a5497eb933426bd2d160d2fb0cf490de8bb9302c304096c71c1d4`, the six top-level versions in the script and the file's header comment, everything they pull in pinned by `scripts/vendor-codemirror-lock.json` and installed with `npm ci`, so the same lock gives the same bytes). Never edited by hand: change a version in the script and run `node scripts/vendor-codemirror.mjs --update-lock` (needs npm and network; the packages install in a temp folder, never in the repo), or without the flag to rebuild from the lock |
| `public/styles/notepad.css` | the notebook's own rules: the top bar button, the dialog, the tab bar and its tools, the name form, the delete question, the empty state and the pictures. The editor's look is `notepad-editor.css`, inside its shadow root | | `public/styles/notepad.css` | the notebook's own rules: the top bar button, the dialog, the tab bar and its tools, the name form, the delete question, the empty state and the pictures. The editor's look is `notepad-editor.css`, inside its shadow root |
| `public/chat.js` | the Quick question chat's PURE rules, shared by the server and the page: `CHAT_LIMIT` / `CHAT_MAX_CHARS` / `CHAT_MAX_ATTACHMENTS` (the combined image + document cap; `CHAT_MAX_IMAGES` is kept as an alias of it), `chatOffline()` (the server's `409 offline` guard), and the page's view model (`chatView`, `sendState`, `nextAbout`, `contextOptions`, `unreadDot` / `shouldChime`). Ask context is the `{ history, about }` model: `nextAbout()` records the last 3 places visited in `history` and sets `about` only when the person picks one from **+ Add context** (`contextOptions()` lists that history plus *This spec*); dropping it or a successful send clears it, so the page never attaches context on its own. Imports only `answers.js`, no module-scope DOM, so `node --test` covers it | | `public/chat.js` | the Quick question chat's PURE rules, shared by the server and the page: `CHAT_LIMIT` / `CHAT_MAX_CHARS` / `CHAT_MAX_ATTACHMENTS` (the combined image + document cap; `CHAT_MAX_IMAGES` is kept as an alias of it), `chatOffline()` (the server's `409 offline` guard), and the page's view model (`chatView`, `sendState`, `nextAbout`, `contextOptions`, `unreadDot` / `shouldChime`). Ask context is the `{ history, about }` model: `nextAbout()` records the last 3 places visited in `history` and sets `about` only when the person picks one from **+ Add context** (`contextOptions()` lists that history plus *This spec*); dropping it or a successful send clears it, so the page never attaches context on its own. Imports only `answers.js`, no module-scope DOM, so `node --test` covers it |
| `public/starters.js` | PURE, no imports: the Role list (`ROLES`, `ROLE_NOT_SET`, `normalizeRole()`, `needsRoleNudge()`: the dashboard banner shows until `looks.json` carries any `role`), the 19 starter templates (Markdown `## heading` sections, shape pinned by a test) and their per-role orders (`TEMPLATES`, `TEMPLATE_ORDERS`, `templatesFor()`, `templateSwap()` for the replace prompt), and the Ask starter sets (`STARTER_SETS`, `STARTER_SET_FOR`, `startersFor()`). Imported by the page's looks and screens and by the tests; in `SERVABLE`, preloaded by `index.html` and parse-checked. The page owns the wording; a skill only flags its fresh-idea `text` card with `"templates": "idea"` | | `public/starters.js` | PURE, no imports: the Role list (`ROLES`, `ROLE_NOT_SET`, `normalizeRole()`, `needsRoleNudge()`: until `looks.json` carries any `role`, the dashboard shows the quiet "Two optional extras" line, held back until the first skill launch sets `looks.skillLaunched`), the 19 starter templates (Markdown `## heading` sections, shape pinned by a test) and their per-role orders (`TEMPLATES`, `TEMPLATE_ORDERS`, `templatesFor()`, `templateSwap()` for the replace prompt), and the Ask starter sets (`STARTER_SETS`, `STARTER_SET_FOR`, `startersFor()`). Imported by the page's looks and screens and by the tests; in `SERVABLE`, preloaded by `index.html` and parse-checked. The page owns the wording; a skill only flags its fresh-idea `text` card with `"templates": "idea"` |
| `public/answers.js` | the page's PURE answer-shaping logic (what an answer reads as, what a placeholder offers, whether a send carries an answer at all). Kept out of the page's entry because `app.js` cannot be imported outside a browser, so anything left in it is untestable. The `scripts/test-web-console-*.mjs` tests import it directly. Learning's share: the `lessons` card's words and answer (`LESSON_KEEP_WORD`, `lessonEditField()`, `lessonLines()`, and `lessonsReply()`, which `tokenFor()` in `screens/core.js` uses: a line per decision plus one `Decisions:` line in the shape `lessons.mjs decide` takes), `LEARNING_ACTIONS` / `learningAction()` / `learningReply()` (the `__learning` send) and `learningBannerText()` (the waiting banner's line, or "" when no lesson is waiting or Learning is off or paused) | | `public/answers.js` | the page's PURE answer-shaping logic (what an answer reads as, what a placeholder offers, whether a send carries an answer at all). Kept out of the page's entry because `app.js` cannot be imported outside a browser, so anything left in it is untestable. The `scripts/test-web-console-*.mjs` tests import it directly. Learning's share: the `lessons` card's words and answer (`LESSON_KEEP_WORD`, `lessonEditField()`, `lessonLines()`, and `lessonsReply()`, which `tokenFor()` in `screens/core.js` uses: a line per decision plus one `Decisions:` line in the shape `lessons.mjs decide` takes), `LEARNING_ACTIONS` / `learningAction()` / `learningReply()` (the `__learning` send) and `learningBannerText()` (the waiting banner's line, or "" when no lesson is waiting or Learning is off or paused). `seedStaged(items, staged, seeded, sent)` stages a `multi` card's `ticked` rows once as if the person had ticked them (`page.local.seeded`, kept with the draft, remembers it so a cleared card is never re-ticked by a redraw or a reload); `startsTicked(item)` is the one test for such a card, shared by `answerLines` ("None ticked" for an empty `ks`), `tokenFor` in `core.js` (the reply says `none`, before any note) and `cards.js` (an emptied pick stays staged as `ks: []`). |
| `public/labels.js` | `taskLabel()` / `activityLabel()`: rewrites a build's `Task 4.2 of 6` activity line to `Task 2 of 6` (only for `implement` / `implement-review`; a plan's `Task 2.1` is a real section number). A separate module for the same reason as `answers.js`: pure, so `node --test` can import it | | `public/labels.js` | `taskLabel()` / `activityLabel()`: rewrites a build's `Task 4.2 of 6` activity line to `Task 2 of 6` (only for `implement` / `implement-review`; a plan's `Task 2.1` is a real section number). A separate module for the same reason as `answers.js`: pure, so `node --test` can import it |
| `public/boot.js` | `playWake()`: the dashboard's first-open wake-up. Self-contained (it owns its timers, the listeners that swallow input mid-run and the one measured glide transform; the page's `stir()` callback times the nudge between the click and the boot, which `screens/dashboard.js` fills with one snore; `skipEl` — the muted Skip button, and Escape — ends the run early with `onSkip` as the cue to silence queued sounds) and free of module-scope DOM access, so it can be imported by the tests and kept out of the screens' render paths; `GLIDE_AT_MS` / `DONE_AT_MS` are its timings | | `public/boot.js` | `playWake()`: the dashboard's first-open wake-up. Self-contained (it owns its timers, the listeners that swallow input mid-run and the one measured glide transform; the page's `stir()` callback times the nudge between the click and the boot, which `screens/dashboard.js` fills with one snore; `skipEl` — the muted Skip button, and Escape — ends the run early with `onSkip` as the cue to silence queued sounds) and free of module-scope DOM access, so it can be imported by the tests and kept out of the screens' render paths; `GLIDE_AT_MS` / `DONE_AT_MS` are its timings |
+11 -7
View File
@@ -85,7 +85,7 @@ plan2code/
├── .claude/ # Repo-local Claude Code config (NOT installed by install.js) ├── .claude/ # Repo-local Claude Code config (NOT installed by install.js)
│ └── skills/ # Maintainer-only dev skills, e.g. plan2code-publish/, plan2code-launcher-update/ │ └── skills/ # Maintainer-only dev skills, e.g. plan2code-publish/, plan2code-launcher-update/
├── .github/ISSUE_TEMPLATE/ # bug.yml, idea.yml, config.yml (target of the console's feedback button) ├── .github/ISSUE_TEMPLATE/ # bug.yml, idea.yml, config.yml (target of the console's feedback button)
├── .readme/ # User guides linked from README (web-console.md, web-console-design.md, walkthrough.md, metrics.md, status-line.md, test-bot.md) ├── .readme/ # User guides linked from README (README.md index, web-console.md, activities.md, web-console-internals.md, web-console-design.md, walkthrough.md, steps.md, launcher.md, metrics.md, status-line.md, test-bot.md)
├── docs/ # Landing page `index.html` served at plan2code.jparkerweb.com (GitHub Pages, `CNAME`) and assets ├── docs/ # Landing page `index.html` served at plan2code.jparkerweb.com (GitHub Pages, `CNAME`) and assets
│ └── screenshots/ # Web console screenshots, <shot>-light.webp and <shot>-dark.webp (generated) │ └── screenshots/ # Web console screenshots, <shot>-light.webp and <shot>-dark.webp (generated)
├── specs/ # Feature specs (if any in-progress) ├── specs/ # Feature specs (if any in-progress)
@@ -112,7 +112,7 @@ plan2code/
| `src/launcher/plan2code.js` | Global `plan2code` command that opens the dashboard skill in Claude Code, Devin or Codex (installed by `I` and Advanced → `E`; also via Advanced → `D`). When the desktop app is installed (`~/.plan2code/app/plan2code-app[.exe]`, or the file `PLAN2CODE_APP` names) and a display exists (Windows and macOS always; Linux needs `DISPLAY` or `WAYLAND_DISPLAY`), it opens the app after the agent and model questions with `--project <folder> --agent <id> [--model <id>]` and exits; `--classic` (never forwarded to the CLI) and a failed spawn keep the terminal flow. The app reads all three (`project::launch_choice`): the picker starts on `--agent`, and `--model` applies to that agent on every start and Restart (`AgentManager::set_model`); a model never applies to another agent. The folder comes from `--project` alone: with none (a bare start of the app) the app shows its own picker, Choose a folder first and focused with the recent folders under it (`project::recent_folders`, the `recent_folders` and `open_recent_folder` commands), and Change project opens the same picker. The list is `recentFolders` in `~/.plan2code/launcher.json`, one rule written twice (`readRecent`, `pushRecent`, `listRecent` in the launcher, their twins in `project.rs`) and held to `scripts/fixtures/recent-folders-cases.json`. Its menu, lookup and no-agent flow come from `agents.json` through `agent-lookup.mjs`, loaded by dynamic `import()` from `~/.plan2code/bin/` (the launcher's one stated exception to its Node-built-ins-only rule; a missing copy falls back to the plain printed install steps) | | `src/launcher/plan2code.js` | Global `plan2code` command that opens the dashboard skill in Claude Code, Devin or Codex (installed by `I` and Advanced → `E`; also via Advanced → `D`). When the desktop app is installed (`~/.plan2code/app/plan2code-app[.exe]`, or the file `PLAN2CODE_APP` names) and a display exists (Windows and macOS always; Linux needs `DISPLAY` or `WAYLAND_DISPLAY`), it opens the app after the agent and model questions with `--project <folder> --agent <id> [--model <id>]` and exits; `--classic` (never forwarded to the CLI) and a failed spawn keep the terminal flow. The app reads all three (`project::launch_choice`): the picker starts on `--agent`, and `--model` applies to that agent on every start and Restart (`AgentManager::set_model`); a model never applies to another agent. The folder comes from `--project` alone: with none (a bare start of the app) the app shows its own picker, Choose a folder first and focused with the recent folders under it (`project::recent_folders`, the `recent_folders` and `open_recent_folder` commands), and Change project opens the same picker. The list is `recentFolders` in `~/.plan2code/launcher.json`, one rule written twice (`readRecent`, `pushRecent`, `listRecent` in the launcher, their twins in `project.rs`) and held to `scripts/fixtures/recent-folders-cases.json`. Its menu, lookup and no-agent flow come from `agents.json` through `agent-lookup.mjs`, loaded by dynamic `import()` from `~/.plan2code/bin/` (the launcher's one stated exception to its Node-built-ins-only rule; a missing copy falls back to the plain printed install steps) |
| `plan2code-app/` | Tauri desktop app (Rust host, xterm panel, the console's dashboard in a frame; its own README). `RELEASE-CHECKLIST.md` lists the by-hand checks before each release. `src-tauri/src/versions.rs` compares the app's version (`tauri.conf.json`) with the installed skills' (`~/.plan2code/bin/version.json`) for the bar's **Update skills** line, which runs `node ~/.plan2code/bin/plan2code.js update` only when pressed | | `plan2code-app/` | Tauri desktop app (Rust host, xterm panel, the console's dashboard in a frame; its own README). `RELEASE-CHECKLIST.md` lists the by-hand checks before each release. `src-tauri/src/versions.rs` compares the app's version (`tauri.conf.json`) with the installed skills' (`~/.plan2code/bin/version.json`) for the bar's **Update skills** line, which runs `node ~/.plan2code/bin/plan2code.js update` only when pressed |
| `plan2code-app/src-tauri/src/attention.rs` | The taskbar signal's rules, pure and knowing nothing about Tauri: `Signal` (`busy`, `ready`, `attention`, `plain`), `badge_for(signal, os, enabled)` (Windows: green dot on `ready`, red on `attention`; macOS: red `!` on `attention` only; Linux: count 1 on `attention`), `should_flash(prev, next, focused, enabled)` (once, only on a change into `ready` or `attention` while unfocused) and `dot_rgba()` (the dot's pixels, in the favicon's colors, which a test checks against `public/favicon.js`). `main.rs` applies the result through `set_attention`, `set_taskbar_signal` and `clear_attention_cmd`; the page asks with the `attention` and `taskbar` messages (`public/app-bridge.js`) and the switch is `taskbarSignal` in the app's own `~/.plan2code/app.json`. | | `plan2code-app/src-tauri/src/attention.rs` | The taskbar signal's rules, pure and knowing nothing about Tauri: `Signal` (`busy`, `ready`, `attention`, `plain`), `badge_for(signal, os, enabled)` (Windows: green dot on `ready`, red on `attention`; macOS: red `!` on `attention` only; Linux: count 1 on `attention`), `should_flash(prev, next, focused, enabled)` (once, only on a change into `ready` or `attention` while unfocused) and `dot_rgba()` (the dot's pixels, in the favicon's colors, which a test checks against `public/favicon.js`). `main.rs` applies the result through `set_attention`, `set_taskbar_signal` and `clear_attention_cmd`; the page asks with the `attention` and `taskbar` messages (`public/app-bridge.js`) and the switch is `taskbarSignal` in the app's own `~/.plan2code/app.json`. |
| `plan2code-app/src-tauri/src/quit_prompt.rs`, `task_dialog.rs` | The quit check shown while an agent runs. `quit_prompt(last_signal)` is pure: the page's last taskbar signal `ready` or `plain` is the waiting case ("Done for now?", Info icon), and `busy`, `attention` or none yet is the working case ("Leave while your agent is busy?", Warning icon). `task_dialog.rs` (Windows only) draws it with `TaskDialogIndirect` through `winapi`: a heading, Stay as the default, and the app's icon in the title bar, since the dialog plugin has no heading and Windows copies its icon into the title bar (the warning once showed twice). `confirm_quit` in `main.rs` runs it on its own thread; macOS and Linux use the plugin box with the same words, where Quit stays the default button (putting Stay first would make Esc quit). A page reload or an unanswered page clears the signal to none (`clear_attention`), so the box stays on the working words until the page reports again; `QUIT_OPEN` keeps a second box from stacking | | `plan2code-app/src-tauri/src/quit_prompt.rs`, `task_dialog.rs` | The quit check shown while an agent runs. `quit_prompt(last_signal)` is pure: the page's last taskbar signal `ready` or `plain` is the waiting case ("Done for now?", Info icon), and `busy`, `attention` or none yet is the working case ("Leave while your agent is busy?", Warning icon). `task_dialog.rs` (Windows only) draws it with `TaskDialogIndirect` through `winapi`: a heading, Stay as the default, and the app's icon in the title bar, since the dialog plugin has no heading and Windows copies its icon into the title bar (the warning once showed twice). `confirm_quit` in `main.rs` runs it on its own thread; macOS and Linux ask through the shell's own modal (`ui_confirm.rs`: `ask_in_window` emits `confirm-request`, the page's `confirmModal` answers with `confirm_answer`), where Stay comes first and has focus, so Stay is the default on every system; the plugin box with the same words is only the fallback while the page is not listening (`confirm_ready`), and there Quit stays the default button (putting Stay first would make Esc quit). The Implementation Loop's Start confirm goes through the same modal (`loop_driver::confirm_lines`: the quick check in a code block, the trunk warning as a callout). A page reload or an unanswered page clears the signal to none (`clear_attention`), so the box stays on the working words until the page reports again; `QUIT_OPEN` keeps a second box from stacking |
| `plan2code-app/src-tauri/src/loop_driver.rs` | The Implementation Loop's driver. Its decisions are pure functions and carry the unit tests: `phase_prompt()` (the prompt each fresh phase session starts on), `judge_outcome()` (the skill's `loopOutcome` against the spec's marks and the setup), `expect_patch()` (the `loopExpect` judging criteria stamped into the session so the console refuses a bad report at post time), `silence_expired()`, `should_retry()` (one retry for a crash or silence, never for a real failure), `open_question()` and `stop_line()`. Around them sit the running record (app memory only), the watch thread and the stop and resume entry points. **The app, not the agent, marks a loop phase done and commits it**; the skill only builds and reports | | `plan2code-app/src-tauri/src/loop_driver.rs` | The Implementation Loop's driver. Its decisions are pure functions and carry the unit tests: `phase_prompt()` (the prompt each fresh phase session starts on), `judge_outcome()` (the skill's `loopOutcome` against the spec's marks and the setup), `expect_patch()` (the `loopExpect` judging criteria stamped into the session so the console refuses a bad report at post time), `silence_expired()`, `should_retry()` (one retry for a crash or silence, never for a real failure), `open_question()` and `stop_line()`. Around them sit the running record (app memory only), the watch thread and the stop and resume entry points. **The app, not the agent, marks a loop phase done and commits it**; the skill only builds and reports |
| `plan2code-app/src-tauri/src/loop_commit.rs` | The loop's commit step, called by `handle_outcome` in a fixed order: prepare (subject, message), stage and check the staged names and sizes against a denylist (`.env*` except `.example`, `.sample`, `.template`; oversized files; a bad list unstages all and stops), save the phase file text, mark done, commit with its own limit, and on a failed commit restore the saved text only if the file still equals what the loop wrote (else stop with "marked, not committed", kept in the reports store). Stop now never commits; `judge_outcome` refuses missing task data and failed tests; the watcher runs under `catch_unwind` and counts unreadable sessions as silence; `loop_state` in `main.rs` redraws the strip after a reload | | `plan2code-app/src-tauri/src/loop_commit.rs` | The loop's commit step, called by `handle_outcome` in a fixed order: prepare (subject, message), stage and check the staged names and sizes against a denylist (`.env*` except `.example`, `.sample`, `.template`; oversized files; a bad list unstages all and stops), save the phase file text, mark done, commit with its own limit, and on a failed commit restore the saved text only if the file still equals what the loop wrote (else stop with "marked, not committed", kept in the reports store). Stop now never commits; `judge_outcome` refuses missing task data and failed tests; the watcher runs under `catch_unwind` and counts unreadable sessions as silence; `loop_state` in `main.rs` redraws the strip after a reload |
| `plan2code-app/src-tauri/src/loop_notify.rs` | The loop's notification: `NotifyKind` (query string, JSON body, Discord, Slack, Teams, Google Chat; its comment lists what a new service needs), `valid_url()`, `valid_param()` (mirrored in `loop-setup.mjs` and `screens/loop-setup.js`), `request_for()` (each kind's address and body) and `send()`, with a 10 second limit and errors that never hold the address. The driver writes the message and calls it from `observe()`, `stop_loop()` and `finish()`. | | `plan2code-app/src-tauri/src/loop_notify.rs` | The loop's notification: `NotifyKind` (query string, JSON body, Discord, Slack, Teams, Google Chat; its comment lists what a new service needs), `valid_url()`, `valid_param()` (mirrored in `loop-setup.mjs` and `screens/loop-setup.js`), `request_for()` (each kind's address and body) and `send()`, with a 10 second limit and errors that never hold the address. The driver writes the message and calls it from `observe()`, `stop_loop()` and `finish()`. |
@@ -121,6 +121,10 @@ plan2code/
| `plan2code-app/src-tauri/src/agents.rs` | Agents in the app: `CustomAgent`, the `Agent` handle over built-ins and custom entries, `load_custom_agents`, reading the Agents file below; the shipped `agents.json` read at run time with the baked copy as fallback; `find_on_path`, the Rust twin of `agent-lookup.mjs`'s `findAgent` (PATH, PATHEXT, the saved PATH from `node_check::resolved_path()`, npm's global folder, the install folders), held to `scripts/fixtures/agent-lookup-cases.json`. The console side is `src/web-console/agents.mjs` | | `plan2code-app/src-tauri/src/agents.rs` | Agents in the app: `CustomAgent`, the `Agent` handle over built-ins and custom entries, `load_custom_agents`, reading the Agents file below; the shipped `agents.json` read at run time with the baked copy as fallback; `find_on_path`, the Rust twin of `agent-lookup.mjs`'s `findAgent` (PATH, PATHEXT, the saved PATH from `node_check::resolved_path()`, npm's global folder, the install folders), held to `scripts/fixtures/agent-lookup-cases.json`. The console side is `src/web-console/agents.mjs` |
| Desktop app install (`install.js`) | `installDesktopApp()` downloads `plan2code-app-<version>-<windows\|macos\|linux>-<x64\|arm64>[.exe]` and `plan2code-app-<version>-SHA256SUMS.txt` from the GitHub release (`PLAN2CODE_RELEASE_BASE` replaces the URL; the tests serve a stand-in), checks the SHA-256 and places the file in `~/.plan2code/app/` (the old file is renamed aside first, since Windows cannot overwrite a running exe). `app` is an install piece (`INSTALL_PIECES`, after `launcher`), so `plan2code update` updates it with the rest. `install()` asks for it after the command (default yes; a no is kept as `skipped` in `install.json`); unattended it installs it unless it is already recorded or was declined. A failed app never fails the install. `.github/workflows/release-app.yml` builds one file per system (`tauri build --no-bundle`) and the checksum list on a published release, after `scripts/check-versions.mjs --tag` | | Desktop app install (`install.js`) | `installDesktopApp()` downloads `plan2code-app-<version>-<windows\|macos\|linux>-<x64\|arm64>[.exe]` and `plan2code-app-<version>-SHA256SUMS.txt` from the GitHub release (`PLAN2CODE_RELEASE_BASE` replaces the URL; the tests serve a stand-in), checks the SHA-256 and places the file in `~/.plan2code/app/` (the old file is renamed aside first, since Windows cannot overwrite a running exe). `app` is an install piece (`INSTALL_PIECES`, after `launcher`), so `plan2code update` updates it with the rest. `install()` asks for it after the command (default yes; a no is kept as `skipped` in `install.json`); unattended it installs it unless it is already recorded or was declined. A failed app never fails the install. `.github/workflows/release-app.yml` builds one file per system (`tauri build --no-bundle`) and the checksum list on a published release, after `scripts/check-versions.mjs --tag` |
### Release channel
Install and update follow release tags, never `main`. `release-app.yml`'s `publish` job ends by fast-forwarding the `release` branch to the tag it just published (no force: a tag not ahead of the branch fails the job), and the README's first install is `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release`. `plan2code update` installs the newest `vX.Y.Z` tag (`newestReleaseTag()` in `src/launcher/plan2code.js`, using `latestTag()` and `runLsRemote()` from the copy of `update-check.mjs` beside it); `--main` installs the tip of `main`, `--tag <ref>` any ref (how to go back to a release); `--main` and a `--tag` naming a branch always pass `--force`, since unreleased work keeps the last release's version and the installer's `Already on` check would install nothing. `plan2code uninstall` runs the newest release's installer the same way, falling back to `main` only when no release tag can be found. The console's release check (`update-check.mjs`) and the app's notice (`versions.rs` `latest_tag()`) use the same rule: the highest plain `vX.Y.Z` in `git ls-remote --tags`, peeled and pre-release tags skipped. The app's Update skills still pins to the app's own tag.
### Agents file ### Agents file
`~/.plan2code/agents.json` holds the person's custom agent CLIs. The web console is its only writer (User Preferences → Agents & models, through `POST /agents`); the `plan2code` launcher and the desktop app only read it. Each reader carries its own copy of the rules (`src/web-console/agents.mjs` for the console, a copy in `src/launcher/plan2code.js`, `agents.rs` in the app), and `scripts/fixtures/agents-cases.json` is the contract all three readers' tests load: file normalization with its warnings, `buildArgs` command lines and `makeId` ids. Change a rule in the fixture first. `~/.plan2code/agents.json` holds the person's custom agent CLIs. The web console is its only writer (User Preferences → Agents & models, through `POST /agents`); the `plan2code` launcher and the desktop app only read it. Each reader carries its own copy of the rules (`src/web-console/agents.mjs` for the console, a copy in `src/launcher/plan2code.js`, `agents.rs` in the app), and `scripts/fixtures/agents-cases.json` is the contract all three readers' tests load: file normalization with its warnings, `buildArgs` command lines and `makeId` ids. Change a rule in the fixture first.
@@ -151,11 +155,11 @@ plan2code/
| `plan2code-4-finalize.md` | 4 | Validate, summarize, feedback, archive (steps 1–7, +optional 6.5) | | `plan2code-4-finalize.md` | 4 | Validate, summarize, feedback, archive (steps 1–7, +optional 6.5) |
| `plan2code-handoff.md` | handoff | Compact the conversation into a self-contained handoff document for a fresh session | | `plan2code-handoff.md` | handoff | Compact the conversation into a self-contained handoff document for a fresh session |
| `plan2code-xray.md` | xray | Explain how and why an area works (files, commits, PRs via `gh` when present), or rank the rough spots worth fixing into `ARCHITECTURE-BRIEF-<date>.md` for Pathfinder or Plan; never edits code | | `plan2code-xray.md` | xray | Explain how and why an area works (files, commits, PRs via `gh` when present), or rank the rough spots worth fixing into `ARCHITECTURE-BRIEF-<date>.md` for Pathfinder or Plan; never edits code |
| `plan2code-diagnose.md` | diagnose | Find a bug's cause under the find-the-cause-first habit (`references/building-habits.md`) and write it up as `specs/<bug-name>/DIAGNOSIS-<YYYYMMDD>.md` without fixing it, then offer Quick Task to fix it, or Plan when the fix is big. The dashboard scan reports such a folder as spec state `diagnosed` ("Bug diagnosed"), which lights Quick Task (suggested) and Plan. Once Quick Task marks the diagnosis `Fixed` (nothing past it in the folder) the state is `fixed` ("Bug fixed"): no pipeline card lights, the picker never pre-selects it, and Quick Task offers to archive it with `specs.mjs archive` | | `plan2code-diagnose.md` | diagnose | Find a bug's cause under the find-the-cause-first habit (`references/building-habits.md`) and write it up as `specs/<bug-name>/DIAGNOSIS-<YYYYMMDD>.md` without fixing it, then offer Quick task to fix it, or Plan when the fix is big. The dashboard scan reports such a folder as spec state `diagnosed` ("Bug diagnosed"), which lights Quick task (suggested) and Plan. Once Quick task marks the diagnosis `Fixed` (nothing past it in the folder) the state is `fixed` ("Bug fixed"): no pipeline card lights, the picker never pre-selects it, and Quick task offers to archive it with `specs.mjs archive` |
| `plan2code-pr-prep.md` | pr-prep | Get a branch ready for review: pick the checks its changes need from the project's `## Test map` (or its config files), let the person trim the plan, run it, give Ready, Ready with notes or Not ready, and write a PR description to copy (following the repo's template) with the create-a-PR link; offers to save `PR-READINESS-<date>.md` into the branch's spec folder; never commits, pushes or opens the PR | | `plan2code-pr-prep.md` | pr-prep | Get a branch ready for review: pick the checks its changes need from the project's `## Test map` (or its config files), let the person trim the plan, run it, give Ready, Ready with notes or Not ready, and write a PR description to copy (following the repo's template) with the create-a-PR link; offers to save `PR-READINESS-<date>.md` into the branch's spec folder; never commits, pushes or opens the PR |
| `plan2code-test.md` | test | Write missing tests: ask where to look, find source files no test covers (matching, plus real coverage when the project already has a coverage tool, offered first), show a plan opening with how this project writes tests, then write and run unit and integration tests; escalates past 8 source files, 8 new test files or 2 runners to a PLAN-DRAFT for Plan, hands a real bug to Diagnose, never changes source code | | `plan2code-test.md` | test | Write missing tests: ask where to look, find source files no test covers (matching, plus real coverage when the project already has a coverage tool, offered first), show a plan opening with how this project writes tests, then write and run unit and integration tests; escalates past 8 source files, 8 new test files or 2 runners to a PLAN-DRAFT for Plan, hands a real bug to Diagnose, never changes source code |
| `plan2code-dead-code.md` | dead-code | Find unused code and dead code: use the project's own dead-code tools, one per language that has files (Knip, vulture, cargo check and others), or search by itself, check every item for callers across the project (`references/caller-search.md`), label each Safe to remove, Check first or Warning, remove only what the person picks, then run the tests and build and put back anything that breaks them, then offer a final review of the removals in the same session (Step 7.5, recommended yes; ships `review.md`, `review-in-build.md`, `test-runs.md` and the review references, as Finalize does); never commits, never installs a tool. Scripts: `dead-code.mjs` (own), `test-map.mjs`, `glob.mjs`, `test-commands.mjs`, `run-check.mjs`, `specs.mjs`, `commit-msg.mjs`, `review-scope.mjs`, `lessons.mjs` | | `plan2code-dead-code.md` | dead-code | Find unused code and dead code: use the project's own dead-code tools, one per language that has files (Knip, vulture, cargo check and others), or search by itself, check every item for callers across the project (`references/caller-search.md`), label each Safe to remove, Check first or Warning, remove only what the person picks, then run the tests and build and put back anything that breaks them, then offer a final review of the removals in the same session (Step 7.5, recommended yes; ships `review.md`, `review-in-build.md`, `test-runs.md` and the review references, as Finalize does); never commits, never installs a tool. Scripts: `dead-code.mjs` (own), `test-map.mjs`, `glob.mjs`, `test-commands.mjs`, `run-check.mjs`, `specs.mjs`, `commit-msg.mjs`, `review-scope.mjs`, `lessons.mjs` |
| `plan2code-deps.md` | deps | Update dependencies: scan every manifest (the npm family, Cargo, pip and uv, Go, .NET), label each available update Safe, Check first or Warning with a reason, show a pick list, apply the picks in batches, run the project's install and checks after each batch and put back whatever breaks (narrowing a failed batch to the breaking pick); a ticked Warning writes `specs/<package>-upgrade/UPGRADE-<YYYYMMDD>.md` instead. The dashboard scan reports such a folder as spec state `upgrade` ("Upgrade ready"), which lights Quick Task (suggested) and Plan; once Quick Task applies it and marks the brief `Done` the state is `upgraded` ("Upgrade done"), finished like `fixed`. Never commits or updates anything not picked; installs a scanner or fixes a small break in project code only after the person approves that exact change, and puts the fix back if it fails. Scripts: `deps.mjs` (own), `test-map.mjs`, `glob.mjs`, `test-commands.mjs`, `run-check.mjs` | | `plan2code-deps.md` | deps | Update dependencies: scan every manifest (the npm family, Cargo, pip and uv, Go, .NET), label each available update Safe, Check first or Warning with a reason, show a pick list, apply the picks in batches, run the project's install and checks after each batch and put back whatever breaks (narrowing a failed batch to the breaking pick); a ticked Warning writes `specs/<package>-upgrade/UPGRADE-<YYYYMMDD>.md` instead. The dashboard scan reports such a folder as spec state `upgrade` ("Upgrade ready"), which lights Quick task (suggested) and Plan; once Quick task applies it and marks the brief `Done` the state is `upgraded` ("Upgrade done"), finished like `fixed`. Never commits or updates anything not picked; installs a scanner or fixes a small break in project code only after the person approves that exact change, and puts the fix back if it fails. Scripts: `deps.mjs` (own), `test-map.mjs`, `glob.mjs`, `test-commands.mjs`, `run-check.mjs` |
| `plan2code-ui-prototype.md` | ui-prototype | Draw several versions of a screen or flow on one page with live dials (drafts under `~/.plan2code/prototypes/`), bring the pick back by Copy and paste for the next round, and save the pair into `specs/<spec>/prototypes/` only on a yes; never changes code | | `plan2code-ui-prototype.md` | ui-prototype | Draw several versions of a screen or flow on one page with live dials (drafts under `~/.plan2code/prototypes/`), bring the pick back by Copy and paste for the next round, and save the pair into `specs/<spec>/prototypes/` only on a yes; never changes code |
| `plan2code-changelog.md` | changelog | Check the CHANGELOG version against the default branch, suggest editable entries for new work, keep `package.json` aligned, offer to commit the result through Git | | `plan2code-changelog.md` | changelog | Check the CHANGELOG version against the default branch, suggest editable entries for new work, keep `package.json` aligned, offer to commit the result through Git |
| `plan2code-git.md` | git | Branches, pull (with conflict help), push, publish and commits (clear message, suggested splits) on the web console's git board, or plain instructions in the terminal (`switch to main`, `commit and push`); asks before every push, publish and delete | | `plan2code-git.md` | git | Branches, pull (with conflict help), push, publish and commits (clear message, suggested splits) on the web console's git board, or plain instructions in the terminal (`switch to main`, `commit and push`); asks before every push, publish and delete |
@@ -176,7 +180,7 @@ Examples:
Some workflows use companion reference files for depth that does not need to load on every invocation. The orchestrator (main workflow file) loads them via `Read` directives during execution. Some workflows use companion reference files for depth that does not need to load on every invocation. The orchestrator (main workflow file) loads them via `Read` directives during execution.
**Pattern:** `src/<source-filename-without-extension>-references/` (e.g., `plan2code-review-references/`). A file several skills read lives in `src/shared-references/` instead and ships to each through `additionalReferences` (e.g., `building-habits.md` into Quick Task, Implement and Implement + Review, and `lessons.md` into every skill that ships `lessons.mjs`). **Pattern:** `src/<source-filename-without-extension>-references/` (e.g., `plan2code-review-references/`). A file several skills read lives in `src/shared-references/` instead and ships to each through `additionalReferences` (e.g., `building-habits.md` into Quick task, Implement and Implement + Review, and `lessons.md` into every skill that ships `lessons.mjs`).
**How the installer handles them:** the directory is copied verbatim to `skills/<skill-name>/references/`, so `Read references/<file>.md` resolves consistently for every agent. There is one output format, with no flat-file sibling directory or path rewrite. **How the installer handles them:** the directory is copied verbatim to `skills/<skill-name>/references/`, so `Read references/<file>.md` resolves consistently for every agent. There is one output format, with no flat-file sibling directory or path rewrite.
@@ -209,7 +213,7 @@ Typing `plan2code` in any directory opens the dashboard skill against the curren
The bracketed flags (each entry's `bypassArgs`; a custom agent's own `bypassArgs`) go in only when permission prompts are off. Right after the agent is chosen, and only when it has such a flag, `chooseBypass()` asks `Turn <CLI>'s permission prompts off?` (Codex: `approval prompts and its sandbox`, worded by `bypassQuestion()`) on every launch, with Yes as the default and no answer remembered; `--keep-permissions` answers no and `--bypass-permissions` answers yes (neither is forwarded; keep wins when both are given), and with no TTY on stdin the prompts stay on unless `--bypass-permissions` is given. When the desktop app will take over, the question is skipped (its launch card has its own tick) and asked only if the app fails to start. The installer prints no warning about it. The bracketed flags (each entry's `bypassArgs`; a custom agent's own `bypassArgs`) go in only when permission prompts are off. Right after the agent is chosen, and only when it has such a flag, `chooseBypass()` asks `Turn <CLI>'s permission prompts off?` (Codex: `approval prompts and its sandbox`, worded by `bypassQuestion()`) on every launch, with Yes as the default and no answer remembered; `--keep-permissions` answers no and `--bypass-permissions` answers yes (neither is forwarded; keep wins when both are given), and with no TTY on stdin the prompts stay on unless `--bypass-permissions` is given. When the desktop app will take over, the question is skipped (its launch card has its own tick) and asked only if the app fails to start. The installer prints no warning about it.
On a terminal it first prints a Planny banner (`renderBanner()`). With more than one on `PATH` it asks `Plan2Code opens inside an AI coding agent. Pick which one to use:` as a numbered menu, the last pick pre-selected and marked `(last used)` (Enter keeps it; a number or a CLI id also works); with one installed it uses that without asking, printing `Opening with <CLI>…` (as does a `--cli` pick); with none it runs the setup flow when a person can see a page (`hasDisplay()` and a TTY or the shortcut; the desktop app first when it is installed, else the console's agent-less `setup` page in the browser) and otherwise prints the install steps (`printNoAgentGuidance()`: each built-in's install command and page, how to add another agent in `~/.plan2code/agents.json`, and to run `plan2code` again) and exits 127. An uninstalled `--cli` pick goes to the same setup flow on that agent when a page can open, else prints that CLI's own steps after its error. `--cli claude` / `devin` / `codex` (or `--cli=<name>`) skips the menu and is never forwarded; an unknown name exits 2, an uninstalled one 127. The pick is saved as `lastCli` in `~/.plan2code/launcher.json`, merged beside `lastFolder`, `recentFolders` and `lastModels`. Then, at a terminal with recent folders to offer, it asks `Which project folder?` as a numbered menu in the style of the model menu: the current folder first (Enter keeps it), the recent folders (at most 5, newest first), then `Choose another folder...` for the native picker. With no recent folders other than the current one (the typed command leaves the current folder out of the list), or no TTY on stdin, there is no menu and it opens the current folder as before. The folder is recorded as `recentFolders` (with `lastFolder` always its first entry) only after the project check passes (`recordFolder()`), on every path including the global command; declining the check records nothing. Before spawning, unless the forwarded args carry `--model` / `--model=` (or, for Codex, `-m`), it asks `Which model should <CLI> use?` from `models.json` plus the user's additions, Enter keeping the model the CLI last used — Ctrl+C at any launcher prompt exits 130. With no TTY on stdin there is no menu (last pick, else the first installed) and no model question: it prints that the CLI will use the model last used in it (switch it in that CLI on its own, or pass `--model <name>`). Headings, numbers, defaults, retry lines and the `plan2code:` error prefixes are colored with `paint()` (the escape values of `install.js`'s `COLORS`, copied), stdout only when stdout is a TTY and stderr only when stderr is, and never when `NO_COLOR` is set; piped runs print plain text and no banner. Other arguments are forwarded to the CLI (`plan2code --model opus`), and its exit code is passed back. `plan2code update` and `plan2code uninstall [--yes] [--purge]` are the two subcommands: neither is forwarded and neither opens an agent. Update runs `npx --yes --allow-git=all git+https://github.com/jparkerweb/plan2code.git --update`, so `install.js --update` reinstalls what `~/.plan2code/install.json` lists; uninstall runs the same npx line with `--uninstall` (an unknown flag exits 2 before npx runs), and `install.js` confirms, removes everything the menu's U option does, then asks about `~/.plan2code` (see `--uninstall` in Development Commands). On every other start, before spawning the CLI, it prints one line when a newer release is out (`Plan2Code v<latest> is out (you have v<installed>). Run: plan2code update`), compared against `~/.plan2code/bin/version.json` and read from the console's cached release check (`~/.plan2code/console/update-check.json`); it never waits on the network, and when the cache is missing or stale it refreshes it in a detached background process so the next start knows. Tests: `scripts/test-launcher.mjs` (run by `npm test`) spawns the launcher against stand-in `claude`/`devin`/`codex` commands and a temp home. On a terminal it first prints a Planny banner (`renderBanner()`). With more than one on `PATH` it asks `Plan2Code opens inside an AI coding agent. Pick which one to use:` as a numbered menu, the last pick pre-selected and marked `(last used)` (Enter keeps it; a number or a CLI id also works); with one installed it uses that without asking, printing `Opening with <CLI>…` (as does a `--cli` pick); with none it runs the setup flow when a person can see a page (`hasDisplay()` and a TTY or the shortcut; the desktop app first when it is installed, else the console's agent-less `setup` page in the browser) and otherwise prints the install steps (`printNoAgentGuidance()`: each built-in's install command and page, how to add another agent in `~/.plan2code/agents.json`, and to run `plan2code` again) and exits 127. An uninstalled `--cli` pick goes to the same setup flow on that agent when a page can open, else prints that CLI's own steps after its error. `--cli claude` / `devin` / `codex` (or `--cli=<name>`) skips the menu and is never forwarded; an unknown name exits 2, an uninstalled one 127. The pick is saved as `lastCli` in `~/.plan2code/launcher.json`, merged beside `lastFolder`, `recentFolders` and `lastModels`. Then, at a terminal with recent folders to offer, it asks `Which project folder?` as a numbered menu in the style of the model menu: the current folder first (Enter keeps it), the recent folders (at most 5, newest first), then `Choose another folder...` for the native picker. With no recent folders other than the current one (the typed command leaves the current folder out of the list), or no TTY on stdin, there is no menu and it opens the current folder as before. The folder is recorded as `recentFolders` (with `lastFolder` always its first entry) only after the project check passes (`recordFolder()`), on every path including the global command; declining the check records nothing. Before spawning, unless the forwarded args carry `--model` / `--model=` (or, for Codex, `-m`), it asks `Which model should <CLI> use?` from `models.json` plus the user's additions, Enter keeping the model the CLI last used — Ctrl+C at any launcher prompt exits 130. With no TTY on stdin there is no menu (last pick, else the first installed) and no model question: it prints that the CLI will use the model last used in it (switch it in that CLI on its own, or pass `--model <name>`). Headings, numbers, defaults, retry lines and the `plan2code:` error prefixes are colored with `paint()` (the escape values of `install.js`'s `COLORS`, copied), stdout only when stdout is a TTY and stderr only when stderr is, and never when `NO_COLOR` is set; piped runs print plain text and no banner. Other arguments are forwarded to the CLI (`plan2code --model opus`), and its exit code is passed back; a bare `--` ends the launcher's own arguments, and everything after it goes to the agent as it is (the separator dropped) and keeps the run in the terminal even with the app installed (`plan2code -- --help` shows the agent's help). When the app opens it takes only the folder, agent and model, so one dim line names any other argument it drops (`droppedForApp()`). `plan2code --help` (`-h`, `help`) prints `usageText()` and `plan2code --version` (`-v`) prints the version in `version.json` beside the launcher; both exit 0 before the banner or any question. `plan2code update` and `plan2code uninstall [--yes] [--purge]` are the two subcommands: neither is forwarded and neither opens an agent. The launcher and `install.js` both start with a Node guard (`nodeVersionProblem()`): below Node 18 they print one sentence and exit 1. Update runs `npx --yes --allow-git=all git+https://github.com/jparkerweb/plan2code.git --update`, so `install.js --update` reinstalls what `~/.plan2code/install.json` lists; uninstall runs the same npx line with `--uninstall` (an unknown flag exits 2 before npx runs), and `install.js` confirms, removes everything the menu's U option does, then asks about `~/.plan2code` (see `--uninstall` in Development Commands). On every other start, before spawning the CLI, it prints one line when a newer release is out (`Plan2Code v<latest> is out (you have v<installed>). Run: plan2code update`), compared against `~/.plan2code/bin/version.json` and read from the console's cached release check (`~/.plan2code/console/update-check.json`); it never waits on the network, and when the cache is missing or stale it refreshes it in a detached background process so the next start knows. Tests: `scripts/test-launcher.mjs` (run by `npm test`) spawns the launcher against stand-in `claude`/`devin`/`codex` commands and a temp home.
**Design constraints:** **Design constraints:**
- **Stable copy, not the package dir** — the installer normally runs from an npx cache directory npm may delete, so `installLauncher()` copies `src/launcher/plan2code.js` to `~/.plan2code/bin/plan2code.js` and the shims point there. Beside it go `update-check.mjs` (the web console's release check, for the terminal notice), `agents.json` and `agent-lookup.mjs` (the shared agent list and lookup rule; `plan2code update` restores a missing copy) and a `version.json` (the installed version). (The metrics/bot wrappers point into `__dirname` and don't have this protection.) - **Stable copy, not the package dir** — the installer normally runs from an npx cache directory npm may delete, so `installLauncher()` copies `src/launcher/plan2code.js` to `~/.plan2code/bin/plan2code.js` and the shims point there. Beside it go `update-check.mjs` (the web console's release check, for the terminal notice), `agents.json` and `agent-lookup.mjs` (the shared agent list and lookup rule; `plan2code update` restores a missing copy) and a `version.json` (the installed version). (The metrics/bot wrappers point into `__dirname` and don't have this protection.)
@@ -230,4 +234,4 @@ On a terminal it first prints a Planny banner (`renderBanner()`). With more than
The macOS and Linux shortcuts carry the `plan2code-launcher` marker as a comment line. A `.lnk` has nowhere to hide one (its Description is the hover tooltip), so it's recognized by what it runs: the UTF-16 strings `plan2code.ps1` and `--pick-folder` stored in the file (`plan2code.cmd` also matches, so shortcuts from before the PowerShell switch get refreshed). `uninstallLauncher()` removes only a recognized shortcut, plus the icons (`plan2code.ico`, `plan2code.png`), `bin/models.json` and `launcher.json` (never the user's `~/.plan2code/models.json`). A shortcut failure prints a warning and never fails the command install. The macOS and Linux shortcuts carry the `plan2code-launcher` marker as a comment line. A `.lnk` has nowhere to hide one (its Description is the hover tooltip), so it's recognized by what it runs: the UTF-16 strings `plan2code.ps1` and `--pick-folder` stored in the file (`plan2code.cmd` also matches, so shortcuts from before the PowerShell switch get refreshed). `uninstallLauncher()` removes only a recognized shortcut, plus the icons (`plan2code.ico`, `plan2code.png`), `bin/models.json` and `launcher.json` (never the user's `~/.plan2code/models.json`). A shortcut failure prints a warning and never fails the command install.
**Installer integration** lives in `install.js` under the `PLAN2CODE COMMAND` section (`installLauncher`, `uninstallLauncher`, plus the shortcut helpers). `install()` awaits it after a successful skills install (so `I` and Advanced → `E` get it), `U` removes it, and Advanced → `D` installs it alone. Every global install writes `~/.plan2code/install.json`, the install record listing the pieces installed (skills, launcher, statusline, loop, metrics, bot); `install.js --update` (what `plan2code update` runs) reinstalls those (metrics and bot only when run from a git checkout), with no menu and never uninstalling, or with no record the skills and the `plan2code` command. After an install, `printGettingStarted()` prints the three steps (cd into the project, start Plan2Code, pick a card) and, when no agent CLI is on `PATH`, how to get one. **Installer integration** lives in `install.js` under the `PLAN2CODE COMMAND` section (`installLauncher`, `uninstallLauncher`, plus the shortcut helpers). `install()` awaits it after a successful skills install (so `I` and Advanced → `E` get it), `U` removes it, and Advanced → `D` installs it alone. Every global install writes `~/.plan2code/install.json`, the install record listing the pieces installed (skills, launcher, statusline, loop, metrics, bot); `install.js --update` (what `plan2code update` runs) reinstalls those (metrics and bot only when run from a git checkout), with no menu and never uninstalling, or with no record the skills and the `plan2code` command. After an install, `printGettingStarted()` prints the three steps (cd into the project, start Plan2Code, pick a card), the PATH line for the person's shell when the bin folder is off `PATH`, and, when `detectAgents()` finds no agent the launcher could run (the shared `agents.json` and `agent-lookup.mjs` rule, plus the custom agents read through the launcher's `customClis()`), how to get one. A `plan2code` already in the bin folder without the launcher marker is saved as `<file>.bak` by `writeLauncherShim()` before the shim is written.
@@ -35,7 +35,7 @@ Anything a workflow step decides with one correct answer (parsing a spec's check
| `git.mjs` (own) | git | `state`, `plan`, `branch-check`, `init-check`, `delete-check`, `cleanup-list`, `conflicts`, `pr-url`, `classify-error`: the repo snapshot, each action's exact command and confirm text (shared by the terminal and the board), branch-name, delete, cleanup and git init checks, a stopped rebase's conflicts, the pull-request link and git's errors sorted into kinds with a next step. Read-only: the agent runs every command it prints, and `guard()` refuses force push, hook skipping, amend, remote delete and blanket add | | `git.mjs` (own) | git | `state`, `plan`, `branch-check`, `init-check`, `delete-check`, `cleanup-list`, `conflicts`, `pr-url`, `classify-error`: the repo snapshot, each action's exact command and confirm text (shared by the terminal and the board), branch-name, delete, cleanup and git init checks, a stopped rebase's conflicts, the pull-request link and git's errors sorted into kinds with a next step. Read-only: the agent runs every command it prints, and `guard()` refuses force push, hook skipping, amend, remote delete and blanket add |
| `ui-prototype.mjs` (shared, with `ui-prototype-round.mjs`, `ui-prototype-page.mjs`, `ui-prototype-drafts.mjs`, `ui-prototype-block.mjs`) | ui-prototype, pathfinder, plan, revise-plan, quick-task (ride-along) | `sweep` (drafts older than 30 days), `new-round`, `assemble` (the page from `round.json`, the variant files and the shell in `references/ui-prototype-shell/`, images and fonts embedded; exit 4 `round-mismatch` when a drafts round's `round.json` names another `name` or `round` than its folder), `check` (the contract's rules, the three image rules `image-type`, `image-size` and `image-missing`, and the size ceiling), `open` (the default browser), `read-block` (a pasted choice block from stdin into fields) and `save` (the pair `specs/<spec>/prototypes/<name>.html` and `.md`, then that prototype's drafts removed). Writes only under `~/.plan2code/prototypes/<project key>/` and, on `save`, the spec's `prototypes/`; never writes project code, never opens a page outside the drafts or `specs/`, never fetches anything over the network. The helper modules are imported only by `ui-prototype.mjs` | | `ui-prototype.mjs` (shared, with `ui-prototype-round.mjs`, `ui-prototype-page.mjs`, `ui-prototype-drafts.mjs`, `ui-prototype-block.mjs`) | ui-prototype, pathfinder, plan, revise-plan, quick-task (ride-along) | `sweep` (drafts older than 30 days), `new-round`, `assemble` (the page from `round.json`, the variant files and the shell in `references/ui-prototype-shell/`, images and fonts embedded; exit 4 `round-mismatch` when a drafts round's `round.json` names another `name` or `round` than its folder), `check` (the contract's rules, the three image rules `image-type`, `image-size` and `image-missing`, and the size ceiling), `open` (the default browser), `read-block` (a pasted choice block from stdin into fields) and `save` (the pair `specs/<spec>/prototypes/<name>.html` and `.md`, then that prototype's drafts removed). Writes only under `~/.plan2code/prototypes/<project key>/` and, on `save`, the spec's `prototypes/`; never writes project code, never opens a page outside the drafts or `specs/`, never fetches anything over the network. The helper modules are imported only by `ui-prototype.mjs` |
| `lessons.mjs` | dashboard, pathfinder, plan, revise-plan, document, implement(-review), review, finalize, quick-task, xray, diagnose, pr-prep, test, dead-code, ui-prototype | Learning's one script. Every answer carries `state` (`not-set-up`, `off`, `on`, `paused`, `unknown`) and `active`, decided only by `learningState()` in the bundled `web-console/learning.mjs`, which it loads at run time through `consoleModule("learning.mjs")` (exit 3 `no-console` without it), so the dashboard and the skills never disagree. `state` (the state, since when Paused for you, the waiting count, whether AGENTS.md exists, whether on the default branch) / `switch on\|off` (the team switch) / `pause on\|off` (Paused for you, refused unless On) / `read` (the lessons for the named paths and the branch's changed files, `marked` when their About files changed since, with a `run` handle so a later read hands over only new areas) / `note` (a lesson, an area, a doubt or an AGENTS.md fix, checked, then held as waiting; nothing while Off or Paused for you; a secret exits 5) / `check` (the secret refusal and the email, handle and person-name flags; reads only) / `list` (the approval list of everything waiting, new failure log lines, the first-ask card) / `decide` (applies the person's choices, or `--first-ask yes\|no`; a test map row fix carries `row` on its list item and is reworded with `row` or with `after` as its one table line, read back by `rowFromLine()` in `test-map.mjs`, and every row is validated and secret-checked again at Apply) / `log-lines` (failure log lines added since Learning was first switched on) / `areas --suggest` (first areas from the test map) / `report` (lessons per area, the oldest, marked and gone ones) / `remove --confirm` (deletes every saved lesson). Writes only the project's `.plan2code/settings.json` and `.plan2code/lessons/<area>.md`, the pointer line and upkeep sentence in the project's `AGENTS.md`, its failure log lines (moved into lessons, marked `(kept in the log)`, or added on a first-ask no), accepted fixes to `AGENTS.md` or an `.agents-docs/` file, and, through the core, the pause and the waiting lessons on this machine only, in `~/.plan2code/learning/<repository key>/`. Never stages or commits | | `lessons.mjs` | dashboard, pathfinder, plan, revise-plan, document, implement(-review), review, finalize, quick-task, xray, diagnose, pr-prep, test, dead-code, ui-prototype | Learning's one script. Every answer carries `state` (`not-set-up`, `off`, `on`, `paused`, `unknown`) and `active`, decided only by `learningState()` in the bundled `web-console/learning.mjs`, which it loads at run time through `consoleModule("learning.mjs")` (exit 3 `no-console` without it), so the dashboard and the skills never disagree. `state` (the state, since when Paused for you, the waiting count, whether AGENTS.md exists, whether on the default branch) / `switch on\|off` (the team switch) / `pause on\|off` (Paused for you, refused unless On) / `read` (the lessons for the named paths and the branch's changed files, `marked` when their About files changed since, with a `run` handle so a later read hands over only new areas) / `note` (a lesson, an area, a doubt or an AGENTS.md fix, checked, then held as waiting; nothing while Off or Paused for you; a secret exits 5) / `check` (the secret refusal and the email, handle and person-name flags; reads only) / `list` (the approval list of everything waiting, new failure log lines, the first-ask card) / `decide` (applies the person's choices, or `--first-ask yes\|no`; a test map row fix carries `row` on its list item and is reworded with `row` or with `after` as its one table line, read back by `rowFromLine()` in `test-map.mjs`, and every row is validated and secret-checked again at Apply) / `log-lines` (failure log lines added since Learning was first switched on) / `areas --suggest` (first areas from the test map) / `report` (lessons per area, the oldest, marked and gone ones) / `remove --confirm` (deletes every saved lesson). Writes only the project's `.plan2code/settings.json` and `.plan2code/lessons/<area>.md`, the pointer line and upkeep sentence in the project's `AGENTS.md`, its failure log lines (moved into lessons, marked `(kept in the log)`, or added on a first-ask no), accepted fixes to `AGENTS.md` or an `.agents-docs/` file, and, through the core, the pause and the waiting lessons on this machine only, in `~/.plan2code/learning/<repository key>/`. Never stages or commits |
| `changes.mjs` | implement, implement-review, quick-task | The sign-off page's Changes tab. `start --session <folder>` snapshots the working tree (tracked, modified and new files, never ignored ones) into a git tree object through a temporary index and `git write-tree`, so the real index, HEAD, branches and working tree stay as they were, and writes the tree id to `<session>/changes-start.json`; a rerun replaces it. `diff --session <folder> [--cap 524288]` snapshots the tree now, compares it with the start tree and writes `<session>/changes.diff` (unified, `git diff --no-color -M` headers; over the cap it is cut at a file boundary with a notice, every file still named; a file that may hold a secret keeps its name and counts, its lines hidden; the counts of hidden and cut files travel as `# counts: <added> <removed> <path>` trailer lines (tab separated fields) that the page applies to files with no lines of their own), printing `{ ok, files, added, removed, truncated, hidden, file }`. Exit 3 for no repository, no snapshot or a snapshot git no longer has, 4 when git cannot snapshot. Work done before `start` never shows, and nothing has to be committed. The notes for Implement and Quick Task (`notes/implement.md`, `notes/quick-task.md`) say when to run each; the page draws the result as a `diff` doc block | | `changes.mjs` | implement, implement-review, quick-task | The sign-off page's Changes tab. `start --session <folder>` snapshots the working tree (tracked, modified and new files, never ignored ones) into a git tree object through a temporary index and `git write-tree`, so the real index, HEAD, branches and working tree stay as they were, and writes the tree id to `<session>/changes-start.json`; a rerun replaces it. `diff --session <folder> [--cap 524288]` snapshots the tree now, compares it with the start tree and writes `<session>/changes.diff` (unified, `git diff --no-color -M` headers; over the cap it is cut at a file boundary with a notice, every file still named; a file that may hold a secret keeps its name and counts, its lines hidden; the counts of hidden and cut files travel as `# counts: <added> <removed> <path>` trailer lines (tab separated fields) that the page applies to files with no lines of their own), printing `{ ok, files, added, removed, truncated, hidden, file }`. Exit 3 for no repository, no snapshot or a snapshot git no longer has, 4 when git cannot snapshot. Work done before `start` never shows, and nothing has to be committed. The notes for Implement and Quick task (`notes/implement.md`, `notes/quick-task.md`) say when to run each; the page draws the result as a `diff` doc block |
**Shared reference for `lessons.mjs`:** `src/shared-references/lessons.md` ships as `references/lessons.md` (through `additionalReferences`) to the same fifteen skills and the dashboard. It is the prose half of Learning: the fixed words (Learning, lesson, waiting; Not set up, Off, On, Paused for you), when a skill runs each command (Start, While working, End, unattended runs, Learning off), and that a failed call means one "Lessons could not be read this run." and carrying on without lessons. **Shared reference for `lessons.mjs`:** `src/shared-references/lessons.md` ships as `references/lessons.md` (through `additionalReferences`) to the same fifteen skills and the dashboard. It is the prose half of Learning: the fixed words (Learning, lesson, waiting; Not set up, Off, On, Paused for you), when a skill runs each command (Start, While working, End, unattended runs, Learning off), and that a failed call means one "Lessons could not be read this run." and carrying on without lessons.
+2 -2
View File
@@ -16,7 +16,7 @@
- **Version sync:** When adding a new version to `CHANGELOG.md`, run `npm run set-version -- <x.y.z>` (`node scripts/set-version.mjs`; with no version on a terminal it shows the current one and asks, Enter taking the next patch; the one writer of every carrier; it never edits the changelog), which updates `version.json` and `package.json` (root) to match. `README.md` (the `Version X.Y.Z` line near the top) also carries the version, and `version.json`'s `releaseDate` moves with it. `version.json` is copied into every skill that ships scripts (`skills/<skill>/scripts/version.json`) and into the shared console (`~/.plan2code/console/<version>/`, whose Help shows it), so after a bump run `npm run build:skills` or `npm test` (`--verify-skills`) fails. The installer displays the version from `version.json` in its header. All three files (`CHANGELOG.md`, `version.json`, `package.json`) must always show the same version number. The desktop app carries it too (under `plan2code-app/`: `package.json`, `package-lock.json` with two lines, `src-tauri/tauri.conf.json`, `src-tauri/Cargo.toml`, `fake-agent/Cargo.toml`, and `Cargo.lock`'s `plan2code-app` and `fake-agent` entries): `node scripts/check-versions.mjs [--tag vX.Y.Z]` compares those, `version.json`, `package.json`, `CHANGELOG.md` and README's line (twelve places in all), `npm test` runs it first on this tree, and the release workflow runs it before building. - **Version sync:** When adding a new version to `CHANGELOG.md`, run `npm run set-version -- <x.y.z>` (`node scripts/set-version.mjs`; with no version on a terminal it shows the current one and asks, Enter taking the next patch; the one writer of every carrier; it never edits the changelog), which updates `version.json` and `package.json` (root) to match. `README.md` (the `Version X.Y.Z` line near the top) also carries the version, and `version.json`'s `releaseDate` moves with it. `version.json` is copied into every skill that ships scripts (`skills/<skill>/scripts/version.json`) and into the shared console (`~/.plan2code/console/<version>/`, whose Help shows it), so after a bump run `npm run build:skills` or `npm test` (`--verify-skills`) fails. The installer displays the version from `version.json` in its header. All three files (`CHANGELOG.md`, `version.json`, `package.json`) must always show the same version number. The desktop app carries it too (under `plan2code-app/`: `package.json`, `package-lock.json` with two lines, `src-tauri/tauri.conf.json`, `src-tauri/Cargo.toml`, `fake-agent/Cargo.toml`, and `Cargo.lock`'s `plan2code-app` and `fake-agent` entries): `node scripts/check-versions.mjs [--tag vX.Y.Z]` compares those, `version.json`, `package.json`, `CHANGELOG.md` and README's line (twelve places in all), `npm test` runs it first on this tree, and the release workflow runs it before building.
- **CHANGELOG ordering:** Entries in `CHANGELOG.md` must be in reverse-chronological order — newest version at the top, oldest at the bottom. New entries are always inserted immediately after the file header. - **CHANGELOG ordering:** Entries in `CHANGELOG.md` must be in reverse-chronological order — newest version at the top, oldest at the bottom. New entries are always inserted immediately after the file header.
- **CHANGELOG house format is not Keep a Changelog:** version headings are `## vX.Y.Z` — with a `v` prefix and **no date**. The release date is recorded only in `version.json`'s `releaseDate`. Category headings carry emoji: `### ✨ Added`, `### 🔧 Changed`, `### 🐛 Fixed`, `### 💥 Breaking`, `### 🗑️ Removed`, `### 📚 Documentation`. Older entries contain one-off variants (`🎁 Added`, `📦 Updated`, `📝 Documentation`, `🏎️ Improved`, `🧪 Testing`) — do not introduce new ones. The `.claude/skills/plan2code-changelog/` skill automates version selection and formatting; use it rather than hand-rolling an entry. - **CHANGELOG house format is not Keep a Changelog:** version headings are `## vX.Y.Z (YYYY-MM-DD)`, with a `v` prefix and the release date from `version.json`'s `releaseDate` (headings before 3.1.0 have no date and are not backfilled; `check-versions.mjs` reads the number only). A minor release opens with a three-bullet `### Highlights`, sections run Added, Changed, Fixed, game changes sit under one `Activities` line and tooling and test lines under `For contributors`. Category headings carry emoji: `### ✨ Added`, `### 🔧 Changed`, `### 🐛 Fixed`, `### 💥 Breaking`, `### 🗑️ Removed`, `### 📚 Documentation`. Older entries contain one-off variants (`🎁 Added`, `📦 Updated`, `📝 Documentation`, `🏎️ Improved`, `🧪 Testing`) — do not introduce new ones. The `.claude/skills/plan2code-changelog/` skill automates version selection and formatting; use it rather than hand-rolling an entry.
- **PowerShell mangles the CHANGELOG emoji:** `Get-Content` / `Select-String` render the `###` heading emoji as `?` under the default Windows console encoding, so a heading audit done that way reports garbage. Read `CHANGELOG.md` with a file-read or grep tool instead. - **PowerShell mangles the CHANGELOG emoji:** `Get-Content` / `Select-String` render the `###` heading emoji as `?` under the default Windows console encoding, so a heading audit done that way reports garbage. Read `CHANGELOG.md` with a file-read or grep tool instead.
- **`.claude/skills/` is tracked:** a new repo-local skill only needs `git add` (see Architecture → Repo-Local Skills). A correction that is a workflow belongs there as a skill, linked from AGENTS.md, not as a Failure log line. - **`.claude/skills/` is tracked:** a new repo-local skill only needs `git add` (see Architecture → Repo-Local Skills). A correction that is a workflow belongs there as a skill, linked from AGENTS.md, not as a Failure log line.
- **Workflow file character limit:** All `src/plan2code-*.md` files (and the dashboard prompt `src/plan2code.md`) must be ≤ 20,000 characters (about 5k tokens, the usual Agent Skills guidance for a SKILL.md body). A husky pre-commit hook enforces this, and `plan2code-metrics` (`improver.ts`, `applier.ts`) applies the same number to proposed prompt edits, so change them together. History: 11,000 originally (headroom under Windsurf's old 12,000-char limit for platform-specific files, gone since 2.1.0's single-format build), 11,500 in 2.4.0, 20,000 in 2.4.1. The limit is now a prompt-size discipline only: the whole SKILL.md loads on every invocation while references load on demand, so situational detail still belongs in a reference file, and anything with one correct answer belongs in a script (see Skill scripts in the architecture doc). - **Workflow file character limit:** All `src/plan2code-*.md` files (and the dashboard prompt `src/plan2code.md`) must be ≤ 20,000 characters (about 5k tokens, the usual Agent Skills guidance for a SKILL.md body). A husky pre-commit hook enforces this, and `plan2code-metrics` (`improver.ts`, `applier.ts`) applies the same number to proposed prompt edits, so change them together. History: 11,000 originally (headroom under Windsurf's old 12,000-char limit for platform-specific files, gone since 2.1.0's single-format build), 11,500 in 2.4.0, 20,000 in 2.4.1. The limit is now a prompt-size discipline only: the whole SKILL.md loads on every invocation while references load on demand, so situational detail still belongs in a reference file, and anything with one correct answer belongs in a script (see Skill scripts in the architecture doc).
@@ -30,7 +30,7 @@
- **Web console oversized bodies:** `readBody()` and `readRaw()` (the `POST /upload` reader) in `routes.mjs` drain the rest of the body past `MAX_BODY` instead of calling `req.destroy()`, so an oversized body gets a 413 rather than a connection reset, and memory still stays capped. A new body reader must drain the same way. - **Web console oversized bodies:** `readBody()` and `readRaw()` (the `POST /upload` reader) in `routes.mjs` drain the rest of the body past `MAX_BODY` instead of calling `req.destroy()`, so an oversized body gets a 413 rather than a connection reset, and memory still stays capped. A new body reader must drain the same way.
- **Web console commands are tied to the directory `open` ran in:** `console.mjs` finds a running server through a handle file under a hash of the project directory (`handleFile(project, sid)` → `runtimeDirFor(project)` → `<RUNTIME_DIR>/<cwdHash(project)>/<sid>.json` in `sessions.mjs`, with `RUNTIME_DIR` = `os.tmpdir()/plan2code-console` (`-<uid>` on Linux and macOS, a 0700 folder with 0600 handles), or `$PLAN2CODE_CONSOLE_HOME/runtime`), and the project is the working directory of `open` / `open --resume`. Run `status`, `chat`, `wait` and `stop` from that same directory. From anywhere else `status` says `live: false`, `chat` / `wait` report `server-gone` (exit 20) and `stop` stops nothing, while the server is in fact still running. It is easy to mistake for a crash when a scratch session is opened from the repo and then driven from its session folder; check `server.log` and `events.ndjson` (a real exit writes an `exit` event or a stack) before chasing one. - **Web console commands are tied to the directory `open` ran in:** `console.mjs` finds a running server through a handle file under a hash of the project directory (`handleFile(project, sid)` → `runtimeDirFor(project)` → `<RUNTIME_DIR>/<cwdHash(project)>/<sid>.json` in `sessions.mjs`, with `RUNTIME_DIR` = `os.tmpdir()/plan2code-console` (`-<uid>` on Linux and macOS, a 0700 folder with 0600 handles), or `$PLAN2CODE_CONSOLE_HOME/runtime`), and the project is the working directory of `open` / `open --resume`. Run `status`, `chat`, `wait` and `stop` from that same directory. From anywhere else `status` says `live: false`, `chat` / `wait` report `server-gone` (exit 20) and `stop` stops nothing, while the server is in fact still running. It is easy to mistake for a crash when a scratch session is opened from the repo and then driven from its session folder; check `server.log` and `events.ndjson` (a real exit writes an `exit` event or a stack) before chasing one.
- **Windows temp paths in web console tests:** `os.tmpdir()` can be an 8.3 short path (`C:\Users\JUSTIN~1.PAR\...`), while `server.mjs` canonicalizes its session dir with `fs.realpathSync.native` to the long form. Any test comparing a server-returned path (e.g. an upload's `path`) against the test's `session` must pass the test side through `fs.realpathSync.native()` first, and compare case-insensitively on Windows. - **Windows temp paths in web console tests:** `os.tmpdir()` can be an 8.3 short path (`C:\Users\JUSTIN~1.PAR\...`), while `server.mjs` canonicalizes its session dir with `fs.realpathSync.native` to the long form. Any test comparing a server-returned path (e.g. an upload's `path`) against the test's `session` must pass the test side through `fs.realpathSync.native()` first, and compare case-insensitively on Windows.
- **Web console assets:** `computeExpectedSkills()` copies references as `Buffer`s, so binary files are fine. Adding a `public/` file needs the three edits in Architecture → Web Console. The vendored `marked.esm.js` sha256 is in `.readme/web-console.md`. - **Web console assets:** `computeExpectedSkills()` copies references as `Buffer`s, so binary files are fine. Adding a `public/` file needs the three edits in Architecture → Web Console. The vendored `marked.esm.js` sha256 is in `.readme/web-console-internals.md`.
- **The default highlight color lives in two places:** changing it means editing `DEFAULT_ACCENT` in `public/palette.js` and the light, system-dark and explicit-dark `--accent*` values in `public/styles/tokens.css`. No test ties them together. - **The default highlight color lives in two places:** changing it means editing `DEFAULT_ACCENT` in `public/palette.js` and the light, system-dark and explicit-dark `--accent*` values in `public/styles/tokens.css`. No test ties them together.
- **Reference file sizing guideline:** Files in `src/plan2code-*-references/` directories target ~100-200 lines each (soft guideline; evaluate splitting above 300). They are NOT subject to the 20,000 character limit. The pre-commit hook (`validate-char-count.js`) only checks `src/plan2code-*.md` flat files — subdirectory contents are automatically excluded. - **Reference file sizing guideline:** Files in `src/plan2code-*-references/` directories target ~100-200 lines each (soft guideline; evaluate splitting above 300). They are NOT subject to the 20,000 character limit. The pre-commit hook (`validate-char-count.js`) only checks `src/plan2code-*.md` flat files — subdirectory contents are automatically excluded.
- **The splitting guideline has a hard ceiling — reference files cannot always be split:** each new reference costs the orchestrator a `Read references/<file>.md` line plus its fallback blockquote (~150-200 chars), which adds up across a prompt's 20,000-char budget. When a reference legitimately exceeds 300 lines (e.g. `plan2code-0-pathfinder-references/chart.md`), that is an accepted trade-off, not an oversight. Nested folders under `-references/` work: `references/` is the real path on every agent. - **The splitting guideline has a hard ceiling — reference files cannot always be split:** each new reference costs the orchestrator a `Read references/<file>.md` line plus its fallback blockquote (~150-200 chars), which adds up across a prompt's 20,000-char budget. When a reference legitimately exceeds 300 lines (e.g. `plan2code-0-pathfinder-references/chart.md`), that is an accepted trade-off, not an oversight. Nested folders under `-references/` work: `references/` is the real path on every agent.
+8 -3
View File
@@ -49,6 +49,11 @@ node scripts/bench-web-console.mjs [--runs 7] [--workflow dashboard]
# PLAN2CODE_TEST_BROWSER=chrome|msedge forces which browser the page tests and these scripts use # PLAN2CODE_TEST_BROWSER=chrome|msedge forces which browser the page tests and these scripts use
node scripts/capture-screenshots.mjs # every screen node scripts/capture-screenshots.mjs # every screen
node scripts/capture-screenshots.mjs --only dashboard # one screen (dashboard-utilities scrolls to the utility cards) node scripts/capture-screenshots.mjs --only dashboard # one screen (dashboard-utilities scrolls to the utility cards)
# After a full capture, rebuild what the landing page derives from it (hero 1280px variants, the 1200x630
# social card) and, until the owner has real desktop app pictures, the labeled placeholders (never overwrites a real file)
node scripts/make-site-images.mjs
node scripts/make-social-card.mjs
node scripts/make-app-placeholders.mjs
# Compare every element's computed style on every screen before and after a stylesheet change # Compare every element's computed style on every screen before and after a stylesheet change
# (dev-only, not in npm test): take a baseline first, then compare after each move # (dev-only, not in npm test): take a baseline first, then compare after each move
@@ -137,14 +142,14 @@ The root `npm test` does not run the metrics or bot vitest suites; run them in t
## Non-Interactive Flags ## Non-Interactive Flags
`install.js` takes no arguments for normal use, but exposes two build hooks and the non-interactive update. Any argument other than these three (when none is present) exits 1 with usage; extra arguments beside `--build-skills` or `--verify-skills` are ignored, while `--update` must be the only argument. `install.js` takes no arguments for normal use, but exposes two build hooks and the non-interactive update. Any argument other than these three (when none is present) exits 1 with usage; extra arguments beside `--build-skills` or `--verify-skills` are ignored, while `--update` takes only `--force` beside it.
| Flag | Action | | Flag | Action |
|------|--------| |------|--------|
| `--build-skills` | Regenerate `skills/` from `src/`, pruning stale skills and reference files | | `--build-skills` | Regenerate `skills/` from `src/`, pruning stale skills and reference files |
| `--verify-skills` | Diff local `skills/` against `src/`; exits 1 on drift. Diagnostic only, the installer rebuilds anyway | | `--verify-skills` | Diff local `skills/` against `src/`; exits 1 on drift. Diagnostic only, the installer rebuilds anyway |
| `--update` | No menu: reinstall what `~/.plan2code/install.json` lists (skills, launcher, app, statusline; metrics and bot only when run from a git checkout, since they run from the install folder, which npx's cache is not), never uninstalling; with no record, the skills and the `plan2code` command. `plan2code update` runs it through npx | | `--update [--force]` | No menu: reinstall what `~/.plan2code/install.json` lists (skills, launcher, app, statusline; metrics and bot only when run from a git checkout, since they run from the install folder, which npx's cache is not), never uninstalling; with no record, the skills and the `plan2code` command. Compact output: `Updating <old> -> <new>` from the record's version (or `Already on <new>`, which stops unless `--force`), each piece's own output held back (`captureOutput()`) and shown only for a warning or a failure, one summary with human piece names (`PIECE_LABELS`), the release notes link and the restart hint; a failed update also prints `plan2code update --tag v<old>`. A failed update, or one whose desktop app was kept because the release has no app file yet, puts the old version back on `install.json`, so the next update (the app's Update and restart included) runs instead of stopping at Already on. `plan2code update` runs it through npx, pinned to the newest `vX.Y.Z` tag the launcher finds with update-check.mjs's `git ls-remote` pick (`--main` takes the tip of `main`, `--tag <ref>` any ref, `--force` is passed on; `PLAN2CODE_LS_REMOTE_FILE` replaces the git call in tests) |
| `--uninstall [--yes] [--purge]` | No menu: confirm y/N (`--yes` skips it), run `uninstallAll()` (the menu's U sequence: skills, dev tools, status line, `plan2code` command, desktop app), then ask whether to also delete `~/.plan2code` (`purgeData()`; `--purge` says yes without asking, `--yes` alone keeps the data). `plan2code uninstall [--yes] [--purge]` runs it through npx | | `--uninstall [--yes] [--purge]` | No menu: confirm y/N (`--yes` skips it), run `uninstallAll()`, then ask whether to also delete `~/.plan2code` (`purgeData()`; `--purge` says yes without asking, `--yes` alone keeps the data). `uninstallAll()` is driven by the pieces `install.json` records plus a quiet probe for strays (`UNINSTALL_STEPS`, `UNINSTALL_PROBES`), prints one line per piece actually removed, falls back to deleting the `plan2code*` folders under `~/.agents/skills` when the skills CLI is unreachable, and removes the versioned console folders and `console-dir` (`removeConsoleFolders()`, stopping a running console first). What stays in `~/.plan2code` is listed by name with its size (`listKeptData()`), and the run always ends with the Removed / Could not remove / To finish block (`printUninstallReport()`). Deleting the data also removes the app's webview data outside `~/.plan2code` (`appWebviewDirs()`, `purgeAppWebview()`), and a running app is named before anything is removed (`appRunning()`). `plan2code uninstall [--yes] [--purge]` runs it through npx |
## How the Installer Works ## How the Installer Works
+7 -3
View File
@@ -97,10 +97,14 @@ Read the current `CHANGELOG.md` on the branch. Look for:
### Step 5 — Draft or fix the CHANGELOG entry ### Step 5 — Draft or fix the CHANGELOG entry
**If no entry exists**, draft a new one based on the commits and changed files. Match this repo's house format exactly — a bare `## vX.Y.Z` heading with **no date**, emoji `###` headings from the Step 2 table, and a blank line between bullets: **If no entry exists**, draft a new one based on the commits and changed files. Match this repo's house format exactly: a `## vX.Y.Z (YYYY-MM-DD)` heading with the release date (take it from `version.json`'s `releaseDate`, or today's date for an entry not yet released; older headings have no date and stay as they are), emoji `###` headings from the Step 2 table in the order Added, Changed, Fixed, and a blank line between bullets. The format going forward:
- A minor release opens with a `### Highlights` block of exactly three plain-language bullets, before Added.
- Game changes sit under one `Activities` line.
- Tooling and test lines go under a `**For contributors**` bullet group at the end of the section.
```markdown ```markdown
## {computed-version-with-v-prefix} ## {computed-version-with-v-prefix} ({release-date})
### ✨ Added ### ✨ Added
@@ -142,7 +146,7 @@ This keeps `package.json`, `version.json`, and `CHANGELOG.md` in lockstep so `np
- Never create a version entry without checking main first — the whole point is to derive the version from main's current state - Never create a version entry without checking main first — the whole point is to derive the version from main's current state
- Always present changes before writing — the user should see and approve the CHANGELOG entry - Always present changes before writing — the user should see and approve the CHANGELOG entry
- Match the existing file's format — `## vX.Y.Z` with no date, emoji `###` headings. Do not introduce Keep a Changelog's `## [x.y.z] - date` style - Match the file's format: `## vX.Y.Z (YYYY-MM-DD)` (older headings carry no date; do not backfill them), emoji `###` headings. Do not introduce Keep a Changelog's `## [x.y.z] - date` style
- Write for someone reading the release notes, not for someone reading the diff — say what the change lets them do - Write for someone reading the release notes, not for someone reading the diff — say what the change lets them do
- If multiple change types exist (Added + Changed), use multiple headings under the same version - If multiple change types exist (Added + Changed), use multiple headings under the same version
- `version.json`'s `releaseDate` is today's date, i.e. when the release is being prepared, not when the work started - `version.json`'s `releaseDate` is today's date, i.e. when the release is being prepared, not when the work started
@@ -21,7 +21,7 @@ Run from the repo root (the folder holding `install.js` and `src/launcher/`). Ru
### Step 2 — Read the current files ### Step 2 — Read the current files
Read `src/launcher/models.json`. It has five keys: `_note` (a string), `claude`, `devin` and `codex` (each an array of `{ "id", "label" }`) and `strengths` (an object, see Step 4c). Keep the `_note` text exactly as read — Step 9 writes it back verbatim and the Validation rules check it. Read `src/launcher/models.json`. It has five keys: `_note` (a string), `claude`, `devin` and `codex` (each an array of `{ "id", "label" }`) and `strengths` (an object, see Step 4c). A `label` is the description only, never the id or a name ahead of a gloss: `{ "id": "sonnet", "label": "latest Sonnet" }`, not `"Sonnet, latest Sonnet"` or `"sonnet (latest Sonnet)"`. The launcher's model menu prints the id in a padded column with the label beside it, and the console and the desktop app show the id next to it too, so a label that repeats the name shows it twice. Devin's and Codex's labels are the display name the vendor uses (`Claude Opus 5.5 Low`), which is their description. Keep the `_note` text exactly as read — Step 9 writes it back verbatim and the Validation rules check it.
Read `src/launcher/agents.json`. It has `schema` (currently `1`) and `agents`, a list of entries. Each entry carries `id`, `name`, `kind` (`builtin` or `template`), `command`, `prompt`, `args`, `bypassArgs`, `modelArgs`, and optional `note`. A `builtin` entry also carries `installUrl`, `install` (lists under `win`, `mac` and `linux`, each `{ label, run, note? }`) and `installDirs` (the same OS keys). Keep the file's shape and order exactly as read. Read `src/launcher/agents.json`. It has `schema` (currently `1`) and `agents`, a list of entries. Each entry carries `id`, `name`, `kind` (`builtin` or `template`), `command`, `prompt`, `args`, `bypassArgs`, `modelArgs`, and optional `note`. A `builtin` entry also carries `installUrl`, `install` (lists under `win`, `mac` and `linux`, each `{ label, run, note? }`) and `installDirs` (the same OS keys). Keep the file's shape and order exactly as read.
@@ -80,7 +80,7 @@ For `models.json`, compare the discovered list with the current one by `id` and
- **added:** offered by the CLI, not in the file. - **added:** offered by the CLI, not in the file.
- **gone:** in the file, no longer offered. - **gone:** in the file, no longer offered.
- **relabeled:** same `id`, a better or changed label. Propose a label in the file's existing style. - **relabeled:** same `id`, a better or changed label. Propose a label in the file's existing style: the description only (see Step 2), never repeating the id.
For `agents.json`, show one table with one row per changed field: For `agents.json`, show one table with one row per changed field:
@@ -137,7 +137,7 @@ Check every rule before `npm test` (Step 10). They mirror the shipped-file tests
- `_note` is present and unchanged from what Step 2 read. - `_note` is present and unchanged from what Step 2 read.
- `claude` and `devin` are both non-empty arrays; `codex` is an array (empty is allowed). - `claude` and `devin` are both non-empty arrays; `codex` is an array (empty is allowed).
- `devin` has at most 30 entries. - `devin` has at most 30 entries.
- Every entry in `claude`, `devin` and `codex` has a non-empty string `id` and a non-empty string `label`. - Every entry in `claude`, `devin` and `codex` has a non-empty string `id` and a non-empty string `label`, and no label is a name followed by a gloss (`Sonnet, latest Sonnet`); `scripts/test-launcher.mjs` checks this too.
- Ids are unique within each list, and labels are unique within each list. - Ids are unique within each list, and labels are unique within each list.
- No Devin id ends in `xhigh`, `max`, `fast` or `priority`. - No Devin id ends in `xhigh`, `max`, `fast` or `priority`.
- Every `strengths` row names a `model` that is in that agent's list in the same file, uses only the words `thrifty`, `balanced` and `best`, and no agent other than the ones already under `strengths` gains a mapping. - Every `strengths` row names a `model` that is in that agent's list in the same file, uses only the words `thrifty`, `balanced` and `best`, and no agent other than the ones already under `strengths` gains a mapping.
+26 -3
View File
@@ -30,7 +30,7 @@ git pull origin main
Read all three files at the repo root and extract each version: Read all three files at the repo root and extract each version:
- `CHANGELOG.md` — parse the first `## vX.Y.Z` heading. Strip the leading `v` → `$CHANGELOG_VERSION`. Note: plan2code CHANGELOG headings are `## vX.Y.Z` (v-prefixed, **no** date and **no** brackets) — different from a `## [x.y.z] - YYYY-MM-DD` format. - `CHANGELOG.md` — parse the first `## vX.Y.Z` heading. Strip the leading `v` → `$CHANGELOG_VERSION`. Note: plan2code CHANGELOG headings are `## vX.Y.Z`, optionally followed by ` (YYYY-MM-DD)` (v-prefixed, **no** brackets; older headings have no date), different from a `## [x.y.z] - YYYY-MM-DD` format. The date is not part of the version.
- `version.json` — the `version` field → `$VERSION_JSON`. Also read its `releaseDate` field → `$RELEASE_DATE` (informational only — shown at the confirm step, never part of the sync gate; use `(none)` if absent). - `version.json` — the `version` field → `$VERSION_JSON`. Also read its `releaseDate` field → `$RELEASE_DATE` (informational only — shown at the confirm step, never part of the sync gate; use `(none)` if absent).
- `package.json` (root) → the `version` field → `$PACKAGE_JSON`. - `package.json` (root) → the `version` field → `$PACKAGE_JSON`.
@@ -80,7 +80,30 @@ If `$CHANGELOG_VERSION` > `$RELEASE_VERSION`, compute:
- `tag = "v$CHANGELOG_VERSION"` - `tag = "v$CHANGELOG_VERSION"`
- `title = "v$CHANGELOG_VERSION"` (plan2code keeps the `v` prefix in release titles) - `title = "v$CHANGELOG_VERSION"` (plan2code keeps the `v` prefix in release titles)
- `notes` = the header line `# What's New 🎉`, then one blank line, then `$SECTION` verbatim (`$SECTION` already starts with the `## vX.Y.Z` heading). Build this as a real multi-line string with **actual newlines** — the `\n\n` shorthand shown elsewhere means "a blank line," never the literal two-character sequence `\` + `n`. Getting this wrong would run the header and the first CHANGELOG heading together with a stray `\n\n` in the published body. - `notes` = the header line `# What's New 🎉`, one blank line, the **fixed header** below (with `$CHANGELOG_VERSION` filled in), one blank line, then the **highlights**, one blank line, then `$SECTION` verbatim (`$SECTION` already starts with the `## vX.Y.Z` heading). Build this as a real multi-line string with **actual newlines** — the `\n\n` shorthand shown elsewhere means "a blank line," never the literal two-character sequence `\` + `n`. Getting this wrong would run the header and the first CHANGELOG heading together with a stray `\n\n` in the published body.
**The fixed header** (the same on every release, so a visitor to the release page finds the install and update commands and the right file without reading the changelog):
````markdown
**Install:** `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release`
**Update:** `plan2code update`
The installer downloads the right app for your system and puts it in place for you, so you only need the files below for a manual download.
| Your system | File |
| --- | --- |
| Windows (64-bit Intel or AMD) | `plan2code-app-$CHANGELOG_VERSION-windows-x64.exe` |
| macOS (Apple silicon) | `plan2code-app-$CHANGELOG_VERSION-macos-arm64` |
| macOS (Intel) | `plan2code-app-$CHANGELOG_VERSION-macos-x64` |
| Linux (64-bit Intel or AMD) | `plan2code-app-$CHANGELOG_VERSION-linux-x64` |
| Any system: check a download | `plan2code-app-$CHANGELOG_VERSION-SHA256SUMS.txt` |
The app files are not code-signed. See [the desktop app guide](https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md#the-app-is-not-code-signed) for what your system may ask and how to answer.
````
Check the install command against the README's "See it" line before publishing; if it has changed, the README wins.
**The highlights** (written fresh for each release, from `$SECTION`): a `### Highlights` heading and exactly three bullets, each one plain sentence about what a person can now do or no longer trips over (no file names, no internal terms). The full list follows below them. When `$SECTION` already opens with its own `### Highlights` block (the changelog format from 3.1.0 on), reuse those bullets as they are: add no second Highlights block.
Present all three to the user and wait for an explicit answer before any write. Offer the optional decorative title suffix — a plain `vX.Y.Z` title is the default, but a release may append one (e.g. `v1.14.0 - 🔍 Review workflow`): Present all three to the user and wait for an explicit answer before any write. Offer the optional decorative title suffix — a plain `vX.Y.Z` title is the default, but a release may append one (e.g. `v1.14.0 - 🔍 Review workflow`):
@@ -105,7 +128,7 @@ If the user supplies a suffix, set `title = "v$CHANGELOG_VERSION " + <suffix>` (
### Step 9 - Publish (on approval) ### Step 9 - Publish (on approval)
The release is created by the `release-app` workflow, **last**, not by this skill. The workflow builds the app on four systems, attaches every file to a draft release, and only then publishes it, so the `vX.Y.Z` tag (which the app's update check watches) never exists before its binaries do. Creating the release here with `gh release create` would put the tag up first and leave users offered an upgrade with nothing to download. Do not do that. The release is created by the `release-app` workflow, **last**, not by this skill. The workflow builds the app on four systems, attaches every file to a draft release, and only then publishes it, so the `vX.Y.Z` tag (which the app's update check watches) never exists before its binaries do; its last step then fast-forwards the `release` branch (what the README installs from) to the new tag, and fails loudly if the tag is not ahead of the branch. Creating the release here with `gh release create` would put the tag up first and leave users offered an upgrade with nothing to download. Do not do that.
On approval, write `$notes` to a temp file, never inline (multiline text on the command line is a quoting bug). `$notes` must already hold **real newlines** (per Step 8) because `printf '%s'` / `WriteAllText` write it byte-for-byte, and the file MUST be **UTF-8** because the notes contain emoji. Then start the workflow on `main`, passing the file as the `notes` input (`-F key=@file` reads the file's contents): On approval, write `$notes` to a temp file, never inline (multiline text on the command line is a quoting bug). `$notes` must already hold **real newlines** (per Step 8) because `printf '%s'` / `WriteAllText` write it byte-for-byte, and the file MUST be **UTF-8** because the notes contain emoji. Then start the workflow on `main`, passing the file as the `notes` input (`-F key=@file` reads the file's contents):
+1 -1
View File
@@ -1 +1 @@
U0VOQwFdv/msSzIgNJjIPVQnlajSdprE48RetOzVyO7JYBHOdjRWja5mP7oOgtMJT6qPSEayYma+SNICMFLBj0juEV93RcOKDiIgcjBIfj2Psj5v524CDy7CersjOxgYF3mDSMroPjyJM/Ax4KNTpupCd4jwGxykCM+tGCtqUN6XoyHbfYLIq1Rx6Bk5dgtsCfc324J2NCsIJHumcZ2rAkqOf+RfTsbTdaJTiyNC3YNwXAEUbVNRBQM/MnYpIResmnoVyJCt6V9JZ1oT8pnoZ+rga49fu/hG8A9uvAeUAjtVMP8Wz4ks6Yer3kubiofEWo4swXdh4Vimd+X9oLv40/oFdcOBGpJRua5+OdKhiKfMBDnCYlHkgf3pxFY+81CUcCeXAuVmmUive9rNtKZaUGQ7/v0U++ZbEMO1Udiewq/wuN4AzU3vsIbbLXI+OUL2zo1fMjWAxVxc8hIMD6U8g8xNstznKvc2dE/1CTXIWwgL+45BiHn7sOQDs/WVdUkR8srM4jYlcraz4Z07+LWLsmkiqxGH4Y8r8zg+S7kwEHID51YEofJ70lDW3P/rX5OoHPNeu8azIbdlYZJV0FIPtmMDF0gNg9doZJVa33IsSN6n+Wg+673ZTOV5nROJbk7bWuyY6WjMHrIZ99vb2XqfcBOTe62J8sa5TXNFL4qx3h+eCQg/xQg/GiVeluiE4a37woqM8FPpHcxZNIgtGjSucx+Yg21zkAQfGVwAnLtzXmaTjpw7IQUzHdmmhp7jVRS6SX7E0o9wf70jsQ+g8wXNhfHCCmiM3l16AzWk6oTmZmDiMpIIHPlkhZmCOroxNXE3Cioo5DDH9AgR3h0hWBLjCEubPg1GQNmMHwe3vk+wmZxbrfkGNhFBPgmA6XIxmjAGpxh5kbw2ItQCBbHleo8dwgp7BM6gfUG9KfexlVeLFY2XwZJ6Fim/onqT0qU/TeccZKxiuBMGe6p6ODQ6UdXpgzFtgU6d0xVEuc/wUvXlo9ooMxo+R94pLSlc9P9qQyuLi6tSyBLQCV7uJoMNPIPixJtGERNLsATPAD14wjux2AVQ5vpIGqBPcp1oyBzWrGLtFkY76ePcebGlImuro5hov7dq/F73Hc16HVhRZHGb471nUt7g+Mh1wiwClEtK2PDVbnTQTTOqxthg+WRYmCiv9BQHtNKuAriQjcbNh4b+7QMe8txCnhzSB7Lm3XPMvHDc8F2BRyNLpYs01RvxP9THCdssE32ZaXBHJKNaO6XCpxD59mvadPsT1pwxEevq9K5lgEsP7iJK36kEutiO4k5G65RMVr5CNngOPhBSNxUHeccnm4AOmbOryvGmbIglCD4+L2Eh9LiWqjmw5EkCkJfwrrRW9QqoVP/6IDKa5e7TafRVJEyLkhOWeqFad9z9ias85eiOzHu48wmNgzUxBIIWOzi/ByWY+kguBLPuDGhTxJFtZyWSn23/FeJPMlIR+oA7N/frxGg9Xb+utdfTdXEUSPFQGzO+PeSSm8fmKYMzXCnZlhn/njqdwiwAtSgSzWGLjRgXtRT65cKtKmzyFKanGHT2wUc0XbjB6cxhJZQfKTnmHLz+42hDBof4cKZMMicu0+3pmYYMxOiv9OMyLFqJi4yrhXxK1m/t7dT18HBAM2h6cqYMQ2ozMSNdasx1bE4lOED2EZ1ShS6OQB/aNjF3MzyxqQpJQABgAoGZd09N8q6y+BZkiT/gvA449HjVr0swCJe3ph43yT+rml0I9GByCU0NmX0P1kfC8M+h03nq0CXIcKFK8/vkgl8mZVXsvDmkTEOZl1ekE+gG634wjErLpx9cyQu6q9u0oqSGOg6VWGOv1xNcyoswK+XQCzXnXciVmR6F9MzEUpe8cyg0HJx/yHmhZqeQS1fxuZ7E7tfEONbff2ABIXk8rEwEEJu87EguIlIpSIPQ7Sr0V0m3+3cJ4S7PygEtyIB4tdES05edjmNb7RoHf3EuC9Tk1z8E+8EWXSqOgJgGLaOdTp3wLqR2m2LFRtJUr1tV5Hkf727F3134Pn0P/2yn7linMlT3G76MyuOPt3r4hCKD8mnyQgDgWmekCqOyQJHKvCqx0yyP+ROzSan9k4XeEfHIFUYB76U29oJ5iZcRALU/DdPcItIXLsDYSwn0iNHi8CawIjF9kZ2MykOuunNujIRb2VcO1dAn+utZ52Xgh/vWxKKar47YZYs+bZi74B+3N2V/4gKgegrSZ6NWbAHOYvBP7bFZ6Gzc6TjAJks38GuOe9wezBM7Eflb3ATt7Os1gSLKPK953nI/XZAuk77UZ82Q8z/W7o3/GqpxhI/5v+bFdrWW8uqpFpF0EW3lIWpY3PuLZdo/lPuNUJC6th3HpFpUV9dqA8h2OesYvVxpS/8C4siwD0NZ4I6bYViXtF3H9mhDHHGVWHPW06dfkaKvMRSSN/ZqYS1dCaArQsdd7v1shvdyAex6Uk/e9Nf5/K8AenGAO4QoXhP3GGfB8SrWt+NzRlbhSV4DeEKCXLiM5FKciticpTv5lV9WqPkpM7WlQayEuGTJAIzWciKsF6qz6JbUmZTmv+ImwvQ87wC65g9M2r8QQzT+qH86TPrzrmO+FC03aMBftF9kK5jkvEPyxW0eJj8feFQlpyYU3hoWSoMDKX2jjqTnIpkKiZ0JQJxMdzgSKJKapvDZYO54x39+tAITNmto2pgHxhZLMXScblgyzcnYcTOVVQlDc6baD9ujiEGO6kayKr1MR4PSGxqxW7dFXsInfB13qzzzSUZpbyurhU7QMyuLCx63+1mH70f3AVUkjTs+xdWWipGDQrrqO2beQxDCLNZJsq8XEckLjKEU5mcj9hUiBG0HVkuSyKfgf5xGQv7dWmOiRlly9E7AWAvltrgole0sfucTYRAVePfW4HAuLdpUrD6tOgwcPSO+ipgmfNcyGpRNdTTJR6UzoQoYFfk2U/iBJH9Nm1aRVYAetjtG2IZl/xJbi3buUcvqxN6TnGcHws0J/o5DBqxng6WQ73sfoQuM2BE5Jktw005f00NdwrdwcDc/5+ws8JRruurwkCLjGDanzD6G9T401Rsto65YkId338LjxDL7zMRPmXonEpWfz9Qw3A/dnLPYJbXS8NcKnaOSN1T2FGOkzZjVbiC5QTsGREEnoDAuMOQVdB+WPycU4rhGHoPbtIXXpO5SQNwyKDuNFqVlM9IlYuVeueiOrHm8AUSdZ+vIIQnRUXXA5yxNLRczQeA2r0nJCxmEvPoWePp6g5AXV3NWyBAMVWJBW7paFmePTVjpfRKa1URLQg6gh34YABPGsnhv6UksQXj9v/9oF9Tts2yLx9kRMjLZgdWFRoGJIoexi9IlIzPmTd32ftVd545lQw34W55657qeh1HHc6pSsNELQCLM6KLz+FHzXSEij6tGyFwOAyyPuofH+fhlRez2LR572fbG691Mq9iWOc7PM7TjPPE0m61GiLK0fJkwPqWw1K4wsblrLnpw+wUjZZW3UBXU20GHg8Okl5f9ukRKhrs/uksD88wdUElJRMRsJ+pfcLxRbh2esO1oGNUZ7ymLjunrIOTMhDZyzgtOrsE+/SiA0dc/SfXVCUO8jTjHQAyzXQWhMt//7eEdhEpj8Xk0ET+cc/Xx0kRuqINskclmZKPRmQ59TStRTF+j3lueNEphjVPnlJh/zghhlWmf/+CJ8ctzWrlJeqluTwHBd94Oh9GpJA03OBVg/NW+dtQY2QkR0Xe7L+ttJZwOhu89r0hoibcjJi5mWFP1UT3BvCJjdLNrx1ZCt5qEz84JAOVu1venIBWYKmEx4E5rXvXbpWnfODX5CdmLM0zeXxMxY3qVezXEUGh4ccBvj898XMGumkp3q7ohlWaK9DI5h3N/ZSHHF7/krmlPGVuG3xAzLVZdd2Q0yrOa1WxdV7HBOfvJpa0GsHSSxDd/sOaVgRMTEgpQdBVsqQQriQ/zM16NjliaC+IUSpOMlUtHu7OUCkNXQVODmvxDREvIQ6mKVfBi+ymQX29zjXnsurN/UG+CwEb0uGwcY39MKcAHzspMnwJUPm+zqJmfRHpN26BhOzYIVFmw6x7FZuuiE224XSm/ByyyUtEalYRJjHi2eYYktN9hpQTCNrPQtzQkVv79TMbxAIPFcKW6loYQo/HrxleiWvWEvF/vAB22pZARMm97zRHgV15JSF61s0KOlGnasGTghCe2jxr/b4f2kpEacoUHiDX959hzsgw4FgXpLLvT4HWD65Yh/9lvKYy2wxpJ12P8PNavlgxjjQH1g7Io9CwlsliS0Rz75aFXzYXYvnEOgMMr3zYhpR2Kpk6OAlt5+BUfso5BioB1RS/xSlGi5Hrkk0SN8iSdp76ChmIcmb6I9yi9rDtBxVvoKT0w/KAbxfuldD1Lu0EoubDqWnW6YdlnHuahMLiEnOIOzE+yEp7ESHz3wqNVQF+o9ElWZ6+X85mRDtfGD+rn4nUMmgqK8cWkBaFXsTmyrW7/INyt6jGgMwq9nLjNa0KY3H6RLAHje40YszdAWwRqVxlo4A8FabBHyfH29p/0zyJtFpbvDt9BiG9ZkbmQJT2lCj9Z/AXTpV9Z67PhHIZg2jhE/5pUaC7oU2Yj+9B3Zd1NUtM6HUK9DJY06W+qFFIA48x/T+ZoiG4/EydXiihgfza9ufgNCsVbLNjeSsqfPy4ELr0GDwJ/dKlXNygX1wOHRVC6QTzUN+BveyV+Jp94ArB/NTjlFiJbqi2lskx/PfRi/9PbLQu1PPj/5uJc6WIfXOfSYR/tLwhU/qbSFpmrosvh3sYV5ApWC7rRCamgs8bv5X5gfNUOu8HheArSPfjklEU66rSfG4+la2iXauBUBgDO1VlYVTmGL5fqG6ytAtyMw6IVPJqgkgpJKoJB0eq8lxS3nIFO0LRp1/BTNVlCH7trZQv0wxwJKUk0Udqs3aIdE/lhJvWrK1L7bdRhieqGEn8QhnqxG3NErDuMFy20uo42KX506SlvMag6qxZX54rjbThAtuO8iDbcGy9Line truncated U0VOQwFXeZZ2LQjdLUSSPDZ4vtw/FiDmfXw9fG8bM3nucaLO+T9XQN9U9t3VdtYnGqX/wKp/UefGXZmTT9BatYKzavI8O9yxDFbOkhu2eA8rQ+LfJ3J7H94EeD9GdEoPvoSaW9GJqyBk/zTVcqapukaBllICd/iouX0PzNk0rMOc7yfhsbWuWsYb4q9E/qn5G4SI3n2zOvsaGZqppJPVQMxWAJQvrQhk6VL+8l48ftO9L02hieVdDs8bmLqhTkF19FQkT1DzGuESlMVEcQP546QtAqtXOpTnO7twtXsCpBOguZ/jLArPFh8lAjMsM3/0LQ8WV7i98zKRyCxELlB+BYwz25BRBIUj2uJNRYloXeLuEyVqS+qC/SScOOlY5Oh2oyFcxyZ8K/ESBKai9djOB36/QlrYD69PNOv2Sb39oHcCObPUofzFSGAVydCtQOsc//my+S/aPkNhTtQEsCAwws5AuCPpuQ1UCUHjkNuWfYWOkOGRNHnlbnLjdKTjm/4ggZQYb4jeGAWqPg+da/ZMSn5Bj+ZTiKOk0d4FPQOwZQlkg6vhdNKYRCJRuni2UC3YaY7dLvtKEPcUpjvI6dK40xt3Lt+DY0i+6r6PcUZRVWdq39SyN/nugd++xTRVozLA80/vBgkgWS46qC2n4q3dXZuz2oNOVz5CnZvh7lUkO46/fUjmgJSAJIXlbd8xsuioXd0bAZT7KwYSYQmOQ30QFO7icfxVp9O2HvShP2y7uNVjArC7Ifp2RiHfVT0yaabsai9huP7enYyyIOL8F/klmiN81Zytcp+CT7mBjei6by9Y4mpl9EnVOg5M1THZua5rjxGatG6QDGtjQRFtfg3zGI7LZjpYZ+GpcOdLEQXWUt64RjvFryQnbgioZw0dzqwQLMOmcLTr/0wN6CcNBoKywlDpWD3NdU2J0xfwU+bAA/i8bvWNx0PrJRWXIMHqjOBnIAQWjQ7At1ReQqg+zu8Du2BshrZARUXIzQu9ronANVTaOASe+6KW7rSseqzyX21xsiNppQr5TcPfl07Fg4vhfSvYbNO5KhNuCHzrvvjqiMZGxIAvj5c5PBnoDuVIyp2cwrETGXfCxPHew1ibzC2oRT0dQ3ObR044uOYJ7/prxrccFVrMCDWl8UnWDu5Vj07ktOfS3c7uNZjekvrikA8QPU89Tb1DlWAXpsBb9Kqio5Z+x4BU26FA/bmGPDhWk2QYgPGahpknnVVgBSrOEf7o9JNmw2ARAncIJf300FYJNY2VO8cJ0g4FcRhuMyxFVD/aoVgkVlWDIypJCLacufkCKqbFLlzLUDj9QAeQkMCQwsIDfWOZsF/dlpPTsXUxgp3jxCuXJRr47fkfXxnemBimPtDWf4oqjm3LRE3alFYjT21EeDOrA0Q05JKNWf6wQkZf5beZsk6p14TbkhE91Ip8s8nsFicgK2gAR7LqEoRyNqhVYTrubcQ0b4zeMr+lg/g/NJUAgqYNk4UYDMV4oJJjaCYJ0tABipaafx3eatd83F/zXnpu/F1QlbAgPtuPLf/m+ZR7GWRWRAc89FVjgZec57ST7wSi4LH/15q56B3Oq91DjXWqHzqXYDJROK5iTrxJxGdXb98L1csyc3bSddsxIOKgL0Fw9P6+CMq7PMsw+ZhpMohwM+HQz5UUAvKJaDx9tK9nqZcNF9mYLNAZcz/QCBFkkdxdCLyu0gkcQwaTHmFCcI1ak6WE5Lb0GY8FwuAEMRyqFlzDbVeEYmVw5DvJZ7fkE25HFV/1kvn7/PNlpjeKlSDtdwAA40PUGH4o7N8DWFUACJFuFPJUJynBeCiT0pPX0PEJkvRluj6BB3tHpRTNjy0CTbUUU3O9sSN64Au0ooEHY8wL1VVHZCjHzgGrPV7qppd0KlvSXKZ6mlmFjmI743jzQn+AV+XCwsxIwa3aCLdGDB70mE/m4yrsMobZVL1gOL1gG3WIQu1ShTFxxb8u8/57TvVYKonFLU8Bc74HEYhPtQiE9nI5nGM59Z6KXXURXnmbUNjk/sQu659C2i7jf1F1dSv8ARCmeGvLL7waJ3iAdTn9RYRqxZKPbSOWqh7tAXzkTeaalA54Xw+RNq8QNylJsTYp7/DxyEJZs1MF7ILxZW2Adxud6TnhPXH3r4/ef8LnQHJjVXmcvQcIpnFrkpkeOFsZHYZbsOaPtxO80s77FwiAnFASTxOQz5fv4/SLam/+hoqWDXni42s42Bs1rKg5HloIlsoL28KL4hBeXdwA1IJJH9crmvOhMqPT4dXbHUt5ixs7CcNzHuO9YqcfcktCpi8RJ/0xKgSKh5w51A+GpezVWlwr6GulZADmL6XFNFfiV9QdYDGdcQRcitlpPMAGsvQ+Oed2n7UWuQfrTWFCqBSV+CAkRjgkGk88Oh/MPqBjsYGzpncWrm9bIc/Ub0Puewatjoj7P4c81OZ1eVwMdrXZFWA3qAtW1sTgf144rqkcRf1bZyt0KmCSvLAmrLLyt6BQJAP3JpHyItqkALB51FhYioG2eYlrbI5m5UdNRG7zqTnsko+us+hmb/DZEAwVh0vgwTnsKBVyasItIEznT6hYBOF+63tBOlZWDZJcp7ihhoYSgdz4CZ4pRRSC7fXNqGYGtBd6xbaweFzp6q7VFs7PtvQJuel0WST2GynOoTH+KLanmXnNTD05P9aMip0QJKHUIH8SlQXZn1OsGx31eNyUCmfauyMpc95hxOTu+1Qg5vnZoREX5u57A7DjlMrhKw0wNuj/FuoiLsYw6neLANlTHiJpHaKr2OecR6dRDgzF1uXrJXIhiv9kUM7nOLj4159vBEcgnZNftPXGrcuAwlXcNDFMP44DdXWiD/EkZkI1niksGB9g1J5WMM0ph7Zta4Irn32DkisYydP5oblSmdEB6NNKpOqYeVT+Gsz9Hc32NSPWhiRo4UU+m4rHvccIP35eRCsTFJjeqK578TLC+n9mIdBSahOzHRkJTV0tZydKMsznYuBnb5FTtGW7IzNVfmov5ErJkd3ngeShna19uFG5hkAuwwbx2ueUc9HiMvTlChd5mSrG+NLzXxQxgwWx2RHqMeivBqa0q0a1c/D9fj1LA7L04cnAvMLdLZM/qjNQMIB73udddnATpzmDsVQXW0vbJm/rnQDNUUQmzW4r26mYlPL/xOOIi+17RQKrULGM5ouC80nbXrwn+fH6uJfd9Ub3xkjM6ddqcU7c4r6I/BjRYNc9b31U6Kw395LqtsGyP5m2fjiROM8ddgNhWwVttGLoJ/rl3/eIkRx4Hrx2WISYiUaN4ZleIeBWHTI5uSj4iNEsaBkskZ3HXvpb680bzHAe85a47sN6ncE4X3IawdIvH5ywIpIcku0xj6LlUccgAtZpxO9aXM0d0Dmdb3vKl4QyIB1vmuUkltwBqDNRGtNtMXngP5e/hPNaEE/TCPB69gp177OC/r1GnIrCZSQGou1tCugXqkcfT9uhwCP4eBFpzz/qFM3bi9TArSXYgyuf8fAM0dVsbpmBgp0nBdNrla3/d4SQv5hQ5fLLfv1An6wzkBdM+jj/Bl+W3B0kOWhzvYXR2/5VO3RwuEb8bQgNvNgu7xePdtjwLYFdIsmaue6jTriVeaW3O6rvRWBdeGKhg/a5mVjESfSjI4/YZMIgnbUHrQyO7IR4gV79sKVugDJ/KpAEYDFqKbm0zJf6J1BTqn03Ru+Xy37xgraYOwPByVCM8PbCOxel9RtOeFx33foDEf7+DKOstrS889srVOJpTUY2/kdKt+lDFX1hEm8H6+SAi/ZNU64YMP7qINPBYZIKBDtgpruyGejz8TsxK22knRXL51IAC+eaBzpYo4zL4APio5uEw6jLg3ti7FtOZU76CHzWnfd+30vO0crDbmBK9uwZz6SeR5uBbnr4E9/xU2CuAkV1zKCUBVzJR2dzl95e1bdgHl0s6Qjd/H0RHocvgK623TpFQNHO3lZMAxPw7xR/N+iXvw1UwMChaFLxZMjRtGVKm7aJixsmT9/MoPgWi2OR/ubeYr8nqkVbGmgbQqLrBum+QsZAEW1nFe5g+tsR4NuT0VFDot0gIOVL1Bktk5BoBkPb6yRGXiUJjyWG7ylmwOiqQ5Y7Kvp24j+PbS2XP0ZYSsAiqoSPfl+GtHbTewg59hjVQo5yy8CkZRZCTD1AE+Uf+6H4BG8ZAgC9OcT63qYZqGOi34HOX8B4Y+U19C/ZTRCRf2fUuS2cDhNR4bE9vjxTliZDhsUw7eKFgD0DtTaNZ7X/uSrboyDDudQpRf4vi3Uz9b9PYsMuPt0qDAd3Z2bjkz5GVFnm0Ig2BiRxZ10G6Lm0WeWsqiZiLsfJut6sGajgeayXJlNeP+mvBF36XrVT92j/116WjCzRSsgWRyUZnidgax0A1O4ck3aagka6jJxwA4+MBmEdUkseZLEt8hny/uJJP5wiF+uSx6xer9mkGrvMYrL1zF7JXnPM338xwrS7GCy/H60TRWrnlqV9ZJsWJgZtdecWtp5qFNZQ6pUW/zJlzjDMeMXONAuWdqZKqZj0VC9pW3WkgO/AoObpIPwShi546jr6xOesR0Qzn4oWAwtdBDnuj487E3r/0pIa7H+vnkrcG1cdJPXoifna+O2U4ejWy60zdDtG4NO7Y8Qq8osr3o+BjAra/1ddgOaaLxvV5Sg0wALzkQLTPmO5kwRwNJoRlWyrA5nEte53vfZ3rkU6cg3jw6G/3kGRhdCdWbzfXlOriojszcV8Tdu0Xi1ThpRq1tFJQmnA1nQ8pk3LisntnT8EC+71fpBHHA5z7GOeyStFweJkoFApSerfe3ZOc62sdE4Nr/kgs3b9BPd+Fpd4J7xMeiC3XMeRB6jGAQES89ghu7iSxcGv24emn42h89mstSOT1m+6Jc2WOuhI0djyVaxbMUOKdfoPAD9uKAcdtt/x39Rlad3PA3niLdOwZb6DMWX7+V23N+1OAgUon0bvGhlc3BtlhLQhERg19/0eg5UwJluGhgLH/pROwz+/fRgzf5UOXmoZZ9DLine truncated
+22 -9
View File
@@ -32,20 +32,32 @@ body:
label: Which skill or tool? label: Which skill or tool?
options: options:
- Dashboard (/plan2code) - Dashboard (/plan2code)
- Init / Init Update - Init / Init update
- Pathfinder - Pathfinder
- Plan / Revise Plan - Plan / Revise plan
- Quick Task
- Document - Document
- Implement / Implement + Review - Implement / Implement + Review
- Review
- Finalize
- Handoff
- Web console (page itself)
- Implementation Loop (desktop app) - Implementation Loop (desktop app)
- Finalize
- Quick task
- Review
- X-ray
- Diagnose
- PR Prep
- Test
- Dead Code
- Update dependencies
- UI Prototype
- Git
- Changelog
- Handoff
- Learning
- Activities (the games)
- Web console (page itself)
- The plan2code launcher (command line)
- Installer
- Metrics - Metrics
- Status line - Status line
- Installer
- Other - Other
validations: validations:
required: true required: true
@@ -55,6 +67,7 @@ body:
label: Where were you working? label: Where were you working?
options: options:
- Web console - Web console
- Desktop app
- Terminal - Terminal
- Not sure - Not sure
validations: validations:
@@ -64,7 +77,7 @@ body:
attributes: attributes:
label: Plan2Code version label: Plan2Code version
description: Found in version.json, the installer banner, or at the bottom of the web console's Help dialog. description: Found in version.json, the installer banner, or at the bottom of the web console's Help dialog.
placeholder: "2.4.0" placeholder: "3.1.0"
- type: input - type: input
id: environment id: environment
attributes: attributes:
+10
View File
@@ -1 +1,11 @@
blank_issues_enabled: false blank_issues_enabled: false
contact_links:
- name: Read the docs
url: https://plan2code.jparkerweb.com
about: The guides, the quick reference and the walkthrough.
- name: Desktop app guide
url: https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md
about: Install, start, update and the not-code-signed prompts of the desktop app.
- name: Report a security problem
url: https://github.com/jparkerweb/plan2code/security/advisories/new
about: Report a vulnerability privately, not as a public issue.
+16 -1
View File
@@ -10,7 +10,7 @@ name: release-app
# plan2code-app-<version>-<os>-<arch>[.exe], plus one checksum file # plan2code-app-<version>-<os>-<arch>[.exe], plus one checksum file
# (plan2code-app-<version>-SHA256SUMS.txt). install.js fetches the matching file and checks it # (plan2code-app-<version>-SHA256SUMS.txt). install.js fetches the matching file and checks it
# against that list. Linux ships the plain binary, not an AppImage: docs/desktop-app.md documents # against that list. Linux ships the plain binary, not an AppImage: docs/desktop-app.md documents
# its WebKitGTK 4.1 dependency instead. The first release is unsigned: docs/desktop-app.md says # its WebKitGTK 4.1 dependency instead. The app is not code-signed: docs/desktop-app.md says
# how to allow it. # how to allow it.
on: on:
@@ -187,3 +187,18 @@ jobs:
if [ "$state" = "true" ]; then if [ "$state" = "true" ]; then
gh release edit "$TAG" --draft=false gh release edit "$TAG" --draft=false
fi fi
- name: Move the release branch to this tag
# The README's first install is `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release`, so new users
# get the newest release and never a half-finished main. Last step, after the release is
# public: a failure earlier leaves the branch on the previous release. Fast-forward only
# (no --force), so a tag that is not ahead of the branch fails loudly instead of
# rewinding what people install.
run: |
# The checkout is shallow, and git decides "fast-forward" locally: without the full
# history the branch's old tip is unknown here and the push is refused as "fetch first".
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
git fetch --no-tags --unshallow origin
fi
git fetch --no-tags origin "refs/tags/${TAG}:refs/tags/${TAG}"
sha="$(git rev-parse "refs/tags/${TAG}^{commit}")"
git push origin "${sha}:refs/heads/release"
+57
View File
@@ -1,5 +1,10 @@
# General # General
### A document-level key handler that must ignore typing has to read e.composedPath(): the Markdown editors live in a shadow root, so e.target is their .md-host element, not the contenteditable inside.
- Kind: how-it-works
- About: src/web-console/public/md-field.js, src/web-console/public/screens/core.js
- Noted: 2026-11-17, implement-review
### A new dialog wider than 440px needs max-width: none next to its width, sized like the Notebook dialog (min(1200px, 90vw)); the base .modal caps every dialog at 440px, so a width alone has no effect. ### A new dialog wider than 440px needs max-width: none next to its width, sized like the Notebook dialog (min(1200px, 90vw)); the base .modal caps every dialog at 440px, so a width alone has no effect.
- Kind: correction - Kind: correction
- About: src/web-console/public/styles/learning.css, src/web-console/public/styles/pieces.css - About: src/web-console/public/styles/learning.css, src/web-console/public/styles/pieces.css
@@ -11,17 +16,69 @@
- About: scripts/test-web-console-shape.mjs, .agents-docs/AGENTS-architecture-console-page.md - About: scripts/test-web-console-shape.mjs, .agents-docs/AGENTS-architecture-console-page.md
- Noted: 2026-11-14, implement-review - Noted: 2026-11-14, implement-review
### A no-hop dashboard request goes as a __<name> send; the agent answers with a top-level patch key checked in validate() (patches.mjs), and pointersForSend() maps it to console-launches.md.
- Kind: convention
- About: src/web-console/patches.mjs, src/web-console/pointers.mjs
- Noted: 2026-11-17, quick-task
### A test run of node install.js with a temp HOME still writes the plan2code shims into the real npm global bin, because npm's prefix does not follow HOME; also set npm_config_prefix to a temp folder.
- Kind: correction
- About: install.js
- Why: A piped --update test run repointed the real plan2code shims at a temp folder until they were fixed by hand.
- Noted: 2026-11-17, implement-review
### Before adding a class to the git board, grep styles/git.css for it: short names like git-tools and git-path are already taken (the Branches search row, the file path cell).
- Kind: correction
- About: src/web-console/public/styles/git.css
- Why: The new tools fold-out reused git-tools and the Branches row's flex rule laid it out side by side.
- Noted: 2026-11-17, quick-task
### Each recordInstalled() in install.js stamps the version being installed into install.json, so a failed update must restore the old one with setRecordVersion(), or a retry says Already on.
- Kind: how-it-works
- About: install.js
- Noted: 2026-11-17, implement-review
### In a Markdown field (md-field.js), CodeMirror's scroller and content are only as tall as the text, not the bordered host: code that hit-tests the scroller must not assume it fills the box.
- Kind: how-it-works
- About: src/web-console/public/md-field.js
- Noted: 2026-11-17, quick-task
### In a node:test file, start fixtures such as a test server in a root before hook, never with a top-level await after the first test(), which lets the runner run after hooks early ### In a node:test file, start fixtures such as a test server in a root before hook, never with a top-level await after the first test(), which lets the runner run after hooks early
- Kind: correction - Kind: correction
- About: scripts/test-script-deps.mjs - About: scripts/test-script-deps.mjs
- Why: test-script-deps.mjs awaited its server mid-file and 7 tests failed on Ubuntu and macOS CI only. - Why: test-script-deps.mjs awaited its server mid-file and 7 tests failed on Ubuntu and macOS CI only.
- Noted: 2026-11-15, Failure log - Noted: 2026-11-15, Failure log
### Playwright counts aria-disabled as disabled: a page test pressing an aria-disabled button (Stop session, Back) uses click({ force: true }) and reads .disabled via evaluate().
- Kind: command
- About: scripts/test-web-console-page-session.mjs
- Noted: 2026-11-17, implement-review
### The Agents & models tab shows a model in two places, the cards (agents/agents-summary.js) and the strengths panel (agents/agents-strengths.js); check a models.json label change in both.
- Kind: how-it-works
- About: src/web-console/public/screens/agents
- Noted: 2026-11-17, implement-review
### The app's webview data sits outside ~/.plan2code, in Tauri's app_local_data_dir() on Windows and Linux (%LOCALAPPDATA%/com.plan2code.desktop); appWebviewDirs() in install.js lists it per OS.
- Kind: how-it-works
- About: install.js
- Noted: 2026-11-17, implement-review
### The desktop app's CSP allows no inline script, so anything that must run before the first paint (the saved theme and accent) goes in the classic head script ui/theme-early.js, not in app.js.
- Kind: convention
- About: plan2code-app/ui/theme-early.js
- Noted: 2026-11-17, implement-review
### The launcher's prompts each open a new readline on stdin, so a test piping several answers at once loses all but the first; drive a multi-prompt flow by writing each answer after a short delay. ### The launcher's prompts each open a new readline on stdin, so a test piping several answers at once loses all but the first; drive a multi-prompt flow by writing each answer after a short delay.
- Kind: how-it-works - Kind: how-it-works
- About: src/launcher/plan2code.js - About: src/launcher/plan2code.js
- Noted: 2026-11-15, implement-review - Noted: 2026-11-15, implement-review
### To drive launcher prompts in scripts/test-launcher.mjs, use runAtTerminal(): it marks stdin as a terminal with a preload file and answers each prompt only once it shows on stdout.
- Kind: convention
- About: scripts/test-launcher.mjs
- Noted: 2026-11-17, implement-review
### When a card in src/plan2code-deps.md changes (what it lists or asks), change the same card in src/web-console/notes/deps.md in the same edit: the console builds the card from the notes. ### When a card in src/plan2code-deps.md changes (what it lists or asks), change the same card in src/web-console/notes/deps.md in the same edit: the console builds the card from the notes.
- Kind: correction - Kind: correction
- About: src/plan2code-deps.md, src/web-console/notes/deps.md - About: src/plan2code-deps.md, src/web-console/notes/deps.md
+23
View File
@@ -0,0 +1,23 @@
# Plan2Code guides
The long-form guides that sit beside the [README](../README.md). The README is the short version: what Plan2Code is and how to install it.
## Using
- [walkthrough.md](walkthrough.md): one feature from a sentence to archived specs, session by session.
- [web-console.md](web-console.md): the web console guide, from the dashboard to the last sign-off.
- [steps.md](steps.md): what each of the six steps asks, writes and hands on.
- [launcher.md](launcher.md): the `plan2code` command, its flags, and using an agent other than Claude Code, Devin or Codex.
- [activities.md](activities.md): the small games behind the die in the console's top bar.
- [status-line.md](status-line.md): the optional three-line Claude Code status bar.
Also: [QUICK-REFERENCE.md](../QUICK-REFERENCE.md) (the one-page card) and [docs/desktop-app.md](../docs/desktop-app.md) (the desktop app and the Implementation Loop).
## Maintaining
- [web-console-internals.md](web-console-internals.md): how the console works, its security model, every route, driving it by hand and refreshing the screenshots.
- [web-console-design.md](web-console-design.md): why the console is shaped the way it is.
- [metrics.md](metrics.md): `plan2code-metrics`, measuring and improving the prompts themselves.
- [test-bot.md](test-bot.md): `plan2code-bot`, the harness that runs the whole workflow unattended.
For the code layout, see [AGENTS.md](../AGENTS.md).
File diff suppressed because it is too large. Load diff
+43
View File
@@ -0,0 +1,43 @@
# The plan2code command and other agents
The command-line side of Plan2Code: what `plan2code` does when you run it, and how to use an agent other than Claude Code, Devin or Codex. Back to the [README](../README.md#install-and-start).
## About the plan2code command
Install (`I`) adds `plan2code` as a global command (Advanced `A` → `D` adds just the command). Run it from any project and the Plan2Code
dashboard opens right there, in **Claude Code**, **Devin** or **Codex**. With more than one installed it asks which and
remembers your pick; `plan2code --cli claude`, `--cli devin` or `--cli codex` skips the question, and `--model <name>`
chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the
Claude Code, Devin or Codex CLI on your `PATH`. After you pick the agent it asks whether to turn its
permission prompts off (Yes by default; `--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass`
in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex, a custom agent's bypass arguments, and no question for a
custom agent that has none; for Codex the question names its sandbox, which that flag turns off too). It asks on every
launch and remembers no answer. `plan2code --keep-permissions` keeps the prompts without asking, and
`plan2code --bypass-permissions` turns them off without asking. With no terminal to ask on (a script or a pipe) the
prompts stay on unless `--bypass-permissions` is given. The installer then offers a desktop shortcut (answer `y`),
which opens a folder menu first: Choose a folder, with the project folders you opened lately under it (with none yet, it goes straight to the folder dialog). In a terminal, `plan2code` offers the same recent folders as a numbered menu. Uninstalling (`U`, or `plan2code uninstall` from any terminal) removes both.
## Using another agent CLI, or none yet
Plan2Code runs inside an AI coding agent CLI. With no agent it can run (none of Claude Code,
Devin or Codex, and no working custom agent),
`plan2code` opens a setup page in your browser (the web console runs it, so no agent is needed).
The page lists each agent as **Found**, **Found outside PATH** or **Not found**, with its install
commands for your system, a Copy button per command and an **Install page** link. Install one and
press **Check again**: no restart needed. An agent found outside `PATH` gets **Use it from here**,
which saves where it was found so you never touch `PATH` yourself. Below the list sit five starter
templates (GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI) for agents Plan2Code does not ship.
**Start with this agent** carries the run straight on in the same tab, onto the new agent's
dashboard. Naming a built-in that is missing with `--cli <name>` opens the same page on that agent
(a missing custom agent prints its own steps and exits 127). In the
desktop app a **Set up an agent** button opens the same page in the window and returns to the
launch card with the found agent picked. Where no page can open, such as over SSH or with no
display, `plan2code` prints the install commands and install pages and exits with code 127.
Once an agent is running, to use a different agent CLI, open the web console's **User Preferences → Agents & models** and add it: a name, the
command, and (optionally) its arguments, the start prompt, arguments for skipping permission prompts, and
how it takes a model. Custom agents are saved in `~/.plan2code/agents.json` and used by both the
`plan2code` command (listed after the built-ins; `--cli <id>` picks one) and the desktop app's picker. The
`/plan2code` start prompt only does something in an agent that loads the installed Plan2Code skills; for
any other, leave the start prompt blank and start a skill yourself. Details in
[web-console.md](web-console.md#agents--models).
+1 -1
View File
@@ -1,4 +1,4 @@
# Metrics &amp; Self-Improvement # Metrics and Self-Improvement
`plan2code-metrics` closes the loop on the workflow itself: it collects data from your finished `plan2code-metrics` closes the loop on the workflow itself: it collects data from your finished
specs, aggregates it across runs and prompt generations, then uses AI to diagnose which step is specs, aggregates it across runs and prompt generations, then uses AI to diagnose which step is
+107
View File
@@ -0,0 +1,107 @@
# The six steps in detail
Back to the [README](../README.md#the-workflow). Each step is its own run, and the specs on disk are the only thing carried from one to the next.
Chain a small one onto the last, or start a fresh session for a big one (rule 1).
## 0 · Pathfinder 🧭 (optional)
On the page: one question at a time with the options and their trade-offs, the map growing in its own
tab, and a **Write a brief** button for a printable summary.
Some ideas are too big and unclear to plan: you can feel the shape of the work but you can't write
it as requirements, so planning would just invent the answers. Pathfinder finds the *way* to the
destination; Step 1 then walks it.
1. **Name the destination** — one or two lines fixing what this effort is finding its way to. Settled
first, because it fixes scope. It also asks where the map should live: **local files** under
gitignored `specs/` (private, solo — the default), or **GitHub Issues** (a map issue with one
sub-issue per decision, native blocking, so your team can see and work the frontier in the tracker).
2. **Chart the map** — a breadth-first grilling surfaces the open decisions. Anything you can phrase
*sharply* becomes a question file; anything you can only sense stays listed as fog.
3. **Clear the questions one at a time** — resolving one burns off the fog behind it, graduating
whatever just became sharp into new questions. After each decision it offers a menu: take the next
question here, or start fresh — recommended after about three, to keep the agent sharp.
Ask for a **brief** at any point and you get a dated, plain-English summary of what has been
decided, what is still open, and what is next — meeting minutes, with no jargon in them.
4. **Hand off** — when nothing is left to decide, it writes a `PLAN-DRAFT` that
`/plan2code-1-plan` resumes from at Phase 4, with requirements, context, and scope already
answered.
**Question types:** `grill` (a decision only you can make — the default) · `research` (a fact gates
it; background agents resolve these, several in parallel) · `sketch` (you need something concrete to
react to) · `legwork` (manual work that has to happen before a decision is possible).
It never answers its own questions, and it **plans, it never builds.** When the urge to just build it
arrives, the map is done. Skip Step 0 entirely when you already know what you're building.
**Out:** `specs/<feature>/pathfinder/map.md` + `questions/` (or a `pathfinder:map` issue and its
sub-issues) → `PLAN-DRAFT-<date>.md`. The draft is always a local file — that is what Step 1 reads.
## 1 · Plan 🤔
On the page: questions in batches of up to three, the phase breakdown as a list you can reorder and
edit, and a sign-off at each stage.
The agent works as a senior architect through seven phases, stopping for you after each: requirements
analysis · system context (reading your actual codebase) · scope assessment (a large project saves and
resumes in a fresh session) · tech stack (needs your explicit sign-off) · architecture design ·
technical specification · transition decision.
It won't finalize below **90% confidence**, and every assumption it makes is written into the draft.
**In:** a description of the feature. **Out:** `PLAN-DRAFT-<date>.md` + `PLAN-CONVERSATION-<date>.md`
## 2 · Document 📝
On the page: a question only where the plan leaves something open, each phase file appearing as its
own tab as it is written, and one sign-off at the end.
The plan becomes the drawing. One `overview.md` with the phase checklist, plus one file per phase of
one-story-point tasks. Each phase is **self-contained** — an agent opening `phase-3.md` cold needs
nothing else to build it. Unit and E2E tests are excluded unless you ask for them.
The overview also identifies the **parallel execution groups**: phases with no shared files or
dependencies, safe to run in separate agents at once.
**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `phase-1…N.md`
## 3 · Implement ⚡
On the page: a progress bar and the phase's task list ticking over as tasks land, then the completion
report and a sign-off card where you approve, ask for changes, or have the code reviewed first.
Point it at `overview.md` and it does the rest: finds the next unchecked phase, implements every task
exactly as specified, ticks tasks off as they land, then reviews its own work against the spec and
writes a completion summary.
One phase per conversation. It won't run tests unless the phase says to.
**In:** `specs/<feature>/overview.md`. **Out:** working code, and updated checkboxes.
Want a second pair of eyes before you sign off? `/plan2code-3-implement-review` builds the phase the
same way, runs a focused review and the fixes you pick, and only then asks for approval.
## Review 🔬 — optional, any time
On the page: a few questions on scope, the findings as a report you can read in full, and a list
where you tick what gets fixed.
An independent second opinion, not a rubber stamp. It figures out its own scope (conversation
context, your instruction, or the git diff as a fallback), analyses across 11 dimensions, and ranks
findings Critical / Warning / Suggestion. Every finding cites a file and a line, or it gets dropped —
and the review pass is read-only. It fixes things only if you ask, and verifies each fix afterwards.
Spec-aware when `specs/` exists, and works fine without it. Most useful right after a planning or
implementation step, but there's no wrong time to run it.
## 4 · Finalize 🧹
On the page: the task audit and the summary as reports, a list of the doc updates to approve, and a
confirmation before anything is archived.
Validates every task against its phase spec, writes the summary and the list of files touched, flags
the docs that drifted (`README`, `CHANGELOG`, `AGENTS.md`), then archives the whole spec folder —
`pathfinder/` included — to `specs--completed/`. That folder is the record of *why* the code looks
like this.
**In:** `specs/<feature>/overview.md`. **Out:** archived specs.
+3 -3
View File
@@ -9,7 +9,7 @@ Each session stays short, and the specs on disk carry everything from one sessio
## Before you start ## Before you start
- **Node.js 18 or newer.** Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal. - **Node.js 18 or newer** (22 or newer if you install Claude Code with npm). Check with `node --version`. No Node? Get it from [nodejs.org](https://nodejs.org/) (the LTS download), or run `winget install OpenJS.NodeJS.LTS` on Windows, `brew install node` on macOS, or use `nvm` on Linux. Then open a new terminal.
- **Git.** Check with `git --version`. The installer is fetched from GitHub with Git, and without it npm stops with `spawn git ENOENT`. No Git? Get it from [git-scm.com](https://git-scm.com/downloads), or run `winget install Git.Git` on Windows, `brew install git` on macOS, or use your package manager on Linux. Then open a new terminal. - **Git.** Check with `git --version`. The installer is fetched from GitHub with Git, and without it npm stops with `spawn git ENOENT`. No Git? Get it from [git-scm.com](https://git-scm.com/downloads), or run `winget install Git.Git` on Windows, `brew install git` on macOS, or use your package manager on Linux. Then open a new terminal.
- **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in. - **Start from your project.** Open your terminal in the project you want to work on (`cd` into it) before you run anything. Plan2Code works on the folder you start it in.
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex). - **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
@@ -96,7 +96,7 @@ Parallel execution groups: Phase 3 and Phase 4 don't share files.
## Sessions 3 to N: Implement, one phase each ## Sessions 3 to N: Implement, one phase each
Look at the session meter in the top bar first. Plan and Document add 2 points each, so after Look at the session meter in the top bar first. Plan and Document add 2 points each, so after
those two the meter is at 4: **Session: getting long**, in yellow. That is the cue to close this those two the meter is at 4: **Conversation: getting long**, in yellow. That is the cue to close this
console session and start a fresh one for the build (run `plan2code` again). This is the first of console session and start a fresh one for the build (run `plan2code` again). This is the first of
the four rules: the four rules:
@@ -134,7 +134,7 @@ Repeat. A fresh session each time. It always finds the next open phase itself.
When you reach a parallel group, it offers you the choice: open a second agent, take the other When you reach a parallel group, it offers you the choice: open a second agent, take the other
phase, and the `[/]` marks keep them from colliding. phase, and the `[/]` marks keep them from colliding.
Pick **Implement + review** instead when review should run automatically before phase approval. Pick **Implement + Review** instead when review should run automatically before phase approval.
**Review** remains available on the dashboard for an independent second opinion at any other time. **Review** remains available on the dashboard for an independent second opinion at any other time.
--- ---
+293
View File
@@ -0,0 +1,293 @@
# The web console, inside
For people who change the console or drive it by hand: how it works, the security model, every route, and how to refresh the screenshots. Using the console? Read [the web console guide](web-console.md) instead.
## How it works
Nothing is installed. The skills ship a small zero-dependency Node server
(`references/web-console/`), and the workflow step starts it when you say yes.
```
agent server (detached) your browser
| | |
|-- open (binds the port, starts ->| |
| the server AND the browser) ---|---------------------------->|
|<-- http://127.0.0.1:PORT/s/TOK/ |<---- the page, first state -|
| | already inside it |
|-- post the first questions ----->|---- pushed to the page ---->|
|-- wait --seconds 240 ----------->| |
| (returns every 4 minutes with | |
| progress, then waits again) |<---- you press Send --------|
|<-- your answers -----------------| |
```
The server runs detached rather than as a background task of the agent, because
agent background tasks get killed at various timeouts, and that would take your
half-finished answers with them.
**It is built to show you something fast.** A browser takes most of a second to
turn up after it is asked, so `open` binds the page's port itself and sends the
browser there before the server has even finished starting; the server takes
the port over a moment later, and the browser's request waits for it rather
than being refused. The page arrives with the session already inside it, so it
draws the real screen without asking for anything first, in your own theme and
colors from the first frame. On a Windows laptop the page is in front of you in
roughly the time the browser itself takes to open.
**It stays up while the page is open.** The page pings it every few seconds, so
the idle clock never runs down while you are there. Close the tab and it shuts
itself down about two minutes later; it stops after four hours unless answers
you sent are still waiting for the agent, and the agent stops it outright when
the session ends.
**The setup session hands its tab to the agent it finds.** A `setup` session is
agent-less: nothing reads its sends, so the page's agent-silence and question
rules are switched off and only the idle deadline ends it. The `plan2code`
launcher started the session and polls it for a pick; **Start with this agent**
posts an `__start` action the launcher collects, and it spawns that agent with
two environment variables, `PLAN2CODE_SETUP_ANNOUNCE` (the setup server's
address) and `PLAN2CODE_SETUP_TOKEN` (a per-session token). The new agent's own
`open` then POSTs its sign-in URL to `POST /handover` on the setup server
instead of opening a browser; the token guards the route, the setup page gets a
`move` event on its `/events` stream carrying the URL, and the tab follows it
onto the new session. Inside the desktop app none of this runs: `open` finds no
setup variables (the launcher scrubs the app ones from the setup console it
starts), the page tells the app `agent-found` instead, and the app closes the
setup page and picks the agent itself.
That also means **the server routinely outlives the agent**. It is the agent, not
the server, that reads your answers, and the two fail separately. The page tells
the two apart: the **?** button at the top right opens Help, whose *What this
page is* tab says which halves are talking right now (and *When something
looks stuck* covers what to check), and Planny stops looking busy once
nothing is listening rather than spinning at you indefinitely.
**State lives in three places**, and none of them is your repository (the one
exception being the note attachments the agent keeps for a spec, above):
| Where | What | Survives |
| --- | --- | --- |
| `~/.plan2code/console/sessions/<id>/` | the questions, your draft, your answers | 30 days after the session was last touched |
| `~/.plan2code/console/sessions/<id>/workspace.json`, `ledger.ndjson`, `workspace-cursor.json` | the workspace's folders (paths, names, descriptions — never their contents), the session meter's events, and how far the agent has been told of workspace changes. Kept beside the session, so they outlive every dashboard hop | with the session |
| `~/.plan2code/console/sessions/<id>/uploads/` | images and documents attached to notes and quick questions | 30 days after the session was last touched |
| `~/.plan2code/handoffs/<id>.md`, `<id>.json` | each handoff's document, and which checkout, spec and skill it belongs to and whether it was picked up (`handoffs.mjs` is their one owner) | 30 days after it was last touched, picked up or not |
| `~/.plan2code/notepads/<folder-name>-<12 hex>/` | your notebook for one folder: `meta.json`, `tabs.json` and, per tab, `tabs/<id>/note.md` and `tabs/<id>/images/` (`notepads.mjs` is their one owner; the agent never reads them, except a tab you send) | until you delete it through Cleanup, which offers it once its newest file is 30 days old |
| `~/.plan2code/console/looks.json` | your role, theme, colors, sounds and card width, the Show Activities and Play activity sounds switches (`hideActivities`, `activitySounds`), the last activity picked (`lastActivity`), best scores (flat `activityBest<Id>` keys: `activityBestSnake`, one per Mini golf course from `activityBestGolfPirate` to `activityBestGolfFrost`, `activityBestTrails`, `activityBestBugs`, `activityBestDrive`, `activityBestStack`, `activityBestBumper`, `activityBestRapids`, `activityBestFuse`, `activityBestHop`, `activityBestBounce`, `activityBestGhoul`, `activityBestFlock`) and each game's memo (`activityMemo<Id>`: Snake's surprises found, Light Trails' furthest arena, Bug Hunt's bugs, bosses and power-ups found, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage) | always |
| `~/.plan2code/console/subagents.json` | your Subagents switch, instruction and limit, per project folder and skill | always |
| `~/.plan2code/console/sessions/<id>/subagents-setting.json`, `subagents-cursor.json` | this session's copy of the switch, and how far the agent has been told of it | with the session |
| `~/.plan2code/agents.json` | your custom agent CLIs (User Preferences → Agents & models), read by the `plan2code` command and the desktop app | always |
| your system temp directory | the port, process id and session token | until reboot |
Each of the workspace and meter files has exactly one writer: the server owns
`workspace.json` (the page changes it only through the `/workspace` routes
under Security), and `console.mjs` owns `ledger.ndjson` and
`workspace-cursor.json`. The meter's count is never stored; it is folded from
the ledger every time (`public/meter.js`), so a repeated `post` never counts
twice. The logic lives in small pure modules the tests import directly —
`public/workspace.js` (names, the footer label, the change lines the agent
reads), `public/meter.js` and `public/mentions.js` (the `@name` popover) — and
**Browse…** runs the per-OS picker in `picker.mjs`, copied from the
`plan2code` launcher and kept in step with it by a test.
**Old sessions clean themselves up.** Each time a session opens, whole session
folders nobody has touched for 30 days are deleted — questions, drafts,
answers, uploads and all, paused or not — along with stray scratch files
(`.json` / `.mjs`) left at the top of `~/.plan2code/console/` for as long, and
handoffs in `~/.plan2code/handoffs/` untouched for as long, both files each.
Your `looks.json` and the `console-dir` pointer are never touched, and neither
is the session being opened. Nothing of value goes with them: the page is
never the record, `specs/` in your project is.
**Or clean up on demand.** *User Preferences → System → Cleanup* → **Find files to
clean up** lists, with sizes, everything in `~/.plan2code/` that is not
needed: sessions untouched for 30 days (never the one you are in), anything at
the top of `~/.plan2code/console/` other than `sessions/`, `runtime/`,
`looks.json`, `workspaces.json`, `loop-setup.json`, `loop-reports.json`,
`subagents.json`, `pr-hosts.json`, `console-dir` and `update-check.json`, and
anything at the top of `~/.plan2code/` other than `console/`, `bin/`,
`launcher.json`, `install.json` (what you installed, which `plan2code update`
reads), `models.json`, `handoffs/` (old handoffs go by age, above),
`notepads/`, `app/` and `app.json` (the desktop app and its settings) and
`agents.json` (your custom agents). Each notebook whose newest file is 30 days old or
more is listed as one item, *Notebook for* its folder, and goes whole; no
automatic sweep ever removes one. It also lists each
folder in the project's `specs--completed/` whose newest file is more than 30
days old: archived specs Finalize moved there. Only a folder git tracks is
deleted: `specs--completed/` is usually gitignored, so git couldn't restore
it, and Cleanup keeps it and says why instead. A stray is listed once
it has sat untouched for an hour, so a lock or temp file another session is
writing right now is never caught. **Delete N items** removes
only the rows you left ticked. A console running from another home
(`PLAN2CODE_CONSOLE_HOME`) only ever looks inside that home.
---
## Security
It is a local dev server that reads files in your project (never writing to it)
and keeps its own state in your home folder, so it is built to be boring about
this:
- Bound to `127.0.0.1` only, never `0.0.0.0`. Not reachable from your network.
- A `Host` header allow-list, which is what stops a website you happen to be
visiting from talking to it through a DNS rebinding trick.
- A 128-bit token in the link, swapped for an `HttpOnly; SameSite=Strict` cookie
on first load so it leaves your address bar, your history and any screenshot.
- A strict Content Security Policy with no inline script allowed.
- Markdown written by the agent is turned into page elements directly and never
into an HTML string, so a document that quotes a hostile README cannot run
anything. It shows up as text, which is what it is.
- Uploads are named by the server (`<uuid>.jpg`, or `<uuid>.<ext>` with the
extension taken from the allow-list, via `crypto.randomUUID()`), never by the
file name you sent, and live only under the session's own `uploads/`. The
server checks the bytes: a JPEG header for images (4 MB cap), and for
documents a `%PDF-` header or strict UTF-8 with no NUL byte (10 MB cap).
Documents are served back only under a fixed type (`application/pdf`, or
`text/plain` for text and code) with `nosniff` (and `sandbox` on text), so
the Sent box can link them. A send may only point at
uploads inside that session's `uploads/`, images in `images` and documents
in `files`.
### Routes
The upload routes, the send, the overview and handoff reads, the workspace and the notebook. Like every page route, they are on `127.0.0.1`
behind the session cookie, and the ones that write also check the request's
origin.
| Route | Does |
| --- | --- |
| `POST /upload` | Raw bytes, original name in `x-p2c-name`. `Content-Type: image/jpeg`: writes `uploads/<uuid>.jpg` and answers `{ ok, id, kind: "image", path, url, name, size }`; not a JPEG → 415, over 4 MB → 413. `Content-Type: application/octet-stream`: a document, its extension from the name's allow-listed extension; writes `uploads/<uuid>.<ext>` and answers `{ ok, id, kind: "file", path, name, size }` with no `url`; not an allowed extension or contents that do not match → 415 `type`, over 10 MB → 413. Any other content type → 415. |
| `GET /uploads/<id>.<ext>` | Serves an upload: an image as `image/jpeg` (the thumbnail after a reload), a document as `application/pdf` or `text/plain; charset=utf-8` with `nosniff` and, on text, `Content-Security-Policy: sandbox`. Only `<uuid>.<allowed ext>` names under `uploads/`; anything else is 404. |
| `DELETE /uploads/<id>.<ext>` | Deletes an image or document removed before sending. 204, or 404 if it is not there. |
| `POST /submit` | The Send. A note may carry `images` and `files`, each `[{ path, name }]`: at most 5 together, images in `images` and documents in `files`, every path inside this session's `uploads/`, otherwise 400. |
| `POST /chat` | A Quick question `{ text, about?, images?, files?, conversation }`, or `{ reset: true, conversation }` for New conversation. Appended to the session's `chat.ndjson`. 400 `too-long` (over 4,000 characters), `image`, `file` or `bad`; 409 `offline`, `stale` or `limit` (10 per conversation). Never refused because a card send is still uncollected. |
| `POST /chat/decision` | Approve or Decline on an edit the agent proposed: `{ re, decision, text?, conversation }`. Once per proposal; does not count toward the 10. |
| `GET /overview?spec=specs/<name>[&file=map\|draft]` | The Overview tab's read of `<spec>/overview.md` (or, with `file=`, the Map tab's `pathfinder/map.md` or the Plan draft tab's live `PLAN-DRAFT-*.md`), as `text/markdown` with `cache-control: no-store` and the file's spec-relative name, URL-encoded, in `x-spec-file`. A missing file is a 204. On the dashboard `spec` must be one of the scanned specs; elsewhere the session's own spec is used. The file's real path must stay inside the project, so `../`, absolute paths and symlinks pointing out all get the same 204 as a missing file, as does an unscanned `spec` or an unknown `file`. |
| `GET /agents-doc[?file=<name>]` | The Dashboard's AGENTS.md tab: `AGENTS.md` (the default) or one `.agents-docs/<name>.md`, as `text/markdown` with `cache-control: no-store`. A dashboard only; any other file name, a missing file or a path that leaves the project is a 204. |
| `GET /prototypes?spec=specs/<name>` | The Prototypes tab's list: `{ files: [{ name, kind }] }` (`kind` `md` or `html`) for the files directly in `<spec>/prototypes/`, or a 204 when there are none. The spec is chosen as for `/overview`. |
| `GET /prototype?spec=specs/<name>&name=<file>.md` | One `.md` from `<spec>/prototypes/`, as `text/markdown` with `cache-control: no-store`; any other name, a missing file or a path that leaves the folder is a 204. |
| `POST /open-prototype` | `{ spec, name }`: opens one `.html` from `<spec>/prototypes/` in the person's default browser. 404 for any other name, 500 when no browser could start. |
| `GET /handoff?id=<id>` | *Read it all*: the handoff's `.md` from `~/.plan2code/handoffs/`, as `text/markdown` with `cache-control: no-store`. A dashboard only, and only an id its own scan listed: a used, unknown or malformed id is 404. |
| `POST /learning/pause` | Pause for me: `{ paused: boolean }` (origin-checked; anything else is 400 `bad-request`, and 409 `not-on` unless Learning is On or Paused for you). Writes the personal pause on this machine only (`pause.json` under `~/.plan2code/learning/<key>/`), the server's only write for Learning, and repaints the row with no agent. |
| `GET /learning/state` | The Learning row's state worked out now, `{ state, pausedSince, waiting, oldestDays }` (`{}` when the project's settings file is from a format it cannot read), with `cache-control: no-store`. |
| `GET /learning/lessons` | Open the lessons, read only: `{ files: [{ name, title, text }] }` from the project's lessons (`.plan2code/lessons/`, saved with the repository), `general.md` first, then the other `.md` files in name order (plain files only, at most 100 of 512 KB each), with `cache-control: no-store`. |
| `GET /workspace` | The Workspace dialog's list: folders, `missing`, `remote` and the agent's folder `issues`. `?check=1` re-checks every folder on disk first. |
| `POST /workspace/add` | `{ path, name?, description? }`. The path is resolved against the folder the session started in (`~` expanded) and must be a folder: 400 `not-a-folder`, `duplicate` (with its `name`; compared case-insensitively on Windows and macOS), `bad-name`, or `name-taken` with a `suggest`. Answers the new entry, `nested: true` when it sits inside another folder in the list. |
| `POST /workspace/edit` | `{ id, name?, description? }`. Renames or re-describes one folder: 400 `bad-name` / `name-taken`, 404 `unknown`. |
| `POST /workspace/remove` | `{ id }`. 400 `original` for the folder the session started in, 404 `unknown`. |
| `POST /workspace/browse` | Opens the system folder picker and answers `{ path }` or `{ cancelled: true }`; never adds anything itself. 409 `busy` while one is open, 404 `no-picker` when the session looks remote or no picker exists. |
| `GET /notepad[?tab=<id>]` | The notepad for the folder this session runs in: `{ tabs: [{ id, name, sent? }], last, tab: { id, text, savedAt, images: [{ id, url, thumb }] } | null }`, with the tab's `text`, `savedAt` and `images` repeated at the top. Without `tab` it answers the last one used; 404 `no-such-tab` for an id it does not have. A notepad in the first shape answers one virtual tab, Notes. Reading never creates or moves a file. |
| `POST /notepad/text?tab=<id>` | `{ text }`. Saves that tab's `note.md` and answers `{ ok, savedAt }`; 400 `bad`, 404 `no-such-tab`, 413 `too-long` (over 1 MB). |
| `POST /notepad/image?tab=<id>` | Raw `image/jpeg` (the page re-encodes every picture first). Writes the tab's `images/<uuid>.jpg` and answers `{ ok, id, url }`; 415 `not-jpeg`, 413 `too-large` (over 4 MB), 409 `too-many` (200 pictures in the tab). |
| `POST /notepad/thumb?id=<uuid>&tab=<id>` | Raw `image/jpeg`: that picture's thumbnail. 404 `not-found` or `no-such-tab`, 415 `not-jpeg`, 413 `too-large`. |
| `POST /notepad/image/delete?tab=<id>` | `{ id }`. Deletes a picture and its thumbnail; 404 `not-found` or `no-such-tab`. |
| `POST /notepad/tab` | `{ name }`. Makes a tab, which becomes the last one used, and answers `{ ok, id, name }`; 400 `bad-name`, 409 `duplicate-name` (any case) or `too-many-tabs` (20). |
| `POST /notepad/tab/rename` | `{ id, name }`. Answers `{ ok, id, name }`; 400 `bad-name`, 404 `no-such-tab`, 409 `duplicate-name`. |
| `POST /notepad/tab/delete` | `{ id }`. Removes the tab from the index, then its folder (text and pictures); 404 `no-such-tab`. |
| `POST /notepad/tab/order` | `{ order: [id] }`, every current id exactly once; 400 `bad` otherwise. |
| `POST /notepad/tab/last` | `{ id }`. Remembers the open tab; 404 `no-such-tab`. |
| `POST /notepad/tab/sent` | `{ id, workflow, spec? }`. Records that the tab was sent (`workflow` one of `pathfinder`, `plan`, `quick-task`, `revise-plan`, `diagnose`, `ui-prototype`; `spec` like `specs/<name>`) as `sent: { workflow, spec?, at }` on its `tabs.json` entry, shown back in `GET /notepad`'s `tabs`. The page posts it only after the Send that carried the filled box; 400 `bad-sent`, 404 `no-such-tab`. |
| `GET /notepad/images/<tab>/<uuid>.jpg`, `<uuid>.thumb.jpg` | Serves a picture or its thumbnail as `image/jpeg`, only by a tab id and a UUID name, a regular file (never a link) whose real path stays inside `~/.plan2code/notepads/`; anything else is 404. |
| `POST /subagents` | `{ on, instruction, max }` (`instruction: null` for the shipped default). Saves the switch for this project and skill and answers `{ ok, setting }`; 400 `not-offered` on a skill without the switch, `bad`, `too-long` (over 2,000 characters) or `max` (outside 1 to 20). |
| `GET /agents` | The agents view's data: your custom agents and the shipped built-ins and templates, each entry merged with its lookup result `{ state, path, where, folder }`: `state` is `found` (on PATH), `outside` (saved Windows PATH, npm's global folder or an install folder) or `missing`, and `where` says which search found it. Built-ins carry their `install` lines for the server's OS only. |
| `POST /agents` | `{ agents, replace? }`. Saves the custom-agent list to `~/.plan2code/agents.json`, validated first (400 `{ error, index, field }`); 409 while the file holds entries `GET /agents` could not read, unless `replace: true`. |
| `POST /agents/test` | `{ command }`. Where a command would run from (`{ found, path }`), for the form's Test button; never runs it. |
| `POST /agents/use-path` | `{ id }`. "Use it from here": saves the location the lookup found off PATH as the agent's `command` (a built-in becomes a new custom entry; 404 unknown, 409 `not-found`). |
| `POST /handover` | Setup sessions only, and only with the session's setup token in `x-plan2code-token`: the new agent's `open` posts `{ url }` here, the server broadcasts a `move` event with it and the setup tab follows. 409 `moved` once it has happened. |
## For maintainers
| | |
| --- | --- |
| Source | `src/web-console/` (one row per file in the files tables of the `.agents-docs/AGENTS-architecture-*.md` area files; a test keeps it complete) |
| Ships as | `skills/<every skill>/references/web-console/` |
| Wiring | one `additionalReferences` entry per skill in `install.js`; the dashboard's menu lives in `public/skills.js` (each entry's `card`; `SKILL_CATALOG` in `public/answers.js` is a lookup on it) |
| Agent contract | a card, `src/web-console/console.md` (read once), plus pointers: the console names a topic file (`console-*.md`, `notes/<workflow>.md`, `building.md` / `building-review.md`) in its own `read` output, once per session per topic, when its moment comes; `console.mjs help <topic>` prints any of them. A `stop` with no `finish`, or a `finish` while `stopWarning` is set, is refused with the fix; `stop --session <sid> --force` ends a dead page or an abandoned session anyway. Patches are one line, with lettered options and the console's own defaults filled in; a refused patch names the field and the fix. Byte budgets keep the card, the notes and a sample session's outputs from growing back (`scripts/test-console-wire-budgets.mjs`) |
| Tests | `node --test scripts/test-web-console-*.mjs` (split by area, shared setup in `scripts/web-console-test-helpers.mjs`), also run by `npm test` |
| Start-up benchmark | `node scripts/bench-web-console.mjs` (needs a local Chrome or Edge for the paint columns, driven through `playwright-core` from `npm install`; `--browser-delay 900` models a real browser launch, `--roundtrip` times Send→agent and post→page) |
| Screenshots | `node scripts/capture-screenshots.mjs` (needs a local Chrome or Edge, driven through `playwright-core` from `npm install`; `PLAN2CODE_TEST_BROWSER=chrome|msedge` forces one) |
| Dependencies | none at runtime. `marked` 15.0.7 (MIT) is vendored for its lexer only, and CodeMirror 6 (MIT) for the notebook's editor as one bundled file, `public/vendor/codemirror.esm.js`, made by the dev-only `node scripts/vendor-codemirror.mjs` from a pinned lock (about 500 KB, loaded only when the Notebook is first opened); the page's policy blocks the `<style>` element CodeMirror writes, so the editor lives in a shadow root where it adopts its rules as a constructed stylesheet (steps in the architecture doc's Notebook point) |
Edit `src/` only. `skills/` is a committed build artifact: regenerate it with
`npm run build:skills` and commit it with the source change, since `npm test`
(via `--verify-skills`) fails when it drifts from `src/`.
### Driving it by hand
You do not need an agent to poke at the console. Point `PLAN2CODE_CONSOLE_HOME`
somewhere disposable first, so you never touch a real session:
```bash
export PLAN2CODE_CONSOLE_HOME=/tmp/p2c-play # Windows: $env:PLAN2CODE_CONSOLE_HOME
cat > /tmp/payload.json <<'JSON'
{ "workflow": "pathfinder", "title": "Playing about",
"items": [ { "id": "q1", "kind": "choice", "title": "Export format",
"body": "Pick one.",
"options": [ { "k": "A", "text": "CSV", "recommended": true },
{ "k": "B", "text": "Excel" } ],
"token": { "A": "a", "B": "b" } } ],
"agent": { "status": "waiting" } }
JSON
node src/web-console/console.mjs open --file /tmp/payload.json # prints the URL, opens the browser
node src/web-console/console.mjs wait --session <sid> --seconds 60
node src/web-console/console.mjs stop --all
```
`node src/web-console/console.mjs help` prints the same command summary an
agent gets when it finds the binary before the docs.
`wait` exits `0` with the answers, `10` if nobody has finished yet, `20` if the
server died, `30` on Cancel. Pick `--seconds` to sit under whatever your harness
allows a single command: it is a poller, so killing it costs nothing, and a
collected result is printed before it is marked collected, which means an
interrupted handover can only repeat itself, never lose an answer. `status`
lists sessions and flags any whose answers were submitted but never collected.
When something misbehaves, the session directory is the whole story:
`state.json` (what the agent published), `draft.json` (what the person has typed
but not sent), `result.json` (what they sent), `events.ndjson` (an append-only
log you can `cat`), and `server.log`.
Set `--idle-ms 60000` on `open` if you want the server to shut itself down
quickly while experimenting.
Two environment variables help when the start is what you are looking at:
| Variable | Does |
| --- | --- |
| `PLAN2CODE_CONSOLE_TRACE=1` | `open` prints a timeline of its steps to stderr (roots found, server spawned, port bound, browser sent, state written, server listening). |
| `PLAN2CODE_BROWSER` | The command that opens the link instead of the system default, run through the shell with the link appended, e.g. `PLAN2CODE_BROWSER='firefox --new-tab'`. |
Every `console.mjs open` of an installed console (one run from a version folder
under `~/.plan2code/console/`) also writes its own directory to
`$PLAN2CODE_CONSOLE_HOME/console-dir` (or `~/.plan2code/console/console-dir`
when the override is unset): it is how an agent finds the console on a later
session without searching the skill install dirs. A console run from a source
checkout leaves the pointer alone.
The vendored file is `src/web-console/public/vendor/marked.esm.js`,
sha256 `7a7d9a521ac9384e0c3a075120a7c486cbd0c3c32cc5601bbb79a23e97403690`.
Only `marked.lexer()` is used; the rendering is ours, in `public/render.js`, and
builds DOM nodes rather than HTML so nothing needs sanitizing.
### Refreshing the screenshots
The docs and the landing page show the console through the images in
`docs/screenshots/`, one light and one dark WebP per screen. Rerun the capture
after any change a person would see on the page: a new layout, a renamed
button, a different color.
```bash
node scripts/capture-screenshots.mjs # every screen
node scripts/capture-screenshots.mjs --only dashboard # one screen
```
Each screen is staged with no agent, from the payloads in
`scripts/screenshots/` (its README names the file behind each screen), in a
throwaway sample project and console home that the script removes when it is
done. It prints each file's size and warns over 300 KB.
Open every image before you commit it: the right screen, both themes, nothing
cut off, and no username, home path or real project name anywhere on it.
+92 -1569
View File
File diff suppressed because it is too large. Load diff
+3 -3
View File
@@ -8,7 +8,7 @@ Plan2Code is a structured 4-step workflow methodology for AI-assisted software d
**Version:** Check `version.json` for current version **Version:** Check `version.json` for current version
**Author:** Justin Parker **Author:** Justin Parker
**License:** MIT **License:** Apache 2.0
Plan2Code is started from the project the person works in (`cd` into it, then run `plan2code`), not from this repository; every newcomer doc says so, next to the Node.js 18+ requirement. Plan2Code is started from the project the person works in (`cd` into it, then run `plan2code`), not from this repository; every newcomer doc says so, next to the Node.js 18+ requirement.
@@ -36,13 +36,13 @@ Details: [Status line](./.agents-docs/AGENTS-architecture-statusline.md)
## Web Console ## Web Console
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) installed once under `~/.plan2code/console/<version>/` (`installSharedConsole` in `install.js`) and reached from every skill through a forwarding stub, `src/web-console-stub/console.mjs`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review, and in Implement, Implement + Review and Quick Task a **Changes** tab: a `diff` doc block fed by the `changes.mjs` skill script, parsed by `public/diff-parse.js` and drawn by `public/diff-view.js`), build progress, the living document, a spec's saved prototypes (a **Prototypes** tab: an `.md` read in place, an `.html` opened in the default browser), an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, private: the agent reads a tab only when you start Pathfinder, Plan, Quick Task, Diagnose, UI Prototype or Revise plan from the dashboard with it and send the box it fills (an idea box marked `fill: "note"`, up to five ticked pictures attached), which then marks the tab sent via `POST /notepad/tab/sent`; the agent CLI never imports the store; removed only through Cleanup once a month untouched), **Activities** behind the top bar's die (thirteen small games, Snake, Mini golf, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash, listed in `public/activities.js` with one module per game under `public/activities/` (Ghoul Rush is its own folder of modules, `public/activities/ghoul-rush/`) and a card line (`blurb`) each, a picker of game rows in two columns, ordered Recently played or A to Z (saved in `activityOrder`), with never-picked games under Not played yet, once two are listed, that plays one game at a time (another pick drops the last game's round), driven by `screens/activities.js` (keys, key releases for a game with `release()`, canvas pointer events for a game with `pointer()`, one frame timer), paused whenever the person's turn comes and resumed only by the person (while that pause's banner is up, only by its **Unpause game** button), best scores in flat `activityBest<Id>` keys in `looks.json` (and the time each game was last picked in `activityPlayed<Id>`) (lowest wins for a game that sets `lowerIsBetter`; Mini golf opens on a dashboard of its six 18-hole courses, one file each under `public/activities/golf-course-<id>.js`, and keeps a best per course, `activityBestGolf<Course>`), and one number a game may keep between sessions in `activityMemo<Id>` (Snake's tally of surprises found, Light Trails' furthest arena, Bug Hunt's tally of finds, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage), never shown to the agent), a built-in 23-topic Help, the app-only **Implementation Loop** (a dashboard card and a setup screen drawn by the page, `public/screens/loop-setup.js`; the last setup remembered per project in `~/.plan2code/console/loop-setup.json`, owned by `loop-setup.mjs`; a page that locks while `state.loop.driving` is set, until the app posts `loopEnd`; a skill run with `--loop` reports a `loopOutcome` instead of asking for sign-off, per `notes/loop.md`), a first-run Welcome, User Preferences (gear: four tabs, Appearance, Agents & models, System and Sounds & activities, on the `public/tabs.js` helper Help also uses, with `public/prefs.js`, `screens/prefs-dialog.js` and `screens/agents-view.js`), an agent-less **setup** page (the `setup` workflow `plan2code` or the desktop app opens when no agent can run: each built-in's found / outside-PATH / missing state from `agent-lookup.mjs`, install lines, Check again, Use it from here, starter templates and Start, which hands the tab to the new agent through a token-guarded `POST /handover` and a `move` event; the app shows it in its window from a Set up an agent button instead) and a bug/idea link to GitHub issues. On opted-in skills (every workflow but the dashboard, setup, Changelog, Git, Handoff and UI Prototype) a **SLine truncated Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) installed once under `~/.plan2code/console/<version>/` (`installSharedConsole` in `install.js`) and reached from every skill through a forwarding stub, `src/web-console-stub/console.mjs`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review, and in Implement, Implement + Review and Quick task a **Changes** tab: a `diff` doc block fed by the `changes.mjs` skill script, parsed by `public/diff-parse.js` and drawn by `public/diff-view.js`), build progress, the living document, a spec's saved prototypes (a **Prototypes** tab: an `.md` read in place, an `.html` opened in the default browser), an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a **git board** for the `git` workflow (a Save, Share, Review, Tidy path, one task card for the step you are on, and the Changes, Branches and Sync tabs folded into **All branches and tools**; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, private: the agent reads a tab only when you start Pathfinder, Plan, Quick task, Diagnose, UI Prototype or Revise plan from the dashboard with it and send the box it fills (an idea box marked `fill: "note"`, up to five ticked pictures attached), which then marks the tab sent via `POST /notepad/tab/sent`; the agent CLI never imports the store; removed only through Cleanup once a month untouched), **Activities** behind the top bar's die (thirteen small games, Snake, Mini golf, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash, listed in `public/activities.js` with one module per game under `public/activities/` (Ghoul Rush is its own folder of modules, `public/activities/ghoul-rush/`) and a card line (`blurb`) each, a picker of game rows in two columns, ordered Recently played or A to Z (saved in `activityOrder`), with never-picked games under Not played yet, once two are listed, that plays one game at a time (another pick drops the last game's round), driven by `screens/activities.js` (keys, key releases for a game with `release()`, canvas pointer events for a game with `pointer()`, one frame timer), paused whenever the person's turn comes and resumed only by the person (while that pause's banner is up, only by its **Unpause game** button), best scores in flat `activityBest<Id>` keys in `looks.json` (and the time each game was last picked in `activityPlayed<Id>`) (lowest wins for a game that sets `lowerIsBetter`; Mini golf opens on a dashboard of its six 18-hole courses, one file each under `public/activities/golf-course-<id>.js`, and keeps a best per course, `activityBestGolf<Course>`), and one number a game may keep between sessions in `activityMemo<Id>` (Snake's tally of surprises found, Light Trails' furthest arena, Bug Hunt's tally of finds, Sunset Drive's roads found, Stack Deploy's highest floor, Bumper Ring's furthest arena, Rapids Run's furthest dam, Hot Potato's furthest venue, Crossing Rush's furthest zone, Bounce Road's furthest stage, Ghoul Rush's most stages cleared in a run, Flock Dash's furthest stage), never shown to the agent), a built-in 23-topic Help, the app-only **Implementation Loop** (a dashboard card and a setup screen drawn by the page, `public/screens/loop-setup.js`; the last setup remembered per project in `~/.plan2code/console/loop-setup.json`, owned by `loop-setup.mjs`; a page that locks while `state.loop.driving` is set, until the app posts `loopEnd`; a skill run with `--loop` reports a `loopOutcome` instead of asking for sign-off, per `notes/loop.md`), a first-run Welcome, User Preferences (gear: four tabs, Appearance, Agents & models, System and Sounds & activities, on the `public/tabs.js` helper Help also uses, with `public/prefs.js`, `screens/prefs-dialog.js` and `screens/agents-view.js`), an agent-less **setup** page (the `setup` workflow `plan2code` or the desktop app opens when no agent can run: each built-in's found / outside-PATH / missing state from `agent-lookup.mjs`, install lines, Check again, Use it from here, starter templates and Start, which hands the tab to the new agent through a token-guarded `POST /handover` and a `move` event; the app shows it in its window from a Set up an agent button instead) and a bug/idea link to GitHub issues. On opted-in skills (every woLine truncated
One agent list and one lookup rule serve the launcher, the console and the app: `src/launcher/agents.json` (the built-ins and starter templates with per-OS install data) and `src/web-console/agent-lookup.mjs` (`loadAgentList()` and `findAgent()`, both copied by `install.js` into `~/.plan2code/bin/`); the app carries a Rust twin held to the same cases by `scripts/fixtures/agent-lookup-cases.json`. One agent list and one lookup rule serve the launcher, the console and the app: `src/launcher/agents.json` (the built-ins and starter templates with per-OS install data) and `src/web-console/agent-lookup.mjs` (`loadAgentList()` and `findAgent()`, both copied by `install.js` into `~/.plan2code/bin/`); the app carries a Rust twin held to the same cases by `scripts/fixtures/agent-lookup-cases.json`.
**Learning** (lessons about a codebase, kept with it): the dashboard draws a Learning row (Not set up, Off, On or Paused for you, with a Pause for me switch and a More menu) and, while lessons are waiting, a banner with Review, both from the scan's `learning` field (`public/screens/learning-row.js`, `public/styles/learning.css`); skills ask for approval through the `lessons` card kind. The server's only write for it is the personal pause, on this machine only (`POST /learning/pause`, under `~/.plan2code/learning/`); every change to the project's Learning files (`.plan2code/settings.json` and `.plan2code/lessons/`) goes through the `lessons.mjs` skill script, which shares one core with the scan, `src/web-console/learning.mjs`. **Learning** (lessons about a codebase, kept with it): the dashboard draws a Learning row (Not set up, Off, On or Paused for you, with a Pause for me switch and a More menu) and, while lessons are waiting, a banner with Review, both from the scan's `learning` field (`public/screens/learning-row.js`, `public/styles/learning.css`); skills ask for approval through the `lessons` card kind. The server's only write for it is the personal pause, on this machine only (`POST /learning/pause`, under `~/.plan2code/learning/`); every change to the project's Learning files (`.plan2code/settings.json` and `.plan2code/lessons/`) goes through the `lessons.mjs` skill script, which shares one core with the scan, `src/web-console/learning.mjs`.
Building or changing an Activities game: follow the game rules in [Activities](./.agents-docs/AGENTS-architecture-activities.md) ("Building an Activities game": lives in the solid lives pill, the endless-lives code (`cheat(on)`) in every game with lives, banners placed away from the player and see-through over what matters, pausing left to the window). Building or changing an Activities game: follow the game rules in [Activities](./.agents-docs/AGENTS-architecture-activities.md) ("Building an Activities game": lives in the solid lives pill, the endless-lives code (`cheat(on)`) in every game with lives, banners placed away from the player and see-through over what matters, pausing left to the window).
Details: [Web console server and contract](./.agents-docs/AGENTS-architecture-console.md), [page](./.agents-docs/AGENTS-architecture-console-page.md), [design points](./.agents-docs/AGENTS-architecture-console-design.md), [Activities](./.agents-docs/AGENTS-architecture-activities.md) (and the Ghoul Rush and Bounce Road files it links) and [.readme/web-console.md](./.readme/web-console.md) Details: [Web console server and contract](./.agents-docs/AGENTS-architecture-console.md), [page](./.agents-docs/AGENTS-architecture-console-page.md), [design points](./.agents-docs/AGENTS-architecture-console-design.md), [Activities](./.agents-docs/AGENTS-architecture-activities.md) (and the Ghoul Rush and Bounce Road files it links) [.readme/web-console.md](./.readme/web-console.md) (the user guide), [.readme/activities.md](./.readme/activities.md) and [.readme/web-console-internals.md](./.readme/web-console-internals.md) (routes, security, driving it by hand, refreshing screenshots)
Why the agent-facing console docs are shaped as they are (the card, pointers, refusals): [Web Console Contract](./.agents-docs/AGENTS-web-console-contract.md); it never ships. Why the agent-facing console docs are shaped as they are (the card, pointers, refusals): [Web Console Contract](./.agents-docs/AGENTS-web-console-contract.md); it never ships.
## Skill Scripts ## Skill Scripts
+44 -6
View File
@@ -2,34 +2,72 @@
All notable changes to Plan2Code will be documented in this file. All notable changes to Plan2Code will be documented in this file.
## v3.1.0 <!-- Format from 3.1.0 on: `## vX.Y.Z (YYYY-MM-DD)` with the date from version.json; a minor release opens with a three-bullet `### Highlights`; sections run Added, Changed, Fixed; game changes sit under one Activities line; tooling and test lines go under "For contributors". Older headings have no date and are not backfilled. -->
## v3.1.1 (2026-11-17)
### ✨ Added ### ✨ Added
- **Learning**: a dashboard row (and a banner) that keeps lessons about the codebase, approved by you. Switch it on or off per project, and the row shows "Switching on…" or "Switching off…" the moment you press the button. Lessons live under `.plan2code/lessons/`, and the failure log can be moved into them. - **desktop app**: Suggest for me, beside Set all to in the Implementation Loop's Strength per phase, asks the dashboard's agent to read each phase and pick a strength for it, with a one-line reason under each row; every pick stays yours to change.
- **Update dependencies**: a new `/plan2code-deps` skill that updates a project's dependencies using each package manager's own outdated and audit output, and writes a held-back upgrade up as an `UPGRADE-<date>.md` brief. Quick Task or Plan can pick that brief up, and the dashboard shows it as "Upgrade ready" and "Upgrade done". - **install**: the install command now ends in `#release`, a branch that moves to each published release, so a new install never gets unfinished work from `main`.
- **UI Prototype**: a new skill, and Quick Task confirms a saved prototype's brief before planning. It can also start from a Notebook tab. - **launcher**: `plan2code update` installs the newest release and prints one short summary (`Updating <old> -> <new>`, or `Already on <new>`); `--main` takes the newest work instead, `--tag <release>` goes back to an earlier one, and `--force` reinstalls.
- **launcher**: `plan2code uninstall` lists what it removes and what it keeps in `~/.plan2code/`, with sizes; `--purge` also removes the desktop app's own data, and `--yes` skips the questions.
- **launcher**: `plan2code --help` and `--version`; arguments after `--` go to the agent unchanged.
- **desktop app**: Update and restart in the top bar installs the newest release with live progress and reopens on the same project, asking first when an agent or a loop is running.
- **desktop app**: the window remembers its size and place, and the terminal gets a right-click menu, copy on select, font size keys and clickable links; new keyboard shortcuts work from both panes.
- **docs**: a SECURITY.md for private vulnerability reports, and the issue form links to the docs, the desktop app guide and security.
- **Learning**: Ask for suggestions on the lessons review now outlines the suggested choice on each lesson (Keep, Drop and the rest) with a dashed ring, without choosing it for you.
### 🔧 Changed
- **license**: Plan2Code is now licensed under Apache 2.0 (it was MIT), with a NOTICE file.
- **installer**: plainer output, with no colors or boxes when piped (`NO_COLOR` is honored), a spinner while the skills install, the exact PATH line for your shell when the command is not found, and a clear stop on Node.js older than 18.
- **web console**: a broad visual refresh (spacing, type, shadow and motion tokens, shared top-bar icons); "Helpers" is now "Subagents" everywhere, and the meter says "Conversation".
- **web console**: Clear acts at once with a 10-second Undo, the finish screen shows one main button, Help groups its topics with a filter and opens with `?`, and Cleanup shows what it will delete and its size.
- **Learning**: the lessons review keeps Ask for suggestions, Not now and Save lessons pinned to the bottom of the dialog, shows a spinner while suggestions are on the way, and lets the answer use the dialog's full width.
- **desktop app**: its own confirm dialogs (Cancel first and focused), plain-language errors with the details underneath, the console's theme from the first paint, and a top bar that folds extra buttons into a "+N more" menu.
- **UI Prototype**: the carry-over card opens ticked as suggested, each item tagged Keep or Free up with its reason.
- **docs**: the README is rewritten and shorter, the long guides moved into `.readme/`, the site hosts its own fonts and has a social card, and the screenshots are refreshed (Notepad is now Notebook).
- **For contributors**: the release workflow fast-forwards the `release` branch, new `make-site-images`, `make-social-card` and `make-app-placeholders` scripts, more screenshot fixtures, and wider launcher, installer, app and console tests.
### 🐛 Fixed
- **web console**: a click anywhere inside a Markdown box's border now puts the cursor in it, not only a click on the text.
- **launcher**: `plan2code update --main` reinstalls even when the version number has not moved (unreleased work on `main` keeps the last release's number), `uninstall` runs the newest release's installer, and a failed update no longer blocks the retry with "Already on".
- **desktop app**: on macOS Ctrl+C stays the interrupt even with text selected, `uninstall --purge` also removes the saved window state, the PATH lookup works under fish, and loop spec names may contain dots.
## v3.1.0 (2026-11-15)
### ✨ Added
- **Learning**: a dashboard row (and a banner) that keeps lessons about the codebase, approved by you. Switch it on or off per project, and the row shows "Switching on…" or "Switching off…" the moment you press the button. Lessons live under `.plan2code/lessons/`, and the failure log can be moved into them. The Lessons review shows that it is working while it saves, and always offers a way out.
- **Update dependencies**: a new `/plan2code-deps` skill that updates a project's dependencies using each package manager's own outdated and audit output, labels each update Safe, Check first or Warning in plain words, checks the untouched tree first so a group is blamed only for what it broke, honors versions the project pins, and writes a held-back upgrade up as an `UPGRADE-<date>.md` brief. It fixes a small break in your code or installs a missing scanner only after you approve that exact change, and its report names the files it fixed. Quick Task or Plan can pick that brief up, and the dashboard shows it as "Upgrade ready" and "Upgrade done".
- **UI Prototype**: a new skill, and Quick Task confirms a saved prototype's brief before planning. It can also start from a Notebook tab, and Pathfinder, Plan, Revise plan and Quick Task can offer one when a decision is about how a screen looks or flows.
- **web console**: a **Changes** tab at sign-off in Implement, Implement + Review and Quick Task. The run snapshots the working tree when it starts and draws the diff of everything it changed at the end, without touching the index or branches.
- **web console**: a **Prototypes** tab lists a spec's saved prototypes. An `.md` is read in place, and an `.html` opens in the default browser. - **web console**: a **Prototypes** tab lists a spec's saved prototypes. An `.md` is read in place, and an `.html` opens in the default browser.
- **web console**: the Activities picker is a two-column Score ledger, ordered by recently played or A to Z. - **web console**: the Activities picker is a two-column Score ledger, ordered by recently played or A to Z.
- **web console**: a swaying question mark beside Ask for suggestions, and a chevron before Send. - **web console**: a swaying question mark beside Ask for suggestions, and a chevron before Send.
- **launcher**: `plan2code` and the desktop shortcut offer the project folders you opened lately (the last five), and the desktop app asks for a folder the same way, with Choose a folder first.
- **Snake**: lives, bonus lives at score marks, and three bosses (Grumpy Golem, Comet Queen, Thunder Toad). - **Snake**: lives, bonus lives at score marks, and three bosses (Grumpy Golem, Comet Queen, Thunder Toad).
- **Bounce Road**: four new music tracks and extras. - **Bounce Road**: four new music tracks and extras.
- **web console**: Ask for suggestions is on the Lessons to keep card, in the Notes panel and in the Lessons modal, where the reply shows in a Suggestions box. - **web console**: Ask for suggestions is on the Lessons to keep card, in the Notes panel and in the Lessons modal, where the reply shows in a Suggestions box.
### 🔧 Changed ### 🔧 Changed
- **tooling**: tool folders (Dead Code's keep list and reports, Learning's settings) now live under `.plan2code/`, which is gitignored. - **tooling**: tool folders (Dead Code's keep list and reports, the metrics data, Learning's settings) now live under `.plan2code/`; the generated folders in it are gitignored, and the Learning settings and lessons are kept with the repository.
- **web console**: a new Notebook tab opens with its name as a `## heading`, and the caret waits under it. - **web console**: a new Notebook tab opens with its name as a `## heading`, and the caret waits under it.
- **web console**: the git board's branch title links to the branch on its host. - **web console**: the git board's branch title links to the branch on its host.
- **web console**: the dashboard keeps each group at one card width with no card left alone on a row, and the approval tip sits centered under the cards. - **web console**: the dashboard keeps each group at one card width with no card left alone on a row, and the approval tip sits centered under the cards.
- **web console**: the Diagnose finish shows the saved diagnosis in full, with Copy report for a ticket elsewhere. - **web console**: the Diagnose finish shows the saved diagnosis in full, with Copy report for a ticket elsewhere.
- **Quick Task**: offers to archive a prototype-only spec folder once it has built from it. - **Quick Task**: offers to archive a prototype-only spec folder once it has built from it.
- **desktop app**: the window no longer takes file drops, and the Loop driver was updated. - **desktop app**: the window no longer takes file drops, the Loop driver was updated, and when the reconnect countdown ends the app tries reconnecting once on its own.
- **docs**: a Test map section in AGENTS.md, and Learning turned on for this repository.
### 🐛 Fixed ### 🐛 Fixed
- **Quick Task**: a finish that offers the review again after a review already ran in that launch is refused. - **Quick Task**: a finish that offers the review again after a review already ran in that launch is refused.
- **web console**: the Lessons modal is as wide as the Notebook (it was stuck at the 440px default). - **web console**: the Lessons modal is as wide as the Notebook (it was stuck at the 440px default).
- **tooling**: the deps test starts its fixture server in a root before hook, so after hooks can no longer run early (it failed on Ubuntu and macOS CI).
## v3.0.6 ## v3.0.6
+1
View File
@@ -0,0 +1 @@
Plan2Code, Copyright 2026 Justin Parker
+17 -5
View File
@@ -16,7 +16,7 @@ The web console is the main way in: a local page where questions, documents, bui
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- | | ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| From your project (shell) | `plan2code` | Opens Claude Code, Devin or Codex on the dashboard (`--cli claude` / `devin` / `codex` to choose) | | From your project (shell) | `plan2code` | Opens Claude Code, Devin or Codex on the dashboard (`--cli claude` / `devin` / `codex` to choose) |
| Inside any agent | `/plan2code` (`$plan2code` in Codex) | Opens the dashboard: a card for every skill, launched on the same page | | Inside any agent | `/plan2code` (`$plan2code` in Codex) | Opens the dashboard: a card for every skill, launched on the same page |
| Install | `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git` | Installs the skills and the `plan2code` command (re-run it to update without the `plan2code` command) | | Install | `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release` | Installs the skills and the `plan2code` command (to update, run `plan2code update`; re-running the install command also works, and removes nothing) |
| Update | `plan2code update` | Updates the skills, command, app and status line, with no menu (metrics and the bot only from a git checkout: `node install.js`); never uninstalls anything | | Update | `plan2code update` | Updates the skills, command, app and status line, with no menu (metrics and the bot only from a git checkout: `node install.js`); never uninstalls anything |
| Uninstall | `plan2code uninstall` | Removes the skills, command, app and dev tools after a Y/N; then asks whether `~/.plan2code/` (your notebooks, handoffs, settings) goes too. `--yes` skips the questions and keeps your data, `--purge` deletes it | | Uninstall | `plan2code uninstall` | Removes the skills, command, app and dev tools after a Y/N; then asks whether `~/.plan2code/` (your notebooks, handoffs, settings) goes too. `--yes` skips the questions and keeps your data, `--purge` deletes it |
| Straight into a skill | `/plan2code-1-plan --web` (any step) | Skips the "web console or terminal?" question and opens the page | | Straight into a skill | `/plan2code-1-plan --web` (any step) | Skips the "web console or terminal?" question and opens the page |
@@ -25,7 +25,11 @@ The install command always opens a menu. Back at your prompt with no output at a
Pick a skill on the dashboard and the same page becomes that session. Details: [.readme/web-console.md](.readme/web-console.md) · worked example: [.readme/walkthrough.md](.readme/walkthrough.md). Pick a skill on the dashboard and the same page becomes that session. Details: [.readme/web-console.md](.readme/web-console.md) · worked example: [.readme/walkthrough.md](.readme/walkthrough.md).
The **Notebook** icon in the top bar opens a private scratch pad for the folder you are in (Markdown and pictures, kept in `~/.plan2code/notepads/`). Private: the agent never reads your Notebook. A tab reaches it only when you start a workflow with it. The **Notebook** icon in the top bar opens a private scratch pad for the folder you are in (Markdown and pictures, kept in `~/.plan2code/notepads/`); the agent reads a tab only when you send it by starting a skill from that tab.
**Desktop app:** the installer also offers a window with the dashboard and your agent's terminal side by side; once installed, `plan2code` opens it.
`plan2code --classic` keeps the agent in your terminal instead.
The **Implementation Loop** (app only) builds every remaining phase of a spec unattended, one fresh agent per phase: [docs/desktop-app.md](docs/desktop-app.md).
## Commands ## Commands
@@ -45,13 +49,14 @@ Every command below is what a dashboard card runs. Typed on its own, each one as
| 3 | /plan2code-3-implement | overview.md | Implemented code | | 3 | /plan2code-3-implement | overview.md | Implemented code |
| 3+review | /plan2code-3-implement-review | overview.md | Reviewed implementation ready for approval (alternative to `/plan2code-3-implement`) | | 3+review | /plan2code-3-implement-review | overview.md | Reviewed implementation ready for approval (alternative to `/plan2code-3-implement`) |
| 4 | /plan2code-4-finalize | overview.md | Archived specs | | 4 | /plan2code-4-finalize | overview.md | Archived specs |
| handoff | /plan2code-handoff | Conversation | Self-contained handoff doc (OS temp dir by default, or a folder you pick such as `handoffs/`) | | handoff | /plan2code-handoff | Conversation | Self-contained handoff doc, saved in `~/.plan2code/handoffs/` and listed on the dashboard to pick up |
| xray | /plan2code-xray | An area, or none | An explanation citing files and commits, or `ARCHITECTURE-BRIEF-<date>.md` with the rough spots you picked | | xray | /plan2code-xray | An area, or none | An explanation citing files and commits, or `ARCHITECTURE-BRIEF-<date>.md` with the rough spots you picked |
| diagnose | /plan2code-diagnose | A bug, or none | `DIAGNOSIS-<date>.md` with the cause and its evidence, then Quick Task (or Plan for a big fix) to fix it | | diagnose | /plan2code-diagnose | A bug, or none | `DIAGNOSIS-<date>.md` with the cause and its evidence, then Quick task (or Plan for a big fix) to fix it |
| pr-prep | /plan2code-pr-prep | Your branch | A readiness verdict (Ready, Ready with notes, Not ready) and a PR description to copy; no commits, no push | | pr-prep | /plan2code-pr-prep | Your branch | A readiness verdict (Ready, Ready with notes, Not ready) and a PR description to copy; no commits, no push |
| test | /plan2code-test | An area, or none | New unit and integration tests in the project's style, run; a bug handed to Diagnose; no source changes | | test | /plan2code-test | An area, or none | New unit and integration tests in the project's style, run; a bug handed to Diagnose; no source changes |
| dead-code | /plan2code-dead-code | A folder, or none | Findings labeled Safe, Check first or Warning, then only the removals you pick, checked by the tests and build; no commits, no installs | | dead-code | /plan2code-dead-code | A folder, or none | Findings labeled Safe, Check first or Warning, then only the removals you pick, checked by the tests and build; no commits, no installs |
| ui-prototype | /plan2code-ui-prototype | A screen or flow, or none | One page of several versions with live dials, your pick pasted back; `prototypes/<name>.html` and `.md` in a spec on a yes; no code changes | | ui-prototype | /plan2code-ui-prototype | A screen or flow, or none | One page of several versions with live dials, your pick pasted back; `prototypes/<name>.html` and `.md` in a spec on a yes; no code changes |
| deps | /plan2code-deps | Your manifests | Each update labeled Safe, Check first or Warning, then only the ones you pick applied in batches with your checks after each; a ticked Warning writes `UPGRADE-<date>.md`; no commits |
| changelog | /plan2code-changelog | Your branch | `CHANGELOG.md` entries and the `package.json` version, from the default branch's latest version | | changelog | /plan2code-changelog | Your branch | `CHANGELOG.md` entries and the `package.json` version, from the default branch's latest version |
| git | /plan2code-git | Your repo | Commits (`<subject>` / `AI Assisted`), branches, pull with conflict help, push, publish | | git | /plan2code-git | Your repo | Commits (`<subject>` / `AI Assisted`), branches, pull with conflict help, push, publish |
@@ -67,13 +72,20 @@ specs/
│ ├── questions/NN-<slug>.md # one decision question per file │ ├── questions/NN-<slug>.md # one decision question per file
│ └── briefs/brief-<date>.md # on-demand plain-English decision briefs │ └── briefs/brief-<date>.md # on-demand plain-English decision briefs
│ # (GitHub Issues backend: map issue + sub-issues instead) │ # (GitHub Issues backend: map issue + sub-issues instead)
├── prototypes/ # From Prototype a screen (saved on a yes)
│ └── <name>.html + <name>.md # the page, and the choice it made
├── PLAN-DRAFT-<date>.md # From Step 1 (verified plan) ├── PLAN-DRAFT-<date>.md # From Step 1 (verified plan)
├── PLAN-CONVERSATION-<date>.md # From Step 1 (conversation log) ├── PLAN-CONVERSATION-<date>.md # From Step 1 (conversation log)
├── DIAGNOSIS-<date>.md # From Diagnose a bug
├── UPGRADE-<date>.md # From Update dependencies (a ticked Warning)
├── overview.md # From Step 2 ├── overview.md # From Step 2
└── phase-X.md # From Step 2 ├── phase-X.md # From Step 2
└── LOOP-SUMMARY-<date>.md # From the Implementation Loop (desktop app)
specs--completed/ # After Step 4 specs--completed/ # After Step 4
└── <feature-name>/ # Archived specs └── <feature-name>/ # Archived specs
.plan2code/ # Saved with the repository: the project's lessons and the Learning switch
``` ```
Note: `<date>` uses YYYYMMDD format (e.g., `20250204`) Note: `<date>` uses YYYYMMDD format (e.g., `20250204`)
+72 -234
View File
@@ -1,19 +1,33 @@
# Plan2Code # Plan2Code
**A spec-driven workflow for AI coding agents.** [![Release](https://img.shields.io/github/v/release/jparkerweb/plan2code)](https://github.com/jparkerweb/plan2code/releases/latest) [![License](https://img.shields.io/github/license/jparkerweb/plan2code)](LICENSE) ![Platforms: Windows, macOS, Linux](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue)
<img src="docs/banner.jpg" alt="banner" data="object-fit:contain;" style="max-width:1024px;"> **Plan it. Approve it. Let it build.**
You work through Plan2Code on a page in your browser. The dashboard lists every step as a card, and - **The app.** A desktop window with the dashboard and your agent's terminal side by side, for Windows, macOS and Linux.
each step's questions, progress and sign-offs arrive on that same page while your agent does the - **The Loop.** It builds every remaining phase of a spec, one fresh agent per phase, while you do something else.
work. What you decide still lands in your repo as plain files: an approved plan becomes phase - **Plain files in your repo.** What you decide lands as specs, so the next session, agent and engineer start from the same plan.
documents, and the agent builds to them one phase at a time, so the next session, the next agent and
the next engineer all start from the same specs.
One command opens it, every step is a card, and the terminal is always there if you prefer it. <img src="docs/banner.jpg" alt="Plan2Code: Planny walking the steps from Pathfinder to Finalize" width="1024">
Version 3.1.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com) Plan2Code is a spec-driven workflow for AI coding agents. You work through it on a page in your browser: the dashboard lists every step as a card, and each step's questions, progress and sign-offs arrive on that same page while your agent does the work. An approved plan becomes phase documents, and the agent builds to them one phase at a time.
Version 3.1.1 · Apache 2.0 · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
---
## Contents
- [See it](#see-it)
- [Install and start](#install-and-start)
- [A session on the page](#a-session-on-the-page)
- [The workflow](#the-workflow)
- [The skills](#the-skills)
- [The four rules](#the-four-rules-that-do-most-of-the-work)
- [What lands in your repo](#what-lands-in-your-repo)
- [Troubleshooting](#troubleshooting)
- [Dive deeper](#dive-deeper)
--- ---
@@ -26,6 +40,12 @@ Version 3.1.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparke
The dashboard, in a project halfway through a build. It suggests the next step for the spec you pick. The dashboard, in a project halfway through a build. It suggests the next step for the spec you pick.
```bash
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release
```
Needs Node.js 18+ and Git (details under [Before you start](#before-you-start)). Then `cd` into your project and run `plan2code`.
--- ---
## Install and start ## Install and start
@@ -38,10 +58,10 @@ The dashboard, in a project halfway through a build. It suggests the next step f
- **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex). - **Ways in.** `plan2code` (Claude Code, Devin or Codex), or type `/plan2code` in your agent (`$plan2code` in Codex).
- **No agent yet?** Install Claude Code, Codex or Devin first, or let the `plan2code` command's setup page walk you through it. - **No agent yet?** Install Claude Code, Codex or Devin first, or let the `plan2code` command's setup page walk you through it.
Installation needs network access and runs through the [skills CLI](https://skills.sh). To update, run `plan2code update` (or re-run the install command). To remove everything, run `plan2code uninstall`: it asks first, then asks whether your own data in `~/.plan2code/` (notebooks, handoffs, settings) goes too. `--yes` skips the questions and keeps your data; add `--purge` to delete it. Installation needs network access and runs through the [skills CLI](https://skills.sh). The command installs the newest release: `#release` is a branch that moves to each release as it is published, so you never get unfinished work from `main`. To update, run `plan2code update`: it installs the newest release too, prints `Updating <old> -> <new>` (or `Already on <new>` and stops; `plan2code update --force` reinstalls anyway), and `plan2code update --main` takes the newest work on `main` instead. **Go back to a release** with `plan2code update --tag v3.0.2` (any release tag works). To remove everything, run `plan2code uninstall`: it asks first, then asks whether your own data in `~/.plan2code/` (notebooks, handoffs, settings) goes too. `--yes` skips the questions and keeps your data; add `--purge` to delete it.
```bash ```bash
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release
``` ```
This fetches the installer to a temp directory, builds the workflow as Agent Skills, delegates This fetches the installer to a temp directory, builds the workflow as Agent Skills, delegates
@@ -76,74 +96,15 @@ The installer opens this menu (cloning and running `node install.js`, below, ope
Already inside your agent? Type `/plan2code` instead (`$plan2code` in Codex). Already inside your agent? Type `/plan2code` instead (`$plan2code` in Codex).
<details> Run `plan2code` from any project to open the dashboard in Claude Code, Devin or Codex (it asks which when more than one is installed). Flags, permission prompts, the desktop shortcut, other agent CLIs and the setup page for a missing agent are in [.readme/launcher.md](.readme/launcher.md).
<summary>About the plan2code command</summary>
Install (`I`) adds `plan2code` as a global command (Advanced `A` → `D` adds just the command). Run it from any project and the Plan2Code ### The desktop app
dashboard opens right there, in **Claude Code**, **Devin** or **Codex**. With more than one installed it asks which and
remembers your pick; `plan2code --cli claude`, `--cli devin` or `--cli codex` skips the question, and `--model <name>`
chooses the model. It works in cmd, PowerShell, Git Bash, macOS and Linux shells, and needs the
Claude Code, Devin or Codex CLI on your `PATH`. After you pick the agent it asks whether to turn its
permission prompts off (Yes by default; `--permission-mode bypassPermissions` in Claude Code, `--permission-mode bypass`
in Devin, `--dangerously-bypass-approvals-and-sandbox` in Codex, a custom agent's bypass arguments, and no question for a
custom agent that has none; for Codex the question names its sandbox, which that flag turns off too). It asks on every
launch and remembers no answer. `plan2code --keep-permissions` keeps the prompts without asking, and
`plan2code --bypass-permissions` turns them off without asking. With no terminal to ask on (a script or a pipe) the
prompts stay on unless `--bypass-permissions` is given. The installer then offers a desktop shortcut (answer `y`),
which opens a folder menu first: Choose a folder, with the project folders you opened lately under it (with none yet, it goes straight to the folder dialog). In a terminal, `plan2code` offers the same recent folders as a numbered menu. Uninstalling (`U`, or `plan2code uninstall` from any terminal) removes both.
</details>
<details> <img src="docs/screenshots/app-terminal-dark.webp" alt="The desktop app: the Plan2Code dashboard on the left and the agent's terminal docked on the right.">
<summary>Using another agent CLI, or none yet</summary>
Plan2Code runs inside an AI coding agent CLI. With no agent it can run (none of Claude Code, The installer also offers the **Plan2Code desktop app**: one window with the dashboard and your agent's terminal side by side, docked right or bottom. A launch card asks which agent, model and effort to start on, and once it is installed `plan2code` opens the app (`plan2code --classic` keeps the terminal flow). `plan2code update` updates the skills, the command and the app together.
Devin or Codex, and no working custom agent),
`plan2code` opens a setup page in your browser (the web console runs it, so no agent is needed).
The page lists each agent as **Found**, **Found outside PATH** or **Not found**, with its install
commands for your system, a Copy button per command and an **Install page** link. Install one and
press **Check again**: no restart needed. An agent found outside `PATH` gets **Use it from here**,
which saves where it was found so you never touch `PATH` yourself. Below the list sit five starter
templates (GitHub Copilot CLI, OpenCode, Gemini CLI, Pi and Cursor CLI) for agents Plan2Code does not ship.
**Start with this agent** carries the run straight on in the same tab, onto the new agent's
dashboard. Naming a built-in that is missing with `--cli <name>` opens the same page on that agent
(a missing custom agent prints its own steps and exits 127). In the
desktop app a **Set up an agent** button opens the same page in the window and returns to the
launch card with the found agent picked. Where no page can open, such as over SSH or with no
display, `plan2code` prints the install commands and install pages and exits with code 127.
Once an agent is running, to use a different agent CLI, open the web console's **User Preferences → Agents & models** and add it: a name, the The app is not code-signed (signing is not planned for now), so your system may ask you to allow it once. More about the app, a manual download and the Implementation Loop: [docs/desktop-app.md](docs/desktop-app.md).
command, and (optionally) its arguments, the start prompt, arguments for skipping permission prompts, and
how it takes a model. Custom agents are saved in `~/.plan2code/agents.json` and used by both the
`plan2code` command (listed after the built-ins; `--cli <id>` picks one) and the desktop app's picker. The
`/plan2code` start prompt only does something in an agent that loads the installed Plan2Code skills; for
any other, leave the start prompt blank and start a skill yourself. Details in
[.readme/web-console.md](.readme/web-console.md#agents--models).
</details>
<details>
<summary>About the desktop app</summary>
The installer also offers the **Plan2Code desktop app**: one window with the dashboard and your agent's
terminal side by side, docked right (or bottom) and collapsible. Every console page, not only the
dashboard, opens inside it. A launch card asks which agent, model and effort to start on, with
permission checks off as its own tick (on by default, matching the terminal flow; untick it to keep
the agent's approval prompts). A **New Session** button in the top bar replaces the agent with a fresh
one on a brief built from the session, and the console's own Session meter points at it when a
session is getting long. Once it is installed, `plan2code` opens the app instead of running the agent
in your terminal. `plan2code --classic` keeps the terminal flow, and so does a Linux machine with no
display (over SSH, say) or any machine over an SSH session. `plan2code update` updates the skills, the
command and the app together; run it in a terminal outside the app when the bar says **Update
available**, then reopen the app. The bar also offers **Update skills** when the app and the installed
skills disagree. `plan2code uninstall` removes all three.
The app can also build a whole spec unattended with the Implementation Loop; see [docs/desktop-app.md](docs/desktop-app.md#implementation-loop).
The first release is unsigned, so macOS (**Open Anyway** in System Settings, Privacy & Security) or
Windows (**More info**, then **Run anyway**) may ask you to allow it once. The app starts the agent
with its normal approval prompts unless you tick the launch card's permission-checks-off option (the
plain `plan2code` command above, without the app, asks instead, with prompts off by default too). Details:
[docs/desktop-app.md](docs/desktop-app.md).
</details>
**Supported tools** (the agents the skills CLI can install into): every agent it supports, including Claude Code · Cursor · **Supported tools** (the agents the skills CLI can install into): every agent it supports, including Claude Code · Cursor ·
GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · OpenCode · Devin · Crush · Pi · GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · OpenCode · Devin · Crush · Pi ·
@@ -192,7 +153,7 @@ worked on right now.
</picture> </picture>
**Sign off.** Read the completion report, then approve the phase or ask for changes. In Implement, **Sign off.** Read the completion report, then approve the phase or ask for changes. In Implement,
you can also have the code reviewed first; Implement + review has already done it. you can also have the code reviewed first; Implement + Review has already done it.
<picture> <picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/signoff-dark.webp"> <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/signoff-dark.webp">
@@ -210,7 +171,7 @@ next check-in, and it never holds up your answers.
There is more on the page when you need it. Notes on any question can carry screenshots and There is more on the page when you need it. Notes on any question can carry screenshots and
documents. The folder label in the bottom bar opens your workspace, where you add other folders documents. The folder label in the bottom bar opens your workspace, where you add other folders
as read-only context and point at them by `@name`. The **Notebook** in the top bar is a private pad of your own for the as read-only context and point at them by `@name`. The **Notebook** in the top bar is a private pad of your own for the
folder, in Markdown with pictures, that the agent reads only when you start a workflow from one of its tabs on folder, in Markdown with pictures, that the agent reads only when you start a skill from one of its tabs on
the dashboard and send the box it fills. The **die** beside it opens **Activities**, the dashboard and send the box it fills. The **die** beside it opens **Activities**,
thirteen small games to play through a long wait, which pause the moment it is your turn. The session meter in the top bar turns from green thirteen small games to play through a long wait, which pause the moment it is your turn. The session meter in the top bar turns from green
to red as a session grows long and suggests a fresh one. **Stop session** saves your place and gives to red as a session grows long and suggests a fresh one. **Stop session** saves your place and gives
@@ -239,31 +200,7 @@ Each box is a card on the dashboard. Chaining a couple of small steps in one ses
start a fresh session before a big plan or build step: planning context leaking into implementation start a fresh session before a big plan or build step: planning context leaking into implementation
is where most agent drift starts. is where most agent drift starts.
The dashboard's cards, and when each one lights up for the spec you pick: Every box is a card, and so is every other skill. They are all in [The skills](#the-skills), with the command for each.
| Card | What it is for | Lights up when |
|------|----------------|----------------|
| Set up this project | Reads your project and writes AGENTS.md, the guide every later step works from. | The project has no AGENTS.md yet |
| Refresh AGENTS.md | Brings AGENTS.md and its notes up to date with what the project has learned lately. | The project has an AGENTS.md |
| Pathfinder | A foggy idea becomes a clear list of decisions, settled one question at a time. | You start fresh, or the spec is still being explored |
| Plan | Requirements, technical design and your approval: the shape of what gets built. | You start fresh, or the spec has a finished Pathfinder map, a drafted plan or a bug diagnosis |
| Revise the plan | Requirements changed mid-build? Adjust the plan without starting over. | The spec is written up into phases, built or not |
| Document | The plan becomes a checklist of small tasks, grouped into phases, that a developer can just do. | The spec has a drafted plan |
| Implement | Builds the next phase, task by task, with a report and your sign-off at the end. | The spec has phases with tasks still to build |
| Implement + review | One phase built, then a careful review of the changes, then your sign-off. All in one run. | The spec has phases with tasks still to build |
| Finalize | Checks the work, writes the summary, files the specs away and suggests the commit message. | Every task in the spec is done |
| Quick task | Too small for the full process? A quick plan, then it just builds it. | Always (suggested when the spec is a diagnosed bug or an upgrade brief) |
| Review | A second opinion on the changes. Problems ranked, and you pick what gets fixed. | Always |
| Handoff | Pack this conversation into a document a fresh session can pick up cold. Any skill's **Stop with a handoff** writes one too, and the dashboard lists them to pick up. | Always |
| Codebase X-ray | Explain how and why an area works, or find the rough spots worth fixing. | Always |
| Diagnose a bug | Find a bug's cause and write it up, without fixing it. | Always |
| Get a PR ready | Runs the checks your branch needs, says if it is ready, and writes the PR description to copy. Never commits, pushes or opens the PR. | Always |
| Write missing tests | Finds code with no tests and writes unit and integration tests in your project's own style. Never changes source code. | Always |
| Clear out dead code | Finds code nothing uses, says how safe each piece is to remove, and removes only what you pick. Uses the dead-code tools your project already has, and never commits. | Always |
| Update dependencies | Scans every manifest, labels each update Safe, Check first or Warning, applies only what you pick in batches with your checks after each, and puts back whatever breaks. A ticked Warning becomes an upgrade brief for Quick task or Plan. Never commits. | Always |
| Prototype a screen | Several versions of a screen on one page, tuned with live dials, and your pick brought back by Copy and paste. Saved into a spec only when you say, and never changes your code. | Always (takes the picked spec as the save folder) |
| Changelog | Checks the CHANGELOG version against the main branch and suggests entries for what is new. | Always |
| Git | Branches, pull, push and commits on one board, asking before anything leaves your machine. | Always (offers to start a repository outside one) |
Pathfinder, Plan, Revise the plan and Quick task can each offer a prototype when a decision is about how a screen looks or flows, and run it right there in the same session; nothing is drawn without your yes. Pathfinder, Plan, Revise the plan and Quick task can each offer a prototype when a decision is about how a screen looks or flows, and run it right there in the same session; nothing is drawn without your yes.
@@ -305,145 +242,45 @@ keep the two out of each other's way.
## The six steps in detail ## The six steps in detail
Each step is its own run, and the specs on disk are the only thing carried from one to the next. Each step is its own run, and the specs on disk are the only thing carried from one to the next. What each step asks, writes and hands on is in [.readme/steps.md](.readme/steps.md).
Chain a small one onto the last, or start a fresh session for a big one (rule 1).
### 0 · Pathfinder 🧭 (optional)
On the page: one question at a time with the options and their trade-offs, the map growing in its own
tab, and a **Write a brief** button for a printable summary.
Some ideas are too big and unclear to plan: you can feel the shape of the work but you can't write
it as requirements, so planning would just invent the answers. Pathfinder finds the *way* to the
destination; Step 1 then walks it.
1. **Name the destination** — one or two lines fixing what this effort is finding its way to. Settled
first, because it fixes scope. It also asks where the map should live: **local files** under
gitignored `specs/` (private, solo — the default), or **GitHub Issues** (a map issue with one
sub-issue per decision, native blocking, so your team can see and work the frontier in the tracker).
2. **Chart the map** — a breadth-first grilling surfaces the open decisions. Anything you can phrase
*sharply* becomes a question file; anything you can only sense stays listed as fog.
3. **Clear the questions one at a time** — resolving one burns off the fog behind it, graduating
whatever just became sharp into new questions. After each decision it offers a menu: take the next
question here, or start fresh — recommended after about three, to keep the agent sharp.
Ask for a **brief** at any point and you get a dated, plain-English summary of what has been
decided, what is still open, and what is next — meeting minutes, with no jargon in them.
4. **Hand off** — when nothing is left to decide, it writes a `PLAN-DRAFT` that
`/plan2code-1-plan` resumes from at Phase 4, with requirements, context, and scope already
answered.
**Question types:** `grill` (a decision only you can make — the default) · `research` (a fact gates
it; background agents resolve these, several in parallel) · `sketch` (you need something concrete to
react to) · `legwork` (manual work that has to happen before a decision is possible).
It never answers its own questions, and it **plans, it never builds.** When the urge to just build it
arrives, the map is done. Skip Step 0 entirely when you already know what you're building.
**Out:** `specs/<feature>/pathfinder/map.md` + `questions/` (or a `pathfinder:map` issue and its
sub-issues) → `PLAN-DRAFT-<date>.md`. The draft is always a local file — that is what Step 1 reads.
### 1 · Plan 🤔
On the page: questions in batches of up to three, the phase breakdown as a list you can reorder and
edit, and a sign-off at each stage.
The agent works as a senior architect through seven phases, stopping for you after each: requirements
analysis · system context (reading your actual codebase) · scope assessment (a large project saves and
resumes in a fresh session) · tech stack (needs your explicit sign-off) · architecture design ·
technical specification · transition decision.
It won't finalize below **90% confidence**, and every assumption it makes is written into the draft.
**In:** a description of the feature. **Out:** `PLAN-DRAFT-<date>.md` + `PLAN-CONVERSATION-<date>.md`
### 2 · Document 📝
On the page: a question only where the plan leaves something open, each phase file appearing as its
own tab as it is written, and one sign-off at the end.
The plan becomes the drawing. One `overview.md` with the phase checklist, plus one file per phase of
one-story-point tasks. Each phase is **self-contained** — an agent opening `phase-3.md` cold needs
nothing else to build it. Unit and E2E tests are excluded unless you ask for them.
The overview also identifies the **parallel execution groups**: phases with no shared files or
dependencies, safe to run in separate agents at once.
**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `phase-1…N.md`
### 3 · Implement ⚡
On the page: a progress bar and the phase's task list ticking over as tasks land, then the completion
report and a sign-off card where you approve, ask for changes, or have the code reviewed first.
Point it at `overview.md` and it does the rest: finds the next unchecked phase, implements every task
exactly as specified, ticks tasks off as they land, then reviews its own work against the spec and
writes a completion summary.
One phase per conversation. It won't run tests unless the phase says to.
**In:** `specs/<feature>/overview.md`. **Out:** working code, and updated checkboxes.
Want a second pair of eyes before you sign off? `/plan2code-3-implement-review` builds the phase the
same way, runs a focused review and the fixes you pick, and only then asks for approval.
### Review 🔬 — optional, any time
On the page: a few questions on scope, the findings as a report you can read in full, and a list
where you tick what gets fixed.
An independent second opinion, not a rubber stamp. It figures out its own scope (conversation
context, your instruction, or the git diff as a fallback), analyses across 11 dimensions, and ranks
findings Critical / Warning / Suggestion. Every finding cites a file and a line, or it gets dropped —
and the review pass is read-only. It fixes things only if you ask, and verifies each fix afterwards.
Spec-aware when `specs/` exists, and works fine without it. Most useful right after a planning or
implementation step, but there's no wrong time to run it.
### 4 · Finalize 🧹
On the page: the task audit and the summary as reports, a list of the doc updates to approve, and a
confirmation before anything is archived.
Validates every task against its phase spec, writes the summary and the list of files touched, flags
the docs that drifted (`README`, `CHANGELOG`, `AGENTS.md`), then archives the whole spec folder —
`pathfinder/` included — to `specs--completed/`. That folder is the record of *why* the code looks
like this.
**In:** `specs/<feature>/overview.md`. **Out:** archived specs.
--- ---
## Prefer the terminal? ## The skills
Each one is a card on the dashboard and a command in your agent. Which cards light up for the spec you pick, the inputs and outputs, and the decision tree are on the [quick reference](QUICK-REFERENCE.md).
| Command | What it does |
|---------|--------------|
| `/plan2code` | Open the dashboard: every skill below as a card, launched on the page |
| `/plan2code-init` | Set up this project: reads it and writes AGENTS.md, the guide every later step works from |
| `/plan2code-init-update` | Refresh AGENTS.md with what the project has learned lately |
| `/plan2code-0-pathfinder` | Pathfinder: turn a foggy idea into decisions, one question at a time, and hand a plan draft to Plan |
| `/plan2code-1-plan` | Plan: requirements, technical design and your approval |
| `/plan2code-2-document` | Document: turn the plan into phase files of small tasks |
| `/plan2code-3-implement` | Implement: build the next phase, with a report and your sign-off |
| `/plan2code-3-implement-review` | Implement + Review: build the phase, review it, then ask for sign-off |
| `/plan2code-4-finalize` | Finalize: check the work, summarize, archive the specs, suggest the commit |
| `/plan2code-1b-revise-plan` | Revise the plan: requirements moved mid-build, so change the specs, not the code |
| `/plan2code-quick-task` | Quick task: a small change with a quick plan, then it builds it |
| `/plan2code-review` | Review: a second opinion on your changes, problems ranked, you pick what gets fixed |
| `/plan2code-handoff` | Handoff: pack this conversation into a document a fresh session picks up cold |
| `/plan2code-xray` | Codebase X-ray: explain how and why an area works, or rank the rough spots; never edits code |
| `/plan2code-diagnose` | Diagnose a bug: find the cause and write it up without fixing it |
| `/plan2code-pr-prep` | PR Prep: run the checks your branch needs, say if it is ready, write the PR description |
| `/plan2code-test` | Write missing tests: find untested code and write tests in your project's style |
| `/plan2code-dead-code` | Clear out dead code: find what nothing uses, remove only what you pick |
| `/plan2code-deps` | Update dependencies: label each update Safe, Check first or Warning, apply what you pick in batches |
| `/plan2code-ui-prototype` | Prototype a screen: several versions on one page with live dials; never changes your code |
| `/plan2code-changelog` | Changelog: check the CHANGELOG version against the default branch, suggest entries |
| `/plan2code-git` | Git: branches, pull, push and commits on one board, asking before anything leaves your machine |
### Prefer the terminal?
Every skill also runs right in the terminal. Each one asks at the start whether you want the web Every skill also runs right in the terminal. Each one asks at the start whether you want the web
console or the terminal; add `--web` to skip the question and go straight to the web console: console or the terminal; add `--web` to skip the question and go straight to the web console:
`/plan2code-1-plan --web plan a REST API for tasks`. `/plan2code-1-plan --web plan a REST API for tasks`.
| Command | Use it when |
|---------|-------------|
| `/plan2code` | Open the dashboard in the web console: every skill below as a card, launched on the page |
| `/plan2code-0-pathfinder` | The idea is too big and unclear to plan. Charts it as decisions, clears them one at a time, hands a hot plan draft to Step 1 |
| `/plan2code-1-plan` | Starting a feature. Full requirements → architecture pass |
| `/plan2code-2-document` | Planning is done. Turn the plan into phase specs |
| `/plan2code-3-implement` | Build the next phase (one per conversation) |
| `/plan2code-3-implement-review` | Build the next phase and review it before you approve it (instead of `/plan2code-3-implement`) |
| `/plan2code-review` | Independent second opinion on local changes, then optional fixes |
| `/plan2code-4-finalize` | All phases done. Validate, summarize, archive |
| `/plan2code-init` | Generate this repo's `AGENTS.md` so every agent starts informed |
| `/plan2code-init-update` | Fold what you learned this session back into `AGENTS.md` |
| `/plan2code-quick-task` | A small change that doesn't warrant the full sequence |
| `/plan2code-1b-revise-plan` | Requirements moved mid-build. Revise the specs, not the code |
| `/plan2code-handoff` | Compact this conversation into a doc the next one resumes from, saved in `~/.plan2code/handoffs/` and listed on the dashboard to pick up |
| `/plan2code-xray` | Explain how and why an area of the code works (citing files, commits and PRs), or rank the rough spots worth fixing into a brief for Pathfinder or Plan; never edits code |
| `/plan2code-diagnose` | Find a bug's cause and write it up as `specs/<bug-name>/DIAGNOSIS-<date>.md` without fixing it, then offer `/plan2code-quick-task` to fix it, or `/plan2code-1-plan` when the fix is big |
| `/plan2code-pr-prep` | Before you open a pull request. Picks the checks the branch's changes need from the project's `## Test map` (or its config files), runs the ones you keep, says Ready, Ready with notes or Not ready, and writes a PR description to copy with the create-a-PR link; never commits, pushes or opens the PR |
| `/plan2code-test` | Parts of the code have no tests. Asks where to look, finds the untested files (plus real coverage when the project already has a coverage tool), shows a plan in the project's own style, then writes and runs unit and integration tests; never changes source code, hands a real bug to `/plan2code-diagnose` |
| `/plan2code-dead-code` | Code nothing calls anymore. Uses the project's own dead-code tools, one per language (Knip, vulture, cargo check and others), or searches by itself, checks every item for callers across the project, labels each Safe to remove, Check first or Warning, removes only what you pick, then runs the tests and build and puts back anything that breaks them; never commits, never installs anything |
| `/plan2code-deps` | Clear a dependency backlog in one sitting. Scans every manifest (npm, pnpm, Yarn, Cargo, pip, uv, Go, .NET), labels each update Safe, Check first or Warning with a reason, applies the ones you pick in batches, runs the install and your checks after each batch and puts back whatever breaks; a ticked Warning writes `specs/<package>-upgrade/UPGRADE-<date>.md`, which the dashboard shows as *Upgrade ready* for `/plan2code-quick-task` or `/plan2code-1-plan`; never commits; installs a scanner or fixes a small break in your code only after you approve that exact change |
| `/plan2code-ui-prototype` | See a screen before it gets built. Draws several versions of a screen or flow on one page that opens in your browser, with live dials for fonts, colors, spacing and feel; Copy and paste brings your pick back for the next round, and a yes saves it as `specs/<spec>/prototypes/<name>.html` and `.md`; never changes your code |
| `/plan2code-changelog` | Check the CHANGELOG version against the default branch, suggest entries for new work you can edit, keep `package.json` aligned, then hand off to Git to commit |
| `/plan2code-git` | Branches, pull, push and commits on one board (or plain instructions in the terminal); asks before every push, publish and delete |
--- ---
## Troubleshooting ## Troubleshooting
@@ -493,7 +330,8 @@ edits out through the skills CLI.
Core reference: Core reference:
- **[.readme/web-console.md](.readme/web-console.md)**: the full guide to the web console, from the dashboard to the last sign-off, including the private Notebook and Activities in the top bar - **[.readme/](.readme/README.md)**: the index of the long guides
- **[.readme/web-console.md](.readme/web-console.md)**: the guide to the web console, from the dashboard to the last sign-off, including the private Notebook, with [Activities](.readme/activities.md) and the [internals](.readme/web-console-internals.md) in their own files
- **[QUICK-REFERENCE.md](QUICK-REFERENCE.md)** — the one-page card: commands, inputs, outputs, decision tree - **[QUICK-REFERENCE.md](QUICK-REFERENCE.md)** — the one-page card: commands, inputs, outputs, decision tree
- **[.readme/walkthrough.md](.readme/walkthrough.md)** — one feature from a sentence to archived specs, session by session - **[.readme/walkthrough.md](.readme/walkthrough.md)** — one feature from a sentence to archived specs, session by session
- **[AGENTS.md](AGENTS.md)** — architecture and contributor guide for this repo - **[AGENTS.md](AGENTS.md)** — architecture and contributor guide for this repo
+13
View File
@@ -0,0 +1,13 @@
# Security
## Reporting a vulnerability
Please report a vulnerability privately, not as a public issue. Use GitHub's private reporting: open the repository's **Security** tab and choose **Report a vulnerability** (or go to <https://github.com/jparkerweb/plan2code/security/advisories/new>).
Include what you found, the version (`version.json`, or the bottom of the web console's Help dialog), your system, and the steps to reproduce it. You can expect a first reply within a few days. Once a fix is released, the report is published with credit to you if you want it.
## What is in scope
Plan2Code runs on your own machine: the installer, the `plan2code` command, the local web console (served on `127.0.0.1` with a per-session token) and the desktop app. Reports about any of these are welcome, in particular anything that lets a web page or another local user reach the console, read or write files outside the project, or run a command the person did not approve.
The desktop app is not code-signed; that is documented in [docs/desktop-app.md](docs/desktop-app.md#the-app-is-not-code-signed) and is not a vulnerability report.
+46 -16
View File
@@ -7,12 +7,16 @@ session. The fresh agent gets a console session of its own, so the Session meter
It is an addition: `/plan2code` typed inside an agent works exactly as before, with or It is an addition: `/plan2code` typed inside an agent works exactly as before, with or
without the app. without the app.
![The launch card: which agent, model and effort to start on, with permission checks as their own tick.](screenshots/app-launch-dark.webp)
![The app with the dashboard on the left and the agent's terminal docked on the right.](screenshots/app-terminal-dark.webp)
## Get it ## Get it
The installer offers the app after the skills and the `plan2code` command: The installer offers the app after the skills and the `plan2code` command:
``` ```
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release
``` ```
Answer **Y** to "Also install the Plan2Code desktop app?" (it is the default). It downloads the file Answer **Y** to "Also install the Plan2Code desktop app?" (it is the default). It downloads the file
@@ -38,10 +42,19 @@ verified. `plan2code-app`'s own `npm run build` can produce `.msi`/NSIS/`.dmg`/`
(Tauri's bundler is on), but the release workflow does not build or publish them; nothing today (Tauri's bundler is on), but the release workflow does not build or publish them; nothing today
downloads or runs one. downloads or runs one.
### Manual download
Only when you cannot run the installer. Open the [latest release](https://github.com/jparkerweb/plan2code/releases/latest), then:
1. Download the file for your system from the table above, and `plan2code-app-<version>-SHA256SUMS.txt` beside it.
2. Verify it: the hash you compute must match that file's line in the checksum list. On macOS use `shasum -a 256 <file>`, on Linux `sha256sum <file>`, on Windows PowerShell `Get-FileHash <file> -Algorithm SHA256`.
3. Put it in `~/.plan2code/app/` (on Windows `%USERPROFILE%\.plan2code\app\`) and name it `plan2code-app` (`plan2code-app.exe` on Windows), so `plan2code` finds it.
4. On macOS and Linux, make it runnable: `chmod +x ~/.plan2code/app/plan2code-app`.
You also need Node.js 18 or newer (the app checks at start and says what to install) and: You also need Node.js 18 or newer (the app checks at start and says what to install) and:
- **Windows:** the WebView2 runtime, which comes with Windows 11 and current Windows 10. - **Windows:** the WebView2 runtime, which comes with Windows 11 and current Windows 10.
- **Linux:** WebKitGTK 4.1 (`libwebkit2gtk-4.1`) and a desktop session. - **Linux:** WebKitGTK 4.1 (`libwebkit2gtk-4.1`) and a desktop session. Install it with `sudo apt install libwebkit2gtk-4.1-0` (Debian, Ubuntu) or `sudo dnf install webkit2gtk4.1` (Fedora).
## Start it ## Start it
@@ -50,7 +63,7 @@ Run `plan2code` in your project, as always. When the app is installed and a wind
running the agent in your terminal. The desktop shortcut the installer can create runs the same running the agent in your terminal. The desktop shortcut the installer can create runs the same
command, so it opens the app too; it asks for the folder first, with **Choose a folder** at the top and the folders you opened lately under it (with none yet, it goes straight to the folder dialog). command, so it opens the app too; it asks for the folder first, with **Choose a folder** at the top and the folders you opened lately under it (with none yet, it goes straight to the folder dialog).
Start the app itself (from the Start menu, the Dock or a launcher) and it asks for a folder the same way: **Choose a folder** first, then your recent folders, newest first. It no longer reopens the last folder on its own. You can also start the app file itself: double-click it in `~/.plan2code/app/`, or run it from a terminal. Nothing adds it to the Start menu, the Dock or a launcher menu, so pin the file yourself if you want a shortcut. It asks for a folder the same way: **Choose a folder** first, then your recent folders, newest first. It no longer reopens the last folder on its own.
Three things keep today's terminal flow: Three things keep today's terminal flow:
@@ -123,9 +136,10 @@ to that offers the same **Reconnect the console** button — never "Restart the
The console also knows when it is running inside the app (the agent it talks to carries that signal): The console also knows when it is running inside the app (the agent it talks to carries that signal):
its session meter, the "Before you close this" guide on a finished step, and the dashboard's red-session its session meter, the "Before you close this" guide on a finished step, and the dashboard's red-session
banner all point at the app's own **New Session** button instead of a command to paste into a new banner all point at the app's own **New Session** button instead of a command to paste into a new
conversation, since New Session already does that in one click. The dashboard's **UPDATE AVAILABLE** conversation, since New Session already does that in one click. The dashboard's **Update available**
banner still shows, beside the bar's own **Update available**, and its steps say to run the command in a banner still shows, beside the bar's own **Update available**: its dialog points at the bar's **Update and
terminal outside the app and then reopen the app (see "Keep it up to date" below). A slash command still offered to continue a step (such as `/plan2code-4-finalize`) stays restart** first, with the command as the fallback, run in a terminal outside the app before reopening the
app (see "Keep it up to date" below). A slash command still offered to continue a step (such as `/plan2code-4-finalize`) stays
exactly as it would in a terminal: paste it into the app's own terminal panel, which runs the real exactly as it would in a terminal: paste it into the app's own terminal panel, which runs the real
agent CLI. agent CLI.
@@ -136,6 +150,12 @@ while you do something else. It is in the app only: the dashboard shows an **Imp
card there, and nowhere else. Pick a spec, answer a short setup, press **Start the loop**, and the app card there, and nowhere else. Pick a spec, answer a short setup, press **Start the loop**, and the app
confirms it once in its own window before anything runs. confirms it once in its own window before anything runs.
![The Implementation Loop setup screen.](screenshots/loop-setup-dark.webp)
![The Loop's banner while a phase builds, with Stop after this phase.](screenshots/loop-banner-dark.webp)
![The Loop's stop screen, with the evidence for why it stopped.](screenshots/loop-stop-dark.webp)
**How it runs.** Each phase gets a fresh agent session, so a long spec never grows one tired **How it runs.** Each phase gets a fresh agent session, so a long spec never grows one tired
conversation. The app, not the agent, decides when a phase counts: it reads the spec's marks, runs the conversation. The app, not the agent, decides when a phase counts: it reads the spec's marks, runs the
quick check, marks the phase done and commits it. With commits on, it commits to the branch you are on and never quick check, marks the phase done and commits it. With commits on, it commits to the branch you are on and never
@@ -148,7 +168,7 @@ not), so your own edits never end up inside a phase's commit.
- **Fix findings**: **Smart pick** (the default) has a fresh agent read the findings and fix only the - **Fix findings**: **Smart pick** (the default) has a fresh agent read the findings and fix only the
ones worth fixing, recording every skip. A skipped Critical stops the phase. **By level** fixes the ones worth fixing, recording every skip. A skipped Critical stops the phase. **By level** fixes the
Critical, Warning and Suggestion findings you tick (all three start ticked). Critical, Warning and Suggestion findings you tick (all three start ticked).
- **Strength per phase** (off): turn on **Set strength per phase** to see one row per phase still to build under four headed columns, **Match my session**, **Thrifty**, **Balanced** and **Best**, and click a dot in a row to pick (the arrow keys move along a row), or use **Set all to** for one pick. A thick line steps through each row's picked dot, so the choices read at a glance, and the model each pick becomes shows at the end of its row. A phase you leave untouched runs on the model the app was launched with, as before. A phase whose agent crashes or goes quiet gets its one retry (when the retry tick is on) one step up (Thrifty to Balanced, Balanced to Best; Best stays Best; **Match my session** runs on the launch model and its retry stays there), and the phase's helpers follow the same strength. Which model each word means for your agent is set in User Preferences, **Agents & models**, under **Strengths in the loop**; an agent with nothing mapped shows the toggle off with a link there. The picks are remembered per project and spec, and a pick for a phase that is done or gone is dropped. - **Strength per phase** (off): turn on **Set strength per phase** to see one row per phase still to build under four headed columns, **Match my session**, **Thrifty**, **Balanced** and **Best**, and click a dot in a row to pick (the arrow keys move along a row), or use **Set all to** for one pick. **Suggest for me**, beside it, asks the agent on the dashboard to read each phase and pick for you: the field grays under a spinner while it thinks, then the rows fill with a one-line reason under each, and you can still change any of them (a row changed by hand drops its reason). If the agent does not answer within two minutes, your picks stay as they were. A thick line steps through each row's picked dot, so the choices read at a glance, and the model each pick becomes shows at the end of its row. A phase you leave untouched runs on the model the app was launched with, as before. A phase whose agent crashes or goes quiet gets its one retry (when the retry tick is on) one step up (Thrifty to Balanced, Balanced to Best; Best stays Best; **Match my session** runs on the launch model and its retry stays there), and the phase's subagents follow the same strength. Which model each word means for your agent is set in User Preferences, **Agents & models**, under **Strengths in the loop**; an agent with nothing mapped shows the toggle off with a link there. The picks are remembered per project and spec, and a pick for a phase that is done or gone is dropped.
- **When a phase asks something**: **Take the agent's best guess** (the default), which records the - **When a phase asks something**: **Take the agent's best guess** (the default), which records the
assumption as a `[?]` task, **Pause and wait for me**, or **Stop the loop**. assumption as a `[?]` task, **Pause and wait for me**, or **Stop the loop**.
- **After the last phase**: **Stop and offer Finalize** (the default) or **Run Finalize automatically**. - **After the last phase**: **Stop and offer Finalize** (the default) or **Run Finalize automatically**.
@@ -202,7 +222,7 @@ with, and it needs permission checks off. With them on, an agent would wait on a
sees, so **Start the loop** stays grayed out until you turn them off (see sees, so **Start the loop** stays grayed out until you turn them off (see
[Permission checks are off by default](#permission-checks-are-off-by-default-same-as-the-terminal)). [Permission checks are off by default](#permission-checks-are-off-by-default-same-as-the-terminal)).
**What is locked while it drives.** Answers, sign-offs, launches, Workspace, Helpers, **Back** and **What is locked while it drives.** Answers, sign-offs, launches, Workspace, Subagents, **Back** and
**New Session** are read-only, and Ask is off, except for a question the loop is waiting on. Activities, Notebook, Help, Preferences, the documents **New Session** are read-only, and Ask is off, except for a question the loop is waiting on. Activities, Notebook, Help, Preferences, the documents
and the code review stay usable, so you can watch, play, or read along. and the code review stay usable, so you can watch, play, or read along.
@@ -252,11 +272,17 @@ clean tree. The in-app **Help** has a matching topic, **Implementation Loop**, w
`plan2code update` brings the skills, the `plan2code` command and the app up together. `plan2code update` brings the skills, the `plan2code` command and the app up together.
When a newer release is out, the app's top bar shows **Update available** with **Copy update command**, When a newer release is out, the app's top bar shows **Update available** with **Update and restart**
and the dashboard shows its **UPDATE AVAILABLE** banner. Neither updates for you: the app cannot replace and a **What's new** link to the release page. **Update and restart** installs the newest release (the
itself while it runs (Windows will not overwrite a running file), so copy the command, run it in a same installer `plan2code update` runs, with its progress in the bar) and then reopens the app on the
terminal outside the app (not the app's terminal panel, which runs your agent), then close the app and same project; no terminal is needed. A running file cannot be overwritten on Windows, but the installer
open it again. renames it aside and the app then restarts into the new one. If an agent or a loop is running, the app
asks first (the same check as closing the window, with Stay as the default); answer Stay and the bar
offers **Restart Plan2Code** for when you are ready. If the update fails, the app you have keeps running
and the bar says why; you can press the button again or run `plan2code update` in a terminal. After the
restart the bar says **Updated to vX** once. The app asks again every few hours while it stays open, and
says so when it cannot check (git missing, or no answer from GitHub). The dashboard's own **Update
available** banner points at **Update and restart** too, and keeps the terminal command as the fallback.
If the app and the installed skills ever differ in version, the app's top bar says so and offers **Update If the app and the installed skills ever differ in version, the app's top bar says so and offers **Update
skills**, which brings the skills level with the app's own version when you press it. That one is a skills**, which brings the skills level with the app's own version when you press it. That one is a
@@ -267,14 +293,18 @@ then asks whether your own data in `~/.plan2code/` (notebooks, handoffs, setting
`--yes` skips both questions and keeps that data; add `--purge` to delete it. Close the app first: `--yes` skips both questions and keeps that data; add `--purge` to delete it. Close the app first:
Windows cannot delete a running file. Windows cannot delete a running file.
## The first release is unsigned ## The app is not code-signed
The app is not code-signed yet, so your system may stop it the first time it starts. It is the same The app is not code-signed, so your system may stop it the first time it starts. Signing is not planned for now. It is the same
file the installer verified against the release's checksum list. file the installer verified against the release's checksum list.
**macOS.** If macOS says the app "cannot be opened because Apple cannot check it for malicious **macOS.** If macOS says the app "cannot be opened because Apple cannot check it for malicious
software": open **System Settings**, then **Privacy & Security**, scroll to the message about software": open **System Settings**, then **Privacy & Security**, scroll to the message about
`plan2code-app`, and press **Open Anyway**. Start `plan2code` again and confirm. `plan2code-app`, and press **Open Anyway**. Start `plan2code` again and confirm. If **Open Anyway** does not appear, remove the quarantine mark and start it again:
```
xattr -d com.apple.quarantine ~/.plan2code/app/plan2code-app
```
**Windows.** If SmartScreen shows "Windows protected your PC": press **More info**, then **Run **Windows.** If SmartScreen shows "Windows protected your PC": press **More info**, then **Run
anyway**. anyway**.
Binary file not shown.
Binary file not shown.
+127 -49
View File
@@ -9,16 +9,25 @@
<meta name="theme-color" content="#0b2150"> <meta name="theme-color" content="#0b2150">
<meta property="og:title" content="Plan2Code: plan it, approve it, let it build"> <meta property="og:title" content="Plan2Code: plan it, approve it, let it build">
<meta property="og:description" content="A spec-driven workflow for AI coding agents, and a desktop app that puts the plan, your agent and every sign-off in one window."> <meta property="og:description" content="A spec-driven workflow for AI coding agents, and a desktop app that puts the plan, your agent and every sign-off in one window.">
<meta property="og:image" content="https://plan2code.jparkerweb.com/banner.jpg"> <meta property="og:type" content="website">
<meta property="og:url" content="https://plan2code.jparkerweb.com/">
<meta property="og:image" content="https://plan2code.jparkerweb.com/social-card.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Plan2Code: Plan it. Approve it. Let it build. Beside it, the Approve this phase card from the web console.">
<meta name="twitter:card" content="summary_large_image">
<link rel="canonical" href="https://plan2code.jparkerweb.com/">
<link rel="icon" href="favicon.ico" sizes="32x32"> <link rel="icon" href="favicon.ico" sizes="32x32">
<link rel="icon" type="image/png" sizes="32x32" href="favicon.png"> <link rel="icon" type="image/png" sizes="32x32" href="favicon.png">
<link rel="icon" href="favicon.svg" type="image/svg+xml"> <link rel="icon" href="favicon.svg" type="image/svg+xml">
<link rel="apple-touch-icon" href="apple-touch-icon.png"> <link rel="apple-touch-icon" href="apple-touch-icon.png">
<link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preload" href="fonts/archivo-latin.woff2" as="font" type="font/woff2" crossorigin>
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> <link rel="preload" href="fonts/martian-mono-latin.woff2" as="font" type="font/woff2" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Archivo:wdth,wght@62..125,300..900&family=Martian+Mono:wght@300..600&display=swap" rel="stylesheet">
<script>document.documentElement.className += " js"</script> <script>document.documentElement.className += " js"</script>
<style> <style>
/* Self-hosted, subset to Latin (see scripts/ and the Phase 11 notes): no blocking request to a font host. */
@font-face { font-family: "Archivo"; font-style: normal; font-weight: 300 900; font-stretch: 62% 125%; font-display: swap; src: url("fonts/archivo-latin.woff2") format("woff2"); }
@font-face { font-family: "Martian Mono"; font-style: normal; font-weight: 300 800; font-stretch: 75% 112.5%; font-display: swap; src: url("fonts/martian-mono-latin.woff2") format("woff2"); }
/* The page is a blueprint: cyanotype blue, chalk-white line work, one highlighter /* The page is a blueprint: cyanotype blue, chalk-white line work, one highlighter
yellow for the moments that are yours (your move, your sign-off). The app window yellow for the moments that are yours (your move, your sign-off). The app window
keeps the product's own warm dark palette, so it reads as the built thing lying keeps the product's own warm dark palette, so it reads as the built thing lying
@@ -74,7 +83,7 @@ body {
img { max-width: 100%; height: auto; } img { max-width: 100%; height: auto; }
a { color: var(--chalk); text-underline-offset: 4px; text-decoration-color: var(--chalk-3); } a { color: var(--chalk); text-underline-offset: 4px; text-decoration-color: var(--chalk-3); }
a:hover { text-decoration-color: var(--mark); } a:hover { text-decoration-color: var(--mark); }
code, kbd { font-family: var(--mono); font-size: 0.8em; } code, kbd { font-family: var(--mono); font-size: max(0.8em, 12.5px); }
:focus-visible { outline: 2px solid var(--mark); outline-offset: 3px; border-radius: 3px; } :focus-visible { outline: 2px solid var(--mark); outline-offset: 3px; border-radius: 3px; }
h1, h2, h3 { margin: 0; font-family: var(--sans); } h1, h2, h3 { margin: 0; font-family: var(--sans); }
h2 { h2 {
@@ -94,7 +103,7 @@ p { margin: 0; }
.sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; } .sr { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
.sheet { padding: 120px 0; border-top: 1px solid var(--line-2); background: var(--bp-900); } .sheet { padding: 120px 0; border-top: 1px solid var(--line-2); background: var(--bp-900); }
.sheet.deep { background: var(--bp-950); } .sheet.deep { background: var(--bp-950); }
.fig-note { margin-top: 14px; color: var(--chalk-3); font: 400 11.5px/1.6 var(--mono); } .fig-note { margin-top: 14px; color: var(--chalk-3); font: 400 12.5px/1.6 var(--mono); }
/* Planny. The star eye is always the highlight color. */ /* Planny. The star eye is always the highlight color. */
.planny { display: block; width: 44px; height: 60px; overflow: visible; flex: none; color: var(--chalk); --shell: var(--bp-800); --star: var(--mark); } .planny { display: block; width: 44px; height: 60px; overflow: visible; flex: none; color: var(--chalk); --shell: var(--bp-800); --star: var(--mark); }
@@ -147,6 +156,8 @@ p { margin: 0; }
.hero-foot { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 24px 48px; align-items: end; margin-top: 32px; } .hero-foot { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 24px 48px; align-items: end; margin-top: 32px; }
.hero-foot .lede { margin-top: 0; } .hero-foot .lede { margin-top: 0; }
.cta { display: flex; flex-wrap: wrap; gap: 12px; } .cta { display: flex; flex-wrap: wrap; gap: 12px; }
.hero-cmd { max-width: 880px; margin: 22px auto 0; }
.cmd.hero-cmd pre { font-size: 15px; }
/* The stage: dimension lines, the app window, the four moments of a session. */ /* The stage: dimension lines, the app window, the four moments of a session. */
.stage { position: relative; max-width: 1320px; margin: 64px auto 0; padding: 0 var(--gutter); } .stage { position: relative; max-width: 1320px; margin: 64px auto 0; padding: 0 var(--gutter); }
@@ -175,7 +186,7 @@ p { margin: 0; }
.surface img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; object-position: top left; opacity: 0; transition: opacity 0.5s ease; } .surface img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; object-position: top left; opacity: 0; transition: opacity 0.5s ease; }
.surface img.on { opacity: 1; } .surface img.on { opacity: 1; }
.stamp { position: absolute; right: 9%; top: 40%; padding: 10px 20px 8px; border: 3px solid var(--mark); border-radius: 6px; color: var(--mark); font: 800 clamp(15px, 2.2vw, 28px)/1.1 var(--sans); font-stretch: 122%; letter-spacing: 0.02em; background: rgba(23, 21, 19, 0.82); transform: rotate(-7deg) scale(1.6); opacity: 0; pointer-events: none; } .stamp { position: absolute; right: 9%; top: 40%; padding: 10px 20px 8px; border: 3px solid var(--mark); border-radius: 6px; color: var(--mark); font: 800 clamp(15px, 2.2vw, 28px)/1.1 var(--sans); font-stretch: 122%; letter-spacing: 0.02em; background: rgba(23, 21, 19, 0.82); transform: rotate(-7deg) scale(1.6); opacity: 0; pointer-events: none; }
.stamp small { display: block; font: 400 11px/1.6 var(--mono); letter-spacing: 0; color: var(--a-ink-2); } .stamp small { display: block; font: 400 12.5px/1.6 var(--mono); letter-spacing: 0; color: var(--a-ink-2); }
.stamp.on { opacity: 1; transform: rotate(-7deg) scale(1); transition: transform 0.22s cubic-bezier(0.2, 1.4, 0.4, 1), opacity 0.12s; } .stamp.on { opacity: 1; transform: rotate(-7deg) scale(1); transition: transform 0.22s cubic-bezier(0.2, 1.4, 0.4, 1), opacity 0.12s; }
.term { display: flex; flex-direction: column; min-width: 0; min-height: 0; background: var(--a-term); border-left: 1px solid var(--a-rule); } .term { display: flex; flex-direction: column; min-width: 0; min-height: 0; background: var(--a-term); border-left: 1px solid var(--a-rule); }
.stage[data-dock="bottom"] .term { border-left: 0; border-top: 1px solid var(--a-rule); height: 190px; } .stage[data-dock="bottom"] .term { border-left: 0; border-top: 1px solid var(--a-rule); height: 190px; }
@@ -186,7 +197,7 @@ html.js .seg { display: inline-flex; }
.seg button + button { border-left: 1px solid rgba(255, 255, 255, 0.22); } .seg button + button { border-left: 1px solid rgba(255, 255, 255, 0.22); }
.seg button[aria-pressed="true"] { background: var(--a-accent); color: #0c1117; } .seg button[aria-pressed="true"] { background: var(--a-accent); color: #0c1117; }
.seg button:focus-visible { outline-offset: -2px; } .seg button:focus-visible { outline-offset: -2px; }
.tb { flex: 1; min-height: 0; margin: 0; padding: 12px; overflow: hidden; font: 400 11.5px/1.75 var(--mono); white-space: pre-wrap; word-break: break-word; display: flex; flex-direction: column; justify-content: flex-end; color: var(--a-ink); } .tb { flex: 1; min-height: 0; margin: 0; padding: 12px; overflow: hidden; font: 400 12.5px/1.75 var(--mono); white-space: pre-wrap; word-break: break-word; display: flex; flex-direction: column; justify-content: flex-end; color: var(--a-ink); }
.tb .d { color: #a39b8e; } .tb .d { color: #a39b8e; }
.tb .g { color: #7fd29a; } .tb .g { color: #7fd29a; }
.tb .b { color: #8fb8f0; } .tb .b { color: #8fb8f0; }
@@ -231,7 +242,7 @@ html:not(.js) .moments button { cursor: default; }
.details svg .hi { stroke: var(--mark); } .details svg .hi { stroke: var(--mark); }
.details svg .hi-fill { fill: var(--mark); stroke: none; } .details svg .hi-fill { fill: var(--mark); stroke: none; }
.details svg .soft { stroke-dasharray: 3 4; stroke: var(--chalk-3); } .details svg .soft { stroke-dasharray: 3 4; stroke: var(--chalk-3); }
.details svg text { fill: var(--chalk-2); stroke: none; font: 400 8px var(--mono); } .details svg text { fill: var(--chalk-2); stroke: none; font: 400 12.5px var(--mono); }
.details p { color: var(--chalk-2); font-size: 15.5px; margin-top: 8px; } .details p { color: var(--chalk-2); font-size: 15.5px; margin-top: 8px; }
/* The Implementation Loop. */ /* The Implementation Loop. */
@@ -248,7 +259,7 @@ html:not(.js) .moments button { cursor: default; }
.banner .pips i.done { background: var(--a-ok); } .banner .pips i.done { background: var(--a-ok); }
.banner .pips i.now { background: var(--a-accent); animation: pulse 1.2s ease-in-out infinite alternate; } .banner .pips i.now { background: var(--a-accent); animation: pulse 1.2s ease-in-out infinite alternate; }
@keyframes pulse { to { opacity: 0.45; } } @keyframes pulse { to { opacity: 0.45; } }
.banner .el { margin-left: auto; color: var(--a-ink-2); font: 400 12px var(--mono); } .banner .el { margin-left: auto; color: var(--a-ink-2); font: 400 12.5px var(--mono); }
.banner .stop { padding: 4px 10px; border: 1px solid var(--a-rule-2); border-radius: 6px; font-size: 12.5px; color: var(--a-ink-2); } .banner .stop { padding: 4px 10px; border: 1px solid var(--a-rule-2); border-radius: 6px; font-size: 12.5px; color: var(--a-ink-2); }
.ledger-scroll { overflow-x: auto; } .ledger-scroll { overflow-x: auto; }
.ledger th:first-child { padding-left: 16px; } .ledger th:first-child { padding-left: 16px; }
@@ -257,7 +268,7 @@ html:not(.js) .moments button { cursor: default; }
.ledger thead th { font-weight: 500; font-size: 12.5px; color: var(--a-ink-2); background: var(--a-panel); } .ledger thead th { font-weight: 500; font-size: 12.5px; color: var(--a-ink-2); background: var(--a-panel); }
.ledger tbody th { font-weight: 600; white-space: nowrap; } .ledger tbody th { font-weight: 600; white-space: nowrap; }
.ledger tbody th small { display: block; font-weight: 400; color: var(--a-ink-2); font-size: 12.5px; } .ledger tbody th small { display: block; font-weight: 400; color: var(--a-ink-2); font-size: 12.5px; }
.ledger td { font-family: var(--mono); font-size: 11.5px; line-height: 1.7; color: var(--a-ink-2); white-space: nowrap; } .ledger td { font-family: var(--mono); font-size: 12.5px; line-height: 1.7; color: var(--a-ink-2); white-space: nowrap; }
.ledger td[data-s="done"] { color: #7fd29a; } .ledger td[data-s="done"] { color: #7fd29a; }
.ledger td[data-s="done"]::before { content: "\2713\00a0"; } .ledger td[data-s="done"]::before { content: "\2713\00a0"; }
.ledger td[data-s="now"] { color: var(--a-ink); } .ledger td[data-s="now"] { color: var(--a-ink); }
@@ -283,21 +294,21 @@ html:not(.js) .moments button { cursor: default; }
.pipe .n { position: relative; display: grid; place-items: center; width: 36px; height: 36px; border: 1.5px solid var(--chalk); border-radius: 50%; background: var(--bp-950); font: 600 13px var(--mono); } .pipe .n { position: relative; display: grid; place-items: center; width: 36px; height: 36px; border: 1.5px solid var(--chalk); border-radius: 50%; background: var(--bp-950); font: 600 13px var(--mono); }
.pipe li.opt .n { border-style: dashed; border-color: var(--chalk-3); color: var(--chalk-2); } .pipe li.opt .n { border-style: dashed; border-color: var(--chalk-3); color: var(--chalk-2); }
.pipe h3 { margin-top: 18px; } .pipe h3 { margin-top: 18px; }
.pipe h3 small { font: 400 11.5px var(--mono); color: var(--chalk-3); margin-left: 4px; } .pipe h3 small { font: 400 12.5px var(--mono); color: var(--chalk-3); margin-left: 4px; }
.pipe p { color: var(--chalk-2); font-size: 14.5px; line-height: 1.5; margin-top: 6px; } .pipe p { color: var(--chalk-2); font-size: 14.5px; line-height: 1.5; margin-top: 6px; }
.pipe code { display: block; margin-top: 12px; color: var(--mark); font-size: 10.5px; line-height: 1.6; } .pipe code { display: block; margin-top: 12px; color: var(--mark); font-size: 12.5px; line-height: 1.6; }
.pipe .out { display: block; margin-top: 4px; color: var(--chalk-3); font: 400 10.5px/1.6 var(--mono); } .pipe .out { display: block; margin-top: 4px; color: var(--chalk-3); font: 400 12.5px/1.6 var(--mono); }
.under { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: 48px 64px; margin-top: 88px; } .under { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: 48px 64px; margin-top: 88px; }
.under h3 { font-size: 1.45rem; font-weight: 800; font-stretch: 115%; letter-spacing: -0.01em; } .under h3 { font-size: 1.45rem; font-weight: 800; font-stretch: 115%; letter-spacing: -0.01em; }
.under h3 + p { color: var(--chalk-2); margin-top: 10px; font-size: 15.5px; } .under h3 + p { color: var(--chalk-2); margin-top: 10px; font-size: 15.5px; }
.tree { margin: 22px 0 0; padding: 20px 22px; border: 1px solid var(--line-2); border-radius: 6px; background: rgba(7, 22, 52, 0.6); font: 400 12px/1.95 var(--mono); color: var(--chalk-2); overflow-x: auto; white-space: pre; } .tree { margin: 22px 0 0; padding: 20px 22px; border: 1px solid var(--line-2); border-radius: 6px; background: rgba(7, 22, 52, 0.6); font: 400 12.5px/1.95 var(--mono); color: var(--chalk-2); overflow-x: auto; white-space: pre; }
.tree b { color: var(--chalk); font-weight: 500; } .tree b { color: var(--chalk); font-weight: 500; }
.tree .x { color: var(--ok); } .tree .x { color: var(--ok); }
.tree .w { color: var(--mark); } .tree .w { color: var(--mark); }
.tree .c { color: var(--chalk-3); } .tree .c { color: var(--chalk-3); }
.skills { margin: 22px 0 0; padding: 0; list-style: none; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 40px; border-top: 1px solid var(--line-2); } .skills { margin: 22px 0 0; padding: 0; list-style: none; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 40px; border-top: 1px solid var(--line-2); }
.skills li { padding: 12px 0; border-bottom: 1px solid var(--line-2); font-size: 14.5px; line-height: 1.45; color: var(--chalk-2); } .skills li { padding: 12px 0; border-bottom: 1px solid var(--line-2); font-size: 14.5px; line-height: 1.45; color: var(--chalk-2); }
.skills code { display: block; color: var(--chalk); font-size: 11.5px; margin-bottom: 3px; } .skills code { display: block; color: var(--chalk); font-size: 12.5px; margin-bottom: 3px; }
.agents { margin-top: 28px; color: var(--chalk-2); font-size: 15.5px; max-width: 72ch; } .agents { margin-top: 28px; color: var(--chalk-2); font-size: 15.5px; max-width: 72ch; }
/* The rules. */ /* The rules. */
@@ -313,6 +324,7 @@ html:not(.js) .moments button { cursor: default; }
.shots img { display: block; width: 100%; border-radius: 8px; box-shadow: 0 0 0 1px rgba(238, 244, 255, 0.22), 0 24px 60px rgba(2, 8, 24, 0.6); } .shots img { display: block; width: 100%; border-radius: 8px; box-shadow: 0 0 0 1px rgba(238, 244, 255, 0.22), 0 24px 60px rgba(2, 8, 24, 0.6); }
.shots figcaption { margin-top: 16px; color: var(--chalk-2); font-size: 15.5px; max-width: 56ch; } .shots figcaption { margin-top: 16px; color: var(--chalk-2); font-size: 15.5px; max-width: 56ch; }
.shots figcaption strong { color: var(--chalk); } .shots figcaption strong { color: var(--chalk); }
.loop-shots { grid-template-columns: minmax(0, 1fr); gap: 28px; margin-top: 36px; }
.aside { margin-top: 56px; display: flex; gap: 18px; align-items: center; color: var(--chalk-2); max-width: 70ch; } .aside { margin-top: 56px; display: flex; gap: 18px; align-items: center; color: var(--chalk-2); max-width: 70ch; }
.aside .planny { width: 34px; height: 46px; } .aside .planny { width: 34px; height: 46px; }
@@ -320,12 +332,17 @@ html:not(.js) .moments button { cursor: default; }
.install { padding: 120px 0 104px; border-top: 1px solid var(--line-2); } .install { padding: 120px 0 104px; border-top: 1px solid var(--line-2); }
.install-grid { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: 48px 64px; align-items: start; } .install-grid { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 7fr); gap: 48px 64px; align-items: start; }
.before { border: 1px solid var(--line-2); border-radius: 6px; background: rgba(7, 22, 52, 0.7); padding: 22px 24px; font-size: 15.5px; } .before { border: 1px solid var(--line-2); border-radius: 6px; background: rgba(7, 22, 52, 0.7); padding: 22px 24px; font-size: 15.5px; }
.before h3 { margin-bottom: 10px; } .needs { margin: 16px 0 0; color: var(--chalk-2); font-size: 15.5px; }
.needs strong { color: var(--chalk); }
.before { margin-top: 16px; padding: 14px 24px; }
.before summary { cursor: pointer; font-weight: 700; color: var(--chalk); min-height: 28px; }
.before summary:focus-visible { outline: 2px solid var(--mark); outline-offset: 4px; }
.before[open] summary { margin-bottom: 10px; }
.before ul { margin: 0; padding-left: 20px; color: var(--chalk-2); } .before ul { margin: 0; padding-left: 20px; color: var(--chalk-2); }
.before li { margin: 8px 0; } .before li { margin: 8px 0; }
.before strong { color: var(--chalk); } .before strong { color: var(--chalk); }
.cmd { display: flex; align-items: center; gap: 12px; margin-top: 20px; padding: 10px 10px 10px 16px; background: var(--bp-950); border: 1.5px solid var(--chalk); border-radius: 6px; } .cmd { display: flex; align-items: center; gap: 12px; margin-top: 20px; padding: 10px 10px 10px 16px; background: var(--bp-950); border: 1.5px solid var(--chalk); border-radius: 6px; }
.cmd pre { flex: 1; min-width: 0; margin: 0; overflow-x: auto; font: 400 11.5px/1.6 var(--mono); white-space: pre; color: var(--chalk); } .cmd pre { flex: 1; min-width: 0; margin: 0; overflow-x: auto; font: 400 12.5px/1.6 var(--mono); white-space: pre; color: var(--chalk); }
.cmd pre span { color: var(--mark); user-select: none; } .cmd pre span { color: var(--mark); user-select: none; }
.copy { flex: none; min-height: 40px; padding: 0 16px; border: 0; border-radius: 4px; background: var(--mark); color: var(--bp-950); font: 700 14px var(--sans); cursor: pointer; } .copy { flex: none; min-height: 40px; padding: 0 16px; border: 0; border-radius: 4px; background: var(--mark); color: var(--bp-950); font: 700 14px var(--sans); cursor: pointer; }
.copy:hover { background: #ffe08a; } .copy:hover { background: #ffe08a; }
@@ -373,7 +390,7 @@ footer .brand { margin-right: auto; }
.details li:first-child { border-top: 0; } .details li:first-child { border-top: 0; }
.moments button { padding: 12px 12px 10px; font-size: 13.5px; } .moments button { padding: 12px 12px 10px; font-size: 13.5px; }
.cmd { flex-direction: column; align-items: stretch; padding: 14px; } .cmd { flex-direction: column; align-items: stretch; padding: 14px; }
.cmd pre { font-size: 11.5px; } .cmd pre { font-size: 12.5px; }
.brand span { display: none; } .brand span { display: none; }
} }
@media (prefers-reduced-motion: reduce) { @media (prefers-reduced-motion: reduce) {
@@ -398,6 +415,11 @@ footer .brand { margin-right: auto; }
.light { position: absolute; left: -3%; right: -3%; top: -110px; height: 560px; background: radial-gradient(ellipse 50% 50% at 50% 50%, var(--light-1), var(--light-2) 40%, transparent 72%); filter: blur(46px); pointer-events: none; } .light { position: absolute; left: -3%; right: -3%; top: -110px; height: 560px; background: radial-gradient(ellipse 50% 50% at 50% 50%, var(--light-1), var(--light-2) 40%, transparent 72%); filter: blur(46px); pointer-events: none; }
.win { transform-origin: 50% 100%; transform: rotateX(var(--tilt, 0deg)); box-shadow: 0 0 0 1px var(--line-2), 0 -18px 70px -10px color-mix(in srgb, var(--light-2) 55%, transparent), 0 40px 90px rgba(0, 0, 0, 0.6); } .win { transform-origin: 50% 100%; transform: rotateX(var(--tilt, 0deg)); box-shadow: 0 0 0 1px var(--line-2), 0 -18px 70px -10px color-mix(in srgb, var(--light-2) 55%, transparent), 0 40px 90px rgba(0, 0, 0, 0.6); }
.moments, .stage .fig-note { position: relative; } .moments, .stage .fig-note { position: relative; }
.pause { display: block; margin: 16px auto 0; min-height: 40px; padding: 0 18px; border: 1px solid var(--line-2); border-radius: 6px; background: transparent; color: var(--chalk); font: 600 14px var(--sans); cursor: pointer; }
html:not(.js) .pause { display: none; }
.pause[aria-pressed="true"] { background: rgba(238, 244, 255, 0.1); }
.pause:hover { background: rgba(238, 244, 255, 0.07); }
.pause:focus-visible { outline: 2px solid var(--mark); outline-offset: 2px; }
.tree, .before { background: color-mix(in srgb, var(--bp-950) 70%, transparent); } .tree, .before { background: color-mix(in srgb, var(--bp-950) 70%, transparent); }
.install { position: relative; overflow: hidden; } .install { position: relative; overflow: hidden; }
.install::before { content: ""; position: absolute; left: 10%; right: 10%; bottom: -330px; height: 460px; background: radial-gradient(ellipse 50% 50% at 50% 50%, var(--light-1), var(--light-2) 40%, transparent 72%); filter: blur(60px); opacity: .5; pointer-events: none; } .install::before { content: ""; position: absolute; left: 10%; right: 10%; bottom: -330px; height: 460px; background: radial-gradient(ellipse 50% 50% at 50% 50%, var(--light-1), var(--light-2) 40%, transparent 72%); filter: blur(60px); opacity: .5; pointer-events: none; }
@@ -454,6 +476,10 @@ footer .brand { margin-right: auto; }
<a class="btn solid" href="#install">Install Plan2Code</a> <a class="btn solid" href="#install">Install Plan2Code</a>
<a class="btn line" href="#workflow">See the workflow</a> <a class="btn line" href="#workflow">See the workflow</a>
</div> </div>
<div class="cmd hero-cmd">
<pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release</pre>
<button class="copy" type="button" aria-label="Copy the install command">Copy</button>
</div>
</div> </div>
</div> </div>
@@ -487,10 +513,10 @@ footer .brand { margin-right: auto; }
</div> </div>
<div class="wbody"> <div class="wbody">
<div class="surface" id="surface"> <div class="surface" id="surface">
<img class="on" src="screenshots/dashboard-plan-dark.webp" width="2560" height="1600" alt="The Plan2Code dashboard for a new task API project: the steps in order as cards, with the Plan card marked Suggested."> <img class="on" src="screenshots/dashboard-plan-dark.webp" srcset="screenshots/dashboard-plan-dark-1280.webp 1280w, screenshots/dashboard-plan-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" fetchpriority="high" aria-hidden="false" alt="The Plan2Code dashboard for a new task API project: the steps in order as cards, with the Plan card marked Suggested.">
<img src="screenshots/question-dark.webp" width="2560" height="1600" alt="A Plan question card, How tasks are paged, with three options, the first marked Suggested, each with its trade-off underneath."> <img src="screenshots/question-dark.webp" srcset="screenshots/question-dark-1280.webp 1280w, screenshots/question-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" loading="lazy" aria-hidden="true" alt="A Plan question card, How tasks are paged, with three options, the first marked Suggested, each with its trade-off underneath.">
<img src="screenshots/build-dark.webp" width="2560" height="1600" alt="Phase 3 of the task API being built: 5 of 11 done on the progress bar, and the phase's task list with the first five ticked."> <img src="screenshots/build-dark.webp" srcset="screenshots/build-dark-1280.webp 1280w, screenshots/build-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" loading="lazy" aria-hidden="true" alt="Phase 3 of the task API being built: 5 of 11 done on the progress bar, and the phase's task list with the first five ticked.">
<img src="screenshots/signoff-dark.webp" width="2560" height="1600" alt="The Approve this phase card, with a button to read the completion report and three choices: Review the code first, Approve this phase, and I want changes."> <img src="screenshots/signoff-dark.webp" srcset="screenshots/signoff-dark-1280.webp 1280w, screenshots/signoff-dark.webp 2560w" sizes="(min-width: 1240px) 900px, 100vw" width="2560" height="1600" loading="lazy" aria-hidden="true" alt="The Approve this phase card, with a button to read the completion report and three choices: Review the code first, Approve this phase, and I want changes.">
<div class="stamp" id="stamp" aria-hidden="true">Approved<small>phase 3 of 4, by you</small></div> <div class="stamp" id="stamp" aria-hidden="true">Approved<small>phase 3 of 4, by you</small></div>
</div> </div>
<div class="term"> <div class="term">
@@ -521,6 +547,7 @@ footer .brand { margin-right: auto; }
<li><button type="button" aria-pressed="false"><strong>Sign off</strong>Nothing is marked complete until you approve it.</button></li> <li><button type="button" aria-pressed="false"><strong>Sign off</strong>Nothing is marked complete until you approve it.</button></li>
</ol> </ol>
<p class="fig-note">Illustration: the app's window drawn around real screenshots of its pages. The terminal lines are an example.</p> <p class="fig-note">Illustration: the app's window drawn around real screenshots of its pages. The terminal lines are an example.</p>
<button class="pause" id="pause" type="button" aria-pressed="false">Pause the tour</button>
</div> </div>
</section> </section>
@@ -552,6 +579,16 @@ footer .brand { margin-right: auto; }
<p>A dot on the taskbar entry turns green when a question or a sign-off is waiting, so the window can sit behind your other work.</p> <p>A dot on the taskbar entry turns green when a question or a sign-off is waiting, so the window can sit behind your other work.</p>
</li> </li>
</ul> </ul>
<div class="shots">
<figure>
<img loading="lazy" src="screenshots/app-launch-dark.webp" width="2560" height="1600" alt="The desktop app's launch card, asking which agent, model and effort to start on.">
<figcaption><strong>Pick the agent first.</strong> The launch card asks which agent, model and effort to start on, with permission checks as their own tick.</figcaption>
</figure>
<figure>
<img loading="lazy" src="screenshots/app-terminal-dark.webp" width="2560" height="1600" alt="The desktop app with the dashboard on the left and the agent's terminal docked on the right.">
<figcaption><strong>The plan beside the agent.</strong> The dashboard and the agent's terminal share one window, docked where you like.</figcaption>
</figure>
</div>
</div> </div>
</section> </section>
@@ -591,6 +628,16 @@ footer .brand { margin-right: auto; }
<div class="ping"><div><b>✅ Phase complete</b><span>Plan2Code loop on task-api: Phase 2 of 4 (Tasks model) is complete. Done: 5 tasks, committed "Add the tasks model" (a41c9e2). Next: Phase 3, API endpoints. Elapsed: phase 6m, run 14m.</span></div></div> <div class="ping"><div><b>✅ Phase complete</b><span>Plan2Code loop on task-api: Phase 2 of 4 (Tasks model) is complete. Done: 5 tasks, committed "Add the tasks model" (a41c9e2). Next: Phase 3, API endpoints. Elapsed: phase 6m, run 14m.</span></div></div>
</div> </div>
<p class="fig-note">Illustration with example data. The message is the one the loop sends to your chat.</p> <p class="fig-note">Illustration with example data. The message is the one the loop sends to your chat.</p>
<div class="shots loop-shots">
<figure>
<img loading="lazy" src="screenshots/loop-setup-dark.webp" width="2560" height="1600" alt="The Implementation Loop setup screen in the desktop app.">
<figcaption><strong>Set it up once.</strong> Pick the phases, a model strength for each and the quick check.</figcaption>
</figure>
<figure>
<img loading="lazy" src="screenshots/loop-banner-dark.webp" width="2560" height="1600" alt="The Implementation Loop banner while a phase builds, with Stop after this phase.">
<figcaption><strong>Watch it run.</strong> The banner shows the phase, the time and a way to stop after this phase.</figcaption>
</figure>
</div>
<div class="stops"> <div class="stops">
<h3>It would rather stop than guess. The loop ends on a stop screen, with the evidence, when:</h3> <h3>It would rather stop than guess. The loop ends on a stop screen, with the evidence, when:</h3>
<ul> <ul>
@@ -627,7 +674,7 @@ footer .brand { margin-right: auto; }
<h3>The checkboxes are the state</h3> <h3>The checkboxes are the state</h3>
<p>Progress lives in the spec files, not in the chat. Close the window mid-phase and nothing is lost.</p> <p>Progress lives in the spec files, not in the chat. Close the window mid-phase and nothing is lost.</p>
<pre class="tree" aria-label="Example spec folder"><b>specs/task-api/</b> <pre class="tree" aria-label="Example spec folder"><b>specs/task-api/</b>
├─ PLAN-DRAFT-2026-11-02.md ├─ PLAN-DRAFT-YYYYMMDD.md
├─ overview.md <span class="c">phases 1 and 2 done</span> ├─ overview.md <span class="c">phases 1 and 2 done</span>
├─ phase-1.md <span class="x">[x] 4 of 4</span> ├─ phase-1.md <span class="x">[x] 4 of 4</span>
├─ phase-2.md <span class="x">[x] 5 of 5</span> ├─ phase-2.md <span class="x">[x] 5 of 5</span>
@@ -647,6 +694,7 @@ footer .brand { margin-right: auto; }
<li><code>/plan2code-xray</code>Explains how and why an area of the code works.</li> <li><code>/plan2code-xray</code>Explains how and why an area of the code works.</li>
<li><code>/plan2code-pr-prep</code>Runs the checks your branch needs and writes the PR description.</li> <li><code>/plan2code-pr-prep</code>Runs the checks your branch needs and writes the PR description.</li>
<li><code>/plan2code-test</code>Finds code with no tests and writes them in your project's style.</li> <li><code>/plan2code-test</code>Finds code with no tests and writes them in your project's style.</li>
<li><code>/plan2code-deps</code>Finds outdated packages, says how safe each update is, and applies only what you pick.</li>
<li><code>/plan2code-dead-code</code>Finds code nothing uses and removes only what you pick.</li> <li><code>/plan2code-dead-code</code>Finds code nothing uses and removes only what you pick.</li>
<li><code>/plan2code-1b-revise-plan</code>Requirements moved mid-build: revise the specs, not the code.</li> <li><code>/plan2code-1b-revise-plan</code>Requirements moved mid-build: revise the specs, not the code.</li>
<li><code>/plan2code-handoff</code>Packs a session into a document a fresh one resumes from.</li> <li><code>/plan2code-handoff</code>Packs a session into a document a fresh one resumes from.</li>
@@ -655,7 +703,7 @@ footer .brand { margin-right: auto; }
</ul> </ul>
</div> </div>
</div> </div>
<p class="agents">The skills install into every agent the skills CLI supports, including Claude Code, Cursor, GitHub Copilot, Windsurf, Codex, Devin, OpenCode, Gemini CLI, Cline, Goose and Zed. Each skill asks whether you want its page or plain terminal prompts, so the whole workflow also runs over SSH with no window at all.</p> <p class="agents">The skills install into every agent the skills CLI supports, including Claude Code, Cursor, GitHub Copilot, Windsurf, Codex, Devin, OpenCode, Gemini CLI, Cline, Goose, Zed and more. Each skill asks whether you want its page or plain terminal prompts, so the whole workflow also runs over SSH with no window at all.</p>
</div> </div>
</section> </section>
@@ -687,7 +735,7 @@ footer .brand { margin-right: auto; }
<figcaption><strong>Ask, beside the cards.</strong> A chat for anything you want to know, answered at the agent's next check-in. It never holds up your answers.</figcaption> <figcaption><strong>Ask, beside the cards.</strong> A chat for anything you want to know, answered at the agent's next check-in. It never holds up your answers.</figcaption>
</figure> </figure>
<figure> <figure>
<img loading="lazy" src="screenshots/notepad-dark.webp" width="2560" height="1600" alt="The Notebook open over a question: two named tabs, and a heading, bullets and bold styled in place as they are typed."> <img loading="lazy" src="screenshots/notebook-dark.webp" width="2560" height="1600" alt="The Notebook open over a question: two named tabs, and a heading, bullets and bold styled in place as they are typed.">
<figcaption><strong>A private notebook.</strong> Markdown and pictures, one pad per folder. The agent reads a tab only when you start a workflow from it.</figcaption> <figcaption><strong>A private notebook.</strong> Markdown and pictures, one pad per folder. The agent reads a tab only when you start a workflow from it.</figcaption>
</figure> </figure>
<figure> <figure>
@@ -695,15 +743,23 @@ footer .brand { margin-right: auto; }
<figcaption><strong>A clear next step.</strong> Every ending says what happened and what to run next, with one button to carry on in the same session.</figcaption> <figcaption><strong>A clear next step.</strong> Every ending says what happened and what to run next, with one button to carry on in the same session.</figcaption>
</figure> </figure>
<figure> <figure>
<img loading="lazy" src="screenshots/dashboard-utilities-dark.webp" width="2560" height="1600" alt="The dashboard's utility cards: Get a PR ready, Write missing tests, Clear out dead code, Changelog, Git and Handoff, each with a line on what it does and its command."> <img loading="lazy" src="screenshots/dashboard-utilities-dark.webp" width="2560" height="1600" alt="The dashboard's utility cards: Diagnose a bug, Get a PR ready, Write missing tests, Clear out dead code, Update dependencies, Prototype a screen, Changelog, Git (noting the folder is not a git repository yet) and Handoff, each with a line on what it does and its command.">
<figcaption><strong>Every skill is a card.</strong> The any-time skills sit on the dashboard beside the steps, each with what it does and the command behind it.</figcaption> <figcaption><strong>Every skill is a card.</strong> The any-time skills sit on the dashboard beside the steps, each with what it does and the command behind it.</figcaption>
</figure> </figure>
<figure> <figure>
<img loading="lazy" src="screenshots/git-dark.webp" width="2560" height="1600" alt="The git board on feature/task-endpoints: the Changes tab opens on a Next step card reading Commit 3 files, above the three changed files ticked for the commit."> <img loading="lazy" src="screenshots/git-dark.webp" width="2560" height="1600" alt="The git board on feature/task-endpoints: the Changes tab opens on a Next step card reading Commit 3 files, above the three changed files ticked for the commit.">
<figcaption><strong>A git board.</strong> Changes, Branches and Sync, opening on your likely next step. It asks before anything is pushed, published or deleted, and it never force-pushes.</figcaption> <figcaption><strong>A git board.</strong> Changes, Branches and Sync, opening on your likely next step. It asks before anything is pushed, published or deleted, and it never force-pushes.</figcaption>
</figure> </figure>
<figure>
<img loading="lazy" src="screenshots/signoff-changes-dark.webp" width="2560" height="1600" alt="The Changes tab beside the Approve this phase card: three changed files listed on the left, and the diff of paginate.js on the right with added and removed lines marked.">
<figcaption><strong>Read the diff before you sign.</strong> The Changes tab lists every file the phase touched, with the diff beside the approval, so you see the code before you say yes.</figcaption>
</figure>
<figure>
<img loading="lazy" src="screenshots/lessons-dark.webp" width="2560" height="1600" alt="The Lessons to keep card: three lessons about the task API, each with Keep, Reword and Drop.">
<figcaption><strong>It remembers what it learned about your code.</strong> Lessons are offered at the end of a run, kept only when you say so, and saved with the repo for the next session.</figcaption>
</figure>
</div> </div>
<p class="aside"><svg class="planny" viewBox="0 0 22 30" aria-hidden="true" focusable="false"><use href="#pl-body"/><use href="#pl-up"/></svg><span>That is Planny. He waves when it is your turn, walks while the agent works, and throws his arms up when you approve a phase.</span></p> <p class="aside"><svg class="planny" viewBox="0 0 22 30" aria-hidden="true" focusable="false"><use href="#pl-body"/><use href="#pl-up"/></svg><span>That is Planny. He waves when it is your turn, walks while the agent works, and throws his arms up when you approve a phase. <a href="https://github.com/jparkerweb/plan2code/blob/main/.readme/walkthrough.md">Read the walkthrough</a> for a whole feature, start to finish.</span></p>
</div> </div>
</section> </section>
@@ -711,26 +767,27 @@ footer .brand { margin-right: auto; }
<div class="wrap install-grid"> <div class="wrap install-grid">
<div> <div>
<h2 id="install-title">One line installs all of it.</h2> <h2 id="install-title">One line installs all of it.</h2>
<p class="lede">The skills, the <code>plan2code</code> command and, if you say yes, the desktop app. Run it again any time to update. MIT licensed.</p> <p class="lede">The skills, the <code>plan2code</code> command and, if you say yes, the desktop app. Run it again any time to update. Apache 2.0 licensed.</p>
</div> </div>
<div> <div>
<div class="before"> <div class="cmd">
<h3>Before you start</h3> <pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release</pre>
<button class="copy" type="button" aria-label="Copy the install command">Copy</button>
</div>
<p class="needs"><strong>Needs Node 18+ and Git.</strong> Includes the desktop app for Windows, macOS and Linux (<a href="https://github.com/jparkerweb/plan2code/releases/latest">latest release</a>).</p>
<details class="before">
<summary>Before you start</summary>
<ul> <ul>
<li><strong>Node.js 18 or newer.</strong> Check with <code>node --version</code>. No Node? Get it from <a href="https://nodejs.org/">nodejs.org</a> (the LTS download), or run <code>winget install OpenJS.NodeJS.LTS</code> on Windows, <code>brew install node</code> on macOS, or use <code>nvm</code> on Linux. Then open a new terminal.</li> <li><strong>Node.js 18 or newer</strong> (22 or newer if you install Claude Code with npm). Check with <code>node --version</code>. No Node? Get it from <a href="https://nodejs.org/">nodejs.org</a> (the LTS download), or run <code>winget install OpenJS.NodeJS.LTS</code> on Windows, <code>brew install node</code> on macOS, or use <code>nvm</code> on Linux. Then open a new terminal.</li>
<li><strong>Git.</strong> Check with <code>git --version</code>. The installer is fetched from GitHub with Git, and without it npm stops with <code>spawn git ENOENT</code>. No Git? Get it from <a href="https://git-scm.com/downloads">git-scm.com</a>, or run <code>winget install Git.Git</code> on Windows, <code>brew install git</code> on macOS, or use your package manager on Linux. Then open a new terminal.</li> <li><strong>Git.</strong> Check with <code>git --version</code>. The installer is fetched from GitHub with Git, and without it npm stops with <code>spawn git ENOENT</code>. No Git? Get it from <a href="https://git-scm.com/downloads">git-scm.com</a>, or run <code>winget install Git.Git</code> on Windows, <code>brew install git</code> on macOS, or use your package manager on Linux. Then open a new terminal.</li>
<li><strong>Start from your project.</strong> Open your terminal in the project you want to work on (<code>cd</code> into it) before you run anything. Plan2Code works on the folder you start it in.</li> <li><strong>Start from your project.</strong> Open your terminal in the project you want to work on (<code>cd</code> into it) before you run anything. Plan2Code works on the folder you start it in.</li>
<li><strong>Ways in.</strong> <code>plan2code</code> (Claude Code, Devin or Codex), or type <code>/plan2code</code> in your agent (<code>$plan2code</code> in Codex).</li> <li><strong>Ways in.</strong> <code>plan2code</code> (Claude Code, Devin or Codex), or type <code>/plan2code</code> in your agent (<code>$plan2code</code> in Codex).</li>
<li><strong>No agent yet?</strong> Install Claude Code, Codex or Devin first, or let the <code>plan2code</code> command's setup page walk you through it.</li> <li><strong>No agent yet?</strong> Install Claude Code, Codex or Devin first, or let the <code>plan2code</code> command's setup page walk you through it.</li>
</ul> </ul>
</div> </details>
<div class="cmd">
<pre><span aria-hidden="true">$ </span>npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git</pre>
<button class="copy" type="button" aria-label="Copy the install command">Copy</button>
</div>
<ul class="after"> <ul class="after">
<li><strong>Then, from your project, run <code>plan2code</code>.</strong> With the app installed it opens the app, and <code>plan2code --classic</code> keeps the agent in your terminal. Already inside your agent? Type <code>/plan2code</code> (<code>$plan2code</code> in Codex).</li> <li><strong>Then, from your project, run <code>plan2code</code>.</strong> With the app installed it opens the app, and <code>plan2code --classic</code> keeps the agent in your terminal. Already inside your agent? Type <code>/plan2code</code> (<code>$plan2code</code> in Codex).</li>
<li><strong>The app is checked before it is kept.</strong> The installer downloads the build for your system (Windows x64, macOS on Apple silicon or Intel, Linux x64) and verifies it against the release's checksum list. This first release is unsigned, so your system may ask you to allow it once. <a href="https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md">Read the app guide</a>.</li> <li><strong>The app is checked before it is kept.</strong> The installer downloads the build for your system (Windows x64, macOS on Apple silicon or Intel, Linux x64) and verifies it against the release's checksum list. The app is not code-signed (signing is not planned for now), so your system may ask you to allow it once. <a href="https://github.com/jparkerweb/plan2code/blob/main/docs/desktop-app.md">Read the app guide</a>.</li>
<li><strong>Back at your prompt with nothing printed?</strong> The installer always opens a menu, so no output at all means npm could not reach the repository and hid the reason. <code>git ls-remote https://github.com/jparkerweb/plan2code.git</code> shows why.</li> <li><strong>Back at your prompt with nothing printed?</strong> The installer always opens a menu, so no output at all means npm could not reach the repository and hid the reason. <code>git ls-remote https://github.com/jparkerweb/plan2code.git</code> shows why.</li>
</ul> </ul>
</div> </div>
@@ -746,23 +803,23 @@ footer .brand { margin-right: auto; }
<a href="https://github.com/jparkerweb/plan2code#readme">README</a> <a href="https://github.com/jparkerweb/plan2code#readme">README</a>
<a href="https://github.com/jparkerweb/plan2code/releases">Releases</a> <a href="https://github.com/jparkerweb/plan2code/releases">Releases</a>
<a href="https://github.com/jparkerweb/plan2code/blob/main/CHANGELOG.md">Changelog</a> <a href="https://github.com/jparkerweb/plan2code/blob/main/CHANGELOG.md">Changelog</a>
<span>MIT license</span> <span>Apache 2.0 license</span>
</div> </div>
</footer> </footer>
<script> <script>
(function () { (function () {
var CMD = 'npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git'; var CMD = 'npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git#release';
var $ = function (i) { return document.getElementById(i); }; var $ = function (i) { return document.getElementById(i); };
var calm = window.matchMedia('(prefers-reduced-motion: reduce)').matches; var calm = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
/* Copy the install command. */ /* Copy the install command. */
var copy = document.querySelector('.copy'); var copies = document.querySelectorAll('.copy');
var copyTimer; var copyTimer, copy;
function copied() { function copied() {
copy.textContent = 'Copied'; [].forEach.call(copies, function (c) { c.textContent = 'Copied'; });
clearTimeout(copyTimer); clearTimeout(copyTimer);
copyTimer = setTimeout(function () { copy.textContent = 'Copy'; }, 1800); copyTimer = setTimeout(function () { [].forEach.call(copies, function (c) { c.textContent = 'Copy'; }); }, 1800);
} }
function copyFallback() { function copyFallback() {
var ta = document.createElement('textarea'); var ta = document.createElement('textarea');
@@ -775,9 +832,11 @@ footer .brand { margin-right: auto; }
try { document.execCommand('copy'); copied(); } catch (e) {} try { document.execCommand('copy'); copied(); } catch (e) {}
document.body.removeChild(ta); document.body.removeChild(ta);
} }
copy.addEventListener('click', function () { [].forEach.call(copies, function (c) {
if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(CMD).then(copied, copyFallback); c.addEventListener('click', function () {
else copyFallback(); if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(CMD).then(copied, copyFallback);
else copyFallback();
});
}); });
/* The window: four moments of one session, played in order until someone picks one. */ /* The window: four moments of one session, played in order until someone picks one. */
@@ -831,7 +890,10 @@ footer .brand { margin-right: auto; }
var m = MOMENTS[i], k; var m = MOMENTS[i], k;
at = i; at = i;
while (timers.length) clearTimeout(timers.pop()); while (timers.length) clearTimeout(timers.pop());
for (k = 0; k < imgs.length; k++) imgs[k].classList.toggle('on', k === i); for (k = 0; k < imgs.length; k++) {
imgs[k].classList.toggle('on', k === i);
imgs[k].setAttribute('aria-hidden', String(k !== i));
}
for (k = 0; k < btns.length; k++) btns[k].setAttribute('aria-pressed', String(k === i)); for (k = 0; k < btns.length; k++) btns[k].setAttribute('aria-pressed', String(k === i));
moments.classList.toggle('auto', auto); moments.classList.toggle('auto', auto);
stamp.classList.remove('on'); stamp.classList.remove('on');
@@ -852,8 +914,24 @@ footer .brand { margin-right: auto; }
}, calm ? 0 : 3000); }, calm ? 0 : 3000);
if (auto) later(function () { show((i + 1) % MOMENTS.length); }, BEAT); if (auto) later(function () { show((i + 1) % MOMENTS.length); }, BEAT);
} }
/* A visible, keyboard-reachable pause for the rotation. */
var pauseBtn = $('pause');
function syncPause() {
/* One fixed label; aria-pressed carries the state. */
pauseBtn.setAttribute('aria-pressed', String(!auto));
}
pauseBtn.addEventListener('click', function () {
auto = !auto;
syncPause();
if (auto) show(at);
else {
while (timers.length) clearTimeout(timers.pop());
moments.classList.remove('auto');
}
});
syncPause();
[].forEach.call(btns, function (b, i) { [].forEach.call(btns, function (b, i) {
b.addEventListener('click', function () { auto = false; show(i); }); b.addEventListener('click', function () { auto = false; syncPause(); show(i); });
}); });
[].forEach.call(document.querySelectorAll('.seg button'), function (b) { [].forEach.call(document.querySelectorAll('.seg button'), function (b) {
b.addEventListener('click', function () { b.addEventListener('click', function () {
+4
View File
@@ -0,0 +1,4 @@
User-agent: *
Allow: /
Sitemap: https://plan2code.jparkerweb.com/sitemap.xml
Binary file not shown.

After

Width:  |  Height:  |  Size: 121 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 128 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 99 KiB

After

Width:  |  Height:  |  Size: 107 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 107 KiB

After

Width:  |  Height:  |  Size: 115 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 119 KiB

After

Width:  |  Height:  |  Size: 121 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 122 KiB

After

Width:  |  Height:  |  Size: 124 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 90 KiB

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 95 KiB

After

Width:  |  Height:  |  Size: 95 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 89 KiB

After

Width:  |  Height:  |  Size: 87 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 97 KiB

After

Width:  |  Height:  |  Size: 91 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 121 KiB

After

Width:  |  Height:  |  Size: 158 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 132 KiB

After

Width:  |  Height:  |  Size: 170 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 104 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 110 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 117 KiB

After

Width:  |  Height:  |  Size: 123 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 122 KiB

After

Width:  |  Height:  |  Size: 128 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 97 KiB

After

Width:  |  Height:  |  Size: 99 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 101 KiB

After

Width:  |  Height:  |  Size: 104 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 73 KiB

After

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

After

Width:  |  Height:  |  Size: 72 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 146 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 156 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 110 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 66 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 62 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 62 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 67 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 109 KiB

After

Width:  |  Height:  |  Size: 111 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 119 KiB

After

Width:  |  Height:  |  Size: 119 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 124 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 132 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 97 KiB

After

Width:  |  Height:  |  Size: 103 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 105 KiB

After

Width:  |  Height:  |  Size: 110 KiB

+6
View File
@@ -0,0 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://plan2code.jparkerweb.com/</loc>
</url>
</urlset>
Binary file not shown.

After

Width:  |  Height:  |  Size: 247 KiB

+1029 -412
View File
File diff suppressed because it is too large. Load diff
+5 -1
View File
@@ -1,7 +1,11 @@
{ {
"name": "plan2code", "name": "plan2code",
"version": "3.1.0", "version": "3.1.1",
"private": true, "private": true,
"license": "Apache-2.0",
"engines": {
"node": ">=18"
},
"bin": { "bin": {
"plan2code-install": "./install.js" "plan2code-install": "./install.js"
}, },
+477 -4
View File
@@ -47,6 +47,137 @@ version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470" checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "async-broadcast"
version = "0.7.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "435a87a52755b8f27fcf321ac4f04b2802e337c8c4872923137471ec39c37532"
dependencies = [
"event-listener",
"event-listener-strategy",
"futures-core",
"pin-project-lite",
]
[[package]]
name = "async-channel"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "924ed96dd52d1b75e9c1a3e6275715fd320f5f9439fb5a4a11fa51f4221158d2"
dependencies = [
"concurrent-queue",
"event-listener-strategy",
"futures-core",
"pin-project-lite",
]
[[package]]
name = "async-executor"
version = "1.14.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f426a31126c735126297bc5ea7a521263c9faff4f63ca415267ee625651c4f37"
dependencies = [
"async-task",
"concurrent-queue",
"fastrand",
"futures-lite",
"pin-project-lite",
"slab",
]
[[package]]
name = "async-io"
version = "2.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "456b8a8feb6f42d237746d4b3e9a178494627745c3c56c6ea55d92ba50d026fc"
dependencies = [
"autocfg",
"cfg-if",
"concurrent-queue",
"futures-io",
"futures-lite",
"parking",
"polling",
"rustix",
"slab",
"windows-sys 0.61.2",
]
[[package]]
name = "async-lock"
version = "3.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0876700b0d007ad25d5508865a4259c3af9af6d296bf663a0d586d0bc3369f6f"
dependencies = [
"event-listener",
"event-listener-strategy",
"pin-project-lite",
]
[[package]]
name = "async-process"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75"
dependencies = [
"async-channel",
"async-io",
"async-lock",
"async-signal",
"async-task",
"blocking",
"cfg-if",
"event-listener",
"futures-lite",
"rustix",
]
[[package]]
name = "async-recursion"
version = "1.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4f8abc12baad266b1c8cec146854c195b5864b4221d4b2ca7296a7ae82d9e451"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.9",
]
[[package]]
name = "async-signal"
version = "0.2.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485"
dependencies = [
"async-io",
"async-lock",
"atomic-waker",
"cfg-if",
"futures-core",
"futures-io",
"rustix",
"signal-hook-registry",
"slab",
"windows-sys 0.61.2",
]
[[package]]
name = "async-task"
version = "4.7.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de"
[[package]]
name = "async-trait"
version = "0.1.92"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.9",
]
[[package]] [[package]]
name = "atk" name = "atk"
version = "0.18.2" version = "0.18.2"
@@ -148,6 +279,19 @@ dependencies = [
"objc2", "objc2",
] ]
[[package]]
name = "blocking"
version = "1.7.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa"
dependencies = [
"async-channel",
"async-task",
"futures-io",
"futures-lite",
"piper",
]
[[package]] [[package]]
name = "brotli" name = "brotli"
version = "9.0.0" version = "9.0.0"
@@ -346,6 +490,15 @@ dependencies = [
"memchr", "memchr",
] ]
[[package]]
name = "concurrent-queue"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
dependencies = [
"crossbeam-utils",
]
[[package]] [[package]]
name = "cookie" name = "cookie"
version = "0.18.2" version = "0.18.2"
@@ -728,6 +881,33 @@ version = "1.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4ef6b89e5b37196644d8796de5268852ff179b44e96276cf4290264843743bb7" checksum = "4ef6b89e5b37196644d8796de5268852ff179b44e96276cf4290264843743bb7"
[[package]]
name = "endi"
version = "1.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099"
[[package]]
name = "enumflags2"
version = "0.7.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1027f7680c853e056ebcec683615fb6fbbc07dbaa13b4d5d9442b146ded4ecef"
dependencies = [
"enumflags2_derive",
"serde",
]
[[package]]
name = "enumflags2_derive"
version = "0.7.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67c78a4d8fdf9953a5c9d458f9efe940fd97a0cab0941c075a813ac594733827"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]] [[package]]
name = "equivalent" name = "equivalent"
version = "1.0.3" version = "1.0.3"
@@ -755,9 +935,29 @@ dependencies = [
"windows-sys 0.61.2", "windows-sys 0.61.2",
] ]
[[package]]
name = "event-listener"
version = "5.4.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2"
dependencies = [
"parking",
"pin-project-lite",
]
[[package]]
name = "event-listener-strategy"
version = "0.5.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93"
dependencies = [
"event-listener",
"pin-project-lite",
]
[[package]] [[package]]
name = "fake-agent" name = "fake-agent"
version = "3.1.0" version = "3.1.1"
dependencies = [ dependencies = [
"serde_json", "serde_json",
"terminal_size", "terminal_size",
@@ -912,6 +1112,19 @@ version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
[[package]]
name = "futures-lite"
version = "2.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f78e10609fe0e0b3f4157ffab1876319b5b0db102a2c60dc4626306dc46b44ad"
dependencies = [
"fastrand",
"futures-core",
"futures-io",
"parking",
"pin-project-lite",
]
[[package]] [[package]]
name = "futures-macro" name = "futures-macro"
version = "0.3.34" version = "0.3.34"
@@ -1255,6 +1468,12 @@ version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
[[package]]
name = "hermit-abi"
version = "0.5.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284"
[[package]] [[package]]
name = "hex" name = "hex"
version = "0.4.3" version = "0.4.3"
@@ -1551,6 +1770,25 @@ version = "2.12.2"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0" checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
[[package]]
name = "is-docker"
version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "928bae27f42bc99b60d9ac7334e3a21d10ad8f1835a4e12ec3ec0464765ed1b3"
dependencies = [
"once_cell",
]
[[package]]
name = "is-wsl"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "173609498df190136aa7dea1a91db051746d339e18476eed5ca40521f02d7aa5"
dependencies = [
"is-docker",
"once_cell",
]
[[package]] [[package]]
name = "itoa" name = "itoa"
version = "1.0.18" version = "1.0.18"
@@ -2201,6 +2439,17 @@ version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "open"
version = "5.4.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8d8c8b8e725ad26404d6896eb2f064294a0a7b4f1d9120210d85544684c4ca95"
dependencies = [
"dunce",
"is-wsl",
"libc",
]
[[package]] [[package]]
name = "openssl" name = "openssl"
version = "0.10.81" version = "0.10.81"
@@ -2250,6 +2499,16 @@ version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d" checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
[[package]]
name = "ordered-stream"
version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9aa2b01e1d916879f73a53d01d1d6cee68adbb31d6d9177a8cfce093cced1d50"
dependencies = [
"futures-core",
"pin-project-lite",
]
[[package]] [[package]]
name = "pango" name = "pango"
version = "0.18.3" version = "0.18.3"
@@ -2275,6 +2534,12 @@ dependencies = [
"system-deps", "system-deps",
] ]
[[package]]
name = "parking"
version = "2.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba"
[[package]] [[package]]
name = "parking_lot" name = "parking_lot"
version = "0.12.5" version = "0.12.5"
@@ -2363,6 +2628,17 @@ version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
[[package]]
name = "piper"
version = "0.2.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c835479a4443ded371d6c535cbfd8d31ad92c5d23ae9770a61bc155e4992a3c1"
dependencies = [
"atomic-waker",
"fastrand",
"futures-io",
]
[[package]] [[package]]
name = "pkg-config" name = "pkg-config"
version = "0.3.34" version = "0.3.34"
@@ -2371,7 +2647,7 @@ checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
[[package]] [[package]]
name = "plan2code-app" name = "plan2code-app"
version = "3.1.0" version = "3.1.1"
dependencies = [ dependencies = [
"chrono", "chrono",
"libc", "libc",
@@ -2382,6 +2658,8 @@ dependencies = [
"tauri", "tauri",
"tauri-build", "tauri-build",
"tauri-plugin-dialog", "tauri-plugin-dialog",
"tauri-plugin-opener",
"tauri-plugin-window-state",
"winapi", "winapi",
] ]
@@ -2424,6 +2702,20 @@ dependencies = [
"miniz_oxide 0.8.9", "miniz_oxide 0.8.9",
] ]
[[package]]
name = "polling"
version = "3.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5d0e4f59085d47d8241c88ead0f274e8a0cb551f3625263c05eb8dd897c34218"
dependencies = [
"cfg-if",
"concurrent-queue",
"hermit-abi",
"pin-project-lite",
"rustix",
"windows-sys 0.61.2",
]
[[package]] [[package]]
name = "portable-atomic" name = "portable-atomic"
version = "1.15.0" version = "1.15.0"
@@ -3083,6 +3375,16 @@ version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
[[package]]
name = "signal-hook-registry"
version = "1.4.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
dependencies = [
"errno",
"libc",
]
[[package]] [[package]]
name = "simd-adler32" name = "simd-adler32"
version = "0.3.10" version = "0.3.10"
@@ -3513,6 +3815,43 @@ dependencies = [
"url", "url",
] ]
[[package]]
name = "tauri-plugin-opener"
version = "2.7.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "54592c6718b42ab198bf11bda6a428a3553ca2f2f8e506df56f6a063ec328331"
dependencies = [
"dunce",
"glob",
"objc2-app-kit",
"objc2-foundation",
"open",
"schemars 0.8.22",
"serde",
"serde_json",
"tauri",
"tauri-plugin",
"thiserror 2.0.21",
"url",
"windows",
"zbus",
]
[[package]]
name = "tauri-plugin-window-state"
version = "2.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5d6815cab7b212f9cfe16a9d79d8d22f9e14159e4a9460f7dec1467167a008e3"
dependencies = [
"bitflags 2.13.2",
"log",
"serde",
"serde_json",
"tauri",
"tauri-plugin",
"thiserror 2.0.21",
]
[[package]] [[package]]
name = "tauri-runtime" name = "tauri-runtime"
version = "2.12.2" version = "2.12.2"
@@ -3620,10 +3959,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
dependencies = [ dependencies = [
"fastrand", "fastrand",
"getrandom 0.3.4", "getrandom 0.4.3",
"once_cell", "once_cell",
"rustix", "rustix",
"windows-sys 0.60.2", "windows-sys 0.61.2",
] ]
[[package]] [[package]]
@@ -3916,9 +4255,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
dependencies = [ dependencies = [
"pin-project-lite", "pin-project-lite",
"tracing-attributes",
"tracing-core", "tracing-core",
] ]
[[package]]
name = "tracing-attributes"
version = "0.1.31"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]] [[package]]
name = "tracing-core" name = "tracing-core"
version = "0.1.36" version = "0.1.36"
@@ -3968,6 +4319,17 @@ version = "1.20.1"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
[[package]]
name = "uds_windows"
version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e"
dependencies = [
"memoffset",
"tempfile",
"windows-sys 0.61.2",
]
[[package]] [[package]]
name = "unicode-ident" name = "unicode-ident"
version = "1.0.27" version = "1.0.27"
@@ -4726,6 +5088,76 @@ dependencies = [
"synstructure", "synstructure",
] ]
[[package]]
name = "zbus"
version = "5.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907"
dependencies = [
"async-broadcast",
"async-executor",
"async-io",
"async-lock",
"async-process",
"async-recursion",
"async-task",
"async-trait",
"blocking",
"enumflags2",
"event-listener",
"futures-core",
"futures-lite",
"hex",
"libc",
"ordered-stream",
"rustix",
"serde",
"serde_repr",
"tracing",
"uds_windows",
"uuid",
"windows-sys 0.61.2",
"winnow 1.0.4",
"zbus_macros",
"zbus_names",
"zvariant",
]
[[package]]
name = "zbus_macros"
version = "5.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40"
dependencies = [
"proc-macro-crate 3.5.0",
"proc-macro2",
"quote",
"syn 3.0.9",
"zbus_names",
"zvariant",
"zvariant_utils",
]
[[package]]
name = "zbus_names"
version = "4.3.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "812a12be4ead7a59e18ea8f047d08add0066b73bc62fc1467066a2472ae088dd"
dependencies = [
"serde",
"winnow 1.0.4",
"zvariant",
]
[[package]]
name = "zcheapstr"
version = "1.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "939f186d9ecebe044315a5cb6d6f78568bbc21152adc954d5a0c2f58bdbc9920"
dependencies = [
"serde",
]
[[package]] [[package]]
name = "zerofrom" name = "zerofrom"
version = "0.1.8" version = "0.1.8"
@@ -4797,3 +5229,44 @@ name = "zmij"
version = "1.0.23" version = "1.0.23"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
[[package]]
name = "zvariant"
version = "5.15.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "80bf6d6cd6a4b601acb64cfb8284cdc643fcfa75ef26ae3c46ec8aa4e8a1fbb7"
dependencies = [
"endi",
"enumflags2",
"serde",
"winnow 1.0.4",
"zcheapstr",
"zvariant_derive",
"zvariant_utils",
]
[[package]]
name = "zvariant_derive"
version = "5.15.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ef2672456ba1cb54b5eaec136e63135b3c7495fb938e53b28a62e633496d486d"
dependencies = [
"proc-macro-crate 3.5.0",
"proc-macro2",
"quote",
"syn 3.0.9",
"zvariant_utils",
]
[[package]]
name = "zvariant_utils"
version = "4.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bad0294361a320b694a328460dc73add56c306150f5cb6bfafc44446120008a3"
dependencies = [
"proc-macro2",
"quote",
"serde",
"syn 3.0.9",
"winnow 1.0.4",
]
+7 -3
View File
@@ -1,6 +1,10 @@
# plan2code-app # plan2code-app
The Plan2Code desktop app (v3.0): one window with the dashboard, a terminal panel for the agent, and a **New Session** button. Built with Tauri 2 (Rust and a web view). Users: see [docs/desktop-app.md](../docs/desktop-app.md). This file is for people who build the app.
The Plan2Code desktop app: one window with the dashboard, a terminal panel for the agent, and a **New Session** button. Built with Tauri 2 (Rust and a web view).
![The desktop app: the dashboard on the left and the agent's terminal docked on the right.](../docs/screenshots/app-terminal-dark.webp)
The app is optional. The Node web console and the skills never depend on it, so running `/plan2code` inside an agent with no app works exactly as before. The app is optional. The Node web console and the skills never depend on it, so running `/plan2code` inside an agent with no app works exactly as before.
@@ -39,14 +43,14 @@ Needs the Rust toolchain pinned in `rust-toolchain.toml`, Node 18+, and the Taur
cd plan2code-app cd plan2code-app
npm install npm install
npm run dev # run the app npm run dev # run the app
npm run build # build the installable bundle npm run build # build the app and local installer bundles (the release ships only the plain executable)
``` ```
## Tests ## Tests
``` ```
cd plan2code-app cd plan2code-app
node scripts/vendor.mjs # once: the xterm files cargo builds against node scripts/vendor.mjs # once: the xterm files and the console's tokens.css cargo builds against
cargo fmt --check cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace cargo test --workspace
+21 -6
View File
@@ -46,6 +46,11 @@ file directly after checking it against the release's checksum list.
`docs/desktop-app.md` describes what you saw `docs/desktop-app.md` describes what you saw
- [ ] `plan2code update` updates the skills, the command and the app, including while the app is - [ ] `plan2code update` updates the skills, the command and the app, including while the app is
running (Windows replaces the file by renaming the old one aside) running (Windows replaces the file by renaming the old one aside)
- [ ] **Update and restart** (bar, with a newer release out): the bar shows the installer's progress,
the app reopens on the same project, and says **Updated to vX** once; with an agent running it
asks first, and Stay leaves the app up with **Restart Plan2Code** offered; a failed update
(try it offline) leaves the old app running with a readable reason; **What's new** opens the
release page in the default browser
## The window (each system) ## The window (each system)
@@ -64,14 +69,24 @@ file directly after checking it against the release's checksum list.
only) and permission mode (checks off is ticked by default, matching the plain `plan2code` only) and permission mode (checks off is ticked by default, matching the plain `plan2code`
launcher; untick it for an agent that keeps its normal approval prompts); a CLI it could launcher; untick it for an agent that keeps its normal approval prompts); a CLI it could
not find is named, not just disabled not find is named, not just disabled
- [ ] **Dock the terminal to the right**: the splitter becomes vertical, the toolbar stacks, and the - [ ] **Dock the terminal to the right**: the splitter becomes vertical, and the
dashboard keeps the rest of the width; dock it back to the bottom dashboard keeps the rest of the width; dock it back to the bottom (the dock button is an icon with a tooltip and a label)
- [ ] **Collapse** the terminal to a thin strip (either dock) and **View Agent Terminal** brings it - [ ] **Collapse** the terminal to a thin strip (either dock) and its expand button (**Show the terminal**) brings it
back; its size from before collapsing is remembered back; its size from before collapsing is remembered
- [ ] Docked right, collapsed: the **View Agent Terminal** label reads top-to-bottom and fits inside the strip, - [ ] Docked right, collapsed: the strip holds only the expand button (and the pill, reading top-to-bottom),
not sideways text running off the edge with nothing running off the edge
- [ ] Collapse the terminal (or shrink it small), let the agent go quiet for a while mid-answer: the - [ ] Collapse the terminal (or shrink it small), let the agent go quiet for a while mid-answer: the
"agent may need you" badge appears on the strip; expanding it clears the badge **Agent may need you** pill appears on the strip; pressing it expands the terminal and focuses it, and the pill clears
- [ ] The splitter takes the keyboard (Tab to it, arrows step it 2%, Home and End go to the ends)
and a double-click returns it to the default width; Ctrl or Cmd with plus, minus and 0 change the
terminal's text size, and it is the same size after a relaunch
- [ ] Switch the theme (and the highlight) in User Preferences: the bar, the terminal frame, the terminal's
colors and the OS title bar all follow at once, and a relaunch opens in that theme with no flash of
the other one (check WebView2 on Windows, and WebKit on macOS and Linux: scrollbars, fonts, title bar)
- [ ] The window appears already painted (no white or blank frame), says "Starting Plan2Code" until the
first screen, remembers its size and position, and opens maximized only on the very first launch
- [ ] Narrow the window: the model text leaves the top bar first, then the status line (both then sit in
the agent menu), and the bar never scrolls; **+N more** opens a list of the other steps
- [ ] The top bar's project and agent menus open under their name, close on a click elsewhere (the - [ ] The top bar's project and agent menus open under their name, close on a click elsewhere (the
console frame and the terminal included) or Escape, and are not cut off by the bar console frame and the terminal included) or Escape, and are not cut off by the bar
- [ ] **Change project** in the top bar's project menu, with an agent running: it asks first, then the folder - [ ] **Change project** in the top bar's project menu, with an agent running: it asks first, then the folder
+1 -1
View File
@@ -1,6 +1,6 @@
[package] [package]
name = "fake-agent" name = "fake-agent"
version = "3.1.0" version = "3.1.1"
description = "A stand-in agent program for the Plan2Code app's tests" description = "A stand-in agent program for the Plan2Code app's tests"
edition = "2021" edition = "2021"
publish = false publish = false
+9 -2
View File
@@ -1,15 +1,16 @@
{ {
"name": "plan2code-app", "name": "plan2code-app",
"version": "3.1.0", "version": "3.1.1",
"lockfileVersion": 3, "lockfileVersion": 3,
"requires": true, "requires": true,
"packages": { "packages": {
"": { "": {
"name": "plan2code-app", "name": "plan2code-app",
"version": "3.1.0", "version": "3.1.1",
"dependencies": { "dependencies": {
"@tauri-apps/api": "2.12.4", "@tauri-apps/api": "2.12.4",
"@xterm/addon-fit": "0.11.0", "@xterm/addon-fit": "0.11.0",
"@xterm/addon-web-links": "0.12.0",
"@xterm/xterm": "6.0.0" "@xterm/xterm": "6.0.0"
}, },
"devDependencies": { "devDependencies": {
@@ -249,6 +250,12 @@
"integrity": "sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==", "integrity": "sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==",
"license": "MIT" "license": "MIT"
}, },
"node_modules/@xterm/addon-web-links": {
"version": "0.12.0",
"resolved": "https://registry.npmjs.org/@xterm/addon-web-links/-/addon-web-links-0.12.0.tgz",
"integrity": "sha512-4Smom3RPyVp7ZMYOYDoC/9eGJJJqYhnPLGGqJ6wOBfB8VxPViJNSKdgRYb8NpaM6YSelEKbA2SStD7lGyqaobw==",
"license": "MIT"
},
"node_modules/@xterm/xterm": { "node_modules/@xterm/xterm": {
"version": "6.0.0", "version": "6.0.0",
"resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.0.0.tgz", "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.0.0.tgz",
+2 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "plan2code-app", "name": "plan2code-app",
"version": "3.1.0", "version": "3.1.1",
"private": true, "private": true,
"description": "Plan2Code desktop app (Tauri). Separate from the repo root so the root and the web console stay dependency-free.", "description": "Plan2Code desktop app (Tauri). Separate from the repo root so the root and the web console stay dependency-free.",
"scripts": { "scripts": {
@@ -11,6 +11,7 @@
"dependencies": { "dependencies": {
"@tauri-apps/api": "2.12.4", "@tauri-apps/api": "2.12.4",
"@xterm/addon-fit": "0.11.0", "@xterm/addon-fit": "0.11.0",
"@xterm/addon-web-links": "0.12.0",
"@xterm/xterm": "6.0.0" "@xterm/xterm": "6.0.0"
}, },
"devDependencies": { "devDependencies": {
+8 -3
View File
@@ -1,5 +1,8 @@
// Copies the xterm files the page loads from node_modules into ui/vendor/, so the // Copies the files the page loads from outside ui/ into ui/vendor/, so the page is
// page is plain files with no bundler. Run before `tauri dev` and `tauri build`. // plain files with no bundler: the xterm files from node_modules, and the web
// console's own tokens.css (its colors, type, radii and layers), so the shell
// wears the same ones and cannot drift from them. Run before `tauri dev` and
// `tauri build`.
import { copyFileSync, mkdirSync } from 'node:fs'; import { copyFileSync, mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path'; import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url'; import { fileURLToPath } from 'node:url';
@@ -12,6 +15,8 @@ const files = [
['node_modules/@xterm/xterm/lib/xterm.js', 'xterm.js'], ['node_modules/@xterm/xterm/lib/xterm.js', 'xterm.js'],
['node_modules/@xterm/xterm/css/xterm.css', 'xterm.css'], ['node_modules/@xterm/xterm/css/xterm.css', 'xterm.css'],
['node_modules/@xterm/addon-fit/lib/addon-fit.js', 'addon-fit.js'], ['node_modules/@xterm/addon-fit/lib/addon-fit.js', 'addon-fit.js'],
['node_modules/@xterm/addon-web-links/lib/addon-web-links.js', 'addon-web-links.js'],
['../src/web-console/public/styles/tokens.css', 'tokens.css'],
]; ];
for (const [from, to] of files) copyFileSync(join(root, from), join(out, to)); for (const [from, to] of files) copyFileSync(join(root, from), join(out, to));
console.log(`vendored ${files.length} xterm files into ui/vendor/`); console.log(`vendored ${files.length} files into ui/vendor/`);
+3 -1
View File
@@ -1,6 +1,6 @@
[package] [package]
name = "plan2code-app" name = "plan2code-app"
version = "3.1.0" version = "3.1.1"
description = "Plan2Code desktop app" description = "Plan2Code desktop app"
edition = "2021" edition = "2021"
publish = false publish = false
@@ -15,6 +15,8 @@ tauri-build = { version = "2.5", features = [] }
[dependencies] [dependencies]
tauri = { version = "2.12", features = [] } tauri = { version = "2.12", features = [] }
tauri-plugin-dialog = "2" tauri-plugin-dialog = "2"
tauri-plugin-opener = "2.7"
tauri-plugin-window-state = "2.5"
portable-pty = "0.9.0" portable-pty = "0.9.0"
serde = { version = "1", features = ["derive"] } serde = { version = "1", features = ["derive"] }
serde_json = "1" serde_json = "1"
@@ -1,7 +1,7 @@
{ {
"$schema": "../gen/schemas/desktop-schema.json", "$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default", "identifier": "default",
"description": "Permissions for the main window: its own commands need none, so only listening to the page events the app sends, plus setting the window's own title to the open project's name and putting it in and out of full screen for an Activities game", "description": "Permissions for the main window: its own commands need none, so only listening to the page events the app sends, plus setting the window's own title to the open project's name and putting it in and out of full screen for an Activities game, plus showing and theming it, the window-state plugin, and opening http and https links (the terminal's clickable URLs) in the default browser, through the opener plugin and nothing else it can do",
"windows": ["main"], "windows": ["main"],
"permissions": ["core:event:allow-listen", "core:event:allow-unlisten", "core:window:allow-set-title", "core:window:allow-is-fullscreen", "core:window:allow-set-fullscreen"] "permissions": ["core:event:allow-listen", "core:event:allow-unlisten", "core:window:allow-set-title", "core:window:allow-is-fullscreen", "core:window:allow-set-fullscreen", "core:window:allow-show", "core:window:allow-set-theme", "window-state:default", {"identifier": "opener:allow-open-url", "allow": [{"url": "https://*"}, {"url": "http://*"}]}]
} }
+1
View File
@@ -22,4 +22,5 @@ pub mod session_reader;
pub mod settings; pub mod settings;
#[cfg(windows)] #[cfg(windows)]
pub mod task_dialog; pub mod task_dialog;
pub mod ui_confirm;
pub mod versions; pub mod versions;
+113 -2
View File
@@ -1131,14 +1131,17 @@ pub fn prompt_support(agent: &Agent) -> bool {
// -------------------------------------------------------- starting a loop // -------------------------------------------------------- starting a loop
/// `specs/<name>`: one folder directly under `specs/`, not a link. /// `specs/<name>`: one folder directly under `specs/`, not a link. The name may
/// hold dots (`polish-3.2`) but never start with one, which also refuses `.`
/// and `..`, matching the page's `isDeletableSpecDir`.
pub fn validate_spec(project: &Path, spec: &str) -> Result<(), String> { pub fn validate_spec(project: &Path, spec: &str) -> Result<(), String> {
let bad = || format!("not a spec folder: {spec}"); let bad = || format!("not a spec folder: {spec}");
let name = spec.strip_prefix("specs/").ok_or_else(bad)?; let name = spec.strip_prefix("specs/").ok_or_else(bad)?;
if name.is_empty() if name.is_empty()
|| name.starts_with('.')
|| !name || !name
.chars() .chars()
.all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_') .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.')
{ {
return Err(bad()); return Err(bad());
} }
@@ -1390,6 +1393,70 @@ pub fn confirm_text(rec: &RunningRecord) -> String {
text text
} }
/// The same Start confirm as lines for the shell's modal: the question, the quick check in a code
/// block, the resume notes as text, and the trunk warning as an amber callout, with no literal
/// backticks (`confirm_text` stays the plain-text form).
pub fn confirm_lines(rec: &RunningRecord) -> Vec<crate::ui_confirm::ConfirmLine> {
use crate::ui_confirm::ConfirmLine;
let name = rec.spec.strip_prefix("specs/").unwrap_or(&rec.spec);
let n = rec.phases.len();
let phases = if n == 1 {
"1 phase".to_string()
} else {
format!("{n} phases")
};
let mut lines = vec![ConfirmLine::text(format!("Build {phases} of {name}?"))];
let check = rec.setup.quick_check.trim();
if check.is_empty() {
lines.push(ConfirmLine::text("No quick check is set."));
} else {
lines.push(ConfirmLine::text(
"After each phase the app runs this quick check:",
));
lines.push(ConfirmLine::code(check));
}
if !rec.rebuilt.is_empty() {
let list: Vec<String> = rec.rebuilt.iter().map(|n| format!("Phase {n}")).collect();
lines.push(ConfirmLine::text(format!(
"{} is marked done but has no commit in the log, so it is built again.",
list.join(" and ")
)));
}
if let Some(files) = rec.resumed_files {
let files = if files == 1 {
"1 uncommitted file".to_string()
} else {
format!("{files} uncommitted files")
};
lines.push(ConfirmLine::text(format!(
"The resumed phase's commit will take {files} already in the tree."
)));
}
if !rec.setup.notify_url.is_empty() {
let when = if rec.setup.notify_phases {
"after each phase, when the loop needs you, or when it ends"
} else {
"When the loop needs you or ends"
};
lines.push(ConfirmLine::text(format!(
"{}, {}.",
capitalized(when),
loop_notify::describe(
rec.setup.notify_kind,
&rec.setup.notify_url,
&rec.setup.notify_param
)
)));
}
if commits_to_trunk(rec) {
let branch = rec.branch.as_deref().unwrap_or_default();
lines.push(ConfirmLine::callout(format!(
"You are on {branch}: every phase will commit straight to it. Start only if that is what you want."
)));
}
lines
}
fn capitalized(text: &str) -> String { fn capitalized(text: &str) -> String {
let mut chars = text.chars(); let mut chars = text.chars();
chars chars
@@ -3778,6 +3845,44 @@ mod tests {
.contains("After each phase, when the loop needs you, or when it ends")); .contains("After each phase, when the loop needs you, or when it ends"));
} }
#[test]
fn the_start_confirm_as_lines_has_the_check_in_a_code_block_and_the_trunk_warning_as_a_callout()
{
let mut s = setup();
s.quick_check = "npm test".into();
s.commit = true;
let mut rec = RunningRecord::new("p".into(), "specs/x".into(), s, vec![phase(1), phase(2)]);
rec.branch = Some("main".into());
let lines = confirm_lines(&rec);
assert_eq!(lines[0].text, "Build 2 phases of x?");
assert!(lines
.iter()
.any(|l| l.kind == "code" && l.text == "npm test"));
let callout = lines
.iter()
.find(|l| l.kind == "callout")
.expect("a callout");
assert!(callout
.text
.contains("You are on main: every phase will commit straight to it."));
assert!(
lines.iter().all(|l| !l.text.contains('`')),
"no literal backticks"
);
assert_eq!(
lines.last().map(|l| l.kind),
Some("callout"),
"the warning reads last"
);
rec.setup.quick_check = String::new();
rec.branch = Some("feature/x".into());
let plain = confirm_lines(&rec);
assert!(plain.iter().any(|l| l.text == "No quick check is set."));
assert!(plain
.iter()
.all(|l| l.kind != "callout" && l.kind != "code"));
}
#[test] #[test]
fn no_web_address_means_no_call_and_an_older_entry_reads_with_none() { fn no_web_address_means_no_call_and_an_older_entry_reads_with_none() {
assert_eq!(notify(&setup(), "x"), None); assert_eq!(notify(&setup(), "x"), None);
@@ -4657,9 +4762,15 @@ second line"
let dir = std::env::temp_dir().join(format!("plan2code-loop-spec-{}", std::process::id())); let dir = std::env::temp_dir().join(format!("plan2code-loop-spec-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir); let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(dir.join("specs").join("lunch-vote")).unwrap(); std::fs::create_dir_all(dir.join("specs").join("lunch-vote")).unwrap();
std::fs::create_dir_all(dir.join("specs").join("polish-3.2")).unwrap();
std::fs::create_dir_all(dir.join("specs").join(".hidden")).unwrap();
std::fs::write(dir.join("specs").join("a-file"), "x").unwrap(); std::fs::write(dir.join("specs").join("a-file"), "x").unwrap();
assert!(validate_spec(&dir, "specs/lunch-vote").is_ok()); assert!(validate_spec(&dir, "specs/lunch-vote").is_ok());
assert!(validate_spec(&dir, "specs/polish-3.2").is_ok());
for bad in [ for bad in [
"specs/.hidden",
"specs/.",
"specs/..",
"specs/missing", "specs/missing",
"specs/a-file", "specs/a-file",
"specs/../x", "specs/../x",
+431 -66
View File
@@ -1,7 +1,7 @@
// Hide the extra console window on Windows release builds. // Hide the extra console window on Windows release builds.
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")] #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
use std::path::Path; use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, OnceLock}; use std::sync::{Arc, Mutex, OnceLock};
@@ -22,6 +22,7 @@ use plan2code_app_lib::session_reader;
use plan2code_app_lib::settings; use plan2code_app_lib::settings;
#[cfg(windows)] #[cfg(windows)]
use plan2code_app_lib::task_dialog; use plan2code_app_lib::task_dialog;
use plan2code_app_lib::ui_confirm;
use plan2code_app_lib::versions; use plan2code_app_lib::versions;
use tauri::ipc::{Channel, InvokeResponseBody}; use tauri::ipc::{Channel, InvokeResponseBody};
use tauri::{Emitter, Manager, State}; use tauri::{Emitter, Manager, State};
@@ -42,12 +43,9 @@ struct AppState {
page: PageChannel, page: PageChannel,
// This window's endpoint for pages the agent's `console.mjs open` wants shown here. // This window's endpoint for pages the agent's `console.mjs open` wants shown here.
announce: Arc<Mutex<Option<AnnounceServer>>>, announce: Arc<Mutex<Option<AnnounceServer>>>,
// The Node version `main()` found before opening the window (Task 1.7 exits // The Node check's result: it runs on a background thread after the
// cleanly on anything else, so this is always a passing version once the // window opens (Task 9.10), so this is unchecked until it reports.
// window exists), and which binary that was, with `resolved_path`'s PATH node: Mutex<NodeReport>,
// (Task 9.9): the first-run checklist's Node row names both.
node_version: Option<String>,
node_binary: Option<String>,
// What the taskbar entry last said, and whether it may say anything. // What the taskbar entry last said, and whether it may say anything.
attention: Mutex<AttentionState>, attention: Mutex<AttentionState>,
// The app itself, once it is set up: the agent's sink clears the taskbar // The app itself, once it is set up: the agent's sink clears the taskbar
@@ -60,6 +58,69 @@ struct AppState {
// kept after the running record is gone so Resume, Fix together with an agent and // kept after the running record is gone so Resume, Fix together with an agent and
// Finalize still work. Memory only. // Finalize still work. Memory only.
last_loop: Mutex<Option<LastLoop>>, last_loop: Mutex<Option<LastLoop>>,
// The version this app was running before an "Update and restart" brought it up: read
// from app.json once at launch (and cleared there), for the page to say "Updated to vX".
updated_from: Option<String>,
// Confirms the shell's own modal is asked (ui_confirm.rs): the answers still to come, and
// whether the page has begun listening for requests (until then the OS box asks instead).
confirms: ui_confirm::Pending,
confirm_ready: AtomicBool,
}
/// What the Node check found, as the page reads it (`app_state` and the
/// `node-status` event share this shape). `checked` is false until the check
/// has finished; `problem` is the failure message, if any.
#[derive(Clone, Default, serde::Serialize)]
#[serde(rename_all = "camelCase")]
struct NodeReport {
checked: bool,
version: Option<String>,
binary: Option<String>,
problem: Option<String>,
}
/// Run the Node check off the main thread and publish its result: store it,
/// tell the page, and on a failure show the dialog and end the app, as
/// `main()` did before the window existed (FR-13).
fn spawn_node_check(app: tauri::AppHandle) {
std::thread::spawn(move || {
let status = node_check::check_node();
let problem = node_check::problem_message(&status);
let version = match &status {
node_check::NodeStatus::Ok(version) => Some(version.clone()),
_ => None,
};
let binary = version
.as_ref()
.and_then(|_| node_check::node_binary_path());
let report = NodeReport {
checked: true,
version,
binary,
problem: problem.clone(),
};
if let Ok(mut slot) = app.state::<AppState>().node.lock() {
*slot = report.clone();
}
let _ = app.emit("node-status", &report);
if let Some(message) = problem {
// The first button is the default: Open nodejs.org, then the app ends either way.
let open_site = app
.dialog()
.message(&message)
.title("Plan2Code needs Node.js")
.kind(MessageDialogKind::Error)
.buttons(MessageDialogButtons::OkCancelCustom(
"Open nodejs.org".to_string(),
"Quit".to_string(),
))
.blocking_show();
if open_site {
let _ = open_url("https://nodejs.org");
}
std::process::exit(1);
}
});
} }
// The console page's last state as the taskbar shows it (attention.rs), and // The console page's last state as the taskbar shows it (attention.rs), and
@@ -146,7 +207,12 @@ fn agent_availability(refresh: Option<bool>) -> serde_json::Value {
// is an error: the page never names the link itself. // is an error: the page never names the link itself.
#[tauri::command] #[tauri::command]
fn open_install_page(id: String) -> Result<(), String> { fn open_install_page(id: String) -> Result<(), String> {
let url = agents::install_page_url(&id)?; open_url(&agents::install_page_url(&id)?)
}
// Opens a web address in the default browser, with the same switches as the console
// open-link.mjs.
fn open_url(url: &str) -> Result<(), String> {
// The same switches as the console open-link.mjs. // The same switches as the console open-link.mjs.
if std::env::var_os("NO_BROWSER").is_some_and(|v| !v.is_empty()) if std::env::var_os("NO_BROWSER").is_some_and(|v| !v.is_empty())
|| std::env::var_os("PLAN2CODE_NO_BROWSER").is_some_and(|v| !v.is_empty()) || std::env::var_os("PLAN2CODE_NO_BROWSER").is_some_and(|v| !v.is_empty())
@@ -155,11 +221,11 @@ fn open_install_page(id: String) -> Result<(), String> {
} }
let mut command = if cfg!(windows) { let mut command = if cfg!(windows) {
let mut c = std::process::Command::new("rundll32.exe"); let mut c = std::process::Command::new("rundll32.exe");
c.args(["url.dll,FileProtocolHandler", &url]); c.args(["url.dll,FileProtocolHandler", url]);
c c
} else if cfg!(target_os = "macos") { } else if cfg!(target_os = "macos") {
let mut c = std::process::Command::new("open"); let mut c = std::process::Command::new("open");
c.arg(&url); c.arg(url);
c c
} else { } else {
let browser = std::env::var("BROWSER") let browser = std::env::var("BROWSER")
@@ -167,7 +233,7 @@ fn open_install_page(id: String) -> Result<(), String> {
.filter(|b| !b.is_empty()) .filter(|b| !b.is_empty())
.unwrap_or_else(|| "xdg-open".to_string()); .unwrap_or_else(|| "xdg-open".to_string());
let mut c = std::process::Command::new(browser); let mut c = std::process::Command::new(browser);
c.arg(&url); c.arg(url);
c c
}; };
command command
@@ -480,6 +546,100 @@ struct QuitOpen;
impl Drop for QuitOpen { impl Drop for QuitOpen {
fn drop(&mut self) { fn drop(&mut self) {
QUIT_OPEN.store(false, Ordering::SeqCst); QUIT_OPEN.store(false, Ordering::SeqCst);
// Stay was the answer (a Quit has already taken the plan): no restart is pending.
if let Ok(mut plan) = RESTART_ON_QUIT.lock() {
*plan = None;
}
}
}
// What an "Update and restart" starts once the app has shut down: the app file to run, the
// project folder to hand it, and this app's version for the "Updated to vX" note.
struct RestartPlan {
exe: PathBuf,
project: Option<PathBuf>,
from_version: String,
}
// Set by `restart_app`, taken by `quit_app`. A Stay answer to the quit check clears it
// (`QuitOpen`'s drop), so a later ordinary quit never restarts.
static RESTART_ON_QUIT: Mutex<Option<RestartPlan>> = Mutex::new(None);
// Starts the new app, detached so it outlives this process. The note for its first page goes
// to app.json first.
fn spawn_restart(plan: &RestartPlan) -> Result<(), String> {
if let Some(file) = settings::settings_file() {
let _ = settings::save_updated_from(&file, &plan.from_version);
}
let mut command = std::process::Command::new(&plan.exe);
command
.args(versions::restart_args(plan.project.as_deref()))
.stdin(std::process::Stdio::null())
.stdout(std::process::Stdio::null())
.stderr(std::process::Stdio::null());
#[cfg(windows)]
{
use std::os::windows::process::CommandExt;
command.creation_flags(0x0000_0008 | 0x0000_0200); // DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP
}
#[cfg(unix)]
{
use std::os::unix::process::CommandExt;
command.process_group(0);
}
command
.spawn()
.map(|_| ())
.map_err(|e| format!("could not start {}: {e}", plan.exe.display()))
}
// Asks through the shell's own modal and waits for the answer: one look for every confirm, with the
// safe button first and focused. None when the page cannot show it (no window yet, or its modal is
// not listening): the caller then asks with the OS box. Blocks, so never call it on the event loop.
fn ask_in_window(
app: &tauri::AppHandle,
build: impl FnOnce(String) -> ui_confirm::ConfirmRequest,
) -> Option<bool> {
let state = app.state::<AppState>();
if !state.confirm_ready.load(Ordering::SeqCst) || app.get_webview_window("main").is_none() {
return None;
}
let (id, rx) = state.confirms.register();
let request = build(id.clone());
if app.emit("confirm-request", &request).is_err() {
state.confirms.forget(&id);
return None;
}
let yes = ui_confirm::wait_for(&rx, ui_confirm::ANSWER_TIMEOUT);
state.confirms.forget(&id);
// Whatever the page still shows for this request goes away with it.
let _ = app.emit("confirm-cancel", &id);
Some(yes)
}
// The modal's answer, by the id the request carried. A stale or invented id changes nothing.
#[tauri::command]
fn confirm_answer(state: State<'_, AppState>, id: String, yes: bool) {
state.confirms.answer(&id, yes);
}
// The page is listening for `confirm-request` from now on.
#[tauri::command]
fn confirm_ready(state: State<'_, AppState>) {
state.confirm_ready.store(true, Ordering::SeqCst);
// A page that has only now started listening (a reload) shows no older modal: whatever was
// asked before it listened is Cancel, not a thread waiting out the timeout with the quit
// check (QUIT_OPEN) held.
state.confirms.cancel_all();
}
// The bar's "..." menu and the macOS menu's Quit: the same quit check as closing the window.
#[tauri::command]
fn request_quit(app: tauri::AppHandle) {
if agent_is_active(&app) {
confirm_quit(&app);
} else {
quit_app(&app);
} }
} }
@@ -523,27 +683,46 @@ fn confirm_quit(app: &tauri::AppHandle) {
QuitCase::Waiting => MessageDialogKind::Info, QuitCase::Waiting => MessageDialogKind::Info,
QuitCase::Working => MessageDialogKind::Warning, QuitCase::Working => MessageDialogKind::Warning,
}; };
// The plugin makes its first button the default, so off Windows Enter // Off Windows the shell's own modal asks, with Stay first and focused, so Stay is the default
// means Quit. Stay first would make Esc quit instead, since the plugin // answer everywhere (the plugin's box makes Quit the default). The OS box is the fallback for a
// reads Esc as "not the first button". // page that cannot show it. Both wait off the event loop.
let app = app.clone(); let app = app.clone();
app.dialog() std::thread::spawn(move || {
.message(prompt.message.clone()) let _open = open;
.title(prompt.heading.clone()) #[cfg(not(windows))]
.kind(kind) {
.buttons(MessageDialogButtons::OkCancelCustom( let asked = ask_in_window(&app, |id| {
prompt.quit.clone(), ui_confirm::quit_request(
prompt.stay.clone(), id,
)) &prompt.heading,
.show({ &prompt.message,
let app = app.clone(); &prompt.quit,
move |quit| { &prompt.stay,
let _open = open; )
});
if let Some(quit) = asked {
if quit { if quit {
quit_app(&app); quit_app(&app);
} }
return;
} }
}); }
// The plugin makes its first button the default, so here Enter means Quit. Stay first
// would make Esc quit instead, since the plugin reads Esc as "not the first button".
let quit = app
.dialog()
.message(prompt.message.clone())
.title(prompt.heading.clone())
.kind(kind)
.buttons(MessageDialogButtons::OkCancelCustom(
prompt.quit.clone(),
prompt.stay.clone(),
))
.blocking_show();
if quit {
quit_app(&app);
}
});
} }
// A running loop counts even between two phases, when no agent runs for a moment. // A running loop counts even between two phases, when no agent runs for a moment.
@@ -557,6 +736,7 @@ fn agent_is_active(app: &tauri::AppHandle) -> bool {
// its record is dropped without a word to the page, so its watch thread never // its record is dropped without a word to the page, so its watch thread never
// takes the ended agent for a crash. // takes the ended agent for a crash.
fn quit_app(app: &tauri::AppHandle) { fn quit_app(app: &tauri::AppHandle) {
let restart = RESTART_ON_QUIT.lock().ok().and_then(|mut plan| plan.take());
let state = app.state::<AppState>(); let state = app.state::<AppState>();
loop_driver::abandon(&state.loop_run); loop_driver::abandon(&state.loop_run);
if let Some(agent) = current_agent(&state) { if let Some(agent) = current_agent(&state) {
@@ -567,6 +747,11 @@ fn quit_app(app: &tauri::AppHandle) {
let _ = console.stop(); let _ = console.stop();
} }
} }
if let Some(plan) = restart {
if let Err(error) = spawn_restart(&plan) {
eprintln!("plan2code: restart failed: {error}");
}
}
app.exit(0); app.exit(0);
} }
@@ -723,15 +908,24 @@ fn app_state(state: State<'_, AppState>) -> serde_json::Value {
let first_run_done = settings_file let first_run_done = settings_file
.as_ref() .as_ref()
.is_some_and(|file| settings::load_first_run_done(file)); .is_some_and(|file| settings::load_first_run_done(file));
let node = state.node.lock().map(|n| n.clone()).unwrap_or_default();
let terminal_font_size = settings_file
.as_ref()
.map_or(settings::DEFAULT_TERMINAL_FONT_SIZE, |file| {
settings::load_terminal_font_size(file)
});
serde_json::json!({ serde_json::json!({
"projectDir": project.as_ref().map(|p| p.dir.to_string_lossy().into_owned()), "projectDir": project.as_ref().map(|p| p.dir.to_string_lossy().into_owned()),
"projectDirSource": project.as_ref().map(|p| p.source), "projectDirSource": project.as_ref().map(|p| p.source),
"lastAgent": last_agent, "lastAgent": last_agent,
"launchModel": state.launch.model, "launchModel": state.launch.model,
// Task 1.7 already exits before the window opens on a missing or too-old // The Node check runs after the window opens: `nodeChecked` is false
// Node, so this is always a pass; the checklist's Node row just names it. // until it finishes, then `node-status` is emitted with the same
"nodeVersion": state.node_version, // fields. A failure shows its dialog and ends the app.
"nodeBinary": state.node_binary, "nodeChecked": node.checked,
"nodeVersion": node.version,
"nodeBinary": node.binary,
"nodeProblem": node.problem,
"skillsVersion": versions::installed_skills_version(), "skillsVersion": versions::installed_skills_version(),
"firstRunDone": first_run_done, "firstRunDone": first_run_done,
// The launcher always passes `--project` alongside `--agent`, so an // The launcher always passes `--project` alongside `--agent`, so an
@@ -739,6 +933,14 @@ fn app_state(state: State<'_, AppState>) -> serde_json::Value {
// or launch card shown. // or launch card shown.
"autoStart": state.launch.agent, "autoStart": state.launch.agent,
"termPanel": term_panel, "termPanel": term_panel,
"terminalFontSize": terminal_font_size,
"copyOnSelect": settings_file.as_ref().map_or_else(
settings::default_copy_on_select,
|file| settings::load_copy_on_select(file),
),
// Set only on the launch right after an "Update and restart": the version the old app
// ran. The page says "Updated to v<this app's version>" once.
"updatedFrom": state.updated_from,
// The Desktop app switch, for the page's User Preferences. // The Desktop app switch, for the page's User Preferences.
"taskbarSignal": state.attention.lock().map_or(true, |guard| guard.enabled), "taskbarSignal": state.attention.lock().map_or(true, |guard| guard.enabled),
}) })
@@ -753,6 +955,30 @@ fn save_term_panel(dock: String, fraction: f64, collapsed: bool) -> Result<(), S
settings::save_term_panel(&file, &dock, fraction, collapsed) settings::save_term_panel(&file, &dock, fraction, collapsed)
} }
/// The terminal's font size (Ctrl/Cmd plus, minus and 0), kept in app.json.
/// A size outside 8 to 32 is refused.
#[tauri::command]
fn save_terminal_font_size(size: u32) -> Result<(), String> {
let file = settings::settings_file().ok_or("no home folder found")?;
settings::save_terminal_font_size(&file, size)
}
/// Copy-on-select for the terminal (Task 10.6): whether selecting text copies it at once.
/// The saved choice, or the OS default (on for Linux, off on Windows and macOS).
#[tauri::command]
fn get_copy_on_select() -> bool {
settings::settings_file().map_or_else(settings::default_copy_on_select, |file| {
settings::load_copy_on_select(&file)
})
}
/// Save the copy-on-select choice in app.json.
#[tauri::command]
fn set_copy_on_select(on: bool) -> Result<(), String> {
let file = settings::settings_file().ok_or("no home folder found")?;
settings::save_copy_on_select(&file, on)
}
/// The first-run checklist passed once: later launches go straight to the /// The first-run checklist passed once: later launches go straight to the
/// launch card (Task 9.4). /// launch card (Task 9.4).
#[tauri::command] #[tauri::command]
@@ -771,15 +997,19 @@ fn version_status(app: tauri::AppHandle) -> versions::VersionStatus {
) )
} }
/// The newest GitHub release's version when it is newer than this app, else none (also none on /// The release check: `{ latest, problem }`. `latest` is the newest GitHub release's version
/// any failure to ask). The page asks once at start and never waits on it. /// when it is newer than this app, else null; `problem` is a short sentence when the check
/// could not run (git missing, no network), else null. The page asks at start and again every
/// few hours, and never waits on it.
#[tauri::command] #[tauri::command]
async fn check_new_release(app: tauri::AppHandle) -> Option<String> { async fn check_new_release(app: tauri::AppHandle) -> versions::ReleaseCheck {
let version = app.package_info().version.to_string(); let version = app.package_info().version.to_string();
tauri::async_runtime::spawn_blocking(move || versions::check_new_release(&version)) tauri::async_runtime::spawn_blocking(move || versions::check_new_release(&version))
.await .await
.ok() .unwrap_or_else(|_| versions::ReleaseCheck {
.flatten() latest: None,
problem: Some("Could not check for updates: the check did not finish.".to_string()),
})
} }
/// What `update_skills` resolves with: the installer's last line, and the version status /// What `update_skills` resolves with: the installer's last line, and the version status
@@ -813,6 +1043,60 @@ async fn update_skills(
Ok(UpdateOutcome { message, status }) Ok(UpdateOutcome { message, status })
} }
/// "Update and restart", step one: the installer unpinned (the newest release, not this app's
/// own tag), with its output live on `progress`. On success the old app keeps running until
/// `restart_app`; on failure it stays as it was and the error is a readable reason.
#[tauri::command]
async fn update_to_newest(
app: tauri::AppHandle,
progress: Channel<String>,
) -> Result<UpdateOutcome, String> {
let message = tauri::async_runtime::spawn_blocking(move || {
versions::run_update_newest(|line| {
let _ = progress.send(line.to_string());
})
})
.await
.map_err(|e| e.to_string())??;
let status = versions::status(
&app.package_info().version.to_string(),
versions::installed_skills_version(),
);
Ok(UpdateOutcome { message, status })
}
/// "Update and restart", step two: start the freshly installed app with this one's `--project`
/// and end this one. With an agent or loop running it first asks through the existing quit
/// check (Windows TaskDialog, or the shell's own modal elsewhere; the plugin box only while the page is not listening) and answers "asking"; Stay leaves
/// everything as it was. `confirmed: true` skips that check, for a page that has already asked
/// in its own confirm. Answers "restarting" when it goes ahead. Fails, leaving this app
/// running, when the installed app file is missing.
#[tauri::command]
fn restart_app(
app: tauri::AppHandle,
state: State<'_, AppState>,
confirmed: bool,
) -> Result<&'static str, String> {
let exe = versions::installed_app_path()
.ok_or("the new app file was not found, so Plan2Code was not restarted")?;
let project = state
.project
.lock()
.ok()
.and_then(|p| p.as_ref().map(|p| p.dir.clone()));
*RESTART_ON_QUIT.lock().map_err(|e| e.to_string())? = Some(RestartPlan {
exe,
project,
from_version: app.package_info().version.to_string(),
});
if !confirmed && agent_is_active(&app) {
confirm_quit(&app);
return Ok("asking");
}
quit_app(&app);
Ok("restarting")
}
/// The OS folder picker, the folder picker's Choose a folder row on a bare /// The OS folder picker, the folder picker's Choose a folder row on a bare
/// start; a choice goes to the top of the recent folders. /// start; a choice goes to the top of the recent folders.
#[tauri::command(async)] #[tauri::command(async)]
@@ -1176,16 +1460,36 @@ async fn start_loop(
&& last.confirmed_notify == notify && last.confirmed_notify == notify
}); });
if !unchanged { if !unchanged {
let go = app // The shell's modal: the quick check in a code block, the trunk warning as a callout.
.dialog() let lines = loop_driver::confirm_lines(&record);
.message(loop_driver::confirm_text(&record)) let asker = app.clone();
.title("Implementation Loop") let asked = tauri::async_runtime::spawn_blocking(move || {
.kind(MessageDialogKind::Info) ask_in_window(&asker, |id| ui_confirm::ConfirmRequest {
.buttons(MessageDialogButtons::OkCancelCustom( id,
"Start".to_string(), title: "Start the Implementation Loop?".to_string(),
"Cancel".to_string(), lines,
)) primary: "Start".to_string(),
.blocking_show(); cancel: "Cancel".to_string(),
danger: false,
safe_first: true,
})
})
.await
.map_err(|e| e.to_string())?;
let go = match asked {
Some(go) => go,
// The page cannot show it: the OS box, with the same words as one paragraph.
None => app
.dialog()
.message(loop_driver::confirm_text(&record))
.title("Implementation Loop")
.kind(MessageDialogKind::Info)
.buttons(MessageDialogButtons::OkCancelCustom(
"Start".to_string(),
"Cancel".to_string(),
))
.blocking_show(),
};
if !go { if !go {
return Ok(false); return Ok(false);
} }
@@ -1382,26 +1686,76 @@ fn loop_dashboard(state: State<'_, AppState>) -> Result<serde_json::Value, Strin
Ok(session) Ok(session)
} }
fn main() { /// True when the window-state plugin's file does not exist yet.
// Without Node 18+ the console and skills cannot run: say so and stop (FR-13). fn first_launch(app: &tauri::AppHandle) -> bool {
let status = node_check::check_node(); use tauri_plugin_window_state::AppHandleExt;
let node_problem = node_check::problem_message(&status); app.path()
let node_version = match &status { .app_config_dir()
node_check::NodeStatus::Ok(version) => Some(version.clone()), .map(|dir| !dir.join(app.filename()).exists())
_ => None, .unwrap_or(false)
}; }
let node_binary = node_version
.as_ref()
.and_then(|_| node_check::node_binary_path());
// macOS gets a real menu bar: Plan2Code (About, Check for Updates, Help, Quit) and the standard Edit
// menu, so Copy, Paste and Select All work in the page's fields. The three custom items tell the
// page (the same actions as the bar's "..." menu); Quit is the predefined one, and the exit it asks
// for goes through the quit check in the run loop below.
#[cfg(target_os = "macos")]
fn build_mac_menu(app: &mut tauri::App) -> tauri::Result<()> {
use tauri::menu::{MenuBuilder, MenuItemBuilder, SubmenuBuilder};
let about = MenuItemBuilder::with_id("about", "About Plan2Code").build(app)?;
let check = MenuItemBuilder::with_id("check-updates", "Check for Updates...").build(app)?;
let help = MenuItemBuilder::with_id("help", "Plan2Code Help").build(app)?;
let app_menu = SubmenuBuilder::new(app, "Plan2Code")
.item(&about)
.item(&check)
.separator()
.item(&help)
.separator()
.quit()
.build()?;
let edit = SubmenuBuilder::new(app, "Edit")
.undo()
.redo()
.separator()
.cut()
.copy()
.paste()
.select_all()
.build()?;
let menu = MenuBuilder::new(app).items(&[&app_menu, &edit]).build()?;
app.set_menu(menu)?;
app.on_menu_event(|app, event| {
let id = event.id().as_ref();
if matches!(id, "about" | "check-updates" | "help") {
let _ = app.emit("app-menu", id);
}
});
Ok(())
}
fn main() {
let args = std::env::args().collect::<Vec<_>>(); let args = std::env::args().collect::<Vec<_>>();
tauri::Builder::default() tauri::Builder::default()
.plugin(tauri_plugin_dialog::init()) .plugin(tauri_plugin_dialog::init())
// Opens the terminal's http and https links (the capability scopes it to those).
.plugin(tauri_plugin_opener::init())
// Size and position come back on the next launch. Not VISIBLE (the
// window stays hidden until the page shows it), nor DECORATIONS or
// FULLSCREEN (an Activities game's full screen must not stick).
.plugin(
tauri_plugin_window_state::Builder::default()
.with_state_flags(
tauri_plugin_window_state::StateFlags::SIZE
| tauri_plugin_window_state::StateFlags::POSITION
| tauri_plugin_window_state::StateFlags::MAXIMIZED,
)
.build(),
)
.manage(AppState { .manage(AppState {
project: Mutex::new(project::resolve(&args)), project: Mutex::new(project::resolve(&args)),
launch: project::launch_choice(&args), launch: project::launch_choice(&args),
node_version, updated_from: settings::settings_file()
node_binary, .and_then(|file| settings::take_updated_from(&file)),
attention: Mutex::new(AttentionState { attention: Mutex::new(AttentionState {
last: None, last: None,
enabled: settings::settings_file() enabled: settings::settings_file()
@@ -1411,6 +1765,9 @@ fn main() {
}) })
.invoke_handler(tauri::generate_handler![ .invoke_handler(tauri::generate_handler![
platform_info, platform_info,
confirm_answer,
confirm_ready,
request_quit,
agent_availability, agent_availability,
open_install_page, open_install_page,
agent_start, agent_start,
@@ -1420,10 +1777,15 @@ fn main() {
agent_reattach, agent_reattach,
app_state, app_state,
save_term_panel, save_term_panel,
save_terminal_font_size,
save_first_run_done, save_first_run_done,
version_status, version_status,
check_new_release, check_new_release,
update_skills, update_skills,
update_to_newest,
restart_app,
get_copy_on_select,
set_copy_on_select,
pick_project_folder, pick_project_folder,
recent_folders, recent_folders,
open_recent_folder, open_recent_folder,
@@ -1496,14 +1858,17 @@ fn main() {
// Without it the agent opens pages the plain way; nothing else breaks. // Without it the agent opens pages the plain way; nothing else breaks.
Err(error) => eprintln!("plan2code: no announce endpoint: {error}"), Err(error) => eprintln!("plan2code: no announce endpoint: {error}"),
} }
if let Some(message) = &node_problem { // First launch ever (the window-state plugin has saved nothing yet):
app.dialog() // open maximized. Later launches get the saved size, position and
.message(message) // maximized state from the plugin.
.title("Plan2Code needs Node.js") if first_launch(app.handle()) {
.kind(MessageDialogKind::Error) if let Some(window) = app.get_webview_window("main") {
.blocking_show(); let _ = window.maximize();
std::process::exit(1); }
} }
#[cfg(target_os = "macos")]
build_mac_menu(app)?;
spawn_node_check(app.handle().clone());
Ok(()) Ok(())
}) })
.build(tauri::generate_context!()) .build(tauri::generate_context!())
+135 -4
View File
@@ -77,14 +77,65 @@ fn node_override_dir(args: &[String]) -> Option<String> {
#[cfg(unix)] #[cfg(unix)]
fn login_shell_path() -> Option<String> { fn login_shell_path() -> Option<String> {
let shell = std::env::var("SHELL").unwrap_or_else(|_| "/bin/sh".to_string()); let shell = std::env::var("SHELL").unwrap_or_else(|_| "/bin/sh".to_string());
// `printenv PATH`, not `echo $PATH`: fish expands `$PATH` to a list and
// echoes it space-separated, which is no PATH at all.
let out = Command::new(&shell) let out = Command::new(&shell)
.args(["-lc", "echo $PATH"]) .args(["-lc", "printenv PATH"])
.output() .output()
.ok()?; .ok()?;
let path = String::from_utf8_lossy(&out.stdout).trim().to_string(); let path = parse_path_output(&String::from_utf8_lossy(&out.stdout));
(out.status.success() && !path.is_empty()).then_some(path) (out.status.success() && !path.is_empty()).then_some(path)
} }
/// A PATH out of a shell's output: the last non-empty line (a login shell's
/// profile may print a banner first), and a space-separated list of absolute
/// folders (what fish's `echo $PATH` prints) turned into a `:` list. A single
/// folder with a space in its name is left alone.
#[cfg_attr(windows, allow(dead_code))]
fn parse_path_output(output: &str) -> String {
let line = output
.lines()
.map(str::trim)
.rfind(|l| !l.is_empty())
.unwrap_or("");
let tokens: Vec<&str> = line.split_whitespace().collect();
let spaced_list = !line.contains(':')
&& tokens.len() > 1
&& tokens
.iter()
.all(|t| t.starts_with('/') || t.starts_with('~'));
if spaced_list {
tokens.join(":")
} else {
line.to_string()
}
}
/// What the PATH lookup is named after in the failure message: the login
/// shell on macOS and Linux (its own file name, such as `fish`), the saved
/// system and user PATH on Windows.
pub fn path_source_label() -> String {
#[cfg(unix)]
{
let shell = std::env::var("SHELL").unwrap_or_else(|_| "/bin/sh".to_string());
shell_name(&shell)
}
#[cfg(not(unix))]
{
"Windows (the system and user PATH)".to_string()
}
}
#[cfg_attr(windows, allow(dead_code))]
fn shell_name(shell: &str) -> String {
let name = shell.rsplit(['/', '\\']).next().unwrap_or(shell);
if name.is_empty() {
"sh".to_string()
} else {
name.to_string()
}
}
static RESOLVED_PATH: Mutex<Option<String>> = Mutex::new(None); static RESOLVED_PATH: Mutex<Option<String>> = Mutex::new(None);
/// The PATH every process this app spawns should run with: an explicit /// The PATH every process this app spawns should run with: an explicit
@@ -250,13 +301,28 @@ pub fn node_binary_path() -> Option<String> {
/// The plain message shown when the check fails; `None` when Node is fine. /// The plain message shown when the check fails; `None` when Node is fine.
pub fn problem_message(status: &NodeStatus) -> Option<String> { pub fn problem_message(status: &NodeStatus) -> Option<String> {
problem_message_from(status, &path_source_label())
}
/// `problem_message` with the PATH source named by the caller, so a test need
/// not depend on this machine's shell.
pub fn problem_message_from(status: &NodeStatus, source: &str) -> Option<String> {
let advice = format!(
"Install the current LTS release from https://nodejs.org and start Plan2Code again.
Looked on PATH from {source}."
);
match status { match status {
NodeStatus::Ok(_) => None, NodeStatus::Ok(_) => None,
NodeStatus::TooOld(v) => Some(format!( NodeStatus::TooOld(v) => Some(format!(
"Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and this computer has {v}.\n\nInstall the current LTS release from https://nodejs.org and start Plan2Code again." "Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and this computer has {v}.
{advice}"
)), )),
NodeStatus::Missing => Some(format!( NodeStatus::Missing => Some(format!(
"Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and it was not found.\n\nInstall the current LTS release from https://nodejs.org and start Plan2Code again." "Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and it was not found.
{advice}"
)), )),
} }
} }
@@ -372,4 +438,69 @@ mod tests {
let inherited = std::env::var("PATH").unwrap_or_default(); let inherited = std::env::var("PATH").unwrap_or_default();
assert!(resolved_path().ends_with(&inherited)); assert!(resolved_path().ends_with(&inherited));
} }
#[test]
fn the_failure_message_names_where_it_looked() {
let text = problem_message_from(&NodeStatus::Missing, "fish").unwrap();
assert!(text.contains("Looked on PATH from fish."));
assert!(text.contains("https://nodejs.org"));
assert!(problem_message_from(&NodeStatus::Ok("v20.0.0".into()), "fish").is_none());
}
#[test]
fn shell_names_come_from_the_last_path_part() {
assert_eq!(shell_name("/usr/bin/fish"), "fish");
assert_eq!(shell_name("/bin/zsh"), "zsh");
assert_eq!(shell_name("bash"), "bash");
assert_eq!(shell_name(""), "sh");
}
#[test]
fn a_colon_path_is_kept_as_it_is() {
assert_eq!(
parse_path_output(
"/usr/local/bin:/usr/bin:/bin
"
),
"/usr/local/bin:/usr/bin:/bin"
);
}
#[test]
fn fish_s_space_separated_list_becomes_a_colon_list() {
assert_eq!(
parse_path_output(
"/home/sam/.nvm/bin /usr/local/bin /usr/bin
"
),
"/home/sam/.nvm/bin:/usr/local/bin:/usr/bin"
);
}
#[test]
fn a_banner_before_the_path_and_a_folder_with_a_space_are_handled() {
assert_eq!(
parse_path_output(
"Welcome back
/usr/bin:/bin
"
),
"/usr/bin:/bin"
);
assert_eq!(
parse_path_output(
"/Users/Jo Smith/bin
"
),
"/Users/Jo Smith/bin"
);
assert_eq!(
parse_path_output(
"
"
),
""
);
}
} }
+141
View File
@@ -10,6 +10,13 @@ const TERM_FRACTION_KEY: &str = "termFraction";
const TERM_COLLAPSED_KEY: &str = "termCollapsed"; const TERM_COLLAPSED_KEY: &str = "termCollapsed";
const FIRST_RUN_DONE_KEY: &str = "firstRunDone"; const FIRST_RUN_DONE_KEY: &str = "firstRunDone";
const TASKBAR_SIGNAL_KEY: &str = "taskbarSignal"; const TASKBAR_SIGNAL_KEY: &str = "taskbarSignal";
const TERMINAL_FONT_SIZE_KEY: &str = "terminalFontSize";
const COPY_ON_SELECT_KEY: &str = "copyOnSelect";
const UPDATED_FROM_KEY: &str = "updatedFrom";
pub const DEFAULT_TERMINAL_FONT_SIZE: u32 = 13;
pub const TERMINAL_FONT_SIZE_MIN: u32 = 8;
pub const TERMINAL_FONT_SIZE_MAX: u32 = 32;
/// The terminal pane's remembered shape: which edge it docks to, how much of /// The terminal pane's remembered shape: which edge it docks to, how much of
/// the window it takes (a fraction, not collapsed or maximized), and whether /// the window it takes (a fraction, not collapsed or maximized), and whether
@@ -111,6 +118,34 @@ pub fn save_term_panel(
write(file, settings) write(file, settings)
} }
/// The terminal's font size in pixels: the saved one, clamped to its range,
/// or 13 when the file has none (an old file) or holds something else.
pub fn load_terminal_font_size(file: &Path) -> u32 {
read(file)
.get(TERMINAL_FONT_SIZE_KEY)
.and_then(|v| v.as_u64())
.map_or(DEFAULT_TERMINAL_FONT_SIZE, |size| {
size.clamp(
u64::from(TERMINAL_FONT_SIZE_MIN),
u64::from(TERMINAL_FONT_SIZE_MAX),
) as u32
})
}
/// Save the terminal's font size, keeping any other key the file holds. A
/// size outside 8 to 32 is rejected rather than saved.
pub fn save_terminal_font_size(file: &Path, size: u32) -> Result<(), String> {
if !(TERMINAL_FONT_SIZE_MIN..=TERMINAL_FONT_SIZE_MAX).contains(&size) {
return Err(format!("font size out of range: {size}"));
}
let mut settings = read(file);
settings.insert(
TERMINAL_FONT_SIZE_KEY.to_string(),
serde_json::Value::from(size),
);
write(file, settings)
}
/// Whether the first-run checklist has already passed once. Once it has, /// Whether the first-run checklist has already passed once. Once it has,
/// later launches go straight to the launch card (Task 9.4). /// later launches go straight to the launch card (Task 9.4).
pub fn load_first_run_done(file: &Path) -> bool { pub fn load_first_run_done(file: &Path) -> bool {
@@ -147,6 +182,54 @@ pub fn save_taskbar_signal(file: &Path, on: bool) -> Result<(), String> {
write(file, settings) write(file, settings)
} }
/// Copy-on-select's default: on for Linux, where selecting text is the
/// copy gesture, off on Windows and macOS, where it would replace what the
/// person last copied.
pub fn default_copy_on_select() -> bool {
cfg!(target_os = "linux")
}
/// Whether selecting text in the terminal copies it at once (Task 10.6). The
/// saved choice, or the per-OS default when the file has none or holds
/// something other than a boolean.
pub fn load_copy_on_select(file: &Path) -> bool {
read(file)
.get(COPY_ON_SELECT_KEY)
.and_then(|v| v.as_bool())
.unwrap_or_else(default_copy_on_select)
}
/// Save the choice, keeping any other key the file holds.
pub fn save_copy_on_select(file: &Path, on: bool) -> Result<(), String> {
let mut settings = read(file);
settings.insert(COPY_ON_SELECT_KEY.to_string(), serde_json::Value::Bool(on));
write(file, settings)
}
/// Note the version the app was running before an "Update and restart", for
/// the new app to say "Updated to vX" once (`take_updated_from`).
pub fn save_updated_from(file: &Path, version: &str) -> Result<(), String> {
let mut settings = read(file);
settings.insert(
UPDATED_FROM_KEY.to_string(),
serde_json::Value::String(version.to_string()),
);
write(file, settings)
}
/// The version noted by `save_updated_from`, read once: the key is removed
/// as it is read, so the message shows one time only.
pub fn take_updated_from(file: &Path) -> Option<String> {
let mut settings = read(file);
let from = settings
.remove(UPDATED_FROM_KEY)?
.as_str()
.map(str::to_string)
.filter(|v| !v.is_empty());
let _ = write(file, settings);
from
}
fn write(file: &Path, settings: serde_json::Map<String, serde_json::Value>) -> Result<(), String> { fn write(file: &Path, settings: serde_json::Map<String, serde_json::Value>) -> Result<(), String> {
if let Some(parent) = file.parent() { if let Some(parent) = file.parent() {
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?; std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
@@ -278,4 +361,62 @@ mod tests {
assert_eq!(loaded.fraction, 0.25); assert_eq!(loaded.fraction, 0.25);
let _ = std::fs::remove_dir_all(file.parent().unwrap()); let _ = std::fs::remove_dir_all(file.parent().unwrap());
} }
#[test]
fn the_terminal_font_size_defaults_round_trips_and_keeps_other_keys() {
let file = temp_file("font-size");
assert_eq!(load_terminal_font_size(&file), 13, "missing file");
save_last_agent(&file, "claude").unwrap();
assert_eq!(
load_terminal_font_size(&file),
13,
"old file without the field"
);
save_terminal_font_size(&file, 18).unwrap();
assert_eq!(load_terminal_font_size(&file), 18);
assert_eq!(load_last_agent(&file).as_deref(), Some("claude"));
save_term_panel(&file, "bottom", 0.4, false).unwrap();
assert_eq!(load_terminal_font_size(&file), 18);
}
#[test]
fn an_out_of_range_terminal_font_size_is_refused_and_a_bad_one_on_disk_is_clamped() {
let file = temp_file("font-size-range");
assert!(save_terminal_font_size(&file, 7).is_err());
assert!(save_terminal_font_size(&file, 33).is_err());
assert_eq!(load_terminal_font_size(&file), 13, "nothing was written");
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, r#"{"terminalFontSize": 400}"#).unwrap();
assert_eq!(load_terminal_font_size(&file), 32);
std::fs::write(&file, r#"{"terminalFontSize": 2}"#).unwrap();
assert_eq!(load_terminal_font_size(&file), 8);
std::fs::write(&file, r#"{"terminalFontSize": "big"}"#).unwrap();
assert_eq!(load_terminal_font_size(&file), 13);
}
#[test]
fn copy_on_select_defaults_per_os_and_keeps_a_saved_choice() {
let file = temp_file("copy-on-select");
// No file: Linux copies on select, Windows and macOS do not.
assert_eq!(default_copy_on_select(), cfg!(target_os = "linux"));
assert_eq!(load_copy_on_select(&file), cfg!(target_os = "linux"));
save_copy_on_select(&file, !default_copy_on_select()).unwrap();
assert_eq!(load_copy_on_select(&file), !default_copy_on_select());
save_copy_on_select(&file, default_copy_on_select()).unwrap();
assert_eq!(load_copy_on_select(&file), default_copy_on_select());
// Something other than a boolean reads as the default.
std::fs::write(&file, r#"{"copyOnSelect":"yes"}"#).unwrap();
assert_eq!(load_copy_on_select(&file), default_copy_on_select());
}
#[test]
fn the_updated_marker_is_read_once_and_keeps_other_keys() {
let file = temp_file("updated-from");
assert_eq!(take_updated_from(&file), None);
save_last_agent(&file, "claude").unwrap();
save_updated_from(&file, "3.1.0").unwrap();
assert_eq!(take_updated_from(&file).as_deref(), Some("3.1.0"));
assert_eq!(take_updated_from(&file), None);
assert_eq!(load_last_agent(&file).as_deref(), Some("claude"));
}
} }
+217
View File
@@ -0,0 +1,217 @@
//! Confirms the Rust side asks the person, drawn by the shell's own modal (`ui/app.js`
//! `confirmModal`) instead of the OS message box: one look, Stay or Cancel first and focused,
//! `role="alertdialog"`. This module is the request's shape and the table of waiting answers; it
//! knows nothing about Tauri. main.rs emits a `confirm-request` event with a [`ConfirmRequest`]
//! and blocks on the [`Receiver`] until the page calls `confirm_answer`.
use std::collections::HashMap;
use std::sync::mpsc::{channel, Receiver, Sender};
use std::sync::Mutex;
use std::time::Duration;
/// How long a confirm may stay unanswered before it counts as Cancel (a reloaded window would
/// otherwise leave its thread waiting for good).
pub const ANSWER_TIMEOUT: Duration = Duration::from_secs(15 * 60);
/// One line of a confirm's body: plain text, a code block or an amber callout.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize)]
pub struct ConfirmLine {
pub kind: &'static str,
pub text: String,
}
impl ConfirmLine {
pub fn text(text: impl Into<String>) -> Self {
Self {
kind: "text",
text: text.into(),
}
}
pub fn code(text: impl Into<String>) -> Self {
Self {
kind: "code",
text: text.into(),
}
}
pub fn callout(text: impl Into<String>) -> Self {
Self {
kind: "callout",
text: text.into(),
}
}
}
/// What the modal shows. `safe_first` puts Cancel (or Stay) first and gives it focus; `danger`
/// colors the primary as the named danger verb.
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ConfirmRequest {
pub id: String,
pub title: String,
pub lines: Vec<ConfirmLine>,
pub primary: String,
pub cancel: String,
pub danger: bool,
pub safe_first: bool,
}
/// The answers still to come, by request id.
#[derive(Default)]
pub struct Pending {
waiting: Mutex<HashMap<String, Sender<bool>>>,
next: Mutex<u64>,
}
impl Pending {
/// A new request id and the receiver its answer arrives on.
pub fn register(&self) -> (String, Receiver<bool>) {
let id = {
let mut next = self.next.lock().unwrap_or_else(|e| e.into_inner());
*next += 1;
format!("confirm-{}", *next)
};
let (tx, rx) = channel();
self.waiting
.lock()
.unwrap_or_else(|e| e.into_inner())
.insert(id.clone(), tx);
(id, rx)
}
/// The page's answer. False when no such request is waiting (a stale or invented id), which
/// changes nothing.
pub fn answer(&self, id: &str, yes: bool) -> bool {
let tx = self
.waiting
.lock()
.unwrap_or_else(|e| e.into_inner())
.remove(id);
tx.is_some_and(|tx| tx.send(yes).is_ok())
}
/// Answers every waiting request with Cancel: a page that has just started listening is not
/// showing an older modal, so whatever was asked before it listened will never be answered.
pub fn cancel_all(&self) {
let waiting = std::mem::take(&mut *self.waiting.lock().unwrap_or_else(|e| e.into_inner()));
for tx in waiting.into_values() {
let _ = tx.send(false);
}
}
/// Forgets a request that was never answered (a timeout, or a window that could not be told).
pub fn forget(&self, id: &str) {
self.waiting
.lock()
.unwrap_or_else(|e| e.into_inner())
.remove(id);
}
}
/// Waits for an answer: true only for an explicit yes; a timeout, a dropped sender or a no is Cancel.
pub fn wait_for(rx: &Receiver<bool>, timeout: Duration) -> bool {
rx.recv_timeout(timeout).unwrap_or(false)
}
/// The quit check's request: the safe answer (Stay) first and focused, the quit verb last.
pub fn quit_request(
id: String,
heading: &str,
message: &str,
quit: &str,
stay: &str,
) -> ConfirmRequest {
ConfirmRequest {
id,
title: heading.to_string(),
lines: vec![ConfirmLine::text(message)],
primary: quit.to_string(),
cancel: stay.to_string(),
danger: true,
safe_first: true,
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn an_answer_reaches_the_waiting_request_once() {
let pending = Pending::default();
let (id, rx) = pending.register();
assert!(pending.answer(&id, true));
assert!(wait_for(&rx, Duration::from_millis(50)));
assert!(
!pending.answer(&id, true),
"answered already: a second answer finds nothing"
);
}
#[test]
fn ids_are_distinct_and_an_unknown_id_answers_nothing() {
let pending = Pending::default();
let (a, _ra) = pending.register();
let (b, _rb) = pending.register();
assert_ne!(a, b);
assert!(!pending.answer("confirm-999", true));
}
#[test]
fn cancel_all_answers_every_waiting_request_with_cancel() {
let pending = Pending::default();
let (a, ra) = pending.register();
let (b, rb) = pending.register();
pending.cancel_all();
assert!(!wait_for(&ra, Duration::from_millis(50)));
assert!(!wait_for(&rb, Duration::from_millis(50)));
assert!(
!pending.answer(&a, true) && !pending.answer(&b, true),
"nothing is left waiting"
);
pending.cancel_all();
}
#[test]
fn no_answer_in_time_is_cancel_and_so_is_a_no() {
let pending = Pending::default();
let (id, rx) = pending.register();
assert!(
!wait_for(&rx, Duration::from_millis(10)),
"timeout is Cancel"
);
let (id2, rx2) = pending.register();
pending.answer(&id2, false);
assert!(!wait_for(&rx2, Duration::from_millis(50)));
pending.forget(&id);
assert!(
!pending.answer(&id, true),
"a forgotten request takes no answer"
);
}
#[test]
fn the_quit_request_puts_stay_first_and_quit_last_as_the_danger_verb() {
let request = quit_request("c1".into(), "Done for now?", "It ends.", "Quit", "Stay");
assert!(request.safe_first && request.danger);
assert_eq!(
(request.primary.as_str(), request.cancel.as_str()),
("Quit", "Stay")
);
let json = serde_json::to_value(&request).unwrap();
assert_eq!(json["safeFirst"], true, "camelCase for the page");
assert_eq!(json["lines"][0]["kind"], "text");
}
#[test]
fn no_text_carries_an_em_dash() {
let request = quit_request("c1".into(), "Done for now?", "It ends.", "Quit", "Stay");
for text in [
&request.title,
&request.lines[0].text,
&request.primary,
&request.cancel,
] {
assert!(!text.contains('\u{2014}'));
}
}
}
+160 -12
View File
@@ -105,10 +105,32 @@ pub fn newer_release(app: &str, ls_remote: &str) -> Option<String> {
(parse(&latest)? > parse(app)?).then_some(latest) (parse(&latest)? > parse(app)?).then_some(latest)
} }
/// Ask GitHub for the newest release and return its version when it is newer than `app`. /// What a release check found, as the page reads it: `latest` is the newest release's version
/// None on any failure (no git, no network, a login prompt, the timeout): a missing answer /// when it is newer than the app; `problem` is a short sentence when the check itself could not
/// is never a reason to nag. No prompt and no console window. /// run (no git, no network, a timeout), else none. An app that is simply current has neither.
pub fn check_new_release(app: &str) -> Option<String> { #[derive(Debug, PartialEq, Eq, Serialize)]
pub struct ReleaseCheck {
pub latest: Option<String>,
pub problem: Option<String>,
}
/// The check's result from `git ls-remote --tags` output, or the reason it could not run.
pub fn release_check_from(app: &str, tags: Result<String, String>) -> ReleaseCheck {
match tags {
Ok(text) => ReleaseCheck {
latest: newer_release(app, &text),
problem: None,
},
Err(reason) => ReleaseCheck {
latest: None,
problem: Some(format!("Could not check for updates: {reason}.")),
},
}
}
/// `git ls-remote --tags` output, or a short reason it could not be had. No prompt and no
/// console window.
fn fetch_tags() -> Result<String, String> {
let mut command = Command::new("git"); let mut command = Command::new("git");
command command
.env("PATH", crate::node_check::resolved_path()) .env("PATH", crate::node_check::resolved_path())
@@ -126,8 +148,14 @@ pub fn check_new_release(app: &str) -> Option<String> {
use std::os::windows::process::CommandExt; use std::os::windows::process::CommandExt;
command.creation_flags(0x08000000); // CREATE_NO_WINDOW, as the console calls are command.creation_flags(0x08000000); // CREATE_NO_WINDOW, as the console calls are
} }
let mut child = command.spawn().ok()?; let mut child = command.spawn().map_err(|e| {
let mut stdout = child.stdout.take()?; if e.kind() == std::io::ErrorKind::NotFound {
"git was not found on PATH".to_string()
} else {
"git could not be run".to_string()
}
})?;
let mut stdout = child.stdout.take().ok_or("git gave no output")?;
let (tx, rx) = mpsc::channel::<String>(); let (tx, rx) = mpsc::channel::<String>();
std::thread::spawn(move || { std::thread::spawn(move || {
let mut text = String::new(); let mut text = String::new();
@@ -138,19 +166,72 @@ pub fn check_new_release(app: &str) -> Option<String> {
Ok(text) => { Ok(text) => {
let ok = child.wait().is_ok_and(|status| status.success()); let ok = child.wait().is_ok_and(|status| status.success());
if ok { if ok {
newer_release(app, &text) Ok(text)
} else { } else {
None Err("GitHub did not answer".to_string())
} }
} }
Err(_) => { Err(_) => {
let _ = child.kill(); let _ = child.kill();
let _ = child.wait(); let _ = child.wait();
None Err("GitHub did not answer in time".to_string())
} }
} }
} }
/// Ask GitHub for the newest release and report it when it is newer than `app`. A failure
/// (no git, no network, a login prompt, the timeout) comes back as a `problem` sentence, never
/// as an error: nothing waits on it.
pub fn check_new_release(app: &str) -> ReleaseCheck {
release_check_from(app, fetch_tags())
}
/// The app file an "Update and restart" starts: `PLAN2CODE_APP` (the launcher's override, also
/// for tests), else the installer's own place, `~/.plan2code/app/plan2code-app[.exe]`, which an
/// update has just replaced; else none. Never this process's own path: a running file the
/// installer renamed aside would still be the old build.
pub fn installed_app_path() -> Option<PathBuf> {
let file = match std::env::var_os("PLAN2CODE_APP").filter(|v| !v.is_empty()) {
Some(file) => PathBuf::from(file),
None => std::env::home_dir()?
.join(".plan2code")
.join("app")
.join(if cfg!(windows) {
"plan2code-app.exe"
} else {
"plan2code-app"
}),
};
file.is_file().then_some(file)
}
/// The arguments the restarted app gets: the same `--project` folder, when there is one.
pub fn restart_args(project: Option<&Path>) -> Vec<std::ffi::OsString> {
match project {
Some(dir) => vec!["--project".into(), dir.as_os_str().to_owned()],
None => Vec::new(),
}
}
/// Which release an installer run installs. `Pinned` is the desktop app's own tag (Update
/// skills never pulls in work the app does not know about); `Newest` passes no tag, so the
/// launcher picks the newest published release itself (Update and restart).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UpdateTarget<'a> {
Pinned(&'a str),
Newest,
}
/// The launcher's arguments after its script path for `target`.
pub fn update_args(target: UpdateTarget) -> Vec<String> {
let mut args = vec!["update".to_string()];
if let UpdateTarget::Pinned(version) = target {
args.push("--tag".to_string());
args.push(format!("v{version}"));
}
args
}
/// Run the existing installer's update (`plan2code update`, through the launcher's own copy), /// Run the existing installer's update (`plan2code update`, through the launcher's own copy),
/// which brings the skills, the launcher and the app level. Pinned to the release tag `app_version` /// which brings the skills, the launcher and the app level. Pinned to the release tag `app_version`
/// names, not `main`, so Update skills never pulls in work the app does not know about yet. Blocks /// names, not `main`, so Update skills never pulls in work the app does not know about yet. Blocks
@@ -161,11 +242,25 @@ pub fn run_update(app_version: &str, on_line: impl FnMut(&str)) -> Result<String
run_update_within(app_version, UPDATE_TIMEOUT, on_line) run_update_within(app_version, UPDATE_TIMEOUT, on_line)
} }
/// "Update and restart"'s install: the same installer and progress readout, unpinned, so the
/// launcher installs the newest release (the newest-tag rule of `plan2code update`).
pub fn run_update_newest(on_line: impl FnMut(&str)) -> Result<String, String> {
run_installer(UpdateTarget::Newest, UPDATE_TIMEOUT, on_line)
}
/// `run_update`, with the timeout as a parameter so a test can use a short one instead of /// `run_update`, with the timeout as a parameter so a test can use a short one instead of
/// `UPDATE_TIMEOUT`'s real five minutes. /// `UPDATE_TIMEOUT`'s real five minutes.
fn run_update_within( fn run_update_within(
app_version: &str, app_version: &str,
timeout: Duration, timeout: Duration,
on_line: impl FnMut(&str),
) -> Result<String, String> {
run_installer(UpdateTarget::Pinned(app_version), timeout, on_line)
}
fn run_installer(
target: UpdateTarget,
timeout: Duration,
mut on_line: impl FnMut(&str), mut on_line: impl FnMut(&str),
) -> Result<String, String> { ) -> Result<String, String> {
let launcher = launcher_dir() let launcher = launcher_dir()
@@ -184,9 +279,7 @@ fn run_update_within(
command.env("PATH", crate::node_check::resolved_path()); command.env("PATH", crate::node_check::resolved_path());
command command
.arg(&launcher) .arg(&launcher)
.arg("update") .args(update_args(target))
.arg("--tag")
.arg(format!("v{app_version}"))
.stdin(Stdio::null()) .stdin(Stdio::null())
.stdout(Stdio::piped()) .stdout(Stdio::piped())
.stderr(Stdio::piped()); .stderr(Stdio::piped());
@@ -408,4 +501,59 @@ mod tests {
}); });
assert!(result.unwrap_err().contains("is missing")); assert!(result.unwrap_err().contains("is missing"));
} }
#[test]
fn the_target_picks_a_pinned_or_an_unpinned_install() {
assert_eq!(
update_args(UpdateTarget::Pinned("3.1.0")),
vec!["update", "--tag", "v3.1.0"]
);
assert_eq!(update_args(UpdateTarget::Newest), vec!["update"]);
}
#[test]
fn a_restart_hands_over_the_same_project_folder() {
assert_eq!(
restart_args(Some(Path::new("/work/app"))),
vec![
std::ffi::OsString::from("--project"),
std::ffi::OsString::from("/work/app")
]
);
assert!(restart_args(None).is_empty());
}
#[test]
fn run_update_newest_passes_no_tag() {
let result = with_fake_launcher(
"newest",
"console.log(process.argv.slice(2).join(' '));",
|| run_update_newest(|_| {}),
);
assert_eq!(result, Ok("update".to_string()));
}
#[test]
fn a_release_check_says_why_it_could_not_run() {
assert_eq!(
release_check_from("3.0.0", Ok(TAGS.to_string())),
ReleaseCheck {
latest: Some("3.10.0".into()),
problem: None
}
);
assert_eq!(
release_check_from("3.10.0", Ok(TAGS.to_string())),
ReleaseCheck {
latest: None,
problem: None
}
);
let failed = release_check_from("3.0.0", Err("git was not found on PATH".into()));
assert_eq!(failed.latest, None);
assert_eq!(
failed.problem.as_deref(),
Some("Could not check for updates: git was not found on PATH.")
);
}
} }
+5 -2
View File
@@ -1,7 +1,7 @@
{ {
"$schema": "https://schema.tauri.app/config/2", "$schema": "https://schema.tauri.app/config/2",
"productName": "Plan2Code", "productName": "Plan2Code",
"version": "3.1.0", "version": "3.1.1",
"identifier": "com.plan2code.desktop", "identifier": "com.plan2code.desktop",
"build": { "build": {
"frontendDist": "../ui", "frontendDist": "../ui",
@@ -14,7 +14,10 @@
"title": "Plan2Code", "title": "Plan2Code",
"width": 1280, "width": 1280,
"height": 800, "height": 800,
"maximized": true, "minWidth": 960,
"minHeight": 600,
"visible": false,
"backgroundColor": "#171513",
"dragDropEnabled": false, "dragDropEnabled": false,
"url": "index.html" "url": "index.html"
} }
+820 -122
View File
File diff suppressed because it is too large. Load diff
Loaded 100 of 226 files, more files were not shown because too many files have changed in this diff. Show more