mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 04:45:33 -08:00
Compare commits
44
Commits
aa6361d39e
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
347831475d | ||
|
|
7e2dae64c6 | ||
|
|
b61e3c4052 | ||
|
|
a90fb8647c | ||
|
|
8459836d3b | ||
|
|
2e2b3e1139 | ||
|
|
f61ef6e0a7 | ||
|
|
72ae44745f | ||
|
|
496bdf3e62 | ||
|
|
e80713742e | ||
|
|
7021ff9a48 | ||
|
|
cb64a8d15e | ||
|
|
faa5438db2 | ||
|
|
66fd2f71a1 | ||
|
|
f715e469ef | ||
|
|
216c64472e | ||
|
|
118ec8b12c | ||
|
|
1516b25ea3 | ||
|
|
bb5bd5986d | ||
|
|
de8a05b958 | ||
|
|
5679101487 | ||
|
|
a0300d4ac2 | ||
|
|
a55951939b | ||
|
|
36648c3e75 | ||
|
|
e6257e92bf | ||
|
|
3fe1de51ed | ||
|
|
c6265795ea | ||
|
|
fde92ef4d2 | ||
|
|
ba19f79f1c | ||
|
|
b38f2b987b | ||
|
|
97b5df61ea | ||
|
|
54b316cdf3 | ||
|
|
2f790027a9 | ||
|
|
d599d87669 | ||
|
|
15d66aa19c | ||
|
|
8bb1b11296 | ||
|
|
9199fc00af | ||
|
|
567a65ff5b | ||
|
|
1d064b18f3 | ||
|
|
d1aab9d006 | ||
|
|
7f32c351b1 | ||
|
|
b3768b47a3 | ||
|
|
8efa1aece1 | ||
|
|
6e84e6a6a4 |
No files matched your search
@@ -1,33 +1,26 @@
|
||||
# Architecture: Activities (the games)
|
||||
> Part of [AGENTS.md](../AGENTS.md) and the [Architecture index](./AGENTS-architecture.md): project guidance for AI coding agents.
|
||||
|
||||
One row per file of every game but Ghoul Rush (which has its own files: [core](./AGENTS-architecture-ghoul-core.md), [stages](./AGENTS-architecture-ghoul-stages.md), [rides](./AGENTS-architecture-ghoul-rides.md)), then the rules every game follows.
|
||||
One row per file of every game but Ghoul Rush (which has its own files: [core](./AGENTS-architecture-ghoul-core.md), [stages](./AGENTS-architecture-ghoul-stages.md), [rides](./AGENTS-architecture-ghoul-rides.md)) and Bounce Road ([its own file](./AGENTS-architecture-bounce.md)), then the rules every game follows.
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `public/activities.js` | the list of activities (`ACTIVITIES`: each game's id, title, picker card line `blurb` and module path) an optional `courses` list (Mini golf's six course ids, which open a course dashboard), `bestKey(id, course?)`, the flat looks.json key for its best score (`activityBestSnake`, one per golf course `activityBestGolfPirate` to `activityBestGolfFrost`, `activityBestTrails`, `activityBestBugs`, `activityBestDrive`, `activityBestStack`, `activityBestBumper`, `activityBestRapids`, `activityBestFuse`, `activityBestHop`, `activityBestBounce`, `activityBestGhoul`, `activityBestFlock`); lists 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, `bestKeys(entry)`, every best key a game keeps, and documents the game contract including the course parts (`courses` and `preview()` on the export, `setCourse()` and `course` on the game), the optional `pointer(type, x, y)`, `release(name)` (a game key let go) and `lowerIsBetter`; data only, imported by the page and by Node |
|
||||
| `public/activities/snake.js` | Snake: its rules as plain exported functions and the game contract (`create({ canvas, tone, onScore })` returning `start`, `pause`, `resume`, `key`, `tick`, `resize`, `score`, `state`); it never runs a timer or listens for keys, so the Activities window drives it; it also holds the music's rules: `MUSIC_TRACKS`, `dealMusic(random, last)` (a round's shuffle of the ten tracks, never opening on the last round's opener), `trackFor(deck, level)` and `heat(round)` (the snake's speed as 0.3 to 1, so the lead and drums are in from the first step) |
|
||||
| `public/activities.js` | the list of activities (`ACTIVITIES`: each game's id, title, picker row line `blurb` and module path) an optional `courses` list (Mini golf's six course ids, which open a course dashboard), `bestKey(id, course?)`, the flat looks.json key for its best score (`activityBestSnake`, one per golf course `activityBestGolfPirate` to `activityBestGolfFrost`, `activityBestTrails`, `activityBestBugs`, `activityBestDrive`, `activityBestStack`, `activityBestBumper`, `activityBestRapids`, `activityBestFuse`, `activityBestHop`, `activityBestBounce`, `activityBestGhoul`, `activityBestFlock`); lists 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, `bestKeys(entry)`, every best key a game keeps, `playedKey(id)` (`activityPlayedSnake`, the epoch ms a game was last picked, 0 for never) and `orderGames(list, looks, order)` (the picker's `{ played, unplayed }`), and documents the game contract including the course parts (`courses` and `preview()` on the export, `setCourse()` and `course` on the game), the optional `pointer(type, x, y)`, `release(name)` (a game key let go) and `lowerIsBetter`; data only, imported by the page and by Node |
|
||||
| `public/activities/snake.js` | Snake: lives (`START_LIVES` 3, `MAX_LIVES` 9, `lifeMark(n)`, `awardLives`, `GRACE_MS` of free passage after a crash puts the snake back mid-board via `respawn`; `cheat(on)` sets `round.infinite`) and the bosses (`BOSSES` by the level that opens with one: 4 Grumpy Golem, 6 Comet Queen, 8 Thunder Toad; `round.boss`, whose orbs are the food, `hitBoss`, `ageBoss`); its rules as plain exported functions and the game contract (`create({ canvas, tone, onScore })` returning `start`, `pause`, `resume`, `key`, `tick`, `resize`, `score`, `state`); it never runs a timer or listens for keys, so the Activities window drives it; it also holds the music's rules: `MUSIC_TRACKS`, `dealMusic(random, last)` (a round's shuffle of the ten tracks, never opening on the last round's opener), `trackFor(deck, level)` and `heat(round)` (the snake's speed as 0.3 to 1, so the lead and drums are in from the first step) |
|
||||
| `public/activities/trails.js` | Light Trails: its rules as plain exported functions (`newRound`, `newHeat`, `turn`, `boost`, `advance` in 8 ms slices (where your crash is held for `GRACE_MS`, a turn in that time riding out of it; rivals get no grace), `choose` and `room` for the rivals' flood-fill steering, `applyPower` (a Mystery becoming another pad), `pickPower` (by each pad's `from` arena, a Heart only under `MAX_LIVES`), `fireLaser`, `hyperjump`, `awardLives` (a life every `LIFE_SCORE` points, the mark moving on at the cap), `spawnItem`, `closeRing`), the `ARENAS` (rivals, sharpness and what each adds), the `POWERS` pads (Boost, Phase, Eraser, Slow-mo, Coin, Heart, Shield held across heats until a crash in your grace pops it, Laser with `LASER_SHOTS`, Score x2 through one `gain()` every score goes through, Wide Trail with its side cells in `rider.wide`, Coin Rain whose `rain` coins never hold back a pad, Hyperjump, Mystery) and the game contract; `START_LIVES` is 5; memo is the furthest arena reached; a read-only `round` getter for the tests only; it also holds the music's rules: `MUSIC_TRACKS` (its five songs) and `dealMusic(random, last)` (a shuffle of them, never opening on `last`); a run plays the deal one song after another, each in full from the top (asking with `{ restart: true }` until the music takes it), moves on when `music()` answers `"ended"`, deals again after the last, and a new run deals afresh, never opening on the song the last run was playing; its tones and hums play `SFX_LOUDER` times as loud through tones.js's `louder`, all but the engine drones (`DRONES`), kept low under the songs |
|
||||
| `public/activities/bugs.js` | Bug Hunt: its rules as plain exported functions (`newRound`, `spawnWave`, `slotPos`, `advance` in 8 ms slices over `round.input`, which `key()` and `release()` set, `hurtBug`, `hurtBoss`, `hitShip`, `applyPower`, `ghostly`, `tentacleTip`, `bossRadius`), the `BUGS` by first wave, the `BOSSES` every `BOSS_EVERY` waves, the `POWERS`, the `SECTORS` scenery and the game contract with `release()`; memo is the tally of `DISCOVERIES` as bits; a read-only `round` getter for the tests only |
|
||||
| `public/activities/drive.js` | Sunset Drive: its rules as plain exported functions (`newRound`, `buildStage`, which appends a stage of road and returns its `forkAt`, `gateAt` and `fork`, `segAt`, `advance` in 8 ms slices over `round.input`, which `key()` and `release()` set, `boost`, `usePower` (the oldest queued power-up, which space fires ahead of `boost`), `hopHeight`, `checkTime`), the `POWERS` in `POWER_ORDER`, the `REGIONS` (roads with their bonus, bends, hills, traffic, colors and props) in `REGION_ORDER`, the projection and drawing (sky, road far to near, props, traffic, Planny's car) and the game contract with `release()`; the next road is built only when the fork is chosen, and `FORK_LEN` must stay at least `DRAW` so it is built before it comes into view; memo is the roads found as bits; a read-only `round` getter for the tests only |
|
||||
| `public/activities/stack.js` | Stack Deploy: its rules as plain exported functions (`newRound`, `spawnBlock`, `advance` in 8 ms slices that slides the block between the walls, `drop`, which drops it where it was last drawn and returns `{ kept, sliced, perfect, miss }`, `isPerfect` and `zoneOf` (3% of the block's width, the slide in `PERFECT_MS`, or `round.minZone`, the `MIN_ZONE_PX` floor the game sets at each resize, whichever is most, but never more than half the block's width, so a drop off the tower is never perfect), `grow`, `speedAt`, `twistsAt`, `styleAt`, `comboPitch`), the `TWISTS` by floor (speed ramp, either side and turning back, lag spikes, wind, rush hour, faster) and the `STYLES` of the tower, the drawing (sky by height, blocks per style, Planny riding the top, the dashed marker of the highest floor) and the game contract with `pointer()` (a press on the board drops) and `release()` (a held up drops once, not at every key repeat, and `key(name, repeat)` ignores a repeat the window marks, so up held through the countdown never drops at its first repeat); a press waits for the first tick after a start or a play-on, so an arrow that resumes never also drops; a miss holds the round running for `OUTRO_MS` while the camera pulls back over the whole tower; memo is the highest floor ever reached, saved on a pause and at the end; a read-only `round` getter for the tests only |
|
||||
| `public/activities/bumper.js` | Bumper Ring: its rules and physics as plain exported functions (`newRound`, `newHeat`, `advance` on a fixed 4 ms sub-step over `round.input`, which `key()` and `release()` set, `push` (accel toward the held direction, capped at the top speed that way, drag easing a car to the floor's own speed), `collide` (circle bounce with restitution `BOUNCE`; the faster car rams and gives `SHOVE_BONUS` more, takes that much less back; under `IMPACT_SPEED` it is a lean, no bounce and no shove, so a pushing match goes to the stronger push), `dash`, `edgeGap` and `outOfRing` (a car is out when its center is past the edge or over an open hole; round or, in the Hall of Mirrors, square), `shrinkAt` and `nextShrinkIn` (whole for `SHRINK_START_MS`, `SHRINK_STEP` a step to `MIN_RING`, then after `SUDDEN_MS` sudden death to `LAST_RING`, under one car's radius, so every heat ends), `aim` (a rival's push, dash and target per personality, with panic near the edge and a sharpness-scaled chance to misjudge), `applyPower`, `spawnPad`, `creditKo` (the last toucher within `CREDIT_MS`, your hit carried through a rival counting as yours, and a rival you rammed into another keeping your credit, the carry lasting `CAROM_MS` from your hit; the combo, the double and the bait bonus), `rivalPower` and `arenaFor` (each built once per arena, since the rules ask every slice), `holeState`), the `ARENAS` (rivals, sharpness, shrink pace, then endless Finals past the ninth), the `RIVALS` personalities and the `POWERS` pads, and the game contract with `release()`; a rival winds a dash up for `WINDUP_MS` (shorter when sharper) before it goes, which is the player's moment to step aside; a big hit holds the action for `HIT_STOP_MS`; memo is the furthest arena reached, which can pass 9; a read-only `round` getter for the tests only. Hand-tuned from the brief's starting numbers (the changes are listed under "As built" in `game-ideas/bumper-ring.md`), aiming for heats of 20 to 60 s from arena 2 on |
|
||||
| `public/activities/bumper.js` | Bumper Ring: its rules and physics as plain exported functions (`newRound`, `newHeat`, `advance` on a fixed 4 ms sub-step over `round.input`, which `key()` and `release()` set, `push` (accel toward the held direction, capped at the top speed that way, drag easing a car to the floor's own speed), `collide` (circle bounce with restitution `BOUNCE`; the faster car rams and gives `SHOVE_BONUS` more, takes that much less back; under `IMPACT_SPEED` it is a lean, no bounce and no shove, so a pushing match goes to the stronger push), `dash`, `edgeGap` and `outOfRing` (a car is out when its center is past the edge or over an open hole; round or, in the Hall of Mirrors, square), `shrinkAt` and `nextShrinkIn` (whole for `SHRINK_START_MS`, `SHRINK_STEP` a step to `MIN_RING`, then after `SUDDEN_MS` sudden death to `LAST_RING`, under one car's radius, so every heat ends), `aim` (a rival's push, dash and target per personality, with panic near the edge and a sharpness-scaled chance to misjudge), `applyPower`, `spawnPad`, `creditKo` (the last toucher within `CREDIT_MS`, your hit carried through a rival counting as yours, and a rival you rammed into another keeping your credit, the carry lasting `CAROM_MS` from your hit; the combo, the double and the bait bonus), `rivalPower` and `arenaFor` (each built once per arena, since the rules ask every slice), `holeState`), the `ARENAS` (rivals, sharpness, shrink pace, then endless Finals past the ninth), the `RIVALS` personalities and the `POWERS` pads, and the game contract with `release()`; a rival winds a dash up for `WINDUP_MS` (shorter when sharper) before it goes, which is the player's moment to step aside; a big hit holds the action for `HIT_STOP_MS`; memo is the furthest arena reached, which can pass 9; a read-only `round` getter for the tests only. Hand-tuned from the brief's starting numbers, aiming for heats of 20 to 60 s from arena 2 on |
|
||||
| `public/activities/bumper-draw.js` | Bumper Ring's drawing: `drawScene(ctx, view)` from a plain view `bumper.js` builds (the round, the board geometry, the effects, the pill numbers), each arena's ring in its fixed palette (`themeFor`), the floor (ice, oil, holes, bumpers, the magnet, the warning bands), the cars (Planny upright at the wheel of a car in `--accent`, star eye and stick arms; rivals with a face each), the pills (laid out by `hudLayout`, which starts a row below rather than run into the ring's countdown or off the board), banners and the start and end strip, and `readColors(canvas)`; decides nothing |
|
||||
| `public/activities/rapids.js` | Rapids Run: its rules as plain exported functions over a round on a river scrolling down a 64 unit wide field, 84 units of it on the board (`newRound(seed)`, `newRiver(seed)`, `buildStretch(river, n, random)` (a stretch's rows from its own seed, each row a center, width and island width: a calm opening, then drifts, narrows and islands, every bank slanting at most `SLOPE` a unit, every channel at least `MIN_CHANNEL` wide, then a `BASIN_W` basin on a boss stretch and the narrowing to the `DAM_W` dam; and its plan of foes, buoys and crates, none in the first `SAFE_START` (where you start again) or by the dam), `ensureRiver`, `riverAt` (a row's banks and island eased from the row before's, so they slant as drawn), `channelsAt`, `channelAt`, `isWater`, `onLand` (the hull sampled at seven points), `placeAt` (the start of a stretch, its dam whole and its plan loaded afresh), `advance` in 4 ms slices over `round.input`, which `key()` and `release()` set: steering eased in, the whirlpools' tug, the speed held (up, down or neither, times the stretch's `pace`), the battery drained (`DRAIN` a second cruising, more at speed), distance points, the guns (`FIRE_MS`, Spread's fan), shots against foes, the boss, the dam and buoys, the foes (skiffs and darters drift and turn at the banks, a darter swerves into your lane, gulls take off as you near and swoop across, sentries fire at you), the boss (`spawnBoss` holds the river and the battery; its volleys by kind), bolts, pickups (a buoy `BUOY_CHARGE`, the magnet's pull, crates), crashes (`lose`: a shield takes any crash but a flat battery and slides you off a bank; blinking for `GRACE_MS` after a restart), skims (`SKIM_POINTS` each `SKIM_MS` closer than `SKIM_GAP` at speed), the dam (`hitDam`, then past it the next stretch, with `FLAWLESS_POINTS` times it for no life lost), `hurtFoe` (the combo, up to `MAX_COMBO`), `hurtBoss` (a life back and a crate), `applyPower`, `stretchFor` (built once a stretch; past the eighth, Night Water 2, 3 and on), `underBanner`, `screenY`, `seeded`), the `FOES`, `BOSSES`, `POWERS` and `STRETCHES`, and the game contract with `release()` (held arrows steer, speed and slow, held space fires; a pause lets go of every key); memo is the furthest dam blasted, which can pass 8; a read-only `round` getter for the tests only. Tuned by a scratch sim: a careful bot clears a stretch in 20 to 35 seconds, and the battery runs flat for one that grabs too few buoys |
|
||||
| `public/activities/rapids-draw.js` | Rapids Run's drawing: `drawScene(ctx, view)` from one view object `rapids.js` refills each frame, in field units: the strip above the field in the page's colors with the pills (laid out by `hudLayout`, which starts a second row rather than run off the board and centers its rows in the strip), the river a look at a time (`LOOKS`: meadow, autumn, canyon, marsh, dusk and night, each in fixed colors, the look changing at each dam): banded banks, the water between them with shore lines and flow streaks carried downstream by the view's clock, pointed islands, trees or rocks; the dam ahead (hazard stripes, a crack for every share knocked out, a trickle once it is close to going) and the broken one behind; charge buoys, crates with their glyphs, whirlpools, skiffs, darters, mines, bank sentries aiming at you and gull drones with their shadows; the mini-boss and its health bar; Planny's jet-skimmer in your highlight with a white trim (so a blue highlight still shows on blue water), his wake, jets, arms to the bars (up when a dam or a boss goes), his box and his star eye in your highlight, bobbing with the star spinning after a crash; shots, bolts, sparks, rings, floating words (kept on the field by `labelSpot`), the combo's big number, the battery gauge beside the field (green, amber, then red and blinking under the low mark), banners, and the start and end strip with the big final score and a dot per named stretch whose dam you have blasted; `readColors(canvas)`, `lookColor`, `inkOn`, `contrast`; decides nothing |
|
||||
| `public/activities/flock.js` | Flock Dash: its rules as plain exported functions over a round scrolling right to left over a 96 by 54 unit field (`newRound(seed)`, `steer` (the leader eased up and down inside the `BAND_MIN` to `BAND_MAX` band at the left), `recordPath`, `placeFlock`, `screenX`, `collect` and `spawnStrays` (a stray joins the flock, the combo up to `MAX_COMBO` within `COMBO_MS`), `buildStage(seed, n)` (a stage's hazards by distance from its own seed, a clear `SAFE_START` and `SAFE_END`, and `clearGap` keeping a way through), `moveHazards`, `hazardHits`, `snapAt` (a snap drops the birds behind the one hit, `scattered` for `SCATTER_MS` so they can be picked up again), `hitLeader` (a life, or a shield; `GRACE_MS` after), `reachPortal` (the jet stream portal, the V of `V_POINTS` a bird when the flock has `min`, `FLAWLESS_POINTS` for no snap or life lost, and the final portal that sways), `applyPower` (crates: tailwind, shield up to `MAX_SHIELDS`, magnet), `banner`, `bannerRow`, `underBanner`, `advance` in `SLICE_MS` slices, `teaser`, `seeded`, `dealMusic`), the `STAGES` table (eight stages, each with its speed, length, stray gap, portal `min`, hazard weights and gap; the place to tune the difficulty), the `HAZARDS` (balloon, gust, stream, cluster, storm, kite, each from its own stage) and `POWERS`, and the game contract with `release()` (held arrows steer, a pause lets go of every key); the round also carries `events` (what the draw and the sounds react to) and `warned` (one gust or storm warning each); memo is the furthest stage reached. The flock is a recorded path with running arc length: follower k sits `k * SPACING` behind the leader along it, so it copies every turn at any speed. `MUSIC_TRACKS` names the five songs, dealt afresh each round |
|
||||
| `public/activities/flock-draw.js` | Flock Dash's drawing: `drawScene(ctx, view)` and `hudLayout` from one view object `flock.js` refills each frame, in field units: the sunset sky (`SKIES`, one palette per stage: the sun sinking, clouds, a rim light from stage 6 and stars on the last), the hazards (balloons and bunches, the head-wind's warning band and gust, slipstreams, thunderheads with their flash and bolt, kites on their strings), the strays and scattered birds, the flock, Planny as the lead bird with a star for an eye, crates and the magnet ring, the tailwind streaks, the portal and the V, the pills (laid out by `hudLayout`, which shrinks them to fit the board), banners, and the end strip with the final score, the best and the teaser; `readColors(canvas)`; decides nothing |
|
||||
| `public/activities/fuse.js` | Hot Potato: its rules as plain exported functions over a round on a 104 by 70 arena (`newRound`, `newMatch(round, venue)`, which lights each bomb on a rival, never you, in a match's first fuse, `advance` in 8 ms slices over `round.input`, which `key()` and `release()` set, `move` (speed eased toward the held direction at `GRIP`, a dash holding its line, belts and ice from the floor), `dash` (a holder's dash is a numbered lunge), `tag` (a holder touching a runner with no bomb passes it, never inside `NO_TAGBACK_MS` of the bomb changing hands, nor back to the one who just passed it within `TAGBACK_MS` while three or more are left, `tagBack`, with `tagSafe` saying who is safe that way for the drawing; a fuse under `PASS_FLOOR_MS`, `NO_TAGBACK_MS` plus `PASS_REACT_MS`, is raised to it on any pass, once a fuse for each runner (`bomb.lifted`); your pass scores, a hot one under `HOT_MS` as passed steps the streak), `burn` (Freeze takes its share first), `blast` (the holder out, everyone near knocked back, the match over when that was you or one is left), `nextFuse` (a survivor with no bomb, the next shorter fuse from `fuseFor`, never more bombs than one for every two left), `think` (a holder chases by its own flood-fill path, weighted toward a boxed-in or dashless target; a runner without a bomb scores candidate spots by the holders' path distance against its own and flees to the best; personalities bend both), `applyPower`, `spawnPickup`, `speedOf`, `clearLine`, `rivalPower` and `venueFor` (each built once per venue), `rivalColors(you)`), the `VENUES`, `LAYOUTS`, `RIVALS` and `POWERS`, and the game contract with `release()` (`key(name, repeat)` never dashes on a repeat); a rival holder winds up (`WINDUP_MS`, shorter when sharp) or, a Trickster, feints (`FAKE_MS`) before a lunge, and a runner a lunge comes at dodges once a lunge at its venue's odds after its reaction time; the fuse ticks quicker and higher as it burns down, on one clock however many bombs burn (yours, else the shortest); a bomb whose fuse has run out passes to nobody; memo is the furthest venue reached, which can pass 9; a read-only `round` getter for the tests only. Tuned by a scratch sim (see "As built" in `game-ideas/hot-potato.md`) |
|
||||
| `public/activities/fuse.js` | Hot Potato: its rules as plain exported functions over a round on a 104 by 70 arena (`newRound`, `newMatch(round, venue)`, which lights each bomb on a rival, never you, in a match's first fuse, `advance` in 8 ms slices over `round.input`, which `key()` and `release()` set, `move` (speed eased toward the held direction at `GRIP`, a dash holding its line, belts and ice from the floor), `dash` (a holder's dash is a numbered lunge), `tag` (a holder touching a runner with no bomb passes it, never inside `NO_TAGBACK_MS` of the bomb changing hands, nor back to the one who just passed it within `TAGBACK_MS` while three or more are left, `tagBack`, with `tagSafe` saying who is safe that way for the drawing; a fuse under `PASS_FLOOR_MS`, `NO_TAGBACK_MS` plus `PASS_REACT_MS`, is raised to it on any pass, once a fuse for each runner (`bomb.lifted`); your pass scores, a hot one under `HOT_MS` as passed steps the streak), `burn` (Freeze takes its share first), `blast` (the holder out, everyone near knocked back, the match over when that was you or one is left), `nextFuse` (a survivor with no bomb, the next shorter fuse from `fuseFor`, never more bombs than one for every two left), `think` (a holder chases by its own flood-fill path, weighted toward a boxed-in or dashless target; a runner without a bomb scores candidate spots by the holders' path distance against its own and flees to the best; personalities bend both), `applyPower`, `spawnPickup`, `speedOf`, `clearLine`, `rivalPower` and `venueFor` (each built once per venue), `rivalColors(you)`), the `VENUES`, `LAYOUTS`, `RIVALS` and `POWERS`, and the game contract with `release()` (`key(name, repeat)` never dashes on a repeat); a rival holder winds up (`WINDUP_MS`, shorter when sharp) or, a Trickster, feints (`FAKE_MS`) before a lunge, and a runner a lunge comes at dodges once a lunge at its venue's odds after its reaction time; the fuse ticks quicker and higher as it burns down, on one clock however many bombs burn (yours, else the shortest); a bomb whose fuse has run out passes to nobody; memo is the furthest venue reached, which can pass 9; a read-only `round` getter for the tests only. Tuned by a scratch sim |
|
||||
| `public/activities/fuse-draw.js` | Hot Potato's drawing: `drawScene(ctx, view)` from one view object `fuse.js` refills each frame, in arena units: the strip above the arena in the page's colors with the pills (laid out by `hudLayout`, which starts a second row rather than run into the fuse and centers its rows in the strip), each venue's floor in its fixed palette (`themeFor`, `venueColor`), ice, running belts, the Rooftop's open edge, the things to run round, pickups, the runners (Planny on his feet with his star eye and stick arms, flailing while he holds a bomb, and still Planny when charred; arms and feet on the floor in `limbInk(level)`, the ink that stands out from that venue's tiles; rivals with a mark per personality; a white ring with a dark edge at the feet of a runner safe from a tag-back; the charred waddle to the nearest wall and the fall from the roof), the bomb over its holder (a red ball with a `<<<` band, growing and glowing as it burns, flashing white while it cannot be passed, its fuse a shortening curl with a spark, the last seconds in big numbers (under the holder's feet when there is no room above, `countY`), a hop across on a pass), blast clouds, the Blackout's dark worked out once a frame in cells, the red edge pulse in a fuse's last second, banners and the start and end strip with the big final score, and `readColors(canvas)`; decides nothing |
|
||||
| `public/activities/hop.js` | Crossing Rush: its rules as plain exported functions over a round on a strip `COLS` (11) cells wide of 30 to 40 lanes, `VIEW_ROWS` (14) on the board at once (`newRound`, `newHeat(round, zone)`, which builds the heat's lanes from the round's seed, kept when a heat runs again, `buildLanes(zone, seed)` (groups of road, highway, ice, river, turtle, rapids or rail lanes with a grass row between each two, the zone's new thing first; the same seed builds the same lanes), `advance` in 8 ms slices (lanes flow, riders drift with their log, rivals choose, everyone is checked where they stand before any hop moves on, then hops and flights; hoppers home in the same slice finish by the moment each landed, a dead heat to you), `hop(round, hopper, dir)` (one cell, two with a Spring; a hopper counts in the cell it leaves for the first half and the one it lands on for the second; an icy lane slides it a cell more), `laneAt`, `occupied(round, row, col, atMs)` (a car or a train on it, or in a river no float or the edge, `atMs` ahead through `shiftAt`, which follows a lane's flips, surges and a Horn exactly), `sendBack` (to the last grass row, `safeBelow`, crediting a shove within `SHOVE_CREDIT_MS`), `shove(round, from, to)` (a cell the way `from` faces, only on a hopper `inReach` and never on one past the half of its hop home, once every `SHOVE_MS`), `plan(round, hopper, random, power)` (a look ahead of `LOOKAHEAD` to `LOOKAHEAD_SHARP` hops over the lanes as they will move, each hop followed by the hopper's wait where it lands; never a hop where it would be hit or fall in at full sharpness; a sloppy rival now and then hops on regardless), `applyPower`, `zoneFor` and `rivalPower` (each built once per zone), `rivalColors(you)`, `standings`), the `ZONES`, `RIVALS` and `POWERS`, and the game contract with `release()` (`key(name, repeat)` hops once a press: never on a repeat, never again until the arrow is let go, never with the press that plays on, and with one hop queued behind the one in the air; a pause drops what is held and the queue); rivals wait `REACT_MS` down to a sharp rival's after each landing, a Bruiser shoves anyone beside it into a lane, a Tagalong follows a row behind you and shoves near the top, and a rival that lets a shove go weighs the next one only after `SHOVE_LOOK_MS`; memo is the furthest zone reached, which can pass 9; a read-only `round` getter for the tests only. Tuned by a scratch sim (see "As built" in `game-ideas/crossing-rush.md`) |
|
||||
| `public/activities/hop.js` | Crossing Rush: its rules as plain exported functions over a round on a strip `COLS` (11) cells wide of 30 to 40 lanes, `VIEW_ROWS` (14) on the board at once (`newRound`, `newHeat(round, zone)`, which builds the heat's lanes from the round's seed, kept when a heat runs again, `buildLanes(zone, seed)` (groups of road, highway, ice, river, turtle, rapids or rail lanes with a grass row between each two, the zone's new thing first; the same seed builds the same lanes), `advance` in 8 ms slices (lanes flow, riders drift with their log, rivals choose, everyone is checked where they stand before any hop moves on, then hops and flights; hoppers home in the same slice finish by the moment each landed, a dead heat to you), `hop(round, hopper, dir)` (one cell, two with a Spring; a hopper counts in the cell it leaves for the first half and the one it lands on for the second; an icy lane slides it a cell more), `laneAt`, `occupied(round, row, col, atMs)` (a car or a train on it, or in a river no float or the edge, `atMs` ahead through `shiftAt`, which follows a lane's flips, surges and a Horn exactly), `sendBack` (to the last grass row, `safeBelow`, crediting a shove within `SHOVE_CREDIT_MS`), `shove(round, from, to)` (a cell the way `from` faces, only on a hopper `inReach` and never on one past the half of its hop home, once every `SHOVE_MS`), `plan(round, hopper, random, power)` (a look ahead of `LOOKAHEAD` to `LOOKAHEAD_SHARP` hops over the lanes as they will move, each hop followed by the hopper's wait where it lands; never a hop where it would be hit or fall in at full sharpness; a sloppy rival now and then hops on regardless), `applyPower`, `zoneFor` and `rivalPower` (each built once per zone), `rivalColors(you)`, `standings`), the `ZONES`, `RIVALS` and `POWERS`, and the game contract with `release()` (`key(name, repeat)` hops once a press: never on a repeat, never again until the arrow is let go, never with the press that plays on, and with one hop queued behind the one in the air; a pause drops what is held and the queue); rivals wait `REACT_MS` down to a sharp rival's after each landing, a Bruiser shoves anyone beside it into a lane, a Tagalong follows a row behind you and shoves near the top, and a rival that lets a shove go weighs the next one only after `SHOVE_LOOK_MS`; memo is the furthest zone reached, which can pass 9; a read-only `round` getter for the tests only. Tuned by a scratch sim |
|
||||
| `public/activities/hop-draw.js` | Crossing Rush's drawing: `drawScene(ctx, view)` from one view object `hop.js` refills each frame, in board units: the strip above the field in the page's colors with the pills (laid out by `hudLayout`, which starts a second row rather than run into your place and centers its rows in the strip), the lanes in fixed colors (`LANES`, `lookOf`; pavement, grass with tufts, bushes and rocks, the checkered finish, roads with dashes and surge chevrons, icy roads, rivers with ripples and Rapids arrows, tracks with a signal that flashes while a train is coming), cars, vans, trucks, logs, turtles that sink and dive, the train, pickups, the hoppers (Planny on his stick feet with his star eye in every state: stretching mid-hop, spinning as he flies back, cheering, slumped when beaten; rival critters with a Hopper's ears, a Daredevil's goggles, a Bruiser's brow and a Tagalong's beak; arms and feet, and each rival's body edge, in `limbInk(look)`, the ink that stands out from that lane), a Shield's ring and a Spring's coil, staggered stars, arrows at the edge for hoppers out of view, the Night Market's dark (soft lights cut from a layer the size of the field with one gradient made with the layer, or in steps with no second canvas), the race bar in the page's colors, banners, and the start and end strip with the big final score; every word kept on the field by `labelSpot`, and `readColors(canvas)`, `zoneColor`; decides nothing |
|
||||
| `public/activities/bounce.js` | Bounce Road: the cars, the hazards against them, the scoring and the round, as plain exported functions over a round on a road scrolling up a 72 unit wide field, 90 units of it on the board (it re-exports every rule of `bounce-road.js` and `bounce-rivals.js`, so the suite imports one module): `newRound(seed, random)`, `advance` in 4 ms slices over `round.input`, which `key()` and `release()` set (a jump press first, then your `move`, the rivals' `think` and `move`, the pads (a boost strip pushes you to `NITRO_TOP` for `BOOST_MS` even off the throttle, and the brake cuts it; a ramp launches any car crossing its lip quick enough `RAMP_AIR` the usual jump; a slick eases the steering at `SLICK_EASE` and makes a knock last for `SLICK_MS`), the bumps (`collide`: boxes pushed apart along the shallower overlap, side on a knock split by mass and harder for the car that did not steer in, end on speed passed forward, into a `HEAVY` truck's back at `CRASH_CLOSE` a crash; with Mega wheels a touch flattens; a close shave, `NEAR_GAP` or less between the boxes at speed and no touch, scores once), the barriers (a cone or a tire knocked flying slows you to `CONE_SLOW`; a block, pot or bucket nose first is a crash, from the side a push out), the hazards placed by the round's clock (a train hits a car on its track, a ball knocks a car by `BALL_KICK`, a sprinkler's jet pushes at `SPRAY_PUSH`, a drop falls `DROP_FALL_MS` after you come within `DROP_TRIGGER`, aimed at your line, and lies there after, a gust pushes at `WIND_PUSH`), then the ground (water or a hole under your middle a life, a flowerbed nose first a crash, a rival off the road out and yours within `CREDIT_MS`)), `jump`, `land` (on a car: flattened for its `points` times the chain up to `MAX_CHAIN`, a truck's roof `HAUL_POINTS`, the Monster a stomp, `STOMP_POINTS`, and on its last of `BOSS_HP` `BOSS_POINTS` times the lap and a life; on the road the chain ends, and the holes, trains, balls and barriers flown over and a ramp's big air score), `stunt` (a stunt's points times `comboOf(streak)`: every `COMBO_STEP` stunts within `STREAK_MS` of each other one more, up to `MAX_COMBO`), `lose` (a Bubble throws you clear instead), `applyPower`, `underBanner(round, y, cam)` (a rival, a coming train, a ball or a thing still falling in the strip) and `BANNER_Y`, `rivalColors(you)`), the `POWERS` (Spring, Bubble, Nitro, Mega wheels) and the game contract with `release()` (`key(name, repeat)`: held arrows drive and steer, space jumps once a press, never on a repeat or with the press that plays on, and a press up to `JUMP_BUFFER_MS` before a landing jumps on it; a pause lets go of every key and drops a press). A stage line scores `STAGE_POINTS` times the stage, `TIME_POINTS` a second under its par and, flawless, `FLAWLESS_POINTS` and a life back up to `MAX_LIVES`. Memo is the furthest stage reached, which can pass 10. A read-only `round` getter is for the tests only. Tuned by scratch bots: a careful bot clears all ten stages with no rivals on every seed tried (23 to 42 s a stage), and a bot with 150 ms reactions and 80 ms jump timing error reaches a median of stage 5 with the rivals out, stage 10 without |
|
||||
| `public/activities/bounce-draw.js` | Bounce Road's drawing: `drawScene(ctx, view)` from one view object `bounce.js` refills each frame, in field units: the strip above the field in the page's colors with the pills (laid out by `hudLayout`: stage, lives, Spring, Bubble, Nitro and Mega with their timers, the chain and the combo with its timer; a pill that would run off the board starts a second row), the road a chunk of `CHUNK_ROWS` rows at a time, drawn off screen once per road and scale, a few kept and copied each frame (rows from `bounce-scenery.js`), the layers over it (`bounce-scenery.js`), the landing rings (yours in your highlight, a rival's in red, the Monster's its own size), the cars through `bounce-cars.js` (every shadow first, upright, then every body with its tumble: Planny in your highlight with his box in the page's panel color and his star eye, arms to the wheel, up in the air or cheering, down at the end; each rival kind in its own style and color, the Cop's siren while it chases, the Monster's dents and a star per life left above it, headlights at Night Lights), sparks, rings, the dark of Night Lights, the chain's big number, the stage bar beside the field, banners, and the start and end strip with the big final score and a dot per stage reached; every word kept on the field by `labelSpot`, and `readColors(canvas)`, `limbInk`, `inkOn`; decides nothing |
|
||||
| `public/activities/bounce-cars.js` | Bounce Road's cars, drawing only and no imports: `drawCarBody(ctx, style, opts)` draws one top-down toy car about the origin, nose up, filling `w` by `h` field units exactly (tires on the box's corners), in one of `CAR_STYLES` (`STYLE_NAMES`: Planny's convertible with his star eye and arms to the wheel, hatch, sedan, coupe, muscle, pickup, van, box truck, police, racer, taxi, jeep, monster) with flat-fill shading worked out from `color` and `accent` (`shade`, `rgbOf`), and options for roll (`tilt`), a jump (`air`: it draws the shadow and the lift itself), a pancake (`squash`), night beams, a siren bar, damage, a boost flame and brake lights, all moving parts on `opts.clock`; `drawCarShadow` and `shadow: false` for a shadows-first pass in screen space; `carLength(style, w)` for a style's natural length and `carReach(style, opts)` (with `MARGINS`) for what reaches outside the box |
|
||||
| `public/activities/bounce-scenery.js` | Bounce Road's scenery, drawing only: each stage's look in fixed colors (`LOOKS`: patio slabs, lawn stripes, kitchen tiles, garden, sand, a toy room's rug, a pond with lily pads, roof shingles, the night lawn with lamps and the Monster's dirt; `lookOf`, `stageColor`, `contrast`, `better`), `drawRow` (one row of the road in three passes over a chunk: the yard, the road's surface, the details: edges slanting from row to row, rivers, plank bridges with jagged broken ends, cracks, flowerbeds, rails across a crossing, cracked road over a pit, checkered stage lines, verge decor), and the layers drawn fresh each frame from the round's clock: `drawTimed` (a drawbridge lifting with its red lights, a swaying bridge where it is now, crumbled road gone to the pit), `drawPads` (running boost chevrons, ramps, slicks), `drawBlocks` (cones, toy blocks, pots, buckets, acorns and tires, knocked ones tumbling off), `drawStars`, `drawSigns` (a mark per hazard), `drawItems`, `drawHazardsLow` (crossing lights, the train, a rolling ball, a falling thing's growing shadow, a sprinkler's head), `drawHazardsHigh` (the jet, gust streaks, the thing still falling), `drawNight` and `drawFireflies`; decides nothing |
|
||||
| `public/activities/bounce-road.js` | Bounce Road's road, rules only: the jump math every hole is sized by (`airMs(v)`, `reach(v)`, `LONGEST_JUMP`, `JUMP_FAIR`, `TOP_SPEED`, `MAX_SPEED`), `stageFor(n)` (built once a stage: the ten of `bounce-roads.js`, then laps from `LAP_FROM`, quicker, keener, busier, the Monster at every Monster Mash) and `stageName`, `newRoad(seed)` and `buildStage(road, n, random)` (a stage's rows from its own seed, by the stage's piece weights: straights, cracks, rivers on bridges with one or two broken spans or a drawbridge, splits round flowerbeds, ramps before a crack with stars beyond, cone or block chicanes, crumbling road, train crossings, swaying bridges, boost strips, slicks, balls, sprinklers, drops and gusts; every hole after a `RUNUP` with a sign and no longer than `MAX_HOLE`, the bridge between two breaks long enough to land `LONGEST_JUMP` on), `ensureRoad`, `groundAt(road, x, d, t)` (a row's edges eased from the row before's; a drawbridge water while lifted, a swaying bridge shifted, crumbled road a hole), `rowGone`, `spanAt`, `holesIn`, `firstAt`, `plainRow`, `safeSpot` (no hole, water, timed part or rails for `RESPAWN_RUN` ahead), and where each timed thing is at a moment: `swayOff`, `drawLift`, `crumbleAt` (falling away `CRUMBLE_DELAY` after you reach it, at `CRUMBLE_SPEED`, under a fair speed), `trainAt` (on, and lit `TRAIN_WARN_MS` before), `ballX`, `sprayAt`, `gustAt`; plus `seeded`, `GROUND`, `MARK`, `SPAN` |
|
||||
| `public/activities/bounce-rivals.js` | Bounce Road's rivals, rules only: `RIVALS` (the Zigzag, Brick, Frog, Nudge, Hauler, Sneak, Bruiser, Racer, Cop and Monster: box, mass, speed, points, how readily each dodges, how often each comes, its car style and whether it comes from behind), `makeCar`, `think(round, car, ms, random)` (each kind's choice of speed and line: the Zigzag's weave, into your path when you follow; the Brick holding your lane and brake-checking from in front, then resting `BRAKE_REST_MS` or more; the Frog's hops toward you; the Nudge's chase and up to 1 + 2 times the stage's `sharp` swipes; the Hauler drifting to block; the Sneak dropping up to `SNEAK_DROPS` cones while you follow; the Bruiser slamming you within `BRUISER_RANGE`; the Racer passing then fleeing; the Cop sitting on your roomier side and leaning in to push you to the near edge for `COP_MS`, never on a bridge or by the water (`nearWater`), nor the Bruiser; the Monster keeping `BOSS_AHEAD` in front, hopping every `BOSS_HOP_MS` to come down where you will be and dropping tires; every rival rubber-banded to stay near you, swerving from under your landing as sharply as its stage allows, keeping to the narrowest road just ahead and the band a swaying bridge always covers, holding a slower car's speed, and hopping any hole, drawbridge, barrier or coming train, or flying off a ramp), `spawnRival`, `pickKind` (one of each special kind at a time), `HEAVY`, `RIVAL_MIN_SPEED` |
|
||||
| `public/activities/bounce-roads.js` | Bounce Road's ten stages as data (no imports): `FIELD_W`, `FIELD_H`, `ROW`, `MAX_HOLE`, `LAP_FROM`, and per stage its length, par time, road widths, piece weights (straights, holes, rivers, splits, ramps, chicanes, crumbling road, trains, swaying bridges, boost strips, slicks, balls, sprinklers, drops, gusts), crack and broken span lengths, bridge widths and shares of broken, double and drawbridge spans, flowerbed sizes, barrier and drop kinds, the rivals' count, kinds, pace and sharpness, power-ups, stars, and whether the Monster comes |
|
||||
| `public/activities/pills.js` | The pills every game but Mini golf draws along its top (no imports): `drawPill(ctx, x, y, w, h, text, color, fill, textY)` on one opaque dark backing, `PILL`, the same in light and dark and over any scene, a timer's share still left tinted at `PILL_TINT`, and the text in `pillInk(color, tinted)`: the pill's own color when it reads at `PILL_CONTRAST` (4.5:1) on the backing (and on the tint while a timer runs), else the least step toward white that does, so warnings stay red; lives are the one solid pill: a pill in the `LIVES` color is drawn on `LIVES_BACK` in white (`LIVES_INK`), its text from `livesText(n)` (a heart per life up to five, `♥ xN` past that, `♡` at none); `pillTint` and `pillContrast` for the unit suite |
|
||||
| `public/activities/golf.js` | Mini golf: six eighteen-hole courses, one round at a time; its rules and physics as plain exported functions (`newRound(courseId)`, `holesOf`, `coursePar`, `strike`, `advance` on a fixed 4 ms sub-step, `nextHole`, `total`, `toPar`, `predictPath` for the spyglass, `moverAt`, `gateShut`, plus ice that barely slows the ball and wells that pull it in or push it away), the `POWERUPS` held for the next putt (`round.held`, then `round.active` for that putt), the arcade swing (`startSwing`, `setPower`, `meterAt`, `meterZone`, `swingShot`: a ping-pong power meter, slow at the bottom and fast at the top, with a MAX band that boosts and an overswing band that shanks; a shot clock in `advance()` that starts the meter after `SHOT_CLOCK_MS` and dribbles the ball after `METER_TRIPS` trips; all on the round's own clock), the pop-up gags, and the game contract with `pointer()` (the aim follows the pointer, a press swings, a press held on a roll fast-forwards), `release()` (held arrows turn the aim, held space fast-forwards) and `lowerIsBetter`, `courses` (the dashboard's cards), `preview(canvas, id, w, h)` (a course's card art) and `setCourse(id)`; deterministic (no `Math.random()`), a read-only `round` getter for the unit suite only |
|
||||
| `public/activities/golf-draw.js` | Mini golf's drawing: `drawCourse(ctx, view)` from a plain view `golf.js` builds, each hole in its theme's fixed palette (`pirate`, `cave` with its darkness and glows, or a newer course's look from `golf-looks.js`, asked first for its grounds, water, tunnels, gates and wells), ice, the scorecard and banners in the course's voice, a bare view for the dashboard's card art, `knownGround`/`knownLiquid` for the unit suite, and `readColors(canvas)`, which reads the `--golf-*` properties `styles/activities.css` mixes from the tokens for the ball, pills and scorecard; decides nothing |
|
||||
@@ -47,16 +40,18 @@ One row per file of every game but Ghoul Rush (which has its own files: [core](.
|
||||
| `public/activities/golf-look-frost.js` | How Frosty Peaks is drawn: its palette, ground, water, props and scenery; drawing only, moving with the round's clock |
|
||||
| `public/activities/golf-paint.js` | Mini golf's shared canvas helpers (`polygon`, `circle`, `ellipse`, `radial`, `fill`, `stroke`, `line`, `label`, `turned`, `t`, `scatter`, `bounds`), no imports, so the drawing files and the looks share them without import loops |
|
||||
| `public/tones.js` | the activities' sound engine, all synthesized in the browser. Three parts: a shared kit of rich one-shot sounds (`RICH`: `layers` of parts played together, each a wave or a noise (`noise`, `pink`, `brown`) with its own `delay`, `gain`, `attack`, a sweeping `filter` and `vibrato`: `explode`, `smash`, `skid`, `whoosh`, `splashBig`, `fanfare`, `gameOver` and some fifty more, up to 1.2 s, at most `MAX_VOICES` parts sounding at once), held **hums** (`hum(id, name, level, pitch)`, called every frame a game wants it: oscillators and noise through one filter that follows the pitch, pulsed for an engine's strokes; a hum not asked for within `HUM_HOLD_MS` fades by itself, so a paused or closed game goes quiet without saying so, `hushTones()` quiets every one and the Activities window calls it whenever it stops ticking; at most `MAX_HUMS`; shared ones `car`, `toycar`, `electric`, `outboard`, `river`, `wind`, `cycle`, `fuse`, `haunt`, `squeal`, `meter`, `swarm`, `train`, `crowd`), and each game's own extras in `public/activities/<id>-sfx.js` (`{ tones, hums }`, plain objects, names prefixed with the game id, merged and frozen here; a name may be defined once across all of them, which `scripts/test-web-console-tones.mjs` checks along with every spec's shape and every name a game's source asks for). Everything plays through one compressor. The older single blips (`BLIPS`): `tone(name, level, pitch)` with an optional loudness from 0 to 1 and an optional pitch that scales every frequency, kept between 0.25 and 4, and an optional fourth `louder` (a game lifting its sounds as a whole, up to `LOUDER_MAX`, also the fifth argument of `hum()`), `unlockTones()`; Snake's blips plus golf's `putt`, `wall`, `bump`, `cup`, `ace` (a three-note rise), `splash`, `power` (a power-up, three notes), `tunnel`, `boom` (a cannon putt), `sizzle` (lava) and `fall` (the pit), the countdown's `count` and `go`, Stack Deploy's `thunk`, `slice` and `perfect`, which it pitches up a scale step for each perfect in a row, and Bumper Ring's `ram`, pitched and leveled by how hard the hit, and `rev`, a rival winding up a dash, and Hot Potato's `tick`, the fuse, which it ticks quicker and pitches higher as the fuse burns down, and `pop`, a pass, and Crossing Rush's `hop`, which it pitches up a step for each quick hop forward in a row, `boing`, a send-back, `bell`, a train coming, and `horn`, and Bounce Road's `engine`, a soft low triangle hum it plays every few frames while you pick up speed (quiet once you cruise or coast), pitched up with your speed, `spring`, a jump, pitched with your speed, and `squash`, a rival flattened, pitched up a step for each in a chain, and `beat`, a low thump while your wheels run on the verge (it borrows the other games' blips for its hazards and rivals), and Rapids Run's `pew` (a shot, a short soft triangle played quietly about seven times a second while fire is held), `charge` (a buoy taken), `lowcell` (the low battery's two-note beep, quicker the lower it runs), `dambreak` (a dam bursting) and `skim` (a bank skimmed at speed, pitched up the more you have skimmed), and Ghoul Rush's `ghoulBlast` (the blaster's bolt, a short soft triangle repeated while fire is held), `zombiePop` (a kill, pitched up a step for each in the chain), `ghoulStomp`, `ghoulBoo`, `ghoulRoar` and `zombieGroan` (now kept for the other games and the tests: Ghoul Rush's monsters speak with their own voices from `ghoul-sfx.js`), `ghoulCandy` (pitched up for candy in quick succession), `batSwoop` (a bat's kill), `doorUnlock` (the key), `doorThrough` (the door to the next room) and `creakBoard` (a crawler coming up, a chandelier or a crumbling board about to go), all soft triangles and sines), silent while Play sounds is off; separate from `sound.js`'s cue queue |
|
||||
| `public/music.js` | the games' chiptune music: a small sequencer over `tones.js`'s context and compressor (`audioOut()`). A game calls `music(name, intensity)` from its `tick`; the track fades out within `MUSIC_HOLD_MS` once it stops being asked for, picks up again on the bar it left, asking for a different track crossfades the two over `CROSSFADE_S` (the old one keeps playing as it fades, so a new level is not a cut), and `hushMusic()` stops it at once. Tracks are note data under `music` in each game's `activities/<id>-sfx.js` (`{ bpm, rush, bar, voices, patterns, order }`, `bar` the steps in a bar when it is not 16, so the track resumes on a bar start and each pattern is whole bars: pulse, triangle and noise-drum voices, each joining once the intensity reaches its `from`; a step a token, `A4`, `-` to hold, `.` a rest, `A3^037` an arpeggio, drums `k s h o`), read by `compileTrack()` and booked `LOOKAHEAD_S` ahead on the audio clock. It also plays recorded **songs**: mp3s a game names under `songs` in its sfx file (a name to a served path, merged by `tones.js` as `SONG_TABLES`, listed by `songNames()`), asked for the same way, one `<audio>` element each made on first use, at `SONG_PEAK` times the volume, faded over `SONG_FADE_MS`; a song plays once, never looped, `music()` returning `"playing"` or `"ended"` (which the window's wrapper passes back to the game), `{ restart: true }` taking it back to the top with `load()` (no seeking, since the server sends no byte ranges), and a song no longer asked for fades and pauses where it was. The window plays it only while Play sounds, Play game sounds and Play game music (`looks.gameMusic`, off by default) are all on |
|
||||
| `public/music.js` | the games' chiptune music: a small sequencer over `tones.js`'s context and compressor (`audioOut()`). A game calls `music(name, intensity)` from its `tick`; the track fades out within `MUSIC_HOLD_MS` once it stops being asked for, picks up again on the bar it left, asking for a different track crossfades the two over `CROSSFADE_S` (the old one keeps playing as it fades, so a new level is not a cut), and `hushMusic()` stops it at once. A track loops while asked for, and `music()` returns `"playing"`, then `"ended"` once it has run through to its last bar (Bounce Road's cue to ask for the next of its twenty), with `{ restart: true }` starting it from its top. Tracks are note data under `music` in each game's `activities/<id>-sfx.js` (`{ bpm, rush, bar, voices, patterns, order }`, `bar` the steps in a bar when it is not 16, so the track resumes on a bar start and each pattern is whole bars: pulse, triangle and noise-drum voices, each joining once the intensity reaches its `from`; a step a token, `A4`, `-` to hold, `.` a rest, `A3^037` an arpeggio, drums `k s h o`), read by `compileTrack()` and booked `LOOKAHEAD_S` ahead on the audio clock. It also plays recorded **songs**: mp3s a game names under `songs` in its sfx file (a name to a served path, merged by `tones.js` as `SONG_TABLES`, listed by `songNames()`), asked for the same way, one `<audio>` element each made on first use, at `SONG_PEAK` times the volume, faded over `SONG_FADE_MS`; a song plays once, never looped, `music()` returning `"playing"` or `"ended"` (which the window's wrapper passes back to the game), `{ restart: true }` taking it back to the top with `load()` (no seeking, since the server sends no byte ranges), and a song no longer asked for fades and pauses where it was. The window plays it only while Play sounds, Play game sounds and Play game music (`looks.gameMusic`, off by default) are all on |
|
||||
| `public/activities/<game>-sfx.js` | each game's own sound effects (`bounce`, `bugs`, `bumper`, `drive`, `flock`, `fuse`, `golf`, `hop`, `rapids`, `snake`, `stack`, `trails`): `tones` (one-shots played with `tone(name, level, pitch)`) and `hums` (held sounds kept going with `hum(id, name, level, pitch)`), merged into `tones.js` beside the shared kit; definitions only |
|
||||
| `public/activities/snake-music.js` | Snake's ten music tracks as data (no imports): `SNAKE_MUSIC`, `{ bpm, rush, voices, patterns, order }` each, named `snake<Place>` and listed in `MUSIC_TRACKS` in `snake.js`. A round deals them in a fresh order, one to each level, so a run hears a different track at every level and none twice. They were picked on the pages in `prototypes/music/snake` (rhythm-first folk and world tunes led by something plucked or reedy, mostly dark or modal), and their bars are not all sixteen steps: 6/8 is 12, 7/8 is 14, ten beats is 20, twelve beats is 24, each pattern a whole number of its bars; merged by `snake-sfx.js` |
|
||||
| `public/activities/light-trails/1.mp3` to `5.mp3` | Light Trails' five background songs, named `trailsSong1` to `trailsSong5` under `songs` in `trails-sfx.js` and listed in `SERVABLE`; re-encoded for size with ffmpeg (80 kbps stereo MP3 at 44.1 kHz, loudness-normalized to -16 LUFS with `loudnorm`, metadata stripped), about 7.6 MB together, and copied into every skill with the rest of the console. The server leaves them out of its start-up cache warm |
|
||||
| `public/activities/flock-dash/1.mp3` to `5.mp3` | Flock Dash's five background songs, named `flockSong1` to `flockSong5` under `songs` in `flock-sfx.js` and listed in `SERVABLE`; re-encoded for size with ffmpeg the way Light Trails' were (80 kbps stereo MP3 at 44.1 kHz, loudness-normalized to -16 LUFS with `loudnorm`, metadata stripped), about 6.4 MB together, and copied into every skill with the rest of the console. The server leaves them out of its start-up cache warm; `flock.js` deals all five in a fresh order each round with `dealMusic()`, plays each in full one after another and deals again after the last, never opening on the song that just ended |
|
||||
| `public/screens/activities.js` | Activities: `#btn-activities` (the die right of the megaphone), `#activities-modal`, the one frame timer (`requestAnimationFrame`, swappable with `setTickSource()` for the page tests), the keys (arrows, W/A/S/D, space, P, Esc; stopped at the dialog so none reach the page behind; `CHEAT_CODE`, typed on a game's board, turns on endless lives through the game's `cheat(on)` until the round starts over, and `dropCheats()` turns it off on leaving for the picker or closing; `STAGE_CODE`, the same arrows then S, calls the game's `stageSelect()` where it has one, Ghoul Rush's practice stage select) and `pauseAll()`, which a new question, a finish, a hidden page, a window blur and a close all go through and which never resumes a game (it also sends a pointer game a cancel, dropping a drag). Canvas pointer events (down, move, up, cancel, with pointer capture) go to a game with `pointer()`, and key releases to a game with `release()`; a press on a paused board resumes without starting a drag. While paused, any game key or a board click resumes, except while a round is `held`: a question or finish that pauses a round on an open window holds it, the banner adds `#activities-unpause` (**Unpause game**) beside **Go to it**, and only that button plays on (`play()` refuses a held round), since a key or click already on its way used to dismiss the banner unread. Go to it, or closing the window any other way, lets the hold go, and a banner with nothing left to say drops it. Every start and play-on first counts down 3, 2, 1 (`COUNT_FROM`, 700 ms a number, `setCountdownMs()` for the page tests, which set 0 unless they test it): the game is already `running`, the frame timer just does not tick it, and game keys, overlay clicks and board presses wait, while P and Esc still pause. With two or more games listed the window opens on the picker (`view`: `"picker"` or `"game"`, `applyView()`): a card button per game (`drawPicker()`, covers in `COVERS` drawn as SVG with `cv-*` token classes, since the page's policy refuses a style attribute) with its blurb, best and a **Last played** or **Round paused** tag, arrows walking the cards (`moveFocus()`), and `#activities-back` (**All games**) back to it. One game at a time: `pick()` drops the last game from `games` when another is picked, and `openActivities()` goes straight back into a paused round. The last pick is kept as `lastActivity` and gets the focus; `lowerIsBetter` games keep the lowest round as the best; the header shows the current game's best (`paintTitle()`). `renderActivities()` in the render pass compares `myTurn()` and `finish()` with the last render and shows the banner with **Go to it**. Loads a game with `import()` when it is picked and keeps it until another is picked; `setActivityList()` lets a test list a stub second game, which brings up the picker |
|
||||
| `public/screens/activities.js` | Activities: `#btn-activities` (the die right of the megaphone), `#activities-modal`, the one frame timer (`requestAnimationFrame`, swappable with `setTickSource()` for the page tests), the keys (arrows, W/A/S/D, space, P, Esc; stopped at the dialog so none reach the page behind; `CHEAT_CODE`, typed on a game's board, turns on endless lives through the game's `cheat(on)` until the round starts over, and `dropCheats()` turns it off on leaving for the picker or closing; `STAGE_CODE`, the same arrows then S, calls the game's `stageSelect()` where it has one, Ghoul Rush's practice stage select) and `pauseAll()`, which a new question, a finish, a hidden page, a window blur and a close all go through and which never resumes a game (it also sends a pointer game a cancel, dropping a drag). Canvas pointer events (down, move, up, cancel, with pointer capture) go to a game with `pointer()`, and key releases to a game with `release()`; a press on a paused board resumes without starting a drag. While paused, any game key or a board click resumes, except while a round is `held`: a question or finish that pauses a round on an open window holds it, the banner adds `#activities-unpause` (**Unpause game**) beside **Go to it**, and only that button plays on (`play()` refuses a held round), since a key or click already on its way used to dismiss the banner unread. Go to it, or closing the window any other way, lets the hold go, and a banner with nothing left to say drops it. Every start and play-on first counts down 3, 2, 1 (`COUNT_FROM`, 700 ms a number, `setCountdownMs()` for the page tests, which set 0 unless they test it): the game is already `running`, the frame timer just does not tick it, and game keys, overlay clicks and board presses wait, while P and Esc still pause. With two or more games listed the window opens on the picker (`view`: `"picker"` or `"game"`, `applyView()`): a picker of game rows in two columns (`drawPicker()`: an Order bar with **Recently played** and **A to Z**, saved in `activityOrder`, and the game count; one grid of `.activities-row` buttons from `orderGames()`, with never-picked games under a **Not played yet** heading that spans both columns; covers in `COVERS` drawn as SVG with `cv-*` token classes, since the page's policy refuses a style attribute) with each game's blurb, a best chip (thousands separators) and a **Last played** or **Paused at N** tag, arrows walking the rows and the course cards by position (`moveFocus()`: left and right through the list, up and down to the nearest button in the next line; an Order button keeps its arrows), and `#activities-back` (**All games**) back to it. One game at a time: `pick()` drops the last game from `games` when another is picked, and `openActivities()` goes straight back into a paused round. The last pick is kept as `lastActivity` and gets the focus; `lowerIsBetter` games keep the lowest round as the best; the header shows the current game's best (`paintTitle()`). `renderActivities()` in the render pass compares `myTurn()` and `finish()` with the last render and shows the banner with **Go to it**. Loads a game with `import()` when it is picked and keeps it until another is picked; `setActivityList()` lets a test list a stub second game, which brings up the picker |
|
||||
| `public/styles/activities.css` | the Activities rules: the die in the top bar, the Notebook-sized dialog, the board and its state overlay, the your-turn banner in the highlight color, the picker and the notes |
|
||||
|
||||
**Building an Activities game:** the rules every game follows, so a new one plays like the rest.
|
||||
|
||||
- **Lives are prominent.** A game with lives draws them as the lives pill: `livesText(round.lives)` in the `LIVES` color from `pills.js`, placed right after the level/stage pill, which `drawPill()` draws solid pink with a heart per life. Never a plain `♥ N` on the dark backing: that was hard to read at a glance. The unit suite checks every game with lives for it.
|
||||
- **Every game adds looks.json keys, and `cleanLooks()` keeps at most 120.** A new game adds a best (one per course for a game with courses), a memo, a played time (`activityPlayed<Id>`) and, with music, a music volume; the picker adds `activityOrder`. About 77 keys are in use, so raise the cap (or fold keys) before the games that would pass 120.
|
||||
- **Every game with lives takes the endless-lives code.** Typing up, down, up, down, left, right, left, right, B, A, space on the board gives endless lives until the round starts over or the person leaves the game (`CHEAT_CODE` in `screens/activities.js`, which calls the game's `cheat(true)` and `cheat(false)` on leaving for the picker or closing). A game with lives answers `cheat(on)` by setting `round.infinite`, never takes a life while it is set (`if (!round.infinite) round.lives -= 1`), lets `start()` make a new round without it, and shows `livesText(Infinity)` ("♥ x∞") in its lives pill. `scripts/test-web-console-activities.mjs` checks every listed game whose round has `lives`.
|
||||
- **Banners never get in the way.** A banner over the board (`"Hit!"`, a new level, a power-up) is placed on the frame it first shows, on the part of the board away from the player, and fades to `BANNER_SEE_THROUGH` (0.12) over `BANNER_FADE_MS` while the player, or anything the player must react to (a diving bug, a bomb, a rival, a hazard, the road over a hill), is in its strip; Snake's `bannerRow()` and `underBanner()` are the model. Give the banner object a `see` field, multiply the draw's alpha by it, and export the strip check (`underBanner`) for the unit suite.
|
||||
- **The window owns pausing.** A game never resumes itself; `screens/activities.js` decides when a key or click plays on, including the hold on a question or finish (see the row above), so a game needs nothing of its own for it. Full screen is the window's too (`setFull()`: the button, `F`, and a turn or finish putting it back; `fitFull()` sizes the game to the whole screen (black bars where its shape leaves room) and docks the overlaid panel in a bar that holds it, `data-dock="side"` or `"below"`, or floats it, `"float"`, shrunk to the score while a round plays and the pointer is still; and tells the desktop app `activities-full`); a game only sees a bigger `resize()`, so a new game needs nothing for it, as long as its `resize()` sets the canvas's CSS size.
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
# Architecture: Bounce Road
|
||||
> Part of [AGENTS.md](../AGENTS.md) and the [Architecture index](./AGENTS-architecture.md): project guidance for AI coding agents.
|
||||
|
||||
Bounce Road's files under `src/web-console/public/activities/`. The other games and the rules every game follows are in [Activities](./AGENTS-architecture-activities.md).
|
||||
|
||||
How it fits together: a **stage** is a theme (its look and what it lays on the road) in a slot (how hard: length, holes, rivals), so a run can deal the themes in a new order and stay fair. Every third stage is a boss stage in that boss's arena; fifteen stages make a lap. Rules never draw and drawing never decides: `bounce.js` refills one view object a frame and `bounce-draw.js` draws from it.
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `public/activities/bounce.js` | the cars, the hazards against them, the gadgets, the scoring and the round, as plain exported functions over a round on a road scrolling up a 72 unit wide field, 90 units of it on the board (it re-exports every rule of `bounce-road.js` and `bounce-rivals.js`, so a suite imports one module). `newRound(seed, random, shuffle)` (the game passes `shuffle` true; the suites leave it off for the classic stage order), `advance` in 4 ms slices over `round.input` (a jump press first, then a `fire`, your `move`, the rivals' `think` and `move`, the pads, the bumps, the barriers, the hazards, `threats`, the ground, progress and traffic). **Driving:** `move`, `jump`, `land` (a landing on a rival flattens it for its points times the chain up to `MAX_CHAIN`; a truck's or the Supply truck's roof is `HAUL_POINTS` and a trampoline; a Spike's roof is a life; a boss takes a hit, `hurtBoss`), `collide` (side knocks split by mass, end on speed passed forward, a heavy back at `CRASH_CLOSE` a crash, a Slasher's blades out a crash, Mega wheels or a Fever flatten on touch), `stunt` (points times `comboOf(streak)`, doubled in a Fever, and it fills the Fever), `lose` (a Bubble saves instead), `underBanner`. **Power-ups** (`POWERS`): Spring, Bubble, Star magnet and a heart work as taken (`applyPower`); the ones with `uses` are gadgets (`GADGETS`: Nitro, Mega wheels, Rockets, Oil slick, Ground pound, Zapper), held one at a time in `you.held` until `usePower`. **The double tap:** `key("action")` jumps at once on the first press and sets `input.fire` on a second within `DOUBLE_TAP_MS` while a gadget is held (never on a repeat, never across a pause), so a jump never waits. **Weapons and the rivals' fire** (`threats`): `round.shots` (rockets: the first rival, boss or barrier in the way), `round.bolts` (a Blaster's: a knock and a slide, never a life), `round.bombs` (a Bomber's, blowing `BOMB_FUSE_MS` on), `round.lobs` (what a boss threw, landing `LOB_MS` on: a barrel lies there as a block, a bomb blows), `round.spills` (oil: yours spins a rival, a boss's takes your grip), the pull of a Magnet rival and the Robo-Vac. **Fever:** `round.fever` fills by `FEVER_GAIN` a stunt; full, `startFever` burns `FEVER_MS` of double points; a life lost halves the meter. **Lives and ranks:** a life every `LIFE_SCORE` points, for a flawless stage and for a boss; a stage line scores `STAGE_POINTS` times the stage, `TIME_POINTS` a second under par and `FLAWLESS_POINTS`, and ranks the stage S to C into `round.ranks`. **The boss hold:** while a boss is alive and the next stage is not yet built, `progress` calls `extendStage` instead of `ensureRoad`, so a boss stage lasts until its boss is beaten (on a road built far ahead, as the suites do, the boss gets away at the line instead). **Road things it settles:** boost strips, ramps, slicks, conveyors (`BELT_PUSH`), spring pads, cones and blocks, bumpers (`BUMPER_POINTS`, a kick, never a life), trains, balls, rollers, sprinklers, drops, gusts, lasers and stompers; an icy or wet stage (`spec.ice`) has less grip everywhere. **The game contract** with `release()`, `cheat(on)`, the events each frame turns into sounds, sparks, floats and banners (`handle`), a power-up's name flashed near the top of the field for `TOAST_MS` (`fx.toast`), the pills (`hudOf`: stage, lives, effects with their timers, the gadget held as `TAP x2: NAME`, the Fever meter, a boss's hp), and the music: `MUSIC_TRACKS` (the twenty chip tracks, a radio in random order), `dealMusic(random, last)` and `MUSIC_HEAT` (the intensity the game asks for: 0.5 on the road, 0.8 while a boss lives, 1 in a Fever), each track played through (`music()` says `"ended"`), a new deal after the last. Memo is the furthest stage reached. A read-only `round` getter is for the tests only. Tuned by scratch bots: a careful bot clears all fifteen classic stages with no rivals on every seed tried, 17 to 35 s a stage |
|
||||
| `public/activities/bounce-roads.js` | the stages as data and plain arithmetic (no imports): `FIELD_W`, `FIELD_H`, `ROW`, `MAX_HOLE`, `WORLD` (every third stage a boss), `CYCLE` (fifteen stages a lap), `MAX_RIVALS`; `THEMES` (fourteen plain themes and five boss arenas: each one's road widths, piece weights, bridges, flowerbeds, barrier and drop kinds, what its ball, roller and stomper are drawn as, `ice`, `dark`, `boss`, and a `tier` for where in a run it belongs), `REGULAR`, `BOSS_ORDER`, `ARENAS`, `TWISTS` (Rush hour, Gold rush, Lights out, Downpour, Supply drop, Turbo lane) with `TWIST_SHARE`, `KIND_FROM` (the slot each rival kind first comes in), `slotFor(n)` (a stage's difficulty from its place: length, par, pace, sharpness, rivals, kinds, crack and gap lengths), `stageSpec(n, id, twist)` (slot, then theme, then what the twist changes), `classicTheme(n)` and `STAGES` (the first lap of an unshuffled run). The place to tune the difficulty |
|
||||
| `public/activities/bounce-road.js` | the road, rules only: the jump math every hole is sized by (`airMs(v)`, `reach(v)`, `LONGEST_JUMP`, `JUMP_FAIR`, `TOP_SPEED`, `MAX_SPEED`); the run's plan, `planAt(road, n)` and `stageFor(n, road)` (with no road, or one made with no shuffle, the classic order; a shuffled road deals each lap from its seed: Chalk Lane first, ten of the plain themes roughly gentle to hard, the bosses in a new order with the Cat last on the first lap, a twist on some plain stages; built once a road) and `stageName`; `newRoad(seed, shuffle)` and `buildStage(road, n, random)` (a stage's rows from its own seed by its piece weights: straights, cracks, rivers on bridges, splits, ramps, chicanes, crumbling road, trains, swaying bridges, boost strips, slicks, balls, sprinklers, drops, gusts, conveyors, spring pads, bumpers, lasers, stompers and rollers; every hole after a `RUNUP` with a sign and no longer than `MAX_HOLE`; a boss stage opens with rockets on the road); `POWER_ROLL` and `rollPower(n, roll)` (which power-up, by stage); `extendStage(road, n, to)` (more of the last stage built, its line moving to the new end: the boss hold); the stunt pieces every theme lays (`WILD` in `bounce-roads.js`): `kicker` (a big ramp, `KICKER_AIR` the usual jump, over a chicane), `wall` (blocks right across the road), `trampoline` (three rows of spring pads) and `turbo` (a `TURBO_W` wide lane of boost strips); `ensureRoad`, `groundAt(road, x, d, t)`, `rowGone`, `spanAt`, `holesIn`, `firstAt`, `plainRow`, `safeSpot`; and where each timed thing is at a moment: `swayOff`, `drawLift`, `crumbleAt`, `trainAt`, `ballX` (a ball's and a roller's middle), `sprayAt`, `gustAt`, `laserAt` (on, and blinking `LASER_WARN_MS` before), `stomperAt` (down, the slice it lands in, and its shadow growing `STOMP_WARN_MS` before); plus `seeded`, `GROUND`, `MARK`, `SPAN` |
|
||||
| `public/activities/bounce-rivals.js` | the rivals, rules only: `RIVALS` (box, mass, speed, points, dodge, weight, car style, and the flags `behind`, `spiky`, `friend`, `boss` with `hp` and a `hint`), `BOSS_KINDS`, `isBoss`, `makeCar`, `think(round, car, ms, random)`, `spawnRival`, `pickKind` (weighted among the stage's kinds, a kind new to the stage more often, one of each special kind at a time), `lob` (a thing thrown at where you are heading). The plain kinds: the Zigzag weaves, the Brick holds your lane and brake-checks, the Frog hops at you, the Sneak drops cones, the Nudge and the Cop chase and shove (never by the water), the Hauler blocks, the Bruiser slams, the Racer passes and flees. The ones with a trick: the Blaster lines up ahead, glows for `AIM_MS` and fires a bolt back down the road; the Slasher pulls alongside, glints for `BLADE_WARN_MS`, then its blades are out for `BLADE_MS`; the Spike sits in your lane, a crash to land on; the Bomber drops bombs while you follow; the Phantom is out of reach for `PHASE_OFF_MS` of every cycle; the Splitter bursts into two Minis; the Magnet hugs an edge and holds your speed; the Supply truck (a friend) keeps ahead for a while, then drives off. The bosses: the Big Rig (`tanker`: lobs barrels, leaks oil), the Robo-Vac (`vac`: sweeps, warns `VAC_WARN_MS`, charges back at you, then drives back up the road through anything), the Whirlybird (`chopper`: `lift` 1 and `high` while it bombs out of reach, then down on the road for `CHOPPER_LOW_MS`), the Monster (hops to come down where you will be, drops tires) and the Cat (`cat`: slams like the Monster, then sweeps across the road for `CAT_SWIPE_MS`). A zapped or oil-spun rival coasts blind (no steering, tricks or hops). Every other rival is rubber-banded to stay near you, swerves from under your landing as sharply as its stage allows, keeps to the narrowest road just ahead, and hops any hole, barrier, coming train, laser or roller |
|
||||
| `public/activities/bounce-draw.js` | Bounce Road's drawing: `drawScene(ctx, view)` from one view object `bounce.js` refills each frame, in field units: the strip above the field in the page's colors with the pills (laid out by `hudLayout`: stage, lives, Spring, Bubble, Nitro and Mega with their timers, the chain and the combo with its timer; a pill that would run off the board starts a second row), the road a chunk of `CHUNK_ROWS` rows at a time, drawn off screen once per road and scale, a few kept and copied each frame (rows from `bounce-scenery.js`), the layers over it (`bounce-scenery.js`), the landing rings (yours in your highlight, a rival's in red, the Monster's its own size), the cars through `bounce-cars.js` (every shadow first, upright, then every body with its tumble: Planny in your highlight with his box in the page's panel color and his star eye, arms to the wheel, up in the air or cheering, down at the end; each rival kind in its own style and color, the Cop's siren while it chases, the Monster's dents and a star per life left above it, headlights at Night Lights), sparks, rings, the dark of Night Lights, the chain's big number, the stage bar beside the field, banners, and the start and end strip with the big final score and a dot per stage reached; every word kept on the field by `labelSpot`, and `readColors(canvas)`, `limbInk`, `inkOn`; decides nothing; since the arcade layer: a boss routed to its own drawer, the Whirlybird lifted over its shadow, a Phantom faded, your landing ring red and crossed over a Spike, the Fever meter along the strip, a boss's health bar across the top of the field, the title and over screens, a CRT scanline pass, and the dark whenever a stage's `dark` is set (Night Lights or a Lights out twist), with lasers, rockets, bolts and blasts drawn over it; it re-exports `CUSTOM_STYLES` |
|
||||
| `public/activities/bounce-extras.js` | the arcade layer's drawing, no rules: `CUSTOM_STYLES` (`vac`, `chopper`, `paw`: the three bosses that are not car styles) with `drawBossBody` and `drawBossShadow`; `drawCarExtras` (a Blaster's turret, a Slasher's blades, a Spike's spikes, a Bomber's rack, a Phantom's shimmer, a Magnet's horseshoe, the Supply truck's crate, zap sparks, an oil spin, a boss dazed); `drawPulls` (a Magnet's and the Robo-Vac's pull), `drawYouUnder` and `drawYouOver` (the Fever's rings, the Star magnet's ring, the gadget held); `drawSpills`, `drawThreatsLow` (bombs, a lob's shadow) and `drawThreatsHigh` (rockets, bolts, lobs in flight, pixel fireballs from `fx.booms`); `drawFever`, `drawBossBar`, `drawTitle` (the logo, PRESS SPACE, GAME OVER, the last fifteen rank badges) and `drawScanlines`. Words are drawn through a `label` handed in by `bounce-draw.js`, which it may not import |
|
||||
| `public/activities/bounce-cars.js` | Bounce Road's cars, drawing only and no imports: `drawCarBody(ctx, style, opts)` draws one top-down toy car about the origin, nose up, filling `w` by `h` field units exactly (tires on the box's corners), in one of `CAR_STYLES` (`STYLE_NAMES`: Planny's convertible with his star eye and arms to the wheel, hatch, sedan, coupe, muscle, pickup, van, box truck, police, racer, taxi, jeep, monster) with flat-fill shading worked out from `color` and `accent` (`shade`, `rgbOf`), and options for roll (`tilt`), a jump (`air`: it draws the shadow and the lift itself), a pancake (`squash`), night beams, a siren bar, damage, a boost flame and brake lights, all moving parts on `opts.clock`; `drawCarShadow` and `shadow: false` for a shadows-first pass in screen space; `carLength(style, w)` for a style's natural length and `carReach(style, opts)` (with `MARGINS`) for what reaches outside the box; plus the newer styles as data rows: armor, buggy, bubble, bus, mini, tow, supply and tanker |
|
||||
| `public/activities/bounce-scenery.js` | Bounce Road's scenery, drawing only: each stage's look in fixed colors (`LOOKS`: patio slabs, lawn stripes, kitchen tiles, garden, sand, a toy room's rug, a pond with lily pads, roof shingles, the night lawn with lamps and the Monster's dirt; `lookOf`, `stageColor`, `contrast`, `better`), `drawRow` (one row of the road in three passes over a chunk: the yard, the road's surface, the details: edges slanting from row to row, rivers, plank bridges with jagged broken ends, cracks, flowerbeds, rails across a crossing, cracked road over a pit, checkered stage lines, verge decor), and the layers drawn fresh each frame from the round's clock: `drawTimed` (a drawbridge lifting with its red lights, a swaying bridge where it is now, crumbled road gone to the pit), `drawPads` (running boost chevrons, ramps, slicks), `drawBlocks` (cones, toy blocks, pots, buckets, acorns and tires, knocked ones tumbling off), `drawStars`, `drawSigns` (a mark per hazard), `drawItems`, `drawHazardsLow` (crossing lights, the train, a rolling ball, a falling thing's growing shadow, a sprinkler's head), `drawHazardsHigh` (the jet, gust streaks, the thing still falling), `drawNight` and `drawFireflies`; decides nothing; plus the nine newer looks (bath, pinball, desk, ice, lava, garage, hall, attic, couch) with their patterns, lava drawn fresh each frame (`drawLava`), an icy sheen and rain (`drawSheen`, `drawRain`), conveyors, spring pads, bumpers, barrels, the balls by kind, rollers, lasers (`drawBeams`), stompers, the newer signs, and every power-up's mark (`itemMark`, `drawPickup`: a gadget is a square crate, the rest round) |
|
||||
| `public/activities/bounce-sfx.js` | its own sounds, merged into `tones.js`: `music` (the twenty tracks of `bounce-music.js`, its only import), `tones` (landings, the Monster, the siren, the crossing, a bumper, a rocket, oil, the ground pound, the Fever, a Slasher's blades, the Cat, the Robo-Vac's charge, a gadget loaded) and `hums` (your motor, the Monster, the Whirlybird's rotor, the Robo-Vac, crumbling road, a sprinkler); definitions only |
|
||||
| `public/activities/bounce-music.js` | its music, all synthesized (no mp3): `SCORES`, twenty short scores (`{ title, key, scale, bpm, kit, bass, arp, drums, A: { chords, lead }, B: { chords, lead } }`: `key` the tonic as a MIDI note for the bass, `chords` a scale degree a bar, `lead` eight bars of sixteen characters, `1` to `7` the scale's degrees, `a` to `g` an octave up, `A` to `G` an octave down, `-` a hold, `.` a rest), and `BOUNCE_MUSIC`, `bounceSong1` to `bounceSong20`, each score turned by `build()` into a `music.js` track when the file loads: a bass, a lead and an arpeggio on one of five chip kits (`KITS`), drums, an echo of the lead (`from` 0.7, a boss) and a harmony under it (`from` 0.9, a Fever), in the order intro, tune, tune with its arpeggio, second tune twice, break, both tunes again (56 bars, 73 to 88 seconds at 146 to 178 bpm, `rush` 14). The bar patterns are `BASS`, `ARP` and `DRUMS`. No imports |
|
||||
|
||||
**Tests.** `scripts/test-web-console-activities-bounce.mjs` (driving, the road and its fairness, the stage plan, the older rivals, the bots), `scripts/test-web-console-activities-bounce-arcade.mjs` (gadgets, the Fever, ranks, the newer hazards and rivals, the bosses, the double tap, the music), `scripts/test-web-console-activities-bounce-game.mjs` (the game contract, pills, tones, drawing) and `scripts/test-web-console-activities-bounce-cars.mjs` (the car art). Changing only Bounce Road: run those four.
|
||||
@@ -12,14 +12,15 @@ Key design points:
|
||||
- **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.
|
||||
- **The CLI hands the agent its terminal line.** `open`, `post` and `wait` (exits `0` and `10`) print `terminalLine: "→ Look at the web console: <url>"` (`terminalLine()` in `sessions.mjs`), and `console.md` asks the agent to end every terminal message with the latest one verbatim, so the tool builds the line rather than the model. In `wait` it is added to the printed result only; the collected `result.json` on disk never carries it. `open` also prints `swept: { sessions, scratch, handoffs }` when it found anything to clean.
|
||||
- **State fields written by `open`, not the agent.** Every `open` (fresh or resume) records `state.worktree` and `state.branch` from `repoRoots()` — the branch is read off `<gitdir>/HEAD` on the walk that already finds the gitdir (`""` on a detached HEAD or outside git; env-relocated repos ask git, as before) — and the page shows them in the footer as the workspace label (`footerLabel()`: `folder · branch`, or `folder + N folders · branch` once folders are added, stepping down through narrower tiers); a click opens the Workspace dialog. `state.wake = true` is set only by a fresh `open --workflow dashboard` and deleted by every resume (server restart, launch, Back to the dashboard); the page also keeps a per-sid `sessionStorage` guard so a reload never replays it.
|
||||
- **`looks.width` is a person-level preference** alongside theme, accent and sounds in `looks.json`. `CARD_WIDTHS` in `public/palette.js` (`narrow` 720, `comfortable` 880 — default — `wide` 1080) is read by the page (`cardWidth()` validates a saved value) and by `routes.mjs`, which paints `data-width` on first load; `styles/tokens.css` maps `data-width` onto the single `--card-width` variable that every column rule uses.
|
||||
- **`looks.width` is a person-level preference** alongside theme, accent and sounds in `looks.json`. `CARD_WIDTHS` in `public/palette.js` (`narrow` 720, `comfortable` 880 — default — `wide` 1080, `ultrawide` 1440) is read by the page (`cardWidth()` validates a saved value) and by `routes.mjs`, which paints `data-width` on first load; `styles/tokens.css` maps `data-width` onto the single `--card-width` variable that every column rule uses.
|
||||
- **`GET /agents-doc` is the other route that reads a project file** (the dashboard's AGENTS.md tab, right after Dashboard, shown while the project has an `AGENTS.md`). A dashboard session only; it serves `AGENTS.md` or one markdown file directly under `.agents-docs/` (`?file=`, default `AGENTS.md`; `readAgentsDoc()` in `sessions.mjs` allows exactly those two shapes and `realpath`s the file inside the root), as `text/markdown` with `no-store`, or a `204` for anything else. The page links `.agents-docs/` files in place through `md()`'s `link` option (`renderAgentsDoc()` in `screens/docs.js`).
|
||||
- **`GET /overview` reads a project file too.** It serves `<spec>/overview.md` as `text/markdown` with `cache-control: no-store` (so the Overview tab is always fresh), or with `?file=map` / `?file=draft` the spec's `pathfinder/map.md` / live `PLAN-DRAFT-*.md` (the dashboard's Map and Plan draft tabs, shown only while the spec has no overview; `readSpecFile()` picks the file and names it in `x-spec-file`), or an empty `204` when there is no such file (normal for most specs, and no failed request in the browser console). A dashboard session honors `?spec=` only when it equals a `dir` in `state.scan.specs`; every other workflow uses `state.specDir` and ignores the query. The root is `state.worktree` (fallback `state.project`), and `readSpecFile()` (which `readOverview()` wraps) resolves and `realpath`s the file and refuses anything outside the root's realpath, so `../`, absolute paths and outward symlinks all get the same 204, as do an unscanned `?spec=` and an unknown `?file=`.
|
||||
- **The Prototypes tab reads a spec's `prototypes/` folder.** `GET /prototypes` lists its `.md` and `.html` files (204 when none), `GET /prototype?name=` serves one `.md`, and `POST /open-prototype` (origin-checked) hands one `.html` to the system's default opener through `openFile()` in `open-link.mjs` (one argument, no shell). The spec is chosen as `/overview` chooses it (`specInView()`); `listPrototypes()`, `readPrototype()` and `prototypeHtmlPath()` in `sessions.mjs` take a bare file name only and refuse any file whose realpath is not directly in the folder. The page shows the tab after the spec file tabs, on the dashboard and in a session alike (`loadPrototypes()`, called from `loadOverview()`).
|
||||
- **Month-old sessions are deleted whole.** `open` lists `staleSessions()` (directories matching the session-id pattern whose `state.json` mtime is older than 30 days, never the sid being opened — no exceptions for paused sessions or unread sends) and `staleScratch()` (top-level regular `.json` / `.mjs` files in the console folder older than 30 days, never `looks.json` or `console-dir` — `PROTECTED_CONSOLE_FILES` — never a directory or symlink) before it prints, and removes them after; `removeSessions()` / `removeScratch()` re-check every name against the session-id pattern / the scratch-name rule before deleting — not the age, the skipped sid or the file type, which the `stale*` listing already decided, so never hand them names that did not come from it. `console.md` tells agents to write temporary payload files into the session's own folder so they go with it.
|
||||
- **User Preferences → System → Cleanup deletes on demand, from a list the server makes.** `POST /cleanup` (origin-checked) with `{ scan: true }` returns `cleanupFindings()`: `{ items: [{ id, where, name, kind, bytes, folder? }], bytes }` (`folder` on `notepad:` items only), ids `session:<sid>` (the `staleSessions()` rule, and every file in the folder that old too, never the serving sid), `console:<name>` (anything at the top of the console home but `PROTECTED_CONSOLE_FILES`, `sessions` and `runtime`, directories too) and `root:<name>` (anything at the top of `~/.plan2code` but `KEPT_PLAN2CODE_ENTRIES`: `console`, `bin`, `launcher.json`, `install.json`, `models.json`, `handoffs`, `notepads`, `app`, `app.json`, `agents.json`), `notepad:<key>` (a month-old notepad, whole; see Notebook below) and `completed:<name>` (each folder or link directly under the session worktree's `specs--completed/` whose newest mtime is older than the session age, 30 days; loose files there stay; the server passes `project: sessionWorktree() || PROJECT`, and without a `project` the archive is never scanned). Both stray kinds must be untouched for `STRAY_GRACE_MS` (an hour, by the newest `lstat` mtime anywhere inside, since rewriting a file never moves its folder's mtime; unreadable reads as fresh): the same folders hold `workspaces.json.lock` and `writeJsonAtomic()`'s `<file>.<pid>.tmp`, which live for milliseconds. `root:` is only scanned when the console home is `<PLAN2CODE_MODELS_DIR or ~/.plan2code>/console`, so a test or dev home never reaches the real folder. Paths never go to the page. `{ delete: [id] }` runs `removeCleanup()`, which re-scans and removes only ids still on the fresh list (symlinks unlinked, never followed), returning `{ removed, bytes, failed, refused, refusal }`. So Cleanup is the one place the server deletes in a project, and it keeps a completed spec git could not give back: `completedSpecs()` marks each `completed:` item `tracked` only when `git ls-files` lists it and `git ls-files --others` lists nothing inside (outside a repository, or gitignored as `specs--completed/` is by default, it is untracked), and `removeCleanup()` refuses an untracked one into `refused`, with `refusal` the line the page's status shows. Nothing records a backup copy, so tracked by git is the only way through. The page always shows the list before **Delete these**.
|
||||
- **User Preferences → System → Cleanup deletes on demand, from a list the server makes.** `POST /cleanup` (origin-checked) with `{ scan: true }` returns `cleanupFindings()`: `{ items: [{ id, where, name, kind, bytes, folder? }], bytes }` (`folder` on `notepad:` items only), ids `session:<sid>` (the `staleSessions()` rule, and every file in the folder that old too, never the serving sid), `console:<name>` (anything at the top of the console home but `PROTECTED_CONSOLE_FILES`, `sessions` and `runtime`, directories too) and `root:<name>` (anything at the top of `~/.plan2code` but `KEPT_PLAN2CODE_ENTRIES`: `console`, `bin`, `launcher.json`, `install.json`, `models.json`, `handoffs`, `notepads`, `app`, `app.json`, `agents.json`, `prototypes`, `learning`), `notepad:<key>` (a month-old notepad, whole; see Notebook below) and `completed:<name>` (each folder or link directly under the session worktree's `specs--completed/` whose newest mtime is older than the session age, 30 days; loose files there stay; the server passes `project: sessionWorktree() || PROJECT`, and without a `project` the archive is never scanned). Both stray kinds must be untouched for `STRAY_GRACE_MS` (an hour, by the newest `lstat` mtime anywhere inside, since rewriting a file never moves its folder's mtime; unreadable reads as fresh): the same folders hold `workspaces.json.lock` and `writeJsonAtomic()`'s `<file>.<pid>.tmp`, which live for milliseconds. `root:` is only scanned when the console home is `<PLAN2CODE_MODELS_DIR or ~/.plan2code>/console`, so a test or dev home never reaches the real folder. Paths never go to the page. `{ delete: [id] }` runs `removeCleanup()`, which re-scans and removes only ids still on the fresh list (symlinks unlinked, never followed), returning `{ removed, bytes, failed, refused, refusal }`. So Cleanup is the one place the server deletes in a project, and it keeps a completed spec git could not give back: `completedSpecs()` marks each `completed:` item `tracked` only when `git ls-files` lists it and `git ls-files --others` lists nothing inside (outside a repository, or gitignored as `specs--completed/` is by default, it is untracked), and `removeCleanup()` refuses an untracked one into `refused`, with `refusal` the line the page's status shows. Nothing records a backup copy, so tracked by git is the only way through. The page always shows the list before **Delete these**.
|
||||
- **The console's path is stated, not searched for.** Each Interface line names `references/web-console/` beside the SKILL.md and the `~/.plan2code/console/console-dir` fallback; the prompts with room (all but pathfinder, plan, document and finalize, which sit near the char limit) also name the canonical global install path `~/.agents/skills/<skill>/references/web-console/` (the skills CLI's real store; every agent dir links into it), and every `console.mjs open` writes `HERE` to `~/.plan2code/console/console-dir` (only `open`, so a `help` or dev run from `src/` never repoints it) so a later session can read the path from a fixed place. Without these the agent hunts the skill install dirs on every session.
|
||||
- **`open` needs no payload, and runs first.** `--file` and `--title` are optional (the title defaults to the folder name). Every skill's Interface line puts `node "<D>/console.mjs" open --workflow <w>` BEFORE reading console.md or the project, and a test (`every skill opens the console before it reads anything`) keeps it that way; a blank session renders a starting screen ("Starting Pathfinder", Planny in flight) until the first post. Every skill replaces the flight with its own animated pose (init — init-update borrows it — pathfinder, plan — revise-plan borrows it — document, implement — implement-review borrows it — finalize, quick-task, review, handoff; only the dashboard keeps the flight), cloned by `startStage()` in `screens/starting.js` from `<template id="start-poses">` in `index.html` and animated under `.pose` in `styles/poses.css`; each `SKILLS` entry's `pose` in `skills.js` is the list (`START_POSES`/`startPose()` in `answers.js` read it), and a test keeps the template in sync with it and every catalog workflow mapped to a pose. The same pose stands above the waiting pane (`.waiting-pane`, agent working with an `activity` and nothing to ask). `posePane()` keeps the pane on screen across renders when the pose is unchanged — `renderMain()` holds any `:scope > [data-pose]` child back from the clear — so the SVG never leaves the DOM, its animations never restart on a state frame, and Planny carries unbroken from launching → starting → waiting. The dashboard's launch hand-off resumes first and reads the launched skill's file after.
|
||||
- **The dashboard scan knows whether the folder is a git repository.** `scanProject()` returns `{ hasAgents, isGit, pending, specs }`; `isGit` comes from `insideGitRepo()`, the same filesystem walk `findRoots()` does (no `git` process, linked worktrees and submodules count, a set `GIT_DIR` / `GIT_WORK_TREE` / `GIT_COMMON_DIR` counts as a repo). The Git card is never grayed, since a clean tree still has branches to switch, pull and push. When `isGit` is `false` the card shows `GIT_INIT_NOTE` ("Not a git repository yet: it offers to start one") as its detail line; a scan with no `isGit` counts as a repo. In a repo, `pending` is `pendingFiles()` in `sessions.mjs`, which calls `countPending()` in `git-repo.mjs`: one bounded `git status --porcelain -z` under `GIT_OPTIONAL_LOCKS=0` (`null` when git cannot say) counting modified, staged, deleted and untracked paths. Above `0` the detail line is `pendingNote(n)` ("3 files to commit"); `0` and `null` show no note. A finish with `commit: true` puts a **Commit it now** button on the finished screen (`commitOffer()`, `renderCommitOffer()`); its `__commit` press makes the agent resume as `git` in the same session and run the commit flow above the board. `open --resume` treats any switch into `git` (this press, or Changelog's "Commit this now?") as a hop, like a dashboard launch: `switchWorkflow()` blanks the page, finish and the last run's `state.git` included, and `draft.json` goes. Without that, the old finish outlived the switch, and the page sat on the old ending above the new questions and the board. A confirm item may carry `files: [{ path, state }]`, drawn as a collapsed table by `filesTable()`. Subagents is **on** by default for the twelve opted-in skills (`defaultSetting()`); a saved Off stays off.
|
||||
- **The dashboard scan knows whether the folder is a git repository.** `scanProject()` returns `{ hasAgents, isGit, pending, specs }`; `isGit` comes from `insideGitRepo()`, the same filesystem walk `findRoots()` does (no `git` process, linked worktrees and submodules count, a set `GIT_DIR` / `GIT_WORK_TREE` / `GIT_COMMON_DIR` counts as a repo). The Git card is never grayed, since a clean tree still has branches to switch, pull and push. When `isGit` is `false` the card shows `GIT_INIT_NOTE` ("Not a git repository yet: it offers to start one") as its detail line; a scan with no `isGit` counts as a repo. In a repo, `pending` is `pendingFiles()` in `sessions.mjs`, which calls `countPending()` in `git-repo.mjs`: one bounded `git status --porcelain -z` under `GIT_OPTIONAL_LOCKS=0` (`null` when git cannot say) counting modified, staged, deleted and untracked paths. Above `0` the detail line is `pendingNote(n)` ("3 files to commit"); `0` and `null` show no note. A finish with `commit: true` puts a **Commit it now** button on the finished screen (`commitOffer()`, `renderCommitOffer()`); its `__commit` press makes the agent resume as `git` in the same session and run the commit flow above the board. `open --resume` treats any switch into `git` (this press, or Changelog's "Commit this now?") as a hop, like a dashboard launch: `switchWorkflow()` blanks the page, finish and the last run's `state.git` included, and `draft.json` goes. Without that, the old finish outlived the switch, and the page sat on the old ending above the new questions and the board. A confirm item may carry `files: [{ path, state }]`, drawn as a collapsed table by `filesTable()`. Subagents is **on** by default for the sixteen opted-in skills (`defaultSetting()`); a saved Off stays off.
|
||||
- **The start path is timed, and `open` is built around it.** Measure with `node scripts/bench-web-console.mjs` (`--browser-delay 900` for a real Chrome launch, `--roundtrip` for Send→agent and post→page, `PLAN2CODE_CONSOLE_TRACE=1` on `open` for a step timeline). Four things make it fast, and each is load-bearing:
|
||||
- **No git process.** `repoRoots()` in `sessions.mjs` finds the common dir and worktree top by walking to `.git` (following `gitdir:` and `commondir` files) — each `git rev-parse` cost 150ms+ on Windows. It asks git only when `GIT_DIR`/`GIT_WORK_TREE`/`GIT_COMMON_DIR` relocate the repo, and uses the native realpath so an 8.3 short name keys the same project git would.
|
||||
- **The socket handover.** `open` spawns the server first, then binds the loopback port itself (the first `listen()` blocks ~50ms on Windows, overlapped with the server's boot), launches the browser on that URL immediately (Chrome via `start` takes ~900ms to its first request, the longest step of all), and hands the listening socket to the server over IPC (`bindLoopback()`/`handOff()` in `sessions.mjs`, `--handoff` in `server.mjs`). Requests queue in the socket until the server takes it; one `open` already accepted is passed across as a socket and acknowledged (`conn-held`) before the channel is closed. No channel, or no socket within 3s, and the server binds its own port; `open` then opens the real URL.
|
||||
@@ -33,7 +34,7 @@ Key design points:
|
||||
| `ledger.ndjson` | `console.mjs` | append-only, one JSON line per entry. Meter events: `launch` (every fresh `open` and every resume into another workflow), `run` (a post's `run`, id scoped by launch, with `tasks` when a built phase reports one) and `answer` (one per item the person answered in a collected send, written by `ledgerAnswers()`, id `<launch>:answer:<send stamp>:<item>`). Also `folder-issue` reports |
|
||||
| `workspace-cursor.json` | `console.mjs` | the last workspace `version` handed to the agent; advanced after the print, never backwards |
|
||||
|
||||
The page changes the workspace only through five routes: `GET /workspace` (`?check=1` re-stats every folder first), `POST /workspace/add` (path resolved against `state.worktree`, `~` expanded, case-insensitive duplicate check on win32/darwin; `not-a-folder`, `duplicate`, `bad-name`, `name-taken` + `suggest`), `POST /workspace/edit`, `POST /workspace/remove` (the original folder refuses) and `POST /workspace/browse` (one picker at a time, 409 `busy`; 404 `no-picker` when `remote` is set or no picker exists; `PLAN2CODE_PICKER_ECHO` stands in for the dialog in tests). `stateFrame()` carries `workspace` (folders, `missing`, `remote`, the current launch's folder `issues`) and `meter` (`meterView()` over the ledger), and both files are on the 1s poll; it also carries an optional `update` once the boot-time release check (`update-check.mjs`) finds a newer release. The agent hears of the workspace through `open` output (`workspace: { folders, missing? }`, which also seeds the cursor) and then each change once, as `workspace: [...]` plus `Workspace: …` reply lines on `wait` exit 0 or `chat`; a change alone never ends a `wait` slice (`pendingWorkspace` on exit 10). `post` and `open --file` lift `run` and `folderIssue` out of the patch into the ledger, never into `state.json`; an unknown event or a malformed issue is exit 3. **Remembered workspaces.** `workspace.mjs` keeps `~/.plan2code/console/workspaces.json` (`WORKSPACES_FILE`, under `PLAN2CODE_CONSOLE_HOME` in tests): `projects[<case-folded worktree>] = { path, project, specs: { "specs/<name>": … } }`, each entry `{ original: { name, description }, folders: [{ path, name, description, nested? }], at }`. `rememberedWorkspace()` answers spec, else project, else nothing; `initialWorkspace(worktree, entry)` builds from it, both in the server's first `workspaceNow()` and in `open`'s read-only `workspaceOnOpen()`, so they agree. `workspace.json` carries `scope` (the spec key or `""`). Every user change (`bumpWorkspace`, not `missing`/`found`) calls `rememberWorkspace()`. `setScope()` swaps the list, logging `removed`/`added`/`renamed`/`described` changes so the cursor stays truthful; `POST /workspace/scope { spec }` (the dashboard picker, on selection and before a launch) seeds an unsaved spec from the project's list, and `followSpecDir()` (state poll, boot) moves the scope to a posted `specDir`, saving the current list as an unsaved spec's. Two writers, each a read-modify-write of one key: the server and `console.mjs forget --spec` (Finalize Step 6). The contract is in `console-workspace.md` and `console-meter.md`, and `building.md` (per-phase `run`), so the skill prompts stay unchanged.
|
||||
The page changes the workspace only through five routes: `GET /workspace` (`?check=1` re-stats every folder first), `POST /workspace/add` (path resolved against `state.worktree`, `~` expanded, case-insensitive duplicate check on win32/darwin; `not-a-folder`, `duplicate`, `bad-name`, `name-taken` + `suggest`), `POST /workspace/edit`, `POST /workspace/remove` (the original folder refuses) and `POST /workspace/browse` (one picker at a time, 409 `busy`; 404 `no-picker` when `remote` is set or no picker exists; `PLAN2CODE_PICKER_ECHO` stands in for the dialog in tests). `stateFrame()` carries `workspace` (folders, `missing`, `remote`, the current launch's folder `issues`) and `meter` (`meterView()` over the ledger), and both files are on the 1s poll; it also carries an optional `update` once the boot-time release check (`update-check.mjs`) finds a newer release. The agent hears of the workspace through `open` output (`workspace: { folders, missing? }`, which also seeds the cursor) and then each change once, as `workspace: [...]` plus `Workspace: …` reply lines on `wait` exit 0 or `chat`; a change alone never ends a `wait` slice (`pendingWorkspaceChanges()` in `workspace.mjs` on exit 10). `post` and `open --file` lift `run` and `folderIssue` out of the patch into the ledger, never into `state.json`; an unknown event or a malformed issue is exit 3. **Remembered workspaces.** `workspace.mjs` keeps `~/.plan2code/console/workspaces.json` (`WORKSPACES_FILE`, under `PLAN2CODE_CONSOLE_HOME` in tests): `projects[<case-folded worktree>] = { path, project, specs: { "specs/<name>": … } }`, each entry `{ original: { name, description }, folders: [{ path, name, description, nested? }], at }`. `rememberedWorkspace()` answers spec, else project, else nothing; `initialWorkspace(worktree, entry)` builds from it, both in the server's first `workspaceNow()` and in `open`'s read-only `workspaceOnOpen()`, so they agree. `workspace.json` carries `scope` (the spec key or `""`). Every user change (`bumpWorkspace`, not `missing`/`found`) calls `rememberWorkspace()`. `setScope()` swaps the list, logging `removed`/`added`/`renamed`/`described` changes so the cursor stays truthful; `POST /workspace/scope { spec }` (the dashboard picker, on selection and before a launch) seeds an unsaved spec from the project's list, and `followSpecDir()` (state poll, boot) moves the scope to a posted `specDir`, saving the current list as an unsaved spec's. Two writers, each a read-modify-write of one key: the server and `console.mjs forget --spec` (Finalize Step 6). The contract is in `console-workspace.md` and `console-meter.md`, and `building.md` (per-phase `run`), so the skill prompts stay unchanged.
|
||||
- **The Subagents switch is a standing instruction, injected only on change.** The page's icon button (`#btn-subagents`, after Write a brief) and `#subagents-modal` show only when the frame's `subagents` block says `offered && supported`. `offered` comes from `public/subagents.js`; `supported` means the latest `{ "type": "open" }` line in `events.ndjson` carries `caps: ["subagents"]` (`latestOpenCaps()`), so an older skill copy's `open` hides the button. Four places hold it, one writer each:
|
||||
|
||||
| File | Writer | Holds |
|
||||
@@ -53,12 +54,13 @@ Key design points:
|
||||
- **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.
|
||||
- **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 eleven 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/notLine 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.
|
||||
- **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.
|
||||
- **`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".
|
||||
- **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 21 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 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.
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
|
||||
@@ -10,6 +10,8 @@ One row per file under `src/web-console/public/` (the games and their sound are
|
||||
| `public/md-field.css` | The frame a Markdown field wears inside its shadow root, linked beside `notepad-editor.css`. |
|
||||
| `public/app.js` | the page's entry and the only page file that starts anything: the start-up block. `index.html` loads it; it imports `screens/core.js` and the screens beside it |
|
||||
| `public/doc-files.js` | a document as the page shows it, and as a file: blocks, Markdown and HTML download |
|
||||
| `public/diff-parse.js` | the Changes tab's parser: the unified diff `changes.mjs diff` writes, read into files, hunks and numbered lines; never throws |
|
||||
| `public/diff-view.js` | the Changes tab: a `diff` doc block drawn as a file list and one unified diff, with its empty, loading and error states (Check again and Reload send `__changes`) |
|
||||
| `public/hops.js` | no imports: the hop rule, `startsClean(from, to)`, which says whether a hop from one workflow to another starts the new skill on a clean page (to or from the dashboard, into Git, or from one skill into another off a finished screen, but never out of Git or into Review); shared by `cmd-open.mjs`, `server.mjs` (its Ask reset) and `screens/core.js` |
|
||||
| `public/looks.js` | how the page looks and sounds: the saved looks, their sync, and the preferences dialog's swatches |
|
||||
| `public/mention-box.js` | the @name suggestions popover under a text box |
|
||||
@@ -20,17 +22,19 @@ One row per file under `src/web-console/public/` (the games and their sound are
|
||||
| `public/send-state.js` | whether Send is available, and what its button says |
|
||||
| `public/skills.js` | the skill list: every per-skill fact the console uses (card, order, start pose, launch scoring, subagent opt-in, which spec states light its card), data only, imported by the page and by Node; the older tables (`SKILL_CATALOG`, `START_POSES`, `CONSOLE_WORKFLOWS` and the rest, in `answers.js`) are lookups on it. Each entry also carries `weight` (what its launch and `run` score on the meter, or null), `started` and `ran` (the meter's labels for them, or null), `resume` (`"overview"`, `"folder"` or null: what the resume command takes after the skill's command) and an optional `card.help` (Help's line for the card when it differs from `blurb`). `WORKFLOWS` (every entry's workflow, in order) and `isWorkflow()` are what the CLI checks a `--workflow` against. The meter's `WEIGHTS`, `LAUNCH_LABELS` and `RUN_LABELS`, `resumeCommand()`, Help's card list and `cmd-help`'s workflow list are all derived from it, so a new skill is one entry here, not an edit to each of those |
|
||||
| `public/sound.js` | the sound cues: which plays, one at a time, held until the first click; seven cues (not Planny snoring or waking) play the file picked in Preferences, saved flat as `soundFile<Event>` (`soundFileQuestion`) out of the 19 files `sound-01` to `sound-19` in `public/sounds/` |
|
||||
| `public/spec-states.js` | the spec states (`diagnosed`, `fixed`, `exploring`, `mapped`, `planned`, `documented`, `building`, `built`, `unrecognized`): each one's picker label, the card it is the natural next step for and its recommendation, data only; which cards a state lights lives in `skills.js`, how a folder maps to a state in `classifySpec()` in `scan.mjs` |
|
||||
| `public/spec-states.js` | the spec states (`diagnosed`, `fixed`, `upgrade`, `upgraded`, `exploring`, `mapped`, `planned`, `documented`, `building`, `built`, `unrecognized`): each one's picker label, the card it is the natural next step for and its recommendation, data only; which cards a state lights lives in `skills.js`, how a folder maps to a state in `classifySpec()` in `scan.mjs` |
|
||||
| `public/card-rows.js` | how many cards a dashboard group draws per row (`steadyColumns(count, width)`): one card width per group, what fits or one column more or fewer to leave no card alone on a row (one empty corner is fine from three across), a last row still short centered; `screens/dashboard.js` applies it as `--dash-cols` and `is-centered` on draw and on resize; tested in `scripts/test-web-console-card-rows.mjs` |
|
||||
| `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/screens/ask.js` | the Ask chat, the Subagents tab, and attaching files to notes |
|
||||
| `public/screens/cards.js` | question cards: every kind, the pager, settled and in-flight records |
|
||||
| `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/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/dashboard.js` | the dashboard: cards, the spec picker, handoff chips, delete, and the first-open wake-up |
|
||||
| `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/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/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 |
|
||||
| `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/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 |
|
||||
@@ -47,7 +51,9 @@ One row per file under `src/web-console/public/` (the games and their sound are
|
||||
| `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/dashboard.css` | The dashboard: the menu, the spec picker, its confirm and the launching pane |
|
||||
| `public/styles/learning.css` | Learning's row (the paused amber tint, the sliding switch, the upward More menu) and the waiting banner, from the saved prototype on the page's tokens |
|
||||
| `public/styles/docs.css` | Documents and the doc tools |
|
||||
| `public/styles/diff.css` | The Changes tab: file list, unified diff and its states, on the page's tokens (added rows `--ok`, removed rows `--warn`) |
|
||||
| `public/styles/ending.css` | The end of a session: the hand-off and the stopping screen |
|
||||
| `public/styles/git.css` | The git board |
|
||||
| `public/styles/help.css` | The help dialog, its diagrams and its tabs |
|
||||
@@ -60,12 +66,12 @@ 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/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/help.js` | the Help dialog's PURE rules: `HELP_TABS` (20 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` (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/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/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, and the pull-request link; 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-view.js` | No DOM access of its own: `drawGitBoard(ctx)` draws the tabbed board (header, 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/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). `git-repo.mjs` re-exports it, and the board's base picker rebuilds the link in the browser with the same code |
|
||||
| `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-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/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/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 |
|
||||
@@ -82,6 +88,6 @@ One row per file under `src/web-console/public/` (the games and their sound are
|
||||
| `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/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/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. |
|
||||
| `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/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 |
|
||||
@@ -5,11 +5,11 @@ The web console is split by area: this file (the server, the CLI and the agent c
|
||||
|
||||
## Web Console
|
||||
|
||||
Optional local browser UI shipped with **every** skill. Source lives in `src/web-console/` and is fanned into each skill by an `additionalReferences: [{ source: 'web-console', target: 'web-console' }]` entry in `SOURCE_PROMPTS`, landing at `skills/<skill>/references/web-console/`. The bare `plan2code` skill is the hub: it opens the console as `--workflow dashboard`, the page draws the skill menu itself (from each `SKILLS` entry's `card` in `public/skills.js`, through `SKILL_CATALOG` in `public/answers.js`, kept in sync with the install set by a test), and a card click reaches the agent as a `{ "i": "__launch", "skill": ..., "workflow": ... }` send — the dashboard then **resumes its own session** under the launched skill's workflow (`open --resume <sid> --workflow <w>` restates `workflow`/`title`/`specDir` on the live server) and runs that skill's file. `plan2code-review` now has a console of its own AND still runs inside builds on the page (a `review` verdict on Implementation's sign-off card, the **Review it now** button on a finished quick task, or Finalize's Step 2.5 final review, offered on every run), so `plan2code-3-implement`, `plan2code-quick-task` and `plan2code-4-finalize` also carry `review.md`, the review references and `review-scope.mjs`, the same way `implement-review` does. `CONSOLE_WORKFLOWS` in `public/answers.js`, built from the same `SKILLS` list, decides whether a copied hand-off asks the next session for the console.
|
||||
Optional local browser UI shipped with **every** skill. Source lives in `src/web-console/` and is fanned into each skill by an `additionalReferences: [{ source: 'web-console', target: 'web-console' }]` entry in `SOURCE_PROMPTS`, landing at `skills/<skill>/references/web-console/`. The bare `plan2code` skill is the hub: it opens the console as `--workflow dashboard`, the page draws the skill menu itself (from each `SKILLS` entry's `card` in `public/skills.js`, through `SKILL_CATALOG` in `public/answers.js`, kept in sync with the install set by a test), and a card click reaches the agent as a `{ "i": "__launch", "skill": ..., "workflow": ... }` send — the dashboard then **resumes its own session** under the launched skill's workflow (`open --resume <sid> --workflow <w>` restates `workflow`/`title`/`specDir` on the live server) and runs that skill's file. `plan2code-review` now has a console of its own AND still runs inside builds on the page (a `review` verdict on Implementation's sign-off card, the **Review it now** button on a finished quick task, Finalize's Step 2.5 final review, offered on every run, or Dead Code's Step 7.5 final review of its removals), so `plan2code-3-implement`, `plan2code-quick-task`, `plan2code-4-finalize` and `plan2code-dead-code` also carry `review.md`, the review references and `review-scope.mjs`, the same way `implement-review` does. `CONSOLE_WORKFLOWS` in `public/answers.js`, built from the same `SKILLS` list, decides whether a copied hand-off asks the next session for the console.
|
||||
|
||||
| File | Role |
|
||||
|---|---|
|
||||
| `console.mjs` | the CLI the agent drives: `open`, `post`, `wait`, `chat` (the instant Quick question check), `keep` (copy a cited note attachment into `specs/<idea>/attachments/`), `delete-spec`, `handoff new`, `delete-handoff` (both on `handoffs.mjs`), `status`, `stop`, `help` (a compact summary for an agent that found the binary but not `console.md`; `help <topic>` prints one contract file, `help topics` lists them). `post --wait <N>` posts and waits in one command |
|
||||
| `console.mjs` | the CLI the agent drives: `open`, `post`, `wait`, `chat` (the instant Quick question check), `keep`, `forget` (copy a cited note attachment into `specs/<idea>/attachments/`), `delete-spec`, `handoff new`, `delete-handoff` (both on `handoffs.mjs`), `status`, `stop`, `help` (a compact summary for an agent that found the binary but not `console.md`; `help <topic>` prints one contract file, `help topics` lists them). `post --wait <N>` posts and waits in one command |
|
||||
| `server.mjs` | HTTP server, spawned **detached** by `open` (never as a harness background task, which get killed on compaction and at assorted timeouts) |
|
||||
| `cmd-chat.mjs` | the `chat` command: hand over Quick questions now, never waiting |
|
||||
| `cmd-help.mjs` | the `help` command: the CLI's usage and the contract's topic files; the usage's workflow list and its build sessions come from `WORKFLOWS` and `isBuild()` in `skills.js` |
|
||||
@@ -18,7 +18,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
|
||||
| `open-link.mjs` | the desktop app's webview opens no new windows, so the page there sends links off the console (`linkLeavesPage()` in `public/app-bridge.js`: http or https on another origin, caught in `wireChrome()`) to `POST /open-link`. `linkToOpen()` takes http and https only (400 otherwise); `openLink()` starts the default browser with the link as one argument, never through a shell (`rundll32 url.dll,FileProtocolHandler` on Windows, `open` on macOS, `$BROWSER` or `xdg-open` elsewhere) and skips it under `PLAN2CODE_NO_BROWSER`. When that fails the page shows the link with a Copy button to paste into a browser |
|
||||
| `loop-setup.mjs` | the Implementation Loop's setup, remembered per project in `~/.plan2code/console/loop-setup.json` (one entry per folded project folder, schema 1): defaults, validation and the read and write the `/loop-setup` route uses. The app reads the same file itself for the quick check, so the page never carries that command |
|
||||
| `spec-carry.mjs` | the spec a desktop app's New Session carries to the fresh dashboard: one short-lived `~/.plan2code/console/spec-carry.json` (`{project, spec, at}`), written by `restart_brief::leave_spec` in the app from the old session's `specDir` (or, from a dashboard, its picker's `specSel` in the draft), taken once by `POST /spec-carry` (`takeSpecCarry`: same folded project, under ten minutes old, one folder under `specs/`) and used by `loadSpecCarry()` in `selectors.js` only when the new picker lists that spec |
|
||||
| `cmd-post-wait.mjs` | `post` and `wait`: publish a patch, then collect what the person sent |
|
||||
| `cmd-post-wait.mjs` | `post` and `wait`: publish a patch, then collect what the person sent. `sessionActions()` hands the send's `__` actions to the agent whole: `__delete`, a `__launch` with its `fromBanner` (sent from a dashboard showing lessons waiting), and `__learning` with every field (`{ "i": "__learning", "do": ... }`, `do` one of `LEARNING_ACTIONS` in `public/answers.js`: `review`, `switch-on`, `switch-off`, `move-log` or `remove`). `__learning` is not a hop: the dashboard agent runs `lessons.mjs`, resumes as the dashboard and posts the menu again, and `pointers.mjs` names `console-launches.md` for it. Pause for me never reaches the agent (`POST /learning/pause`) |
|
||||
| `cmd-small.mjs` | the small commands: keep, forget, delete-spec, handoff, delete-handoff, status and stop; `handoff new` refuses an unknown `--workflow` the same way `open` does |
|
||||
| `files.mjs` | where the console's files live, how they are written safely, and the argument parser both command lines share |
|
||||
| `agents.mjs` | the rules of `~/.plan2code/agents.json` (see "Agents file" in [the install file](./AGENTS-architecture-install.md)), console side: `normalizeAgents()` reads the file into clean entries and warnings, never throwing; `validateForSave()` checks what User Preferences sends and names the first bad entry and field; `makeId()`, `buildArgs()` (the command line from an entry) and `resolveCommand()` (where a command runs from, never running it). Served by `GET` / `POST /agents` and `POST /agents/test` in `routes.mjs` |
|
||||
@@ -26,10 +26,11 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
|
||||
| `inbox.mjs` | the Quick question chat's inbox beside the card slot |
|
||||
| `console-docs.md` | the topic file for `docs` in a patch (tabs of blocks), named by the console at the first patch that carries `docs`; not read up front. Byte-budgeted with the card and the notes in `scripts/test-console-wire-budgets.mjs` |
|
||||
| `pointers.mjs` | which topic file the console names and when: once per session per topic, remembered in the session folder (`pointers.json`), reset by a resume |
|
||||
| `patches.mjs` | checking and merging an agent's patch into the session state: `validate()` (the house rules; allows `templates` only as `"idea"` on a `text` item, anything else exits 3), the patch merge, `resolveDocFiles()` and `applyPatch()` |
|
||||
| `routes.mjs` | every URL the page can call, in one ordered list (`ROUTES`, walked by `handle()`); `server.mjs` hands each request to it |
|
||||
| `scan.mjs` | what the dashboard knows about the repo: `scanProject()`, `classifySpec()` (a folder's files to a spec state), `TASK_LINE_RE` (re-exported from `spec-files.mjs`) and `removeSpec()` |
|
||||
| `sessions.mjs` | a session's roots and handle files (`repoRoots()`, `healthOk()`, `attachmentName()`: the kept-file name `<slug>-<id8>.<ext>`, the same upload always gets the same name, `readOverview()`) and the console folder's housekeeping: the three sweeps `open` runs fire-and-forget after it prints (`sweepUploads()`, `staleSessions()` / `removeSessions()`, `staleScratch()` / `removeScratch()`) and `cleanupFindings()` / `removeCleanup()` for User Preferences → System → Cleanup |
|
||||
| `metrics-pattern.json` | the PLAN-DRAFT scrape shapes the bait scanner in `patches.mjs` reads (`METRICS_BAIT`); one of three copies with the skill scripts' `SCRAPE` and `plan2code-metrics/src/metrics-pattern.json`, which `test-web-console-hardening.mjs` keeps in step |
|
||||
| `patches.mjs` | checking and merging an agent's patch into the session state: `validate()` (the house rules; allows `templates` only as `"idea"` on a `text` item, anything else exits 3; the `lessons` kind, the approval card `lessons.mjs list` prints, is checked by `lessonsProblems()` against `LESSON_ROW_TYPES`, only one may be open at a time, and it is the one card the dashboard accepts, drawn there in a dialog for Review from the Learning banner; its `rows` and its `firstAsk.lesson` are the project's own words, which Keep saves as noted, so the wording scan leaves them out and checks only the card's own title, body, opening and first-ask sentences), the patch merge, `resolveDocFiles()` (`file` blocks and the refresh of `file` and `diff` blocks), `resolveDocImages()` (`image` blocks, and `diff` blocks: `{ id, diff: "changes.diff" }` names a `.diff` file directly in the session folder, read with `fs.realpathSync.native` confined to that folder and cut at `DOC_FILE_MAX` with the too-large line; stored as `diff` plus `text`, left out of the wording scan) and `applyPatch()` |
|
||||
| `routes.mjs` | every URL the page can call, in one ordered list (`ROUTES`, walked by `handle()`); `server.mjs` hands each request to it. Learning's three: `POST /learning/pause` (origin-checked; `{ paused: boolean }`, `400 bad-request` otherwise, `409 not-on` unless Learning is on or paused) writes the personal pause through `writePause()` (`pause.json` under `~/.plan2code/learning/<key>/`, the server's only write for Learning, never into the project), patches `scan.learning` in `state.json` in place and pushes it, so the row repaints with no agent; `GET /learning/state` returns `learningScan()` worked out now (`{}` when the settings format is unknown; the Loop's stop card, a page after a pause); `GET /learning/lessons` returns `{ files: [{ name, title, text }] }` for Open the lessons, read-only: `general.md` first, then every other `.md` directly in the project's `.plan2code/lessons/` in name order, plain files only (no link, no sub-folder, at most 100 files of 512 KB each). Both `GET`s send `cache-control: no-store` |
|
||||
| `scan.mjs` | what the dashboard knows about the repo: `scanProject()`, `classifySpec()` (a folder's files to a spec state; a `DIAGNOSIS-*.md` gives `diagnosed` or `fixed`, an `UPGRADE-*.md` brief from Update dependencies `upgrade` ("Upgrade ready") or, once its `**Status:**` reads `Done`, `upgraded` ("Upgrade done"), and a plan conversation or pathfinder map wins over either), `TASK_LINE_RE` (re-exported from `spec-files.mjs`) and `removeSpec()`. `open` (`cmd-open.mjs`) adds three fields that live outside the repo's specs, so `specs.mjs list` never sees them: `handoffs`, `handoffsDir` and `learning` (`learningScan()`: `{ state, pausedSince, waiting, oldestDays }`, `state` one of `not-set-up`, `off`, `on`, `paused`; left out when the settings format is unknown or the read fails, so the page draws no Learning row) |
|
||||
| `sessions.mjs` | a session's roots and handle files (`repoRoots()`, `healthOk()`, `attachmentName()`: the kept-file name `<slug>-<id8>.<ext>`, the same upload always gets the same name, `readOverview()`) and the console folder's housekeeping: the three sweeps `open` runs fire-and-forget after it prints (`sweepUploads()`, `staleSessions()` / `removeSessions()`, `staleScratch()` / `removeScratch()`) and `cleanupFindings()` / `removeCleanup()` for User Preferences → System → Cleanup. `KEPT_PLAN2CODE_ENTRIES` names the entries at the top of `~/.plan2code/` that Cleanup never offers (`console`, `bin`, `launcher.json`, `install.json`, `models.json`, `handoffs`, `notepads`, `app`, `app.json`, `agents.json`, `prototypes`, `learning`); a new top-level entry joins it and the Cleanup test in `scripts/test-web-console-server.mjs` |
|
||||
| `settings.mjs` | the person's saved console settings: Subagents and pull-request hosts |
|
||||
| `spec-files.mjs` | no imports: how a spec's markdown files are read, `MARKERS`, `TASK_LINE_RE`, `TASK_ID_RE`, `CHECKBOX_RE`, `STATUS_RE`, `statusOf()` and `countTasks()`; shared by `scan.mjs`, `patches.mjs` and `src/skill-scripts/specs.mjs` (through `consoleModule()`) |
|
||||
| `static.mjs` | serving the page's own files: `SERVABLE` (the allow-list), `TYPES`, caching and ETags, the accent colors, and `CSS_ORDER` + `joinedStyles()`, the one place the cascade order is stated |
|
||||
@@ -39,10 +40,11 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
|
||||
| loop setup `phaseStrength` / `strengths` | `loop-setup.mjs` keeps the per-project toggle and, per spec folder, a list of `{n, name, strength}` picks, pruned as specs finish and phases move (twin: `LoopSetup` in `loop_driver.rs`). `loop_driver.rs` starts a phase with `AgentManager::start_phase_on(prompt, model, effort, env)` and sets `PLAN2CODE_LOOP_STRENGTH` (thrifty, balanced or best) in its environment, which `cmd-open.mjs` reads to give the phase's helpers the same Helper strength line; a retry goes one step up with `models::next_strength` (Rust twin of `nextStrength`; a Match my session phase stays) |
|
||||
| `git-repo.mjs` | the one read-only reader of a git repository: the worktree status (`countPending()`, behind `pendingFiles()`), the branch table, the default branch, a merge or rebase in progress, the remotes and their web addresses, the last fetch and the pull-request link; `snapshot()` is what `open` and every `reread` store as `state.git`. Every git call carries `GIT_OPTIONAL_LOCKS=0`, so a background look never takes the index lock. Imported by `cmd-open.mjs`, `cmd-post-wait.mjs` and `sessions.mjs`; the git skill's `git.mjs` reaches it through `common.mjs` |
|
||||
| `handoffs.mjs` | the handoff store, the only code that names, lists, marks, deletes and sweeps handoffs, all in `~/.plan2code/handoffs/` (`PLAN2CODE_HANDOFFS_DIR` for tests; `PLAN2CODE_NOW` pins its clock): `newHandoff()` claims `YYYY-MM-DD-HHmm-handoff` (`-2`, `-3` on a clash, the `.json` created exclusively) and writes only `<id>.json` (`{ v: 1, id, title, worktree, project, spec, workflow, skill, written, fromStop, usedAt }`), the agent writing `<id>.md`; `listHandoffs(worktree)` (unused, same worktree, `.md` present, newest first, title and Next task read off the document); `readHandoffMeta()`, `markHandoffUsed()`; `removeHandoff()` (`HANDOFF_ID` only, regular files, never a link, realpath inside the folder, throws on any refusal); `staleHandoffs()` / `removeHandoffs()` for the sweep |
|
||||
| `learning.mjs` | Learning's core, shared with the `lessons.mjs` skill script: the one `learningState()` (not set up, off, on, paused, unknown), the repository key, the tracked `.plan2code/settings.json` read, and the two stores on this machine under `~/.plan2code/learning/<key>/` (`pause.json`, `waiting/<id>.json`; `PLAN2CODE_LEARNING_DIR` moves them for tests); `learningScan()` is the dashboard's `scan.learning`, read without pruning. Never writes into a project |
|
||||
| `notepads.mjs` | the notebook store (the feature is named Notebook; its code, routes and storage folder keep the name `notepad`), the only code that names, reads, writes and removes notebooks, one per folder Plan2Code runs in, in `~/.plan2code/notepads/<folder-name>-<12 hex>/` (`PLAN2CODE_NOTEPADS_DIR` for tests), split into named tabs: `meta.json` (`{ v: 2, folder, created }`), `tabs.json` (`{ v: 1, order, last, tabs: { id: { name, created, sent? } } }`) and `tabs/<id>/note.md` with `tabs/<id>/images/`. `notepadKey()` (the folder's basename slug and the first 12 hex of `sha256(foldKey(folder))`), `listTabs()` / `defaultTabId()`, `readNotepad(folder, tab)` (never creates or writes anything; `{ tabs, last, tab }` with the tab's `text`, `savedAt` and `images` repeated at the top), the tab changes `createTab()` / `renameTab()` / `reorderTabs()` / `setLastTab()` / `deleteTab()` (index first, then the folder; names pass `normalizeTabName()`, `TAB_NAME_MAX` 40, any case compared by `nameKey()`, `NOTEPAD_MAX_TABS` 20), `saveNote(folder, tab, text)` (1 MB cap, atomic), `addImage()` / `addThumb()` / `removeImage()` (JPEG bytes only, 200 pictures per tab, UUID names), `imagePath()` (regular files whose realpath stays inside the folder), `staleNotepads(now, maxAgeMs)` (the real folders directly under it named like a key, never a link or a file, whose newest file is at least `maxAgeMs` old, as `{ key, folder, path }` with `folder` from `meta.json` or null), `removeNotepad(key)` (the key checked against `NOTEPAD_KEY_RE`, the path kept inside the notepads folder by `path.relative`, a link refused, then the whole folder removed; User Preferences, Cleanup is its only caller) and `NotepadError` (`code` and `status`, turned into `{ error }` by the `/notepad` routes). **Migration:** a notepad in the first shape (`note.md` and `images/` at the top) reads as one virtual tab, Notes (`LEGACY_TAB_ID`), and writes nothing; its first write moves the files into `tabs/<LEGACY_TAB_ID>/` and writes `tabs.json` last, every step safe to run again after a crash. A `tabs.json` that does not hold up is set aside as `tabs.json.corrupt` and rebuilt from the tab folders on the next write. Every write runs under a `notepad.lock` in the notepad's folder. The agent CLI never imports it: nothing in a notepad reaches the agent |
|
||||
| `picker.mjs` | the per-OS native folder picker behind **Browse…** (`pickerCommand()` → `{ command, args, env }` or `null`; `pickFolder()` runs it with async `spawn`, so the server keeps serving while the dialog is open). Copied from `src/launcher/plan2code.js` (self-contained CommonJS, so it cannot be shared) with the prompt as a parameter; a drift test keeps the two in step |
|
||||
| `update-check.mjs` | the dashboard's release check, server-only (never in `SERVABLE`): `compareVersions()` (numeric X.Y.Z, `null` otherwise), `latestTag()` (the highest `refs/tags/vX.Y.Z`, peeled `^{}` and pre-release tags skipped), `checkForUpdate({ installed, cacheFile, now, run })` (never throws) and `runLsRemote()` (`git ls-remote --tags` on the repo: no shell, `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, SSH `BatchMode` when `GIT_SSH_COMMAND` is unset, `windowsHide`, killed at 10 s; git authenticates itself, the console never touches a credential). The answer, failures included, is cached for an hour in `~/.plan2code/console/update-check.json` (`UPDATE_CHECK_FILE`, in `PROTECTED_CONSOLE_FILES` so no sweep removes it). `server.mjs` starts it after the ready line and never awaits it; `stateFrame()` carries `update: { installed, latest }` only when a newer release exists (its `latest` is part of `haveKey()`, so a page that connected first still gets it), and `GET /version` returns `{ version, latest }`. Tests seed a fresh cached failure in every console home, so no test server reaches the network. The `plan2code` launcher reads the same cache for its terminal release notice (a copy of this module sits in `~/.plan2code/bin/`) |
|
||||
| `console.md` | the core of the agent-facing contract, read once per conversation (every skill ships the same copy, so a dashboard hop never re-reads it): starting, the turn (`post --wait`, the exit codes, handling a send, `settle`), posting, the payload and its kinds, documents (including `file` blocks), the house rules, and an index of the topic files below with the moment each is read. A test caps it at 24,000 characters |
|
||||
| `console-finish.md` · `console-stop.md` · `console-chat.md` · `console-workspace.md` · `console-subagents.md` · `console-launches.md` · `console-meter.md` · `console-attachments.md` · `console-trouble.md` | topic files, each read only when its moment first comes: finishing (the finish and its buttons), stop requests (the way home mid-workflow, `stopWarning`, resuming a pause), Quick questions, the Workspace, standing instructions and helper reports, dashboard launches and the menu payload, the session meter's `run` events (read only when a `run` is refused: the notes inline every `run`), keeping a cited note attachment, and recovery |
|
||||
| `notes/<workflow>.md` | per-workflow notes (`init` for both inits, `pathfinder` with Briefs, `plan`, `revise-plan`, `document`, `implement` for both builds, `loop` for a build the desktop app's Implementation Loop runs with `--loop` (where it reports a `loopOutcome` instead of asking for sign-off), `quick-task`, `review`, `finalize`, `handoff`, `changelog`, `git`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`). Each skill's Interface line reads `<D>/console.md` and its own notes file right after `open`; a test checks every skill names one that exists |
|
||||
| `notes/<workflow>.md` | per-workflow notes (`init` for both inits, `pathfinder` with Briefs, `plan`, `revise-plan`, `document`, `implement` for both builds, `loop` for a build the desktop app's Implementation Loop runs with `--loop` (where it reports a `loopOutcome` instead of asking for sign-off), `quick-task`, `review`, `finalize`, `handoff`, `changelog`, `git`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`, `ui-prototype`). Each skill's Interface line reads `<D>/console.md` and its own notes file right after `open`; a test checks every skill names one that exists |
|
||||
| `building.md` · `building-review.md` | the build half of the contract, for `implement`, `implement-review` and `quick-task`: progress posts (`agent.activity`, `agent.quietMinutes`, `file` blocks re-read with `refresh`), the chat check between tasks, questions mid-build and stop requests; `building-review.md` is the review run on the page (the sign-off's `review` verdict, **Review it now**, Implement + Review's Stage 2, Finalize's Step 2.5), read only when asked for |
|
||||
@@ -5,7 +5,7 @@
|
||||
|
||||
```
|
||||
plan2code/
|
||||
├── src/ # Source workflow prompts (19 markdown files)
|
||||
├── src/ # Source workflow prompts (21 markdown files)
|
||||
│ ├── plan2code-0-pathfinder-references/ # Reference files for pathfinder skill
|
||||
│ │ ├── brief.md # Dated plain-English decision briefs
|
||||
│ │ ├── chart.md # MODE A: destination + frontier grills, templates
|
||||
@@ -18,7 +18,9 @@ plan2code/
|
||||
│ ├── shared-references/ # Reference files shared across skills
|
||||
│ │ ├── building-habits.md # Find the cause, test first, pin behavior (quick-task, implement, implement-review, test)
|
||||
│ │ ├── helper-strength.md # How strong a model and how much effort each helper gets (init, init-update, pathfinder, plan, revise-plan, document, quick-task, implement, implement-review, review, finalize, xray, diagnose, pr-prep, test)
|
||||
│ │ └── test-runs.md # Choosing what tests to run: targeted per task and phase, full suite only where the plan puts it (document, implement, implement-review, quick-task, review, finalize, pr-prep, test)
|
||||
│ │ ├── lessons.md # Learning: the fixed words and when a skill runs each `lessons.mjs` command (dashboard, pathfinder, plan, revise-plan, document, implement, implement-review, review, finalize, quick-task, xray, diagnose, pr-prep, test, dead-code, ui-prototype)
|
||||
│ │ ├── review-in-build.md # The review a building skill runs on its own work (quick-task, implement, implement-review, review, finalize, dead-code)
|
||||
│ │ └── test-runs.md # Choosing what tests to run: targeted per task and phase, full suite only where the plan puts it (document, implement, implement-review, quick-task, review, finalize, pr-prep, test, dead-code)
|
||||
│ ├── plan2code-review-references/ # Reference files for review skill
|
||||
│ │ ├── verification-protocol.md # Deep verification + confidence calibration
|
||||
│ │ ├── dimensions.md # 11 dimensions with detailed checklists
|
||||
@@ -29,8 +31,15 @@ plan2code/
|
||||
│ │ └── ai-agent-file-sync.md # Step 7: replace AI configs with AGENTS.md refs
|
||||
│ ├── plan2code-4-finalize-references/ # Reference files for finalize skill
|
||||
│ │ └── community-feedback-submission.md # STEP 6.5 payload schema + submission tiers
|
||||
│ ├── skill-scripts/ # Scripts shared across skills: install.js copies the ones a skill lists into skills/<skill>/scripts/ (specs, commit-msg, review-scope, agents-md, agent-files, glob, test-map, test-match, test-commands, run-check, common)
|
||||
│ └── plan2code-<skill>-scripts/ # A skill's own scripts, same copy rule (pathfinder, finalize, changelog, git, xray, pr-prep and test each have one)
|
||||
│ ├── plan2code-dead-code-references/ # Reference files for dead-code skill
|
||||
│ │ └── caller-search.md # How to search for a symbol's callers before calling it dead
|
||||
│ ├── plan2code-ui-prototype-references/ # Reference files for ui-prototype skill
|
||||
│ │ ├── ui-prototype-contract.md # The contract between model-written variants and the shipped shell
|
||||
│ │ ├── ui-prototype-design.md # Making each variant look designed: structure, type, color, the dials
|
||||
│ │ ├── ui-prototype-rounds.md # Rounds, the paste back, the save into a spec
|
||||
│ │ └── ui-prototype-shell/ # The page shell the script assembles every round from (shell.html, shell.js, shell.css, base.css)
|
||||
│ ├── skill-scripts/ # Scripts shared across skills: install.js copies the ones a skill lists into skills/<skill>/scripts/ (specs, commit-msg, review-scope, agents-md, agent-files, glob, test-map, test-match, test-commands, run-check, lessons, common)
|
||||
│ └── plan2code-<skill>-scripts/ # A skill's own scripts, same copy rule (pathfinder, finalize, changelog, git, xray, pr-prep, test and dead-code each have one)
|
||||
├── plan2code-bot/ # Autonomous end-to-end workflow test runner (TypeScript, tsup, Claude Agent SDK, vitest); user docs in .readme/test-bot.md
|
||||
├── plan2code-metrics/ # Recursive self-improvement toolchain
|
||||
│ ├── src/ # TypeScript source
|
||||
@@ -47,7 +56,7 @@ plan2code/
|
||||
│ └── plan2code.ico # Desktop shortcut icon (Windows)
|
||||
├── src/web-console/ # Local browser UI bundled into every skill (Node.js, zero deps, no build)
|
||||
│ ├── console.mjs # CLI the agent drives: open, post, wait, chat, keep, status, stop, help
|
||||
│ ├── server.mjs, routes.mjs, static.mjs, cmd-*.mjs, picker.mjs, and the by-job files (files, sessions, patches, scan, inbox, workspace, settings, agents, agent-lookup, git-repo, handoffs, in-app, loop-setup, notepads, open-link, pointers, spec-files, update-check)
|
||||
│ ├── server.mjs, routes.mjs, static.mjs, cmd-*.mjs, picker.mjs, and the by-job files (files, sessions, patches, scan, inbox, workspace, settings, agents, agent-lookup, git-repo, handoffs, in-app, learning, loop-setup, notepads, open-link, pointers, spec-files, update-check)
|
||||
│ ├── console.md, console-*.md, notes/, building*.md # Agent-facing contract (console.md read once, the rest on demand)
|
||||
│ └── public/ # Page assets served to the browser
|
||||
├── scripts/ # Development scripts
|
||||
@@ -71,7 +80,7 @@ plan2code/
|
||||
│ └── plan2code-<name>/ # SKILL.md plus references/ and scripts/ where present
|
||||
│ # Generated by npm run build:skills; consumed by skills add
|
||||
├── .husky/ # Git hooks (husky)
|
||||
│ └── pre-commit # Runs fix-line-endings, then character count validation
|
||||
│ └── pre-commit # Refuses a staged `nul` file (check-staged-nul), runs fix-line-endings, then character count validation
|
||||
├── .agents-docs/ # The detail files AGENTS.md links to (this file and its siblings)
|
||||
├── .claude/ # Repo-local Claude Code config (NOT installed by install.js)
|
||||
│ └── skills/ # Maintainer-only dev skills, e.g. plan2code-publish/, plan2code-launcher-update/
|
||||
@@ -100,7 +109,7 @@ plan2code/
|
||||
| `version.json` | Version metadata (name, version, description) |
|
||||
| `QUICK-REFERENCE.md` | User quick-reference card |
|
||||
| `src/statusline-claude/` | Claude CLI status bar (see [the status line file](./AGENTS-architecture-statusline.md)) |
|
||||
| `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. 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/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 |
|
||||
@@ -131,10 +140,10 @@ plan2code/
|
||||
| `plan2code.md` | — | The dashboard: opens the web console's skill menu and launches the picked skill into its own session |
|
||||
| `plan2code-init.md` | Init | Generate AGENTS.md as index + `.agents-docs/` section files (progressive discovery) |
|
||||
| `plan2code-init-update.md` | Update | Update AGENTS.md with learnings; detects and routes edits to `.agents-docs/` files |
|
||||
| `plan2code-0-pathfinder.md` | 0 | Chart a foggy idea as a map (local files, or GitHub Issues) of decision questions under `specs/<idea>/pathfinder/`, resolve them one at a time, hand a seeded PLAN-DRAFT to Step 1 |
|
||||
| `plan2code-quick-task.md` | quick | Lightweight planning for small tasks (standalone — not a pipeline step) |
|
||||
| `plan2code-1-plan.md` | 1 | Requirements analysis & architecture |
|
||||
| `plan2code-1b-revise-plan.md` | 1b | Mid-implementation revisions |
|
||||
| `plan2code-0-pathfinder.md` | 0 | Chart a foggy idea as a map (local files, or GitHub Issues) of decision questions under `specs/<idea>/pathfinder/`, resolve them one at a time, hand a seeded PLAN-DRAFT to Step 1; ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype, which replaces the runnable UI sketch |
|
||||
| `plan2code-quick-task.md` | quick | Lightweight planning for small tasks (standalone — not a pipeline step); ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype |
|
||||
| `plan2code-1-plan.md` | 1 | Requirements analysis & architecture; ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype |
|
||||
| `plan2code-1b-revise-plan.md` | 1b | Mid-implementation revisions; ships `ui-prototype.md`, its `ui-prototype-*` references, the shell and the five `ui-prototype*.mjs` scripts (ride-along) for its offer of a UI prototype |
|
||||
| `plan2code-2-document.md` | 2 | Create implementation specs |
|
||||
| `plan2code-3-implement.md` | 3 | Execute implementation (phase by phase) |
|
||||
| `plan2code-3-implement-review.md` | 3 | Execute one phase, run focused review and fixes, then request approval |
|
||||
@@ -145,7 +154,9 @@ plan2code/
|
||||
| `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-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; never commits, never installs a tool. Scripts: `dead-code.mjs` (own), `test-map.mjs`, `glob.mjs`, `test-commands.mjs`, `run-check.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-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-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 |
|
||||
|
||||
@@ -165,7 +176,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.
|
||||
|
||||
**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).
|
||||
**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.
|
||||
|
||||
@@ -198,7 +209,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.
|
||||
|
||||
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`. 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. `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.
|
||||
|
||||
**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.)
|
||||
@@ -207,7 +218,7 @@ On a terminal it first prints a Planny banner (`renderBanner()`). With more than
|
||||
- **Marker-based ownership** — every shim contains `plan2code-launcher`; `uninstallLauncher()` removes only files carrying it, leaving any other `plan2code` bin alone.
|
||||
- **Resolving the CLI** — `findAgent()` in the shared `agent-lookup.mjs` does the lookup: `PATH` (+ `PATHEXT` on Windows), the saved Windows PATH from the registry (`addSavedWindowsPath()`), npm's global bin and each entry's `installDirs`, giving `found` / `outside` / `missing` (the desktop app's `find_on_path` in `agents.rs` is its twin, held to `scripts/fixtures/agent-lookup-cases.json`). An `.exe` is spawned directly; a `.cmd`/`.bat` wrapper goes through `cmd.exe /d /s /c` with quoted args, since Node refuses to spawn batch files without a shell. The installer warns only when neither `claude` nor `devin` is on `PATH`.
|
||||
- **No bin-name overlap** — the installer's own bin in `package.json` is `plan2code-install` (→ `install.js`), so `plan2code` belongs to the launcher alone. npx runs a package's only bin whatever it's named, so the README's `npx … plan2code.git` command is unaffected; keep it the only bin, or npx will need `-c plan2code-install`.
|
||||
- **`--pick-folder` is shortcut-only** — the launcher strips it before building the CLI's args. The shortcut runs the CLI menu, then the folder picker, then the model menu. With it, a native folder picker chooses the cwd instead: on Windows, the Explorer-style `IFileOpenDialog` (`FOS_PICKFOLDERS`) via `powershell -STA -EncodedCommand`, its C# interop (`WINDOWS_PICKER_SOURCE`) passed in an env var and compiled with `Add-Type` (~0.5s), with a TopMost owner form so it doesn't open behind the console — Windows PowerShell's `FolderBrowserDialog` is the old tree-only dialog, and is kept only as the fallback when `Add-Type` is blocked (Constrained Language Mode, AppLocker); `osascript choose folder` on macOS, and `zenity` then `kdialog` on Linux (only when `DISPLAY`/`WAYLAND_DISPLAY` is set). If there's no picker, or the picker fails, it falls back to a typed `Project folder [last]:` prompt. A picker that exits 0/1 with nothing printed means the person canceled, so the launcher exits 0. The picker starts on the last pick, stored in `~/.plan2code/launcher.json`. From the shortcut, a non-zero exit other than Ctrl+C (130 / `0xC000013A`) waits for Enter so the error doesn't vanish with the window. Typed in a terminal, `plan2code` behaves exactly as before.
|
||||
- **`--pick-folder` is shortcut-only** — the launcher strips it before building the CLI's args. The shortcut runs the CLI menu, then the folder menu (`Choose a folder...` first and the default, the recent folders under it; with no recent folders, or no TTY, it goes straight to the picker), then the model menu. `Choose a folder...` runs a native folder picker that chooses the cwd instead: on Windows, the Explorer-style `IFileOpenDialog` (`FOS_PICKFOLDERS`) via `powershell -STA -EncodedCommand`, its C# interop (`WINDOWS_PICKER_SOURCE`) passed in an env var and compiled with `Add-Type` (~0.5s), with a TopMost owner form so it doesn't open behind the console — Windows PowerShell's `FolderBrowserDialog` is the old tree-only dialog, and is kept only as the fallback when `Add-Type` is blocked (Constrained Language Mode, AppLocker); `osascript choose folder` on macOS, and `zenity` then `kdialog` on Linux (only when `DISPLAY`/`WAYLAND_DISPLAY` is set). If there's no picker, or the picker fails, it falls back to a typed `Project folder [last]:` prompt. A picker that exits 0/1 with nothing printed means the person canceled, so the launcher exits 0. The picker starts on the last pick, stored in `~/.plan2code/launcher.json`. From the shortcut, a non-zero exit other than Ctrl+C (130 / `0xC000013A`) waits for Enter so the error doesn't vanish with the window. Typed in a terminal, `plan2code` behaves exactly as before.
|
||||
|
||||
**Desktop shortcut** — after the shims are written, `installLauncher()` (now async) calls `offerDesktopShortcut()`. It asks `Also add a Plan2Code shortcut to your desktop? (y/N)`, skips the question when stdin isn't a TTY, and refreshes an existing marked shortcut without asking. `installDesktopShortcut()` writes it to the real desktop (`[Environment]::GetFolderPath('Desktop')` on Windows, which covers OneDrive redirection; `xdg-user-dir DESKTOP` on Linux; `~/Desktop` otherwise):
|
||||
|
||||
|
||||
@@ -14,17 +14,18 @@ Anything a workflow step decides with one correct answer (parsing a spec's check
|
||||
|
||||
| Script | Skills | Does |
|
||||
|---|---|---|
|
||||
| `specs.mjs` | plan, revise-plan, document, implement, implement-review, review, quick-task, finalize, handoff, diagnose | `list` / `status` (the dashboard state, Phase Checklist, groups, task markers, numbering, the implement selection verdict, consistency checks) / `check` / `check-draft` / `metrics` / `mark` / `tick` / `archive`. `list` imports `scanProject()` from the bundled `web-console/scan.mjs`, and `status` calls `deriveSpecState()` and `pickPhaseFiles()` from `web-console/spec-files.mjs`, the one rule the scan also uses, so the dashboard and the skills never disagree on a spec's state (a phase with only blocked tasks left stays `building`, and `finalizeReady` lights Finalize once each has a written reason). `mark` writes the phase file's Status line on every move (`--to in-progress` too). `check`'s format rules (no Status line, a checkbox under Notes, a task pointing at a line number, a bare `[!]`) warn, and fail only a spec whose overview.md carries `<!-- plan2code-format: 2 -->`. `archive` that has to copy removes the source only once every file name and size at the target matches (`PLAN2CODE_ARCHIVE_FAULT` is its test seam) |
|
||||
| `commit-msg.mjs` | implement(-review), review, quick-task, finalize, init-update, git | The `<subject>` / `AI Assisted` commit command (two `-m` flags), with an optional `git add -- <files>` from `--files`. There is no add-everything option: `--add-all` was retired, and `scripts/test-script-git.mjs` fails if it returns anywhere in `src/` |
|
||||
| `review-scope.mjs` | review, implement(-review), quick-task, finalize, pr-prep, test | Review Mode's git fallback: files, lines, doc share, base branch |
|
||||
| `glob.mjs` | init, init-update, implement(-review), quick-task, finalize, pr-prep, test, dead-code | The glob subset (`**`, `*`, `?`, `{a,b}`) as a RegExp, and forward-slash path normalizing; imported by `test-map.mjs` and `test-match.mjs` |
|
||||
| `test-map.mjs` | init, init-update, implement(-review), quick-task, finalize, pr-prep, test, dead-code | `read` / `write` the project test map (one `\| Area \| Paths \| Run \| Shared \|` table under `## Test map` in `AGENTS.md`, or behind one link to `.agents-docs/`); every line outside the table stays byte-identical |
|
||||
| `specs.mjs` | plan, revise-plan, document, implement, implement-review, review, quick-task, finalize, handoff, diagnose, dead-code | `list` / `status` (the dashboard state, Phase Checklist, groups, task markers, numbering, the implement selection verdict, consistency checks) / `check` / `check-draft` / `metrics` / `mark` / `tick` / `archive`. `list` imports `scanProject()` from the bundled `web-console/scan.mjs`, and `status` calls `deriveSpecState()` and `pickPhaseFiles()` from `web-console/spec-files.mjs`, the one rule the scan also uses, so the dashboard and the skills never disagree on a spec's state (a phase with only blocked tasks left stays `building`, and `finalizeReady` lights Finalize once each has a written reason). `mark` writes the phase file's Status line on every move (`--to in-progress` too). `check`'s format rules (no Status line, a checkbox under Notes, a task pointing at a line number, a bare `[!]`) warn, and fail only a spec whose overview.md carries `<!-- plan2code-format: 2 -->`. `archive` that has to copy removes the source only once every file name and size at the target matches (`PLAN2CODE_ARCHIVE_FAULT` is its test seam) |
|
||||
| `commit-msg.mjs` | implement(-review), review, quick-task, finalize, init-update, git, dead-code | The `<subject>` / `AI Assisted` commit command (two `-m` flags), with an optional `git add -- <files>` from `--files`. There is no add-everything option: `--add-all` was retired, and `scripts/test-script-git.mjs` fails if it returns anywhere in `src/` |
|
||||
| `review-scope.mjs` | review, implement(-review), quick-task, finalize, pr-prep, test, dead-code | Review Mode's git fallback: files, lines, doc share, base branch |
|
||||
| `glob.mjs` | init, init-update, implement(-review), quick-task, finalize, pr-prep, test, dead-code, deps | The glob subset (`**`, `*`, `?`, `{a,b}`) as a RegExp, and forward-slash path normalizing; imported by `test-map.mjs` and `test-match.mjs` |
|
||||
| `test-map.mjs` | init, init-update, implement(-review), quick-task, finalize, pr-prep, test, dead-code, deps | `read` / `write` the project test map (one `\| Area \| Paths \| Run \| Shared \|` table under `## Test map` in `AGENTS.md`, or behind one link to `.agents-docs/`); every line outside the table stays byte-identical |
|
||||
| `test-match.mjs` | implement(-review), quick-task, finalize, pr-prep, test | `covers` (changed files to the map rows and tests that cover them, plus shared-ground hints), `gaps` (source files no test covers, ranked by recent change) and `nearest` (existing tests to read for style) |
|
||||
| `test-commands.mjs` | init, init-update, pr-prep, test, dead-code | `discover`: the whole-suite command, per-folder runners, lint/types/build checks, coverage commands already present and the language's built-in runner, from config files only |
|
||||
| `run-check.mjs` | implement(-review), quick-task, finalize, pr-prep, test, dead-code | Run one command with a timeout, kill its process tree on timeout, and classify it `passed`, `failed`, `timeout` or `not-started` with the output's tail |
|
||||
| `test-commands.mjs` | init, init-update, pr-prep, test, dead-code, deps | `discover`: the whole-suite command, per-folder runners, lint/types/build checks, coverage commands already present and the language's built-in runner, from config files only |
|
||||
| `run-check.mjs` | implement(-review), quick-task, finalize, pr-prep, test, dead-code, deps | Run one command with a timeout, kill its process tree on timeout, and classify it `passed`, `failed`, `timeout` or `not-started` with the output's tail |
|
||||
| `pr-prep.mjs` (own) | pr-prep | `template` (the PR template and its headings), `pr-url` (the create-a-PR link through `git-repo.mjs`) and `spec` (the branch's spec folder for the save offer). Read-only |
|
||||
| `coverage.mjs` (own) | test | `read --lcov` / `--go-func`: coverage output as per-file lines, hits and percent, plus the total. Read-only, runs no tool |
|
||||
| `dead-code.mjs` (own) | dead-code | `detect` (the dead-code tools the project already has, languages, file counts), `run --tool` (a tool's output as candidates), `narrow` (folders ranked by candidates), `keep list\|filter\|add\|remove` (the shared keep list, `.plan2code-dead-code/keep.md`; rows matched by file, name and the hash of the item's declaration line, `#n` for the n-th identical line, `file:` for a whole file; `remove` takes `--hash` or `--line` and exits 2 `ambiguous-entry` when two rows share a name), `backup` and `restore --verify` (copies outside the project and a checked put-back), `report write` (`.plan2code-dead-code/reports/DEAD-CODE-<date>.md`; `tool` one id or a list of ids) and `gitignore-check` / `gitignore-add`. Writes only code removals the agent makes, `keep.md` and, on a yes, a report and the `.gitignore` line |
|
||||
| `dead-code.mjs` (own) | dead-code | `detect` (the dead-code tools the project already has, languages, file counts), `run --tool` (a tool's output as candidates), `narrow` (folders ranked by candidates), `keep list\|filter\|add\|remove` (the shared keep list, `.plan2code/dead-code/keep.md`; rows matched by file, name and the hash of the item's declaration line, `#n` for the n-th identical line, `file:` for a whole file; `remove` takes `--hash` or `--line` and exits 2 `ambiguous-entry` when two rows share a name), `backup` and `restore --verify` (copies outside the project and a checked put-back), `report write` (`.plan2code/dead-code/reports/DEAD-CODE-<date>.md`; `tool` one id or a list of ids) and `gitignore-check` / `gitignore-add`. Writes only code removals the agent makes, `keep.md` and, on a yes, a report and the `.gitignore` line |
|
||||
| `deps.mjs` (own) | deps | One file in fixed sections, one adapter per ecosystem behind one interface (npm, pnpm and Yarn; Cargo; pip; uv; Go; .NET): `detect` (lockfiles, members, missing tools, the run folder under the OS temp folder), `scan` (rows, held, notScanned, stillOpen; a declared runtime it cannot cut by sets `runtimeNotChecked`; a missing or failed audit sets `notAudited`), `notes` (release-note slices via `gh api` or `fetch`), `fit` (the newest version the project's runtime runs, per adapter; a runtime hold with one becomes a pick, `unknown` rows go to the agent), `pins` (each row's exact version written in the project's own files, outside its lockfile and manifests: `pins.json`), `label` (the pure FR-6 to FR-9 rules: Safe, Check first, Warning; `reasons` plus `reasonsPlain` in plain English; a row with a pin is never Safe; a record's `usedIn` lists the files that import the package), `checks` (the checks for the baseline, or one group's targeted checks narrowed by `usedIn` and pins), `baseline` and `compare` (read `run-check.mjs --log` logs, never run checks: tests red before or flaky never blame a group), `batches` (`--picks`, `--split` narrowing), `backup`, `apply` (the package manager's own update; `failed` also on `unpicked`, `overshot` past a runtime-cut target, `undoFailed` or `needsNewerRuntime`), `fix` (one approved replacement in one project file after `apply`: never a lockfile or manifest of the batch, never under `node_modules`, `.git` or `specs`, never binary or over 1 MB, the text found exactly once; the file is backed up into the batch's backup first, so restore puts it back), `restore --verify` (byte for byte, fixed files included and named in `fixed[]`; a file it cannot put back is `mismatched {path, reason}` with `verified: false`, never a crash), `install-tool` (the exact install line of a scanner the scan listed missing; runs nothing, the prompt runs it through `run-check.mjs` after approval), `handoff` (`specs/<package>-upgrade/UPGRADE-<date>.md`, never outside `specs/`) and `cleanup`. Never runs `--force`, an audit fix or a tool install. Writes manifests and lockfiles only through `apply` and `restore`, any other project file only through `fix` after the person approved that exact change, and a ticked brief. Tests: `scripts/test-script-deps.mjs` against stub CLIs on a temp PATH and fixtures in `scripts/fixtures/deps/` named with each tool's version |
|
||||
| `agents-md.mjs` | init, init-update | AGENTS.md structure, budget, orphans, broken links, always-inline sections. With no AGENTS.md yet (Init's run, so said once), `notices` warns when `.gitignore` keeps `specs--completed/` out of git, since archived specs are then not backed up |
|
||||
| `agent-files.mjs` | init, init-update | Detect and replace other agents' config files with AGENTS.md pointers |
|
||||
| `pathfinder.mjs` (own) | 0-pathfinder | `init` (the map in its Step 5 state from `--destination`, `--scores` and `--fog`; refuses an existing map) and `add` (the next `questions/NN-<slug>.md` plus its map row), with the references' templates kept as the fallback, then `reconcile`, `frontier`, `claim`, `resolve`, `rule-out`, `trail`, `gate` (which also prints the exact PLAN-DRAFT status line `specs.mjs` reads), `lint`, `brief-data`. Writes rows as `[Name](link): tail` with no em dash, and still reads maps written the old way |
|
||||
@@ -32,7 +33,12 @@ Anything a workflow step decides with one correct answer (parsing a spec's check
|
||||
| `xray.mjs` (own) | xray | `hotspots` (churn, files changed together, often-changed files with no test, from `git log` over a capped window) and `history <path>` (commits following renames, a blame summary, PR titles and first paragraphs through `gh` when signed in, and which sources were used). Read-only |
|
||||
| `changelog-state.mjs` (own) | changelog | `state`, `bump`, `set-package-version`: the default branch's version, whether the branch's entry can be extended (not released, not on another branch), the file's heading style, the gap since the entry was last touched; only `set-package-version` writes, and only the version field |
|
||||
| `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` |
|
||||
| `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 |
|
||||
|
||||
**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.
|
||||
|
||||
**Conventions** (`common.mjs`): Node 18+ built-ins only; one JSON object on stdout (`ok: false` plus `error`, `message`, `next` on a handled failure, the same line on stderr); exit 0 ok, 1 crash, 2 bad arguments, 3 not found, 4 invalid or check failed, 5 refused; `--help` documents commands and exit codes; writes take `--dry-run`; `PLAN2CODE_NOW` pins the clock for tests. A SKILL.md names a script as `node "<S>/<name>.mjs"`, where `<S>` is `scripts/` beside it.
|
||||
|
||||
**Tests:** `scripts/test-skill-scripts.mjs` (installer plumbing and the shared scripts), `scripts/test-script-<skill>.mjs` (a skill's own, and the newer shared scripts: `test-script-test-map.mjs`, `test-script-test-match.mjs`, `test-script-test-commands.mjs`, `test-script-run-check.mjs`, `test-script-pr-prep.mjs`, `test-script-coverage.mjs`), with fixtures from `scripts/skill-script-helpers.mjs`. Importing that module rebuilds `skills/` unless `npm_lifecycle_event` is `test` (`npm test` has just built it). Git fixtures go through `copyFixture()` (`scripts/fixture-helpers.mjs`): built once per test file, copied per test, since every `git` process costs a few hundred milliseconds on Windows; a remote inside the fixture is added with `slashed()` so the copy's `.git/config` can be pointed at its own origin. They run the built `skills/` tree, and one test fails if any SKILL.md or shipped reference names a `<S>/<name>.mjs` that skill does not ship. The per-skill scripts import `./common.mjs`, which only sits beside them in the built tree, so run them from `skills/`, not `src/`.
|
||||
**Tests:** `scripts/test-skill-scripts.mjs` (installer plumbing and the shared scripts), `scripts/test-script-<skill>.mjs` (a skill's own, and the newer shared scripts: `test-script-test-map.mjs`, `test-script-test-match.mjs`, `test-script-test-commands.mjs`, `test-script-run-check.mjs`, `test-script-pr-prep.mjs`, `test-script-coverage.mjs`, `test-script-lessons.mjs`, `test-script-deps.mjs`, `test-script-changes.mjs`), with fixtures from `scripts/skill-script-helpers.mjs`. Importing that module rebuilds `skills/` unless `npm_lifecycle_event` is `test` (`npm test` has just built it). Git fixtures go through `copyFixture()` (`scripts/fixture-helpers.mjs`): built once per test file, copied per test, since every `git` process costs a few hundred milliseconds on Windows; a remote inside the fixture is added with `slashed()` so the copy's `.git/config` can be pointed at its own origin. They run the built `skills/` tree, and one test fails if any SKILL.md or shipped reference names a `<S>/<name>.mjs` that skill does not ship. The per-skill scripts import `./common.mjs`, which only sits beside them in the built tree, so run them from `skills/`, not `src/`.
|
||||
@@ -13,5 +13,6 @@ This file is an index. The architecture notes are split by area so each file sta
|
||||
| Web console: design points | [AGENTS-architecture-console-design.md](./AGENTS-architecture-console-design.md) | why the console is built as it is: preferences, the wait, the transport, notebook, handoffs, tests, adding a page file |
|
||||
| Activities | [AGENTS-architecture-activities.md](./AGENTS-architecture-activities.md) | every game but Ghoul Rush, and the rules every game follows ("Building an Activities game") |
|
||||
| Ghoul Rush | [core](./AGENTS-architecture-ghoul-core.md), [stages](./AGENTS-architecture-ghoul-stages.md), [rides](./AGENTS-architecture-ghoul-rides.md) | the files table for the Ghoul Rush game |
|
||||
| Bounce Road | [AGENTS-architecture-bounce.md](./AGENTS-architecture-bounce.md) | the files table for the Bounce Road game |
|
||||
|
||||
The web console's files tables run across six files (server and contract, page, activities, and the three Ghoul Rush files); `scripts/test-web-console-shape.mjs` reads them all and fails when a console file has no row in any of them.
|
||||
@@ -14,18 +14,18 @@
|
||||
|
||||
## Gotchas / Pitfalls
|
||||
|
||||
- **Version sync:** When adding a new version to `CHANGELOG.md`, run `node scripts/set-version.mjs <x.y.z>` (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's `references/web-console/` (the console's 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 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.
|
||||
- **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.
|
||||
- **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).
|
||||
- **Keep LF line endings:** `.gitattributes` pins `eol=lf` because `validate-char-count.js` counts the characters on disk, and a CRLF checkout adds about one per line to every prompt. Measure with `node scripts/validate-char-count.js` before trusting a near-limit prompt. Git never writes CRLF here, but tools do (Python writing in text mode on Windows, some editors and generators), so `scripts/fix-line-endings.mjs` puts every text file git sees back to LF: `npm run fix:eol` by hand, `--check` to only list, and it runs by itself as npm's `pretest`, in the husky pre-commit before the char count, and after every Write or Edit through the PostToolUse hook in `.claude/settings.json`. In a Python script that writes repo files, open them with `newline="\n"` (or write bytes) anyway.
|
||||
- **The pre-commit hook runs the LF fix, then the char-count check:** `.husky/pre-commit` is `node scripts/fix-line-endings.mjs` followed by `node scripts/validate-char-count.js`. `skills/` drift, parse errors and test failures are caught only by the tests, so run them before committing: the targeted suites for a change that stays in one area, the full `npm test` for shared code or before a PR (see "Targeted tests first" in [Development Commands](./AGENTS-development-commands.md)). Sub-package tests are separate; see [Development Commands](./AGENTS-development-commands.md).
|
||||
- **The pre-commit hook runs the `nul` check, the LF fix, then the char-count check:** `.husky/pre-commit` is `node scripts/check-staged-nul.mjs` (refuses a staged file named `nul`, which a stray `> nul` in Git Bash writes on Windows), then `node scripts/fix-line-endings.mjs`, then `node scripts/validate-char-count.js`. `skills/` drift, parse errors and test failures are caught only by the tests, so run them before committing: the targeted suites for a change that stays in one area, the full `npm test` for shared code or before a PR (see "Targeted tests first" in [Development Commands](./AGENTS-development-commands.md)). Sub-package tests are separate; see [Development Commands](./AGENTS-development-commands.md).
|
||||
- **`skills/` is generated build output (gitignored):** edit `src/` only. The installer rebuilds `skills/` on every run, so it is always up to date at install time. `npm test` runs `install.js --build-skills` so a broken `SOURCE_PROMPTS` entry or unreadable source fails CI. Never hand-edit `skills/`; `install.js --verify-skills` can diff a stale tree against `src/` when diagnosing.
|
||||
- **Metrics internal prompts have no char limit:** Files in `plan2code-metrics/src/prompts/` are NOT subject to the 20,000 char limit — only `src/plan2code-*.md` consumer-facing prompts are.
|
||||
- **User Feedback table format:** The `## User Feedback` markdown table in `overview.md` has a strict format the collector regex depends on. Field names are matched case-insensitively; the house form is `Rating`, `Reason`, `Went Well`, `Went Poorly`, and `Rating` must parse to an integer from 1 to 10. Pipe characters in values must be escaped as `\|`.
|
||||
- **PLAN-DRAFT confidence numbers are scraped by regex:** `collector.ts` scrapes the latest `specs/<feature>/PLAN-DRAFT-*.md` prose. Overall confidence falls back to prose only when `<!-- METRICS_JSON ... -->` lacks `confidence` (`collector.ts:186-196`): `Confidence: 95%`, or a table row `| Confidence | 95` with no `%`. The four *breakdown* patterns (`collector.ts:200-203`) run on every draft, METRICS_JSON or not: `/[Rr]equirements?[:\s|]+(\d{1,2})/` and its siblings match a bare dimension word followed by whitespace, a colon, or a pipe and then digits. So a PLAN-DRAFT written by anything other than `/plan2code-1-plan` Phase 7 must keep `Confidence` followed by a number (with `%`, or as a table row) **and** bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed by a number off the page — including innocent table rows like `| Requirements | 11 |`. Otherwise the metrics pipeline records a planning-step confidence that no planning step produced. `/plan2code-0-pathfinder` works around this by hyphenating the labels (`Requirements-clarity 22/25`), which breaks the character class.
|
||||
- **PLAN-DRAFT confidence numbers are scraped by regex:** `collector.ts` scrapes the latest `specs/<feature>/PLAN-DRAFT-*.md` prose. Overall confidence falls back to prose only when `<!-- METRICS_JSON ... -->` lacks `confidence` (the `confidence` patterns in `metrics-pattern.json`): `Confidence: 95%`, or a table row `| Confidence | 95` with no `%`. The four *breakdown* patterns (`breakdown` in `metrics-pattern.json`, one source shared with the console's bait scanner and the skill scripts' `SCRAPE`, kept in step by `test-web-console-hardening.mjs`) run on every draft, METRICS_JSON or not: each matches a bare dimension word followed by whitespace or a colon and then digits, or a table row whose number ends the row. So a PLAN-DRAFT written by anything other than `/plan2code-1-plan` Phase 7 must keep `Confidence` followed by a number (with `%`, or as a table row) **and** bare `Requirements` / `Feasibility` / `Integration` / `Risk` followed by a number off the page — including innocent table rows like `| Requirements | 11 |`. Otherwise the metrics pipeline records a planning-step confidence that no planning step produced. `/plan2code-0-pathfinder` works around this by hyphenating the labels (`Requirements-clarity 22/25`), which breaks the character class.
|
||||
- **Web console result-handoff invariant:** `result.json` holds answers a person pressed Send on. **An uncollected result (no `consumedAt`) is never overwritten and never deleted.** `/submit` and `/cancel` return 409 while one is pending, `open` clears the file only when it is already consumed, and `wait` stamps `consumedAt` **after** printing the result, never before, and exits by setting `process.exitCode` rather than calling `process.exit()`. That ordering is deliberate: an agent harness that kills a long shell command must not be able to land between "marked collected" and "handed over", and `process.exit()` can truncate an unflushed pipe. A repeat delivery is recoverable, a lost one is not. Two separate data-loss bugs came from breaking this in different places, and both were silent: the person sees "Sent", the agent never receives it. Any new code path that touches `result.json` must preserve the invariant, and `scripts/test-web-console-lifecycle.mjs` guards it (its "result handoff (regressions)" tests). Related: the server writes each submitted answer onto its item as `submitted`, and `validate()` in `patches.mjs` must keep excluding that field from the completion-marker and metrics-scraper scans, which are meant for agent-authored text only. A person who typed `TASK_COMPLETE` into an answer would otherwise make every later patch unpostable.
|
||||
- **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.
|
||||
@@ -35,4 +35,4 @@
|
||||
- **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.
|
||||
- **Windows global bins for metrics and bot are wrappers, not `npm link`:** on win32 the installer writes `<name>.cmd` and `<name>.ps1` into `npm config get prefix`, each running `node <package>/dist/bin/<name>.js` (the metrics and bot installers both do this). After a source change, `npm run build` in the package is enough; no reinstall.
|
||||
- **plan2code-metrics only runs from a repo checkout:** `analyzer.ts` and `improver.ts` load `src/prompts/analyze.md` / `improve.md` at runtime through `new URL('../src/prompts/...', import.meta.url)`, resolved relative to `dist/` (`analyzer.ts:11`, `improver.ts:13`). A packed or copied `dist/` without `src/prompts/` fails.
|
||||
- **plan2code-metrics only runs from a repo checkout:** `analyzer.ts` and `improver.ts` load `src/prompts/analyze.md` / `improve.md` at runtime through `new URL('../src/prompts/...', import.meta.url)`, resolved relative to `dist/` (`ANALYZE_PROMPT_PATH` in `analyzer.ts`, `IMPROVE_PROMPT_PATH` in `improver.ts`). A packed or copied `dist/` without `src/prompts/` fails.
|
||||
@@ -80,6 +80,8 @@ The full `npm test` takes minutes and drives a browser per page suite. When a ch
|
||||
|
||||
The fast lane is `npm run test:fast` (`scripts/test-fast.mjs`): it runs the files in `scripts/test-lanes.json`'s `fast` array through `node-test.mjs`. **Two-list rule:** every `scripts/test-*.mjs` is named in exactly one of `fast` and `skipFast`. A new test file that starts a console server, runs a console page suite or plays a game goes in `skipFast`; anything else goes in `fast`. `node scripts/check-test-lanes.mjs` fails (and runs first in `npm test`) when a file is in neither list, in both, or named but missing. `test-fast.mjs` itself is a runner and sits in `skipFast`. `.github/workflows/fast-tests.yml` runs the lane on Ubuntu for every pull request, and on all three systems for pushes to main and pull requests labeled `full-matrix`.
|
||||
|
||||
The same areas as one-command rows live in the [Test map](./AGENTS-test-map.md), which PR Prep and Test read; keep both in step.
|
||||
|
||||
| What changed | Run |
|
||||
|---|---|
|
||||
| An Activities game (`public/activities/*`), `public/tones.js` or `public/music.js` | `node --test scripts/test-web-console-tones.mjs scripts/test-web-console-activities.mjs`, plus the game's own `scripts/test-web-console-activities-<game>*.mjs` when it has one; add `test-web-console-page-activities.mjs` when the Activities window or its switches changed |
|
||||
@@ -88,6 +90,8 @@ The fast lane is `npm run test:fast` (`scripts/test-fast.mjs`): it runs the file
|
||||
| The launcher (`src/launcher/`) | `node --test scripts/test-launcher.mjs` |
|
||||
| A skill's script | `npm run build:skills`, then `node --test scripts/test-script-<skill>.mjs` (and `test-skill-scripts.mjs` for the shared plumbing) |
|
||||
| Dead Code (`src/plan2code-dead-code-scripts/`, `scripts/fixtures/dead-code/`) | `npm run build:skills`, then `node scripts/node-test.mjs scripts/test-script-dead-code.mjs` |
|
||||
| Update Dependencies (`src/plan2code-deps-scripts/`, `scripts/fixtures/deps/`) | `npm run build:skills`, then `node scripts/node-test.mjs scripts/test-script-deps.mjs` |
|
||||
| UI Prototype (`src/skill-scripts/ui-prototype*.mjs`, `src/plan2code-ui-prototype-references/`, `scripts/fixtures/ui-prototype/`) | `npm run build:skills`, then `node scripts/node-test.mjs scripts/test-script-ui-prototype.mjs scripts/test-ui-prototype-page.mjs` |
|
||||
| A workflow prompt (`src/plan2code-*.md`) | `node scripts/validate-char-count.js` and `node scripts/check-skill-table.mjs` |
|
||||
| A new skill or console workflow | First update the hand-written tables that list every workflow: the `SUBAGENT_WORKFLOWS` count and the meter's `WEIGHTS`, `LAUNCH_LABELS` and `RUN_LABELS` in `test-web-console-logic.mjs`, `notesFor` in `test-web-console-speed.mjs`, the event list in `src/web-console/console-meter.md` (checked by `test-web-console-chat-stress.mjs`) and a `BUDGETS.notes` entry in `test-console-wire-budgets.mjs`. Then run those four suites plus `test-web-console-skills.mjs` and `test-web-console-spec-states.mjs`; the PR Prep and Test build missed all five tables and only the full suite caught them |
|
||||
| Docs or comments only | `node --test scripts/test-us-english.mjs scripts/test-line-endings.mjs` |
|
||||
@@ -167,7 +171,7 @@ The skills CLI owns distribution from step 4 onward. It stores canonical skills
|
||||
| Path | `skills/<skill-name>/SKILL.md` |
|
||||
| Skill name | `generateSkillName(prompt)`, such as `plan2code-1-plan` or `plan2code-init` |
|
||||
| Frontmatter | `name`, `description`, `disable-model-invocation: true` |
|
||||
| Reference files | `skills/<skill-name>/references/<path>`, copied from `src/<prompt>-references/` and `additionalReferences` (any file type; every skill bundles `web-console/` plus a copy of `version.json`) |
|
||||
| Reference files | `skills/<skill-name>/references/<path>`, copied from `src/<prompt>-references/` and `additionalReferences` (any file type; every skill bundles `web-console/`, and a skill with scripts also gets `scripts/version.json`) |
|
||||
| Scripts | `skills/<skill-name>/scripts/<file>.mjs`, plus `common.mjs` and a generated `version.json` (see Skill Scripts in the architecture doc) |
|
||||
|
||||
`disable-model-invocation: true` is unconditional because these workflows are user-initiated. Agents that do not recognize the field ignore it.
|
||||
|
||||
@@ -87,7 +87,7 @@ Feedback is collected during finalize (Step 5) or retroactively via the CLI. Pip
|
||||
| `archival_success_rate` | ≥ 0.99 | higher is better |
|
||||
| `avg_user_rating` | ≥ 7.0 | higher is better |
|
||||
|
||||
On start the CLI asks for the plan2code repo path (default: saved `plan2codeRepoPath` in `~/.plan2code-metrics.json`, else auto-detected up to 5 parent dirs) and the project path (default: cwd). Data is stored in `<project>/.plan2code-metrics/` (runs/, aggregated.json, proposals/).
|
||||
On start the CLI asks for the plan2code repo path (default: saved `plan2codeRepoPath` in `~/.plan2code-metrics.json`, else auto-detected up to 5 parent dirs) and the project path (default: cwd). Data is stored in `<project>/.plan2code/metrics/` (runs/, aggregated.json, proposals/).
|
||||
|
||||
## Prompt fingerprints and the one-time regrouping
|
||||
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
# Test map
|
||||
> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.
|
||||
|
||||
Which checks cover which files, read by PR Prep and Test (`test-map.mjs read` checks every path and command). Per-area web console suites and the new-skill checklist do not fit one row: see "Targeted tests first" in [Development Commands](./AGENTS-development-commands.md).
|
||||
|
||||
| Area | Paths | Run | Shared |
|
||||
|---|---|---|---|
|
||||
| Activities games | `src/web-console/public/activities/**`, `src/web-console/public/tones.js`, `src/web-console/public/music.js` | `node --test scripts/test-web-console-tones.mjs scripts/test-web-console-activities.mjs` | no |
|
||||
| Launcher | `src/launcher/**` | `node --test scripts/test-launcher.mjs` | no |
|
||||
| Dead Code script | `src/plan2code-dead-code-scripts/**`, `scripts/fixtures/dead-code/**` | `npm run build:skills && node scripts/node-test.mjs scripts/test-script-dead-code.mjs` | no |
|
||||
| Update Dependencies script | `src/plan2code-deps-scripts/**`, `scripts/fixtures/deps/**` | `npm run build:skills && node scripts/node-test.mjs scripts/test-script-deps.mjs` | no |
|
||||
| UI Prototype script and shell | `src/skill-scripts/ui-prototype*.mjs`, `src/plan2code-ui-prototype-references/**`, `scripts/fixtures/ui-prototype/**` | `npm run build:skills && node scripts/node-test.mjs scripts/test-script-ui-prototype.mjs scripts/test-ui-prototype-page.mjs` | no |
|
||||
| Lessons script | `src/skill-scripts/lessons.mjs`, `src/web-console/learning.mjs` | `npm run build:skills && node scripts/node-test.mjs scripts/test-script-lessons.mjs` | no |
|
||||
| Changes tab and script | `src/skill-scripts/changes.mjs`, `src/web-console/public/diff-parse.js`, `src/web-console/public/diff-view.js`, `src/web-console/public/styles/diff.css` | `npm run build:skills && node scripts/node-test.mjs scripts/test-script-changes.mjs scripts/test-web-console-diff-parse.mjs scripts/test-web-console-page-changes.mjs` | no |
|
||||
| Learning on the console | `src/web-console/learning.mjs`, `src/web-console/public/screens/learning-row.js`, `src/web-console/public/styles/learning.css` | `node scripts/node-test.mjs scripts/test-web-console-learning.mjs scripts/test-web-console-page-learning.mjs` | no |
|
||||
| Workflow prompts | `src/plan2code-*.md` | `node scripts/validate-char-count.js && node scripts/check-skill-table.mjs` | no |
|
||||
| Desktop app | `plan2code-app/**` | `cd plan2code-app && cargo test` | no |
|
||||
| Metrics | `plan2code-metrics/**` | `cd plan2code-metrics && npm test` | no |
|
||||
| Bot | `plan2code-bot/**` | `cd plan2code-bot && npm test` | no |
|
||||
| Shared code | `install.js`, `src/web-console/public/skills.js`, `src/web-console/console.mjs`, `src/web-console/routes.mjs`, `src/web-console/static.mjs`, `scripts/*-helpers.mjs` | `npm test` | yes |
|
||||
| Docs only | `**/*.md` | `node --test scripts/test-us-english.mjs scripts/test-line-endings.mjs` | no |
|
||||
@@ -30,6 +30,8 @@ A rule stated in six files is read six times and still skipped. The console sees
|
||||
|
||||
Documents are read from `file` blocks rather than pasted so the page and the disk cannot disagree, and a progress post only has to ask for `refresh`. `assumed` and `draft` exist so a half-finished doc is not read as decisions. A doc `version` never goes back because the page keys its "new version" marker on it.
|
||||
|
||||
A `diff` block follows the same rule: the agent writes a change set to a `.diff` file with `changes.mjs diff` and names it, so the agent never carries a patch through its own context and a large change costs a few typed tokens, not thousands. The server only reads it (read-only, the one file named, directly inside the session folder, so a block can never point the page at a project or system file) and caps it at the file block's 512 KB. Its text is code the repository holds, so the wording scan leaves it out as it does a `file` block.
|
||||
|
||||
## Noted questions
|
||||
|
||||
A person's note on an open question may change what it asks, and the agent's reply in the thread does not say what happens to the question. The server therefore records the fact (`noted`) when the note lands, and `validate()` refuses a new open required question until each noted one is reworded, deleted or confirmed with `stands: true`. A thread cannot answer this: it stays true forever after one reply. The page shows the same flag as a tag, and keeps the arrival notice and a New mark until the new question is opened, since eight seconds is easy to miss mid-sentence.
|
||||
|
||||
@@ -1 +1 @@
|
||||
U0VOQwGrCRNv/is5f2tebFg9olqnWS6/DBeWvY1oCHyaX3bV14wburXibwHxysSAsHqUiMQBwfDzOQGguTcyoBx/V61a+u0gNWiK7dXyDh+UCLR2+JhKcvrXknJ/3xG7RZA+trrB6zanaloZRl0FADkeROal64nWUGT8WxOPHnfj0An4Epe3OyP6dAs6WZkPu8gjm6HS5QmDuPwrW2sxyMOrmfuxltf7wyQsnGMK3RyG+PnrHmZbMtQ2SCqzxHtSnpt1tXDv7tW8/lFBeQUcdipZT57E/NxzPloRHLtlzwM8Bfn5RQ+aji5X5KermeGqHr8UXYAKhPsLKIYt0qogq06YsLA2cTbLDiqbSawqNm8lJLBohmFMLu3YjJVRIIjFfi4PcGLz2w8extZhIuXICAYlsPwEVhVJ0DQHevxbGigbc9+jknWT7+p92xvfj26LrywQhXELtyKqFDr8Aaoac35rKHmWEUwVuMo3JDgeLP0RZJkgLBQ9NY61cW9rbOMDt7XSKf6YFBcdSz34M3FCkk9N9eVSMwEe1kGGBghFQIWckWFmSEKXNzzEddf4/yIxk1YeDKrPD0Xkkykkrnfzqewhzg2zbfUrdbH1t/UGss+GTo05qEZT93beZd+CqasGCZGSiWFAENYscpp6PC+7A55vr7VA9nsQUvGxDfs84P0fm2xcVC2s8IoNSZ7smWv7ruqVT3AZ6UQ1UvYh44WiDC49zVreq9n6DxxmPCHhc1PKMS9GVTpO6rgDuYBXbLMEMgSPtL0ugfXm2QkuDF2o4uqjb5HwGJZpNVLm/I8iG2S4EnJKRwPqQ54uEwUxQLluq6VmO9Rg+IRYp/zMEqF1Qc4HDnAvlD6tFTR+yWujlr/k1X5lp3v7csgYTT69aj1fxpXL1ZijPDOf6vqErHMYZN01wt1PoLuUkS8s/hmtaiOmzr6f17Y8cuDv+9APStWC8NzHwoKZjxis8Rdkn7Up2f7hzbUv2B8xABosmhW0JHgtlVbaFSMlRn0lsGIXl1OkUCl4Ry7Bf5lRLM/IhzdlHMyPuVqa4jkddUI1nL+u/h1XfVWXWfByxqeYLLRAlmhwFDZaN8HxCnEVh+Xm0xSZQgH7K2kqoRfRPTAzkBQkUJ6feIjTZhixFioudI0vT4/Oc056bp4EZ7FKGmdOIeeuBFUlLJhHdjd3hclspDFEIFF0Mpx4fjHPvcB1bSIo2uyn2moqspebsW10mEW7dNLi5JNGldkmfmY7ACZl559fdsArIZHTXFYFmxu7jcbqqy4prZLvQnWrntNIQyYC+RXCB4OafWn+fVjjX75DqmF58EHjB1QvKB7jiMrVj4NZk1pTb0gREISo44oQ+HCZpyfNnzu/clZ01t6cT+qtgeYBDGv8tjm2lk0eEnYr9LPF8wrSWu0tT/j97cABgKJMiMpONHARMf+nAvrz5SYjEDhGkn+Lv921zL4fowwe6SXLbPBcMzaZqTw80ipLcTQIAG+efdKq1Rl0821LcPIZRCLdhjou/XDxV+hSzWG6ZdJCF9hqVOHzl+2ojwjO0c9Vw/EdA/wsVJvBeFpcBl1hIv2vlDqWgY4VKzUh0hL2r5WF8pTvHYoek8rqC+7/9N5MaFSqDkpiRWcgkuZ3Eb/rwP4vWp5p+abBUUNc/Vm0MuDfW/65wpikAh/L6lULlI4+XJCx87CsfdXlfzwIzc9IRpjhP/ytp87Apm90MUWriPkNqx7FgHpSBsH6ml54+DKg7NcPyN7WzJzhUhCWC0e4vklnON5I6YsV+at94tdmvt1xIOPK2BcusiPvJJFkk/txseS1FSDvgK8HB43Iop1mSe2WjoJsnxUSW6xPMr+Cnmjwx2sFdxkP5Yf6gleS8aYxjnHY5iavk4I3v4K6PPQx9HX+nBqZvWp6vUODCirbtsLRRWwiZ2OvWNE4x7ytxeqi07dYGjsL9EuU47zmjjfGsWz+319HdICOTdrgstovkE1fccTv1GQqrNcfAd9Lhan+lGRCfKWIedHTV9k/K1MGOURX+pexY5x5xcJ+TXjhQDLVbpHnysVAMYIjyoiCj7LPRvXWiVLAOvQLVNafodTPnqBuKjAvw31CaU/Wip/HSoHY18Qo1vOdDpbmpvKK7xasqxUcmNiYmnjWltDpJONXITPAFXrm0/yK59USv5L/8WnJn1TTgNPJAtCg8E86Sm5aznHbv4d24wtpkfoxMAho12nruPT1fU/ETAINt/C40VvYla1A5a653YIDByzVFdBJxCE+LCZQ+cJ5hoV1qaYcfdYVATfl0XnHhlpAG4gqbOimJvdXxcv2fslwsW5Z4U8JPUic3pnBTmde27sQ9EsU3YYAbzabezB2MbCay25AqHtAyjEwLTgKfpbFD4b+ns9zszXNpirt1wjiMrTYjSz6VZ6QLOsCmXjxAm6ffBFEJYp7GpFMWdVHekspw4myJWNxOdaUlPXZVLdPfpW3Pi93OJxkRmfAg/OcNMZ/d8ZBs84y71KyM0K8QZSzAioViqG0x/dRjAyqHOIn5mo/qYhiQryoEUnMGOak2nLU8a8mnmKC7yK3aZcsSO17GQNgVKE2VordvGxmrLw+vLQQ2PO9tvx8P9xjXgZIBzaT8WlEG3U1KiDq8N2Yw5oQwFAdP1MC0EHryUCkXR5lesOVSVNGo3X2aRHCS1D1kkJlRq7e6tBg8EuEoYAx6b/7uhSSycyEe7ceOWpsNyk2BLj/1KGRLyTZntLMCMkYW9Oq+P5h/OTqUrQ5GP4zBgbbR72qqPDlwIm5XVqlVaNictht1Qneg+z+SdYcyE3Fazgp6ElkBjnLpQMZJHiY4QPuMH6Msz+RB/W/3l408QUfS7txOdK9ZR7mhI8DTT7XbTwdBqeJ8fg5N+LDYcQNpjpb5sCZZLSq2jQkbd7OaGsUkRfhwMFvbrCpFoZzvuvn/S8c8810nSqTI50lzTdJ88Cb81H3/22GYjCbX/gRtxlcS6WGIxH1m5Qg4eHgTmf4okzqVRrdJNlXUnqQlAG1BsFf+sy4R88sCo3+c+UrS/qlOlLctkSZiHpDF+b3GeYQjicAuNwThW5ncDSBP//R9CAC9QscSf31TBm3/1/Lo10Klg/rZFk+JPl7TvPBVRCY4D+nIbmPt5av/E9tmiiMSH4B3eFP1oJiSB9oyEQPMaz/cf4kI3trcYoJmbreO6h768poZjE6x2fB3zE0Wmdv6tpaq5hjBkreGHnHSPxoQlq9HViVzTVY8aLsrBTumYYl4ZKgAhGZUTh6V0mDH3Ig4tSUSrqqKqXWRMullmNF+EN+4kPZabm9mWwvy2EUSyhmIpLTMVPau9tJU/7Z4/a+y7HBITgQZpQ0Tnf9M29+kFMZHDyn9R8sQGPxhQdmXsdoI20ceXvlUOMQvaJw6hju0Ub2Pn5SItM9s0cDk88lQWot4OvzISV7QcIuvDpNlIlC8FNN7vpmMW+d20QY8Ll9/CC8TJk+LTWca9dBYzXamcNwvtf/0AbQqqbIB1cnmaZeA3nlX4uo8A8kwf83fVXmyKZzE9wPA4a8d+9ybjbI2UyFH09AO25aiYpKqV1Ucy/5+8W5Yno2lmhdPPiAVLrA8x5vqQnAg3ZKnYBmQibPqz9Km4l2Jv+NoUdJpsN0f+7uLVlWZ95GZn/Qi/WrSvJgxdK8FlnzAnKNgkB2rdtNZh0WI4cFrEbt+chPLMfZFYOzFF2OUuG88sg/H+qcUPsJ32dJAK0Lb35DToufhDgUDpbD4w5ywulsR85EMxEydL+G+rjl72dvQNv+krriyeWg6fvJWsjfcxLWS6xny1J29uMwhPGLo2Bk7IQpR+uv0uCM9As7rtvnXojTMUYRNvZTMi0npfXCPUzRgF0Z3Pm6oTTr+9JPZfDMV6tdb6p5yc4vAHZUz6qoFAwgdB7xLy0CDAzW7kdkSr+ksmB2w8pyWBUMCoBaLTt8isNx8anD9J3QxlkfZAjMjSoG8O7vR2P0zH62bJBZGC5VzMDfuK4pOu1UgGGKxpzX315yU4txPd3AD0ICjK872sS/epn2dy0O6IdEYbkrwIQjV18ic593pWXVpLRJUtuX9vyg98zMGO5R5mFu2ty9RoHQ4wnLg2Nv5L6l5kVsSj4q/3fojALsyLOyxnbpJlyQLDOE3i/Wy33iyjzyPuwm7XajtY1QzOKDqcfqn0B/K3eau1UG+8So/A7Q8HiEbFp4z+B4PT55UzgN571d2Ez/HOdDWvp5eCPgT6GgHWet7oA70KZ+IWs0457fIEZbNNGj4SvwL93rM+BZ4d3otzmeUAp/EWZEzcJ5fzR5hUKVaXmZoSIyiIi4UC0yfeR+J6SeYw8itAYDBaV3BMfr2mR1AI2anQ/CRgJK/tgIUKLRWFWJHkobe3xRdASqgRDpNMjrFu0mI34NHJOP1htfLpD6GCDm7gHtLAmONUh8ggzTKPO9y1hI9otKhI6zftRNLnNDMeNidRRUsWIRg8NizVJm3zsKHPhSmjsS/7S5Wa3qaEG/9nDz4YrwEdCkdsC/Wk9eWnnp8/NrJE5cLqWoYtqBImAQajLABtky5NChn2SyGK8ojEu+Ji3DpdljJput3iG6b0LcPG72rut5o3fCvGc5F90bTX0Udt0URRga+Hw3clnAZouNy1HeBPqVmUaHeyhotDwyY+bGXEmQCVx9YvgdmCXrMP8s9s9v9S/k2DLw7ijuzd3y1yQ2vE+jcCde+AmAs0atvYQ9hH5xatN23OVCxYzZZ9YtBxyHrAos71Gdik52aZ+vi4LuYV2L0VL75anAMTxQF2T+Q1ZPNbY7aTZpl2HGHLOUFei+5ZNDThzofgwcqCzydK9KyvB47bRPYAq+dti/JRER3Eh2LLUxsBSR8/RI5yMioTPt/agJQoaPTt0Hznq+P1KcjKP53yVW5FquXn3RYHJOXOxNZlTYGYWUcL0ZVvpVa1lJ4nNWbvghX8dSfYoeuR7+s0UqSmzgjaPdHT+T2yBy5DAysZliefE+O6CGhNd/YK3JAVvLine 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
|
||||
+2
-3
@@ -4,13 +4,12 @@ dist/
|
||||
plan2code-metrics/dist
|
||||
plan2code-metrics/node_modules
|
||||
plan2code-metrics/package-lock.json
|
||||
.plan2code-loop
|
||||
.plan2code-metrics
|
||||
.plan2code/metrics/
|
||||
.plan2code/dead-code/
|
||||
.cognition/
|
||||
handoffs/
|
||||
node_modules/
|
||||
/package-lock.json
|
||||
SYNC.md
|
||||
|
||||
# Generated by install.js/`npm run build:skills` from src/, regenerated on
|
||||
# every install, so it never needs committing. Anchored: .claude/skills/ and
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# General
|
||||
|
||||
### 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
|
||||
- About: src/web-console/public/styles/learning.css, src/web-console/public/styles/pieces.css
|
||||
- Why: The Lessons dialog declared width: min(720px, ...) without max-width: none and rendered about 440px wide.
|
||||
- Noted: 2026-11-15, quick-task
|
||||
|
||||
### A new file under src/web-console/ needs a row in the AGENTS-architecture console files tables; run scripts/test-web-console-shape.mjs after adding one, since it fails until the row exists.
|
||||
- Kind: convention
|
||||
- About: scripts/test-web-console-shape.mjs, .agents-docs/AGENTS-architecture-console-page.md
|
||||
- Noted: 2026-11-14, implement-review
|
||||
|
||||
### 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
|
||||
- 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.
|
||||
- Noted: 2026-11-15, Failure log
|
||||
|
||||
### 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
|
||||
- About: src/launcher/plan2code.js
|
||||
- Noted: 2026-11-15, 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.
|
||||
- Kind: correction
|
||||
- About: src/plan2code-deps.md, src/web-console/notes/deps.md
|
||||
- Why: A review fix widened the code-changes card in the prompt only, and the re-check found the notes still listing the old rows.
|
||||
- Noted: 2026-11-14, implement-review
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"format": 1,
|
||||
"learning": "on"
|
||||
}
|
||||
@@ -10,6 +10,7 @@ Each session stays short, and the specs on disk carry everything from one sessio
|
||||
## 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.
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
@@ -312,6 +312,7 @@ Built for a mixed product and engineering room reading one screen together.
|
||||
- **One box grows.** On the primary card, the answer box that is being typed in — a `text` question's box, a choice's *Something else* box once picked, or the note under a verdict / confirm / recap once shown — is `textarea.grow`, and the card takes the column's full height above the pager (`.card.is-primary.has-grow { flex: 1 1 auto; }`). `fitGrowBox()` in `app.js` writes the card's free height as the box's `min-height`, **never under 160px**; a `ResizeObserver` watches the main column rather than the box, so the box growing can never retrigger it, and it writes only on a change over 1px. `resize: vertical` with that moving floor makes the handle taller-only; past the fill the card scrolls. Every other box keeps its ordinary size, and the notes panel is untouched.
|
||||
- **A switch per sound.** Every cue is an event in `SOUND_EVENTS` (`palette.js`), each naming its file and rank: `startSkill` (`sounds/sound-14.mp3`, played once the dashboard's **Start** is accepted) 5, `bootup` 4, `sessionStart` (`sounds/sound-07.mp3`) / `sessionEnd` (`sounds/sound-15.mp3`) 3, `question` (`sounds/sound-14.mp3`) / `skillReady` (`sounds/sound-16.mp3`) / `chatReply` (`sounds/sound-06.mp3`) 2, `newTab` (`sounds/sound-05.mp3`) 1, `snore` (`sleeping.mp3`, looped by the wake-up outside the queue) 0. The queue, the held slot and the one-at-a-time rule in `app.js` work on events, one `Audio` per file shared by the events that use it. User Preferences shows a *Play sounds* master (`looks.sound`) over one box per event, saved flat as `sound<Event>` (`soundStartSkill`, …) because `looks.json` only holds flat values; `soundPrefs()` turns any missing or non-boolean switch on, so a file from before the switches keeps every sound. A cue plays only while the master and its own switch are both on; the master off grays the boxes but keeps their ticks, and ticking a box plays it. Seven cues (not `snore` or `bootup`) also keep a pick out of the 19 files in `public/sounds/`, saved flat as `soundFile<Event>` (`soundFileQuestion`); `soundFilePrefs()` validates it against `SOUND_FILES` and a missing or unknown value falls back to the event's default, `sound.js` plays it, and the picker's select and Play button call `previewSound()`, which cuts off what is playing and is dropped behind a still-audible ranked cue.
|
||||
- **Send breathes.** `#btn-send:not(:disabled)` runs `send-pulse`, a soft accent ring that spreads and fades every 2.4s; a disabled Send is still, and reduced motion switches it off.
|
||||
- **Two marks sway.** A `.nudge` is a small accent mark that slides 3px either side of rest (`nudge-sway`, 1.4s each way) just left of the button it points at: the chevron `#send-nudge` before Send, shown only while Send is the filled step (`sendIsStep` in `core.js`, hidden as a send starts, until the next footer render decides again), and the `?` before a live **Ask for suggestions** chip (`suggestNudge()` in `ask.js`, left out while the chip is disabled). The notes panel is redrawn often, so the `?` starts with a negative `animation-delay` taken from the clock and never jumps back to its first frame. Both are `aria-hidden`, and reduced motion holds them still.
|
||||
- **Per-tab scroll memory.** An in-memory `Map` keyed by view id holds the scroller's position (the main column on a document or the Overview, the card on the questions view, with the item it belonged to), restored when the tab comes back. Page-local, never persisted, cleared when the session turns into or out of the dashboard.
|
||||
- **The Overview tab.** Appears only while `GET /overview` returns a file for the session's spec (on the dashboard: the picker's spec; gone for *start from scratch*), fetched with `no-store` on load, on a spec change and on every tab click, so it always shows the file as it is on disk. On the dashboard, a spec with no overview gets a **Map** tab (`?file=map`, `pathfinder/map.md`) and a **Plan draft** tab (`?file=draft`, the live `PLAN-DRAFT-*.md`) in its place, each while its file exists, fetched and drawn the same way; away from the dashboard only the overview is read, since a session's own map or draft is the work already in front of it. Rendered through the same DOM-only markdown path as every doc, captioned read-only. It never becomes a doc: the page is not the record.
|
||||
- **The footer slot.** The workspace label sits centered in the footer's middle track, 12px and muted: `footerLabel()` in `public/workspace.js` builds `folder · branch` (from the workspace's original folder and `state.branch`), or `folder + N folders · branch` once folders are added, and `renderWhere()` steps down through its narrower tiers (`FOOTER_TIERS`) until the text fits. A warning dot marks a missing or unreadable folder. A click opens the Workspace dialog (`#workspace-modal`), where each folder has its own **Copy path**. The notification pill is fixed over the same spot and covers it while it shows, on purpose: nothing there needs pressing while the pill is up. The dashboard keeps the footer for this label alone: `renderFooter()` puts `is-dash` on it, which hides the summary and Send (and on a narrow screen keeps the label, the one thing left in the bar); the footer only disappears there when there is no label to show.
|
||||
|
||||
+135
-55
@@ -55,7 +55,7 @@ Scroll down for the utilities. Outside a git repository the **Git** card says so
|
||||
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="../docs/screenshots/dashboard-utilities-dark.webp">
|
||||
<img src="../docs/screenshots/dashboard-utilities-light.webp" alt="The utility cards: Get a PR ready, Write missing tests, Clear out dead code, Changelog, Git, which notes that the folder is not a git repository yet and offers to start one, and Handoff.">
|
||||
<img src="../docs/screenshots/dashboard-utilities-light.webp" alt="The utility cards: Get a PR ready, Write missing tests, Clear out dead code, Prototype a screen, Changelog, and Git, which notes that the folder is not a git repository yet and offers to start one.">
|
||||
</picture>
|
||||
|
||||
---
|
||||
@@ -138,6 +138,12 @@ Scroll down for the utilities. Outside a git repository the **Git** card says so
|
||||
not documented yet shows its **Map** (`pathfinder/map.md`) and its
|
||||
**Plan draft** (the live `PLAN-DRAFT-*.md`) as tabs instead, each when it
|
||||
exists.
|
||||
- **Saved prototypes, beside the spec.** When the spec in view (the one
|
||||
picked on the dashboard, or the session's own) has saved UI prototypes in
|
||||
its `prototypes/` folder, a **Prototypes** tab lists them. An `.md` opens
|
||||
in place, with **Back to Prototypes**; an `.html` opens in your default
|
||||
browser. Once Quick Task has built from a folder that holds only
|
||||
prototypes, it offers to archive that folder to `specs--completed/`.
|
||||
- **Where you are, at the bottom.** The footer names the folder the session
|
||||
was launched from and its git branch (`plan2code · feature/…`), muted in
|
||||
the middle. Click it to open the Workspace dialog (see *Your workspace*).
|
||||
@@ -177,7 +183,7 @@ Scroll down for the utilities. Outside a git repository the **Git** card says so
|
||||
turns red if that press was never collected, and goes back to the plain
|
||||
icon once nothing is left, so a console left in a background tab can be
|
||||
checked at a glance.
|
||||
- **Help.** The **?** at the top right opens a Help dialog with 21 topics,
|
||||
- **Help.** The **?** at the top right opens a Help dialog with 23 topics,
|
||||
one per tab down the left (across the top on a narrow window), opening on
|
||||
the one for where you are. It is part of the page itself, so it still reads
|
||||
fully when the page has lost its program.
|
||||
@@ -232,10 +238,16 @@ Quick Task has fixed it, the folder reads *Bug fixed*: Quick Task offers to
|
||||
archive it to `specs--completed/`, and until then the picker never opens on it
|
||||
and hides it while *Hide unavailable workflows* is on. Its chip has a visible
|
||||
**Delete** button in place of the hover ✕ other specs carry, and one confirm
|
||||
removes the folder (any other spec also asks you to type its name). Click a card and Planny
|
||||
removes the folder (any other spec also asks you to type its name).
|
||||
**Update dependencies** works the same way for a held-back upgrade: a ticked
|
||||
Warning on its pick list writes `specs/<package>-upgrade/UPGRADE-<date>.md`,
|
||||
and the picker reads *Upgrade ready* with Quick Task (suggested) and Plan lit.
|
||||
Once Quick Task has applied it and its checks pass, the folder reads *Upgrade
|
||||
done*, treated like *Bug fixed* (Help's *Update dependencies* topic covers the
|
||||
whole run). Click a card and Planny
|
||||
flies while it gets ready;
|
||||
a few seconds later the same page is that skill's console, already running. No
|
||||
command names to remember. Pathfinder, Plan, Quick Task, Diagnose and Revise plan can also
|
||||
command names to remember. Pathfinder, Plan, Quick Task, Diagnose, UI Prototype and Revise plan can also
|
||||
start from one of your [Notebook](#your-notebook) tabs: see *Sent from the
|
||||
dashboard* there.
|
||||
|
||||
@@ -250,6 +262,15 @@ prompt that points a fresh conversation at the file, and **Delete** removes it
|
||||
for good after one confirm. Handoffs from *Stop with a handoff* (below) and
|
||||
from the Handoff skill land in the same place, `~/.plan2code/handoffs/`.
|
||||
|
||||
The dashboard also has a **Learning** row, showing one of four states for the
|
||||
project: *Not set up*, *Off*, *On* or *Paused for you*. **Pause for me** is
|
||||
personal: it pauses Learning for you alone, and nobody else on the project is
|
||||
affected. When lessons are waiting for your review, a banner at the top of the
|
||||
dashboard says how many and offers **Review**. Lessons you keep are saved as the
|
||||
project's lessons in `.plan2code/lessons/`, saved with the repository, while
|
||||
waiting lessons and your pause stay on this machine only, in `~/.plan2code/`;
|
||||
nothing is saved without your approval, and nothing is committed for you.
|
||||
|
||||
A freshly opened dashboard starts with Planny asleep in the middle of the page.
|
||||
Click to wake him: he snores once while he gets a gentle shake side to side,
|
||||
then about five seconds of him powering on to a boot-up sound (arms lifting
|
||||
@@ -504,8 +525,9 @@ working in.
|
||||
bullet). It stays on this machine. A box filled from a tab is an ordinary
|
||||
draft from then on: like anything you type, its text is kept with the
|
||||
session's draft and its pictures with its uploads, unread until you send it.
|
||||
- **Sent from the dashboard.** On a lit Pathfinder, Plan or Quick Task card
|
||||
with *Start fresh*, and on a lit Revise plan card with a spec picked that has
|
||||
- **Sent from the dashboard.** On a lit Pathfinder, Plan, Quick Task or UI
|
||||
Prototype card with *Start fresh*, on a lit Diagnose card whatever is
|
||||
picked, and on a lit Revise plan card with a spec picked that has
|
||||
no plan change waiting, the confirm pane offers **Start with a note from your
|
||||
Notebook**. Turn it on and pick a tab: empty tabs are grayed, a tab you have
|
||||
sent shows a small **sent** badge, and a preview shows the whole tab, its text
|
||||
@@ -513,7 +535,8 @@ working in.
|
||||
untick one to tick another. A tab over 50 KB gets a *Long tab* note so you can
|
||||
trim it first, and the pane's command line reads `+ note: <tab>`. Pressing
|
||||
**Start** is the consent, and nothing is put on the launch itself. The skill's
|
||||
first open text box marked `"fill": "note"` (the idea box, or Revise plan's
|
||||
first open text box marked `"fill": "note"` (the idea box, Diagnose's
|
||||
*What is wrong*, UI Prototype's *What to prototype*, or Revise plan's
|
||||
*What should change* box) then arrives filled, once, with the tab's text and
|
||||
the ticked pictures attached, and you can edit it before you press **Send**. A
|
||||
tab or picture deleted in between leaves the box empty (with a note) or skips
|
||||
@@ -533,12 +556,15 @@ working in.
|
||||
The **die** in the top bar, right of the megaphone, opens **Activities**: small
|
||||
games to play while you wait, say through a long build. Thirteen ship today,
|
||||
**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**. The window opens on a
|
||||
**picker**: a card per game with a small cover scene, a line about it, its best
|
||||
score, and a **Last played** tag on the one you played last, which also has the
|
||||
focus. Click a card (or walk the cards with the arrows and press space or
|
||||
Enter) to open its game, and **All games** at the bottom left goes back to the
|
||||
picker. One game plays at a time: going back keeps a round paused on its card
|
||||
(**Round paused, score 14**), reopening the window goes straight back into a
|
||||
**picker**: a row per game, in two columns on a wide window, with a small cover
|
||||
scene, a line about it, its best score, and a **Last played** tag on the one you
|
||||
played last, which also has the focus. The **Order** bar above sorts the games
|
||||
you have played by **Recently played** or **A to Z** (your choice is kept), and
|
||||
games you have never picked sit at the end under **Not played yet**. Click a row
|
||||
(or walk the rows with the arrows and press space or Enter) to open its game,
|
||||
and **All games** at the bottom left goes back to the picker. One game plays at
|
||||
a time: going back keeps a round paused on its row (**Paused at 14**),
|
||||
reopening the window goes straight back into a
|
||||
paused round, and picking a different game ends it. While a game is on screen,
|
||||
the header shows its best, such as **Activities · Snake best: 12**, or
|
||||
**Snake: no best yet**.
|
||||
@@ -551,7 +577,9 @@ new bests and game over each get a sound of their own. A game can play
|
||||
chiptune music too, made the same way, which builds as play heats up (Sunset
|
||||
Drive has a song for each road, Snake a different one at every level, dealt from ten at
|
||||
the start of a round so none repeats, and Ghoul Rush a track for each room, played at
|
||||
one steady level and fuller in a boss fight), and Light Trails and Flock Dash play five
|
||||
one steady level and fuller in a boss fight, and Bounce Road a radio of twenty fast
|
||||
arcade tunes in a shuffled order, with an extra voice for a boss and another in a
|
||||
Fever), and Light Trails and Flock Dash play five
|
||||
recorded songs each as background music, each in full, one after another in an
|
||||
order shuffled for every run: **Play activity music** in **User
|
||||
Preferences → Sounds & activities** is on by default (turn it off there). **Play activity sounds** there turns the games'
|
||||
@@ -559,9 +587,10 @@ sounds (the 3, 2, 1 and the new-best burst included) and their music on or
|
||||
off and leaves the page's own cues alone; the **Play sounds** switch above it
|
||||
silences all of it, and a paused or closed game goes quiet at once. A game
|
||||
with music has its own **Music** slider beside **Full screen**, which sets that
|
||||
game's music volume and is remembered per game (Snake, Light Trails, Sunset Drive and Flock Dash start at 70,
|
||||
game's music volume and is remembered per game (Snake, Light Trails, Sunset Drive, Bounce Road and Flock Dash start at 70,
|
||||
Ghoul Rush at 65).
|
||||
|
||||
- **Snake** gives you three lives: a crash costs one and puts the snake back mid-board with its length and score, flickering through 2.5 seconds of free passage. A life is earned back at 100, 250, 450 and 700 points, then every 300, up to nine (the endless-lives code works here too). Levels 4, 6 and 8 open with a boss that wanders the board while the food becomes its orbs: the Grumpy Golem stomps rocks down, the Comet Queen throws comets and the Thunder Toad leaps where a ring warned. Each orb eaten costs the boss a hit point, touching it is a crash, and beating it earns a life.
|
||||
- **Snake** speeds up as it grows: 120 ms a step at its starting three cells,
|
||||
4 ms quicker for each cell beyond, never under 60 ms, and 3% quicker again
|
||||
for each level. Every 5 foods is a new level, which opens with Slow-mo on
|
||||
@@ -913,46 +942,91 @@ Ghoul Rush at 65).
|
||||
coin. Planny's star is your highlight color, and a rival whose color sits
|
||||
too close to it wears a spare one. The start and end screens show the
|
||||
furthest zone you have reached.
|
||||
- **Bounce Road** is a fast scrolling road seen from above: Planny races a
|
||||
springy toy car up a road laid across a giant's house and yard, with
|
||||
rival toy cars on it that mean to stop him. Hold up to drive, down to brake
|
||||
(a toy car never quite stops), the arrows to steer (a little less in the
|
||||
air) and space to jump, once a press; a jump needs a little speed and goes
|
||||
further the faster you are, and a ramp launches you on its own. Bump a
|
||||
- **Bounce Road** is a fast arcade road seen from above, in the spirit of
|
||||
the late 80s cabinets: Planny races a springy toy car up a road laid across
|
||||
a giant's house and yard, with rival toy cars on it that mean to stop him.
|
||||
Hold up to drive, down to brake (a toy car never quite stops), the arrows
|
||||
to steer (a little less in the air) and space to jump, once a press; a
|
||||
jump needs a little speed and goes further the faster you are. Bump a
|
||||
rival sideways and it slides: one that leaves the road within 1.5 seconds
|
||||
of your bump is yours. Land on one and it is flattened while you bounce up
|
||||
again; land on another before your wheels touch the road and the **bounce
|
||||
chain** climbs, up to x8. Every stunt in quick succession (a crush, a
|
||||
bump-off, a hole, train, ball or barrier jumped, a ramp's big air, a close
|
||||
shave past a rival, a boost strip) steps the **combo**, which multiplies
|
||||
the points once more every third stunt in a row, up to x4, and runs out
|
||||
after 2.6 seconds without one. Water or a hole under your wheels, a crash
|
||||
(a flowerbed or a toy block nose first, a train, a truck's back) or
|
||||
anything landing on you (a ring on the road shows where) costs one of three
|
||||
lives, and you go back a little before the spot, with room to get up to
|
||||
speed. Ten stages of 25 to 45 seconds each, every one bringing something
|
||||
new: **Chalk Lane** (cracks, boost strips, cones), **Hose Creek** (broken
|
||||
bridges, a sprinkler, the Frog), **Kitchen Floor** (oil slicks, a rolling
|
||||
orange, the Sneak, who drops cones), **Flowerbed Fork** (splits, ramps,
|
||||
falling flowerpots, the Nudge), **Sandbox Run** (road that crumbles behind
|
||||
you, the Hauler, the Bruiser), **Toy Room** (a toy train crossing, toy-block
|
||||
chicanes, the Racer), **Garden Pond** (swaying bridges, drawbridges, the
|
||||
Cop), **Rooftop Gutter** (gusts), **Night Lights** (everything, in the dark)
|
||||
and **Monster Mash**, where the Monster truck hops at you and must be
|
||||
stomped five times; then the road goes round again from Kitchen Floor,
|
||||
quicker and meaner. The rivals get keener every stage: they block your
|
||||
line, brake in front of you, swerve from under your landings, hop the gaps
|
||||
and keep the pack close. Every hole has a warning sign and a straight
|
||||
run-up, and can be cleared at 80% of the top speed. Power-ups lie on the
|
||||
road from Hose Creek: **Spring**, **Bubble** (one free save), **Nitro** and
|
||||
**Mega wheels** (bigger and heavier: flatten whatever you touch). Points
|
||||
come from new road, rivals flattened (each kind its own, times the chain)
|
||||
and bumped off, jumps, big air, close shaves, stars and boost strips (times
|
||||
the combo), the Monster (2,000 for beating it), and each stage line (100
|
||||
times the stage, a bonus for beating its par time, and with no life lost
|
||||
250 more and a life back, up to five). Planny's car is your highlight
|
||||
color, and a rival whose color sits too close to it wears a spare one. The
|
||||
start and end screens show the furthest stage you have reached.
|
||||
chain** climbs, up to x8. Every stunt in quick succession steps the
|
||||
**combo**, which multiplies the points once more every third stunt in a
|
||||
row, up to x4, and runs out after 2.6 seconds without one. Stunts also
|
||||
fill the **Fever** meter along the bottom of the pills: full, it burns for
|
||||
seven seconds of double points, with any rival you touch flattened.
|
||||
Water or a hole under your wheels, a crash or anything landing on you (a
|
||||
ring or a growing shadow shows where) costs one of three lives, and you go
|
||||
back a little before the spot, with room to get up to speed. A life comes
|
||||
back for a stage with none lost, for a boss beaten and at every 8,000
|
||||
points, up to five.
|
||||
- **Gadgets and weapons.** Power-ups lie on the road from the second
|
||||
stage, and each one's name flashes at the top of the field as you take
|
||||
it. Some work as you take them: **Spring** (a longer next jump),
|
||||
**Bubble** (one free save), **Star magnet** and, rarely, an **extra
|
||||
life**. The rest are gadgets, held one at a time (the pill reads
|
||||
`TAP x2`) until you **double-tap space**: the first press still jumps at
|
||||
once, so a jump never waits, and a second within about a quarter of a
|
||||
second sets the gadget off. **Rockets** (three shots: the first rival or
|
||||
barrier ahead blows up, and a boss takes a hit), **Oil slick** (two
|
||||
spills behind you: a rival that crosses one spins off the road, and it is
|
||||
yours), **Ground pound** (two slams: you drop like a stone and the
|
||||
shockwave flattens what is near and throws the rest), **Zapper** (every
|
||||
rival near loses its steering, its tricks and its hops for 3.5 seconds),
|
||||
**Nitro** and **Mega wheels**. With nothing held, a **Supply truck** turns
|
||||
up now and then: land on its roof for a gadget.
|
||||
- **Stages and bosses.** A lap is fifteen short stages of 20 to 35 seconds,
|
||||
and every third is a boss stage, which opens with rockets on the road.
|
||||
Each run deals the stages afresh: Chalk Lane first, then ten of the
|
||||
fourteen plain themes, roughly from gentle to hard, and the five bosses
|
||||
in a new order with the Cat last. Some stages carry a **twist**, named
|
||||
under the stage: Rush hour, Gold rush, Lights out, Downpour, Supply drop
|
||||
or Turbo lane. The themes: **Chalk Lane**, **Hose Creek** (broken
|
||||
bridges, a sprinkler), **Kitchen Floor** (oil, a rolling orange, the
|
||||
rolling pin), **Bubble Bath** (soap, faucet jets that throw you up),
|
||||
**Flowerbed Fork** (forks, ramps, falling flowerpots), **Pinball Alley**
|
||||
(bumpers that kick you away for points, conveyors), **Homework Desk**
|
||||
(rolling pencils, slamming books), **Sandbox Run** (road that crumbles
|
||||
behind you), **Toy Room** (a toy train, a mallet), **Freezer Aisle** (no
|
||||
grip anywhere, snowballs), **Garden Pond** (swaying bridges,
|
||||
drawbridges), **Rooftop Gutter** (gusts), **The Floor Is Lava** and
|
||||
**Night Lights** (everything, in the dark, with lasers across the road).
|
||||
Every theme also lays stunt pieces: a **kicker** (a big ramp that flies
|
||||
you over a whole chicane, through a long line of stars), a **wall** of
|
||||
blocks right across the road (jump it), a **trampoline** (three rows of
|
||||
spring pads, bounce after bounce) and a **turbo lane** (a narrow run of
|
||||
boost strips).
|
||||
The bosses, each in its own arena and each beaten by landing on it (a
|
||||
rocket or a ground pound counts too): the **Big Rig** lobs barrels at
|
||||
where you are heading and leaks oil; the **Robo-Vac** sweeps the hall,
|
||||
then charges back down the road at you, which is your moment to jump on
|
||||
it; the **Whirlybird** bombs from out of reach, then swoops down to the
|
||||
road; the **Monster truck** hops at you and drops tires; **the Cat**
|
||||
slams its paw down and sweeps it across the road. A boss stage lasts
|
||||
until its boss is beaten: the road keeps coming, and the stage line only
|
||||
turns up once the boss is flattened. Past the fifteenth stage the run laps:
|
||||
quicker, keener, and every boss with one more hit in it.
|
||||
- **Rivals.** The Zigzag, Brick, Frog, Sneak, Nudge, Hauler, Bruiser,
|
||||
Racer and Cop block, brake, hop, litter, shove and chase. The later ones
|
||||
each have a trick, named as they first come: the **Blaster** shoots back
|
||||
down the road (a bolt knocks and slows you, never a life; jump it), the
|
||||
**Slasher** pulls alongside and its blades come out (keep off its
|
||||
sides), the **Spike** must never be landed on (bump it off or shoot it),
|
||||
the **Bomber** leaves lit bombs, the **Phantom** fades out of reach, the
|
||||
**Splitter** bursts into two Minis when flattened (two more for the
|
||||
chain), and the **Magnet** drags you toward the edge it hugs.
|
||||
- **Scoring.** Points come from new road, rivals flattened (each kind its
|
||||
own, times the chain), blown up and bumped off, jumps over holes, trains,
|
||||
balls, rollers, lasers, stompers and barriers, big air, close shaves,
|
||||
stars, bumpers and boost strips (times the combo), a boss (2,000 for
|
||||
beating it), and each stage line (100 times the stage, a bonus for
|
||||
beating its par time, and with no life lost 250 more). Each stage is
|
||||
ranked S, A, B or C, and the end screen lines the ranks up. The game has
|
||||
its own radio: twenty synthesized arcade tunes, played in a random order. Planny's car is your
|
||||
highlight color, and a rival whose color sits too close to it wears a
|
||||
spare one. The start and end screens show the furthest stage you have
|
||||
reached.
|
||||
- **Ghoul Rush** is a fast, dark run-and-gun through a haunted house:
|
||||
Planny sprints left to right through a mansion a room at a time, the view
|
||||
scrolling with him. The house is pitch dark: you see what his glow, his
|
||||
@@ -1478,7 +1552,7 @@ Ghoul Rush at 65).
|
||||
P or Esc during the count pauses again.
|
||||
- **Keys.** Arrows or W/A/S/D steer, space starts and plays (and boosts in
|
||||
Light Trails, fires while held in Bug Hunt, burns nitro in Sunset Drive,
|
||||
where held up drives and held down brakes, drops the block in Stack Deploy, dashes in Bumper Ring, where held arrows push, fires while held in Rapids Run, where held up speeds up and held down slows, dashes in Hot Potato, where held arrows run, uses the oldest pickup in Crossing Rush, where an arrow hops once a press, jumps once a press in Bounce Road, where held up drives and held down brakes, fires while held in Ghoul Rush, where held arrows run, up jumps once a press and down drops through a shelf, and climbs and dives in Flock Dash, where held up and down fly the leader and held left and right ease forward and back), P pauses, R starts the round over (from the 3, 2, 1), F (or **Full screen** under the board) gives the game the whole screen and F or Esc puts it back, and Esc closes the window with the game paused. In full screen the board takes the whole screen, as big as its shape allows, with black bars where the shape leaves room, and a panel (the game's name, the score line, the game's **Music** slider for a game with music, Exit full screen) is laid over it: docked in the side bar when that bar is at least 220 px wide, in the bottom bar on a tall screen when that is at least 110 px tall, and otherwise floating in the top right corner (Sunset Drive's 16:9 board on a 16:9 screen), where it shrinks to the score line in the bottom right corner while a round plays and the pointer is still. The board never gives up room for the panel. The pointer hides after two still seconds. In the desktop app the page asks the app (`activities-full`) to lay the console over its bar and terminal and put the window in full screen, since the app's frame allows the page no full screen of its own. A question, a sign-off or a finish takes a full-screen game back to the window's own size as it pauses it. A page with no mouse or trackpad
|
||||
where held up drives and held down brakes, drops the block in Stack Deploy, dashes in Bumper Ring, where held arrows push, fires while held in Rapids Run, where held up speeds up and held down slows, dashes in Hot Potato, where held arrows run, uses the oldest pickup in Crossing Rush, where an arrow hops once a press, jumps once a press in Bounce Road, where held up drives and held down brakes and a double tap sets off the gadget held, fires while held in Ghoul Rush, where held arrows run, up jumps once a press and down drops through a shelf, and climbs and dives in Flock Dash, where held up and down fly the leader and held left and right ease forward and back), P pauses, R starts the round over (from the 3, 2, 1), F (or **Full screen** under the board) gives the game the whole screen and F or Esc puts it back, and Esc closes the window with the game paused. In full screen the board takes the whole screen, as big as its shape allows, with black bars where the shape leaves room, and a panel (the game's name, the score line, the game's **Music** slider for a game with music, Exit full screen) is laid over it: docked in the side bar when that bar is at least 220 px wide, in the bottom bar on a tall screen when that is at least 110 px tall, and otherwise floating in the top right corner (Sunset Drive's 16:9 board on a 16:9 screen), where it shrinks to the score line in the bottom right corner while a round plays and the pointer is still. The board never gives up room for the panel. The pointer hides after two still seconds. In the desktop app the page asks the app (`activities-full`) to lay the console over its bar and terminal and put the window in full screen, since the app's frame allows the page no full screen of its own. A question, a sign-off or a finish takes a full-screen game back to the window's own size as it pauses it. A page with no mouse or trackpad
|
||||
(touch only) shows "Activities need a keyboard." in place of the board.
|
||||
- **Best scores** show beside the score while you play and after each round.
|
||||
Snake, Light Trails, Bug Hunt, Sunset Drive, Stack Deploy, Bumper Ring, Rapids Run, Hot Potato, Crossing Rush, Bounce Road, Ghoul Rush and Flock Dash keep their highest score. Mini golf keeps its lowest
|
||||
@@ -1874,7 +1948,7 @@ exception being the note attachments the agent keeps for a spec, above):
|
||||
| `~/.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`) 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) | always |
|
||||
| `~/.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 |
|
||||
@@ -1966,7 +2040,13 @@ origin.
|
||||
| `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`. |
|
||||
@@ -1982,7 +2062,7 @@ origin.
|
||||
| `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`; `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`. |
|
||||
| `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. |
|
||||
|
||||
@@ -36,11 +36,13 @@ Details: [Status line](./.agents-docs/AGENTS-architecture-statusline.md)
|
||||
|
||||
## 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), build progress, the living document, 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 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 page of game cards 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` (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 21-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, Finalize, Changelog, Git and Handoff) a **Subagents** button in the top bar turns helpers on or off per project and skill (on by default for those skills until switched off, saved in `~/.plan2code/console/subagents.json`), and a Helper strength choice (Balanced, Thrifty, Best, Match my session; rules in `src/shared-references/helper-strength.md`, shipped in the sixteen helper skills); the agent hears of it as a standing instruction only when it changes, and reports its helpers in a **Subagents** tab beside Ask (contract in `console-subagents.md`). Per-skill facts live iLine 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 (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
|
||||
|
||||
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`.
|
||||
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 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) and [.readme/web-console.md](./.readme/web-console.md)
|
||||
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
|
||||
@@ -57,6 +59,12 @@ Run the targeted suites for the part you changed, not the full `npm test`, when
|
||||
|
||||
Details: [Development Commands](./.agents-docs/AGENTS-development-commands.md)
|
||||
|
||||
## Test map
|
||||
|
||||
The area-to-check table PR Prep and Test read (`| Area | Paths | Run | Shared |`); `Shared` rows mean the full `npm test`.
|
||||
|
||||
Details: [Test map](./.agents-docs/AGENTS-test-map.md)
|
||||
|
||||
## Code Style & Gotchas
|
||||
|
||||
Language/toolchain conventions for `install.js` vs TypeScript packages, US English spelling, and pitfalls to avoid (version sync, `.gitignore` pre-flight, character limits, User Feedback table format).
|
||||
@@ -76,8 +84,12 @@ The web console draws him as inline SVG in `src/web-console/public/index.html`,
|
||||
╰┬─┬╯
|
||||
```
|
||||
|
||||
Lessons: approved lessons about this codebase live in `.plan2code/lessons/`, one file per area plus `general.md`. Each file lists the paths it covers; read the matching file before changing that code.
|
||||
|
||||
## Keeping this file current
|
||||
|
||||
During a Plan2Code skill run, mistakes are offered as lessons at the end of the run, not written here. Outside a skill run, add one line to the failure log as before.
|
||||
|
||||
The `Failure log` section below is a recording of mistakes made by previous AI Agents while working with this code base.
|
||||
|
||||
When you make a mistake, get corrected, or discover something about this codebase that wasn't written down:
|
||||
@@ -94,13 +106,12 @@ When you make a mistake, get corrected, or discover something about this codebas
|
||||
|
||||
- Do not audit `CHANGELOG.md` headings through PowerShell — the emoji come back as `?`. See the gotcha for the correct approach.
|
||||
- Sync upstream only through `/sync-repo`, and verify its baseline against the real tree before porting: an earlier sync silently skipped a whole upstream release (the `3-implement-review` skill) while the recorded version froze. Update the baseline with `.claude/skills/sync-repo/set-synced.mjs`, never with a shell pipe over the decrypted body. Keep plan2code's ticket-free `commit-msg.mjs` (`<subject>`, `AI Assisted`) through every sync: upstream's ticket-from-branch rule was ported by mistake once and removed in v2.6.0.
|
||||
- After a sync merge, run `npm test` before trusting a "clean" file: when upstream and plan2code fixed the same bug, `git merge-file` keeps both copies without a conflict (a sync once left `let pattern` declared twice in `app.js`, caught only by `parse-check`).
|
||||
- When extracting upstream files in Git Bash, run `git show <ref>:<path>` with `MSYS_NO_PATHCONV=1` and `C:/` style paths (never `/c/`): path conversion rewrites `origin/main:.readme/x.md` into `origin\main;.readme\x.md`, the show fails, and the merge silently runs against an empty "theirs". Check every extracted file is non-empty before merging.
|
||||
- After a sync merge, check it before trusting a "clean" file: extract upstream files in Git Bash with `git show <ref>:<path>` under `MSYS_NO_PATHCONV=1` and `C:/` style paths (never `/c/`), since path conversion rewrites `origin/main:.readme/x.md` into `origin\main;.readme\x.md` and the merge silently runs against an empty "theirs" (check every extracted file is non-empty); then run `npm test`, since when upstream and plan2code fixed the same bug `git merge-file` keeps both copies without a conflict (a sync once left `let pattern` declared twice in `app.js`, caught only by `parse-check`).
|
||||
- After a sync, grep the result for every upstream name the rebrand map can miss (the `/sync-repo` body lists them): the owner slug and company name in any case, the bare brand word inside identifiers and fixtures, and the ticket key followed by anything, not only digits. Each slipped through once: an owner slug in `feedback-payload.mjs` and its test (fixed by hand to `jparkerweb/plan2code`); in v2.7.0 a `KEPT_<BRAND>_ENTRIES` constant, a `<brand>Dir` option, a `"<brand>"` test folder and an owner slug in a git remote URL; in v2.8.0 git board fixtures built as `` `feature/<KEY>-${11000 + i}-…` `` template literals, which a digits-only rewrite to `ABC-<n>` misses. No upstream name may appear in plain text anywhere in this repo.
|
||||
- When a new first-run dialog is added to the web console, set its seen flag in `scripts/capture-screenshots.mjs`'s `looks.json` too: the Welcome dialog once covered the regenerated dashboard screenshots until `welcomeSeen: true` was added.
|
||||
- Import `scripts/skill-script-helpers.mjs` in any test that builds git fixtures for a skill script or `git-repo.mjs`: it scrubs the whole test process's git config, so fixtures, imported modules and spawned scripts agree. Mixed configs broke `git plan switch` once (a global `core.autocrlf=true` checked fixtures out with CRLF the scrubbed script read as changed). It also rebuilds `skills/` and prunes any skill folder `install.js` does not list, so register a new skill in `SOURCE_PROMPTS` before running its `scripts/test-script-<name>.mjs` or the script under test vanishes.
|
||||
- Before deleting a test file that upstream split or removed, diff plan2code's copy against the rebranded upstream base and port the plan2code-only tests: v2.7.0's split of the web console suite would otherwise have dropped seven hardening tests (now in `scripts/test-web-console-hardening.mjs`).
|
||||
- When a `CHANGELOG.md` heading gets a version number, write the heading by hand, then run `node scripts/set-version.mjs <x.y.z>`, which sets the same number in every file that carries it in the same change, then run `npm run build:skills`: `version.json` (with its `releaseDate`), the root `package.json`, README's `Version X.Y.Z` line, and under `plan2code-app/`: `package.json`, `package-lock.json` (two lines), `src-tauri/tauri.conf.json`, `src-tauri/Cargo.toml`, `fake-agent/Cargo.toml` and `Cargo.lock` (the `plan2code-app` and `fake-agent` entries). `node scripts/check-versions.mjs` compares all of them and runs in `npm test`; widen its `SOURCES` when a new file carries the version. The changelog skill only touches `package.json`: v2.9.0 nearly shipped with `version.json` at 2.8.1, and README's line sat at 2.6.0 for three releases.
|
||||
- When a `CHANGELOG.md` heading gets a version number, write the heading by hand, then run `npm run set-version` (with no version on a terminal it shows the current one and asks, Enter taking the next patch; `npm run set-version -- <x.y.z>` sets one directly), which sets the same number in every file that carries it in the same change, then run `npm run build:skills`: `version.json` (with its `releaseDate`), the root `package.json`, README's `Version X.Y.Z` line, and under `plan2code-app/`: `package.json`, `package-lock.json` (two lines), `src-tauri/tauri.conf.json`, `src-tauri/Cargo.toml`, `fake-agent/Cargo.toml` and `Cargo.lock` (the `plan2code-app` and `fake-agent` entries). `node scripts/check-versions.mjs` compares all of them and runs in `npm test`; widen its `SOURCES` when a new file carries the version. The changelog skill only touches `package.json`: v2.9.0 nearly shipped with `version.json` at 2.8.1, and README's line sat at 2.6.0 for three releases.
|
||||
- When a page test (`scripts/test-web-console-page-*.mjs`) fails only on CI or only in a full run, look for a race with a redraw before suspecting the change, and fix the test, not the timeout: read styles and set scrolls through `styleOf()`, `stylesOf()` and `scrollCard()` in `page-test-helpers.mjs` (a card a redraw replaced reads "" for every style and scrolls nothing; `test-web-console-shape.mjs` now fails a raw `locator.evaluate` that does either), and wait for the page to hold what the next step needs before acting (the workspace frame before typing `@`, the notepad's drawn marks, a newly selected tab). Keep `npm test`'s file concurrency under `scripts/node-test.mjs`'s cap of one file per spare core: a flat `--test-concurrency=8` ran 8 browsers on 3 and 4 core runners and failed a different page test on every CI run. On a busy local machine, rerun the failing files alone first; the chat stress test and the session suite's "no submitted frame within 5s" cascade still fail that way under load.
|
||||
- Run `npm test` and `cargo test` from a terminal outside the desktop app, or with `PLAN2CODE_IN_APP`, `PLAN2CODE_APP_TOKEN`, `PLAN2CODE_APP_VERSION`, `PLAN2CODE_APP_ANNOUNCE`, `PLAN2CODE_EMBED_ORIGIN`, `PLAN2CODE_CONSOLE_SID` and `PLAN2CODE_LOOP_STRENGTH` unset (`env -u ... npm test`; a Loop phase's agent has the last one, and two `loop_driver` strength tests then fail with `never saw the env line`): inherited from the app they fail about 34 tests that check behavior outside the app (the update banner, the terminal line, cookies, open's browser launch), and a test console announces itself to the live window. A `cargo test` run mid-build once took the window over that way, then left an agent-less dashboard in it, and the build's question was never seen. The app now ignores sessions outside its console store (`take_announced` in `main.rs`), and the Rust console tests scrub the variables, but the JS suites do not. Before pushing a change under `plan2code-app/`, also run `cargo fmt --check` and `cargo clippy --workspace --all-targets -- -D warnings` there, not only `cargo test`: CI's `app` workflow fails on either, and the Rust code once reached a PR never formatted (20 files) with three clippy errors, one only macOS and Linux could see (see plan2code-app/README.md "Tests"). `loop_driver` tests failing with `never saw ... agent generations` and no `ARGS` line in the output mean `target/debug/fake-agent` is older than its source (a file restored with an old time, so Cargo never rebuilds it): `touch plan2code-app/fake-agent/src/main.rs` and rerun. A stale binary once read as 2 real failures in PR Prep.
|
||||
- Never fix CRLF by hand, one file at a time: run `npm run fix:eol` (`scripts/fix-line-endings.mjs`). Windows Python in text mode, among other tools, writes CRLF into files git keeps as LF; a whole session's edits once came out CRLF and 14 other files were found the same way. It now also runs as `pretest`, in the pre-commit hook and after every agent Write or Edit (see the LF gotcha in Code Style).
|
||||
|
||||
@@ -2,6 +2,45 @@
|
||||
|
||||
All notable changes to Plan2Code will be documented in this file.
|
||||
|
||||
## v3.1.0
|
||||
|
||||
### ✨ 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**: 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.
|
||||
- **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).
|
||||
- **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.
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
- **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**: 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 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.
|
||||
- **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
|
||||
|
||||
- **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).
|
||||
- **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
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
- **tooling**: `npm run set-version` runs `scripts/set-version.mjs`, and with no version on a terminal it shows the current one and asks for the new one, Enter taking the next patch; a script or a pipe still gets the usage line and exits 2.
|
||||
|
||||
## v3.0.5
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
+3
-1
@@ -2,7 +2,8 @@
|
||||
|
||||
## 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.
|
||||
- **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).
|
||||
- **No agent yet?** Install Claude Code, Codex or Devin first, or let the `plan2code` command's setup page walk you through it.
|
||||
@@ -50,6 +51,7 @@ Every command below is what a dashboard card runs. Typed on its own, each one as
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ 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.
|
||||
|
||||
Version 3.0.5 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
Version 3.1.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
|
||||
---
|
||||
|
||||
@@ -32,7 +32,8 @@ The dashboard, in a project halfway through a build. It suggests the next step f
|
||||
|
||||
### 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.
|
||||
- **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).
|
||||
- **No agent yet?** Install Claude Code, Codex or Devin first, or let the `plan2code` command's setup page walk you through it.
|
||||
@@ -89,7 +90,7 @@ custom agent that has none; for Codex the question names its sandbox, which that
|
||||
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 picker first. Uninstalling (`U`, or `plan2code uninstall` from any terminal) removes both.
|
||||
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>
|
||||
@@ -131,8 +132,9 @@ one on a brief built from the session, and the console's own Session meter point
|
||||
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, and the bar offers the same **Update skills** when the app and the
|
||||
installed skills disagree. `plan2code uninstall` removes all three.
|
||||
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).
|
||||
|
||||
@@ -210,7 +212,7 @@ documents. The folder label in the bottom bar opens your workspace, where you ad
|
||||
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
|
||||
the dashboard and send the box it fills. The **die** beside it opens **Activities**,
|
||||
two small games (Snake and Mini golf) 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
|
||||
you the command to carry on later, and **Back to the dashboard** takes you home to pick the next
|
||||
step in the same session.
|
||||
@@ -250,7 +252,7 @@ The dashboard's cards, and when each one lights up for the spec you pick:
|
||||
| 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) |
|
||||
| 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 |
|
||||
@@ -258,9 +260,13 @@ The dashboard's cards, and when each one lights up for the spec you pick:
|
||||
| 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.
|
||||
|
||||
---
|
||||
|
||||
## The four rules that do most of the work
|
||||
@@ -290,6 +296,8 @@ moves it to `specs--completed/`. The layout and progress marks are on the
|
||||
Add `specs/` to your project's `.gitignore`: it's your working
|
||||
drawing, not a deliverable. Share a folder deliberately with `git add -f` when you want to.
|
||||
|
||||
`.plan2code/` is what Plan2Code saves with the repository: the project's lessons and the Learning switch. It's shared with your team, so commit it and don't add it to `.gitignore`.
|
||||
|
||||
Step 2 marks which phases don't share files. Open a second agent on one of those, and the `[/]` marks
|
||||
keep the two out of each other's way.
|
||||
|
||||
@@ -431,6 +439,8 @@ console or the terminal; add `--web` to skip the question and go straight to the
|
||||
| `/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 |
|
||||
|
||||
|
||||
+18
-8
@@ -48,7 +48,9 @@ You also need Node.js 18 or newer (the app checks at start and says what to inst
|
||||
Run `plan2code` in your project, as always. When the app is installed and a window can open,
|
||||
`plan2code` asks which agent and model (as before) and then opens the app on that folder instead of
|
||||
running the agent in your terminal. The desktop shortcut the installer can create runs the same
|
||||
command, so it opens the app too.
|
||||
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.
|
||||
|
||||
Three things keep today's terminal flow:
|
||||
|
||||
@@ -112,7 +114,7 @@ separate context-window meter of its own, so there is only ever one gauge to rea
|
||||
threshold is tuned. The terminal panel has its own toolbar: dock it to the bottom or the right, collapse
|
||||
it to a thin strip, or maximize it; its size is remembered. An "agent may need you" badge appears on a
|
||||
collapsed or small panel once the agent has sat quiet for a while. **Change project** (in the project
|
||||
menu) asks first if an agent is running, then stops it and the console before opening the new folder.
|
||||
menu) asks first if an agent is running, then stops it and the console before opening the new folder. It shows the same folder picker, with **Choose a folder** first and the recent folders under it (the one already open is left out); Cancel or Escape keeps the project as it is.
|
||||
|
||||
If the console itself ever needs reconnecting (it stopped, or the skills were just updated), every path
|
||||
to that offers the same **Reconnect the console** button — never "Restart the console" in one place and
|
||||
@@ -121,9 +123,9 @@ 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):
|
||||
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
|
||||
conversation, since New Session already does that in one click; and the console's own "update available"
|
||||
banner never shows, since the app's **Update skills** button (below) already covers it with no shell
|
||||
involved. A slash command still offered to continue a step (such as `/plan2code-4-finalize`) stays
|
||||
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
|
||||
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
|
||||
exactly as it would in a terminal: paste it into the app's own terminal panel, which runs the real
|
||||
agent CLI.
|
||||
|
||||
@@ -248,9 +250,17 @@ clean tree. The in-app **Help** has a matching topic, **Implementation Loop**, w
|
||||
|
||||
## Keep it up to date
|
||||
|
||||
`plan2code update` brings the skills, the `plan2code` command and the app up together. If the app
|
||||
and the installed skills ever differ in version, the app's top bar says so and offers **Update
|
||||
skills**, which runs that same update when you press it. It never updates on its own.
|
||||
`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**,
|
||||
and the dashboard shows its **UPDATE AVAILABLE** banner. Neither updates for you: the app cannot replace
|
||||
itself while it runs (Windows will not overwrite a running file), so copy the command, run it in a
|
||||
terminal outside the app (not the app's terminal panel, which runs your agent), then close the app and
|
||||
open it again.
|
||||
|
||||
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
|
||||
single click, because it never has to replace the app. Nothing updates on its own.
|
||||
|
||||
To remove the app along with the skills and the command, run `plan2code uninstall`. It asks first,
|
||||
then asks whether your own data in `~/.plan2code/` (notebooks, handoffs, settings) goes too.
|
||||
|
||||
+793
-924
File diff suppressed because it is too large.
Load diff
Binary file not shown.
|
After Width: | Height: | Size: 89 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 97 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 117 KiB After Width: | Height: | Size: 121 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 127 KiB After Width: | Height: | Size: 132 KiB |
+108
-30
@@ -146,7 +146,11 @@ const SOURCE_PROMPTS = [
|
||||
bare: true,
|
||||
displayName: 'Dashboard Mode',
|
||||
description: 'Open the web console dashboard and launch any Plan2Code skill from the menu',
|
||||
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
|
||||
scripts: ['lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
source: 'plan2code-init.md',
|
||||
@@ -180,9 +184,16 @@ const SOURCE_PROMPTS = [
|
||||
name: 'pathfinder',
|
||||
displayName: 'Pathfinder Mode',
|
||||
description: 'charting of a foggy idea as a map of decision questions, cleared one at a time',
|
||||
// ui-prototype.md rides along (with its references, shell and scripts) for the
|
||||
// offer of a UI prototype, which runs in the same conversation; every carried
|
||||
// name starts with ui-prototype so none collides with this skill's own files.
|
||||
scripts: ['ui-prototype.mjs', 'ui-prototype-round.mjs', 'ui-prototype-page.mjs', 'ui-prototype-drafts.mjs', 'ui-prototype-block.mjs', 'lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'plan2code-ui-prototype.md', target: 'ui-prototype.md' },
|
||||
{ source: 'plan2code-ui-prototype-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -194,7 +205,10 @@ const SOURCE_PROMPTS = [
|
||||
isUtility: true,
|
||||
// review.md rides along for the web console's "Review it now" button, which
|
||||
// runs the review in the same session once the quick task is built.
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs'],
|
||||
// ui-prototype.md rides along (with its references, shell and scripts) for the
|
||||
// offer of a UI prototype, which runs in the same conversation; every carried
|
||||
// name starts with ui-prototype so none collides with this skill's own files.
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs', 'changes.mjs', 'ui-prototype.mjs', 'ui-prototype-round.mjs', 'ui-prototype-page.mjs', 'ui-prototype-drafts.mjs', 'ui-prototype-block.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
|
||||
@@ -202,7 +216,10 @@ const SOURCE_PROMPTS = [
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'plan2code-review.md', target: 'review.md' },
|
||||
{ source: 'plan2code-review-references' }
|
||||
{ source: 'plan2code-review-references' },
|
||||
{ source: 'plan2code-ui-prototype.md', target: 'ui-prototype.md' },
|
||||
{ source: 'plan2code-ui-prototype-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -211,10 +228,16 @@ const SOURCE_PROMPTS = [
|
||||
name: 'plan',
|
||||
displayName: 'Planning Mode',
|
||||
description: 'Requirements analysis and architecture design',
|
||||
scripts: ['specs.mjs'],
|
||||
// ui-prototype.md rides along (with its references, shell and scripts) for the
|
||||
// offer of a UI prototype, which runs in the same conversation; every carried
|
||||
// name starts with ui-prototype so none collides with this skill's own files.
|
||||
scripts: ['specs.mjs', 'ui-prototype.mjs', 'ui-prototype-round.mjs', 'ui-prototype-page.mjs', 'ui-prototype-drafts.mjs', 'ui-prototype-block.mjs', 'lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'plan2code-ui-prototype.md', target: 'ui-prototype.md' },
|
||||
{ source: 'plan2code-ui-prototype-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -223,10 +246,16 @@ const SOURCE_PROMPTS = [
|
||||
name: 'revise-plan',
|
||||
displayName: 'Revision Mode',
|
||||
description: 'Modify specs mid-implementation when requirements change',
|
||||
scripts: ['specs.mjs'],
|
||||
// ui-prototype.md rides along (with its references, shell and scripts) for the
|
||||
// offer of a UI prototype, which runs in the same conversation; every carried
|
||||
// name starts with ui-prototype so none collides with this skill's own files.
|
||||
scripts: ['specs.mjs', 'ui-prototype.mjs', 'ui-prototype-round.mjs', 'ui-prototype-page.mjs', 'ui-prototype-drafts.mjs', 'ui-prototype-block.mjs', 'lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'plan2code-ui-prototype.md', target: 'ui-prototype.md' },
|
||||
{ source: 'plan2code-ui-prototype-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -235,11 +264,12 @@ const SOURCE_PROMPTS = [
|
||||
name: 'document',
|
||||
displayName: 'Documentation Mode',
|
||||
description: 'Transform planning output into structured implementation docs',
|
||||
scripts: ['specs.mjs'],
|
||||
scripts: ['specs.mjs', 'lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' }
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -250,7 +280,7 @@ const SOURCE_PROMPTS = [
|
||||
description: 'Execute implementation phase by phase',
|
||||
// review.md rides along for the web console's review offer on the sign-off
|
||||
// card, which runs the review in the same session before the phase is approved.
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs'],
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs', 'changes.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
|
||||
@@ -258,7 +288,8 @@ const SOURCE_PROMPTS = [
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'plan2code-review.md', target: 'review.md' },
|
||||
{ source: 'plan2code-review-references' }
|
||||
{ source: 'plan2code-review-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -267,7 +298,7 @@ const SOURCE_PROMPTS = [
|
||||
name: 'implement-review',
|
||||
displayName: 'Implementation + Review Mode',
|
||||
description: 'Implement one phase, review it, then request sign-off',
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs'],
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs', 'changes.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'plan2code-3-implement.md', target: 'implement.md' },
|
||||
@@ -276,7 +307,8 @@ const SOURCE_PROMPTS = [
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'plan2code-review.md', target: 'review.md' },
|
||||
{ source: 'plan2code-review-references' }
|
||||
{ source: 'plan2code-review-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -288,12 +320,13 @@ const SOURCE_PROMPTS = [
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when a change, branch or spec needs an independent review for bugs, spec drift and gaps, before a commit or pull request. Run it as /plan2code-review.",
|
||||
isUtility: true,
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs'],
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/review-in-build.md', target: 'review-in-build.md' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' }
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -304,14 +337,15 @@ const SOURCE_PROMPTS = [
|
||||
description: 'Validate, summarize, and archive completed work',
|
||||
// review.md rides along for Step 2.5's final review, which runs in the
|
||||
// same session before the summary is written and the spec is archived.
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs'],
|
||||
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'run-check.mjs', 'lessons.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'shared-references/review-in-build.md', target: 'review-in-build.md' },
|
||||
{ source: 'plan2code-review.md', target: 'review.md' },
|
||||
{ source: 'plan2code-review-references' }
|
||||
{ source: 'plan2code-review-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -333,10 +367,11 @@ const SOURCE_PROMPTS = [
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when you want to understand how and why an area of the code works, or find its rough spots worth fixing. Run it as /plan2code-xray.",
|
||||
isUtility: true,
|
||||
scripts: [],
|
||||
scripts: ['lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -348,11 +383,12 @@ const SOURCE_PROMPTS = [
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when a bug's cause is unknown and you want it found and written up without a fix. Run it as /plan2code-diagnose.",
|
||||
isUtility: true,
|
||||
scripts: ['specs.mjs'],
|
||||
scripts: ['specs.mjs', 'lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -364,11 +400,12 @@ const SOURCE_PROMPTS = [
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when a branch is nearly done and you want its checks run, a readiness verdict and a pull-request description. Run it as /plan2code-pr-prep.",
|
||||
isUtility: true,
|
||||
scripts: ['review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'test-commands.mjs', 'run-check.mjs'],
|
||||
scripts: ['review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'test-commands.mjs', 'run-check.mjs', 'lessons.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -380,12 +417,13 @@ const SOURCE_PROMPTS = [
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when code has no tests or weak ones and you want unit and integration tests written in the project's own style. Run it as /plan2code-test.",
|
||||
isUtility: true,
|
||||
scripts: ['review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'test-commands.mjs', 'run-check.mjs'],
|
||||
scripts: ['review-scope.mjs', 'glob.mjs', 'test-map.mjs', 'test-match.mjs', 'test-commands.mjs', 'run-check.mjs', 'lessons.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -397,13 +435,53 @@ const SOURCE_PROMPTS = [
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when you want unused code paths and dead code in your project found, labeled by how safe each is to remove, and removed only where you pick. Run it as /plan2code-dead-code.",
|
||||
isUtility: true,
|
||||
scripts: ['test-map.mjs', 'glob.mjs', 'test-commands.mjs', 'run-check.mjs'],
|
||||
// review.md rides along for Step 7.5's final review of the removals, which
|
||||
// runs in the same session, as Finalize's Step 2.5 does, with the scripts
|
||||
// review.md names.
|
||||
scripts: ['test-map.mjs', 'glob.mjs', 'test-commands.mjs', 'run-check.mjs', 'specs.mjs', 'commit-msg.mjs', 'review-scope.mjs', 'lessons.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'plan2code-dead-code-references/caller-search.md', target: 'caller-search.md' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
|
||||
{ source: 'shared-references/test-runs.md', target: 'test-runs.md' },
|
||||
{ source: 'shared-references/review-in-build.md', target: 'review-in-build.md' },
|
||||
{ source: 'plan2code-review.md', target: 'review.md' },
|
||||
{ source: 'plan2code-review-references' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
source: 'plan2code-deps.md',
|
||||
stepNumber: 'deps',
|
||||
name: 'deps',
|
||||
displayName: 'Update Dependencies Mode',
|
||||
description: 'Find outdated dependencies, label how safe each update is, and apply only what you pick with your checks run after each batch',
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when you want your project's outdated dependencies found, labeled by how safe each update is, and applied only where you pick, with your checks run and anything that breaks put back. Run it as /plan2code-deps.",
|
||||
isUtility: true,
|
||||
// deps.mjs comes from src/plan2code-deps-scripts/; these are the shared ones it runs.
|
||||
scripts: ['test-map.mjs', 'glob.mjs', 'test-commands.mjs', 'run-check.mjs'],
|
||||
// helper-strength.md for the assess step's helpers (light, medium).
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
source: 'plan2code-ui-prototype.md',
|
||||
stepNumber: 'ui-prototype',
|
||||
name: 'ui-prototype',
|
||||
displayName: 'UI Prototype Mode',
|
||||
description: 'Draw several versions of a screen or flow on one page, tune them with live dials, and bring the choice back',
|
||||
// Shown to the agent in place of the generic header text: when the skill fits and its command.
|
||||
skillDescription: "Use when you want to see several versions of a screen or flow, tune them with live dials and bring your choice back. Run it as /plan2code-ui-prototype.",
|
||||
isUtility: true,
|
||||
scripts: ['ui-prototype.mjs', 'ui-prototype-round.mjs', 'ui-prototype-page.mjs', 'ui-prototype-drafts.mjs', 'ui-prototype-block.mjs', 'lessons.mjs', 'glob.mjs', 'test-map.mjs'],
|
||||
additionalReferences: [
|
||||
{ source: 'web-console', target: 'web-console' },
|
||||
{ source: 'shared-references/lessons.md', target: 'lessons.md' }
|
||||
]
|
||||
},
|
||||
{
|
||||
source: 'plan2code-changelog.md',
|
||||
stepNumber: 'changelog',
|
||||
@@ -457,6 +535,8 @@ function generateStepLabel(prompt) {
|
||||
if (prompt.stepNumber === 'pr-prep') return 'PR Prep';
|
||||
if (prompt.stepNumber === 'test') return 'Test';
|
||||
if (prompt.stepNumber === 'dead-code') return 'Dead Code';
|
||||
if (prompt.stepNumber === 'deps') return 'Update Dependencies';
|
||||
if (prompt.stepNumber === 'ui-prototype') return 'UI Prototype';
|
||||
if (prompt.stepNumber === 'changelog') return 'Changelog';
|
||||
if (prompt.stepNumber === 'quick') return 'Quick Task';
|
||||
return `Step ${prompt.stepNumber}`;
|
||||
@@ -2902,9 +2982,7 @@ async function installDesktopApp({ quiet = false, unattended = false, outcome =
|
||||
return fail(`the file was verified but could not be put in ${APP_DIR} (${error.message}); close the app and try again.`);
|
||||
}
|
||||
recordInstalled('app');
|
||||
console.log(` ${COLORS.GREEN}${SYMBOLS.SUCCESS}${COLORS.RESET} Installed: ${APP_DEST}`);
|
||||
console.log(` ${COLORS.YELLOW}${SYMBOLS.WARNING}${COLORS.RESET} The app is unsigned, and it starts the agent with permission checks off.`);
|
||||
console.log(` ${COLORS.YELLOW}${SYMBOLS.WARNING}${COLORS.RESET} See docs/desktop-app.md for how to allow it on macOS and Windows if needed.`);
|
||||
console.log(` ${COLORS.YELLOW}${SYMBOLS.INFO}${COLORS.RESET} The app is unsigned; if needed, see docs/desktop-app.md for how to allow it.`);
|
||||
console.log('');
|
||||
outcome.app = true;
|
||||
return 0;
|
||||
|
||||
+3
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "plan2code",
|
||||
"version": "3.0.5",
|
||||
"version": "3.1.0",
|
||||
"private": true,
|
||||
"bin": {
|
||||
"plan2code-install": "./install.js"
|
||||
@@ -9,10 +9,11 @@
|
||||
"prepare": "husky",
|
||||
"build:skills": "node install.js --build-skills",
|
||||
"fix:eol": "node scripts/fix-line-endings.mjs",
|
||||
"set-version": "node scripts/set-version.mjs",
|
||||
"play": "node scripts/play.mjs",
|
||||
"pretest": "node scripts/fix-line-endings.mjs",
|
||||
"test:fast": "node scripts/test-fast.mjs",
|
||||
"test": "node scripts/check-test-lanes.mjs && node scripts/validate-char-count.js && node install.js --build-skills && node scripts/check-versions.mjs && node scripts/check-doc-size.mjs && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node scripts/check-prompt-wording.mjs && node scripts/check-console-openings.mjs && node scripts/node-test.mjs scripts/test-line-endings.mjs scripts/test-us-english.mjs scripts/test-script-git.mjs scripts/test-git-repo.mjs scripts/test-skill-scripts.mjs scripts/test-script-test-map.mjs scripts/test-script-test-match.mjs scripts/test-script-test-commands.mjs scripts/test-script-run-check.mjs scripts/test-script-pr-prep.mjs scripts/test-script-dead-code.mjs scripts/test-script-coverage.mjs scripts/test-script-changelog.mjs scripts/test-web-console-git.mjs scripts/test-web-console-git-board.mjs scripts/test-web-console-chat.mjs scripts/test-web-console-subagents.mjs scripts/test-web-console-pointers.mjs scripts/test-console-wire-budgets.mjs scripts/test-web-console-speed.mjs scripts/test-web-console-qa.mjs scripts/test-web-console-concurrency.mjs scripts/test-web-console-workspace.mjs scripts/test-web-console-lifecycle.mjs scripts/test-web-console-chat-stress.mjs scripts/test-web-console-server.mjs scripts/test-web-console-session.mjs scripts/test-web-console-logic.mjs scripts/test-web-console-agents-doc.mjs scripts/test-web-console-activities.mjs scripts/test-web-console-activities-rapids.mjs scripts/test-web-console-activities-flock.mjs scripts/test-web-console-activities-bounce.mjs scripts/test-web-console-activities-bounce-game.mjs scripts/test-web-console-activities-ghoul.mjs scripts/test-web-console-activities-ghoul-graveyard.mjs scripts/test-web-console-activities-ghoul-grounds.mjs scripts/test-web-console-activities-ghoul-chapel.mjs scripts/test-web-console-activities-ghoul-sanatorium.mjs scripts/test-web-console-activities-ghoul-village.mjs scripts/test-web-console-activities-ghoul-mine.mjs scripts/test-web-console-activities-ghoul-carnival.mjs scripts/test-web-console-activities-ghoul-frozen.mjs scripts/test-web-console-activities-ghoul-bog.mjs scripts/test-web-console-activities-ghoul-lantern.mjs scripts/test-web-console-activities-ghoul-marrow.mjs scripts/test-web-console-activities-ghoul-mat.mjs scripts/test-web-console-activities-ghoul-eye.mjs scripts/test-web-console-activities-ghoul-bonestair.mjs scripts/test-web-console-activities-ghoul-heart.mjs scripts/test-web-console-activities-ghoul-ending.mjs scripts/test-web-console-activities-ghoul-ride.mjs scripts/test-web-console-activities-ghoul-cart.mjs scripts/test-web-console-activities-ghoul-sled.mjs scripts/test-web-console-activities-ghoul-banister.mjs scripts/test-web-console-activities-ghoul-gurney.mjs scripts/test-web-console-activities-ghoul-hearse.mjs scripts/test-web-console-activities-ghoul-wagon.mjs scripts/test-web-console-activities-ghoul-pew.mjs scripts/test-web-console-activities-ghoul-mower.mjs scripts/test-web-console-activities-ghoul-tray.mjs scripts/test-web-console-activities-ghoul-arms.mjs scripts/test-web-console-activities-ghoul-dice.mjs scripts/test-web-console-activities-ghoul-gameover.mjs scripts/test-web-console-activities-ghoul-intro.mjs scripts/test-web-console-activities-ghoul-bossintro.mjs scripts/test-web-console-activities-ghoul-story.mjs scripts/test-web-console-activities-ghoul-bones.mjs scripts/test-web-console-activities-ghoul-retry.mjs scripts/test-web-console-activities-bounce-cars.mjs scripts/test-web-console-tones.mjs scripts/test-web-console-skills.mjs scripts/test-web-console-spec-states.mjs scripts/test-spec-carry.mjs scripts/test-spec-carry-page.mjs scripts/test-web-console-state.mjs scripts/test-web-console-send-state.mjs scripts/test-web-console-strengths.mjs scripts/test-web-console-shape.mjs scripts/test-script-pathfinder.mjs scripts/test-skill-test-runs.mjs scripts/test-launcher.mjs scripts/test-agents-file.mjs scripts/test-agent-lookup.mjs scripts/test-web-console-source.mjs scripts/test-web-console-hardening.mjs scripts/test-web-console-embed.mjs scripts/test-web-console-in-app.mjs scripts/test-web-console-loop.mjs scripts/test-web-console-handoffs.mjs scripts/test-web-console-notepad.mjs scripts/test-script-xray.mjs scripts/test-script-finalize.mjs scripts/test-getting-started.mjs scripts/test-install-update.mjs scripts/test-browser-helper.mjs scripts/test-web-console-page-cards.mjs scripts/test-web-console-page-dashboard.mjs scripts/test-web-console-page-session.mjs scripts/test-web-console-page-ask.mjs scripts/test-web-console-page-workspace.mjs scripts/test-web-console-page-help.mjs scripts/test-web-console-page-prefs.mjs scripts/test-web-console-page-git.mjs scripts/test-web-console-page-notepad.mjs scripts/test-web-console-page-send.mjs scripts/test-web-console-page-loop.mjs scripts/test-web-console-page-activities.mjs scripts/test-web-console-page-setup.mjs scripts/test-standalone-check.mjs scripts/test-check-versions.mjs scriptsLine truncated
|
||||
"test": "node scripts/check-test-lanes.mjs && node scripts/validate-char-count.js && node install.js --build-skills && node scripts/check-versions.mjs && node scripts/check-doc-size.mjs && node scripts/parse-check.mjs && node scripts/check-skill-table.mjs && node scripts/check-prompt-wording.mjs && node scripts/check-console-openings.mjs && node scripts/node-test.mjs scripts/test-line-endings.mjs scripts/test-us-english.mjs scripts/test-script-git.mjs scripts/test-git-repo.mjs scripts/test-skill-scripts.mjs scripts/test-script-test-map.mjs scripts/test-script-lessons.mjs scripts/test-script-test-match.mjs scripts/test-script-test-commands.mjs scripts/test-script-run-check.mjs scripts/test-script-pr-prep.mjs scripts/test-script-dead-code.mjs scripts/test-script-deps.mjs scripts/test-script-ui-prototype.mjs scripts/test-script-coverage.mjs scripts/test-script-changelog.mjs scripts/test-script-changes.mjs scripts/test-web-console-git.mjs scripts/test-web-console-git-board.mjs scripts/test-web-console-chat.mjs scripts/test-web-console-subagents.mjs scripts/test-web-console-pointers.mjs scripts/test-web-console-learning.mjs scripts/test-console-wire-budgets.mjs scripts/test-web-console-speed.mjs scripts/test-web-console-qa.mjs scripts/test-web-console-concurrency.mjs scripts/test-web-console-diff-parse.mjs scripts/test-web-console-workspace.mjs scripts/test-web-console-lifecycle.mjs scripts/test-web-console-chat-stress.mjs scripts/test-web-console-server.mjs scripts/test-web-console-session.mjs scripts/test-web-console-logic.mjs scripts/test-web-console-agents-doc.mjs scripts/test-web-console-prototypes.mjs scripts/test-web-console-activities.mjs scripts/test-web-console-activities-rapids.mjs scripts/test-web-console-activities-flock.mjs scripts/test-web-console-activities-bounce.mjs scripts/test-web-console-activities-bounce-game.mjs scripts/test-web-console-activities-ghoul.mjs scripts/test-web-console-activities-ghoul-graveyard.mjs scripts/test-web-console-activities-ghoul-grounds.mjs scripts/test-web-console-activities-ghoul-chapel.mjs scripts/test-web-console-activities-ghoul-sanatorium.mjs scripts/test-web-console-activities-ghoul-village.mjs scripts/test-web-console-activities-ghoul-mine.mjs scripts/test-web-console-activities-ghoul-carnival.mjs scripts/test-web-console-activities-ghoul-frozen.mjs scripts/test-web-console-activities-ghoul-bog.mjs scripts/test-web-console-activities-ghoul-lantern.mjs scripts/test-web-console-activities-ghoul-marrow.mjs scripts/test-web-console-activities-ghoul-mat.mjs scripts/test-web-console-activities-ghoul-eye.mjs scripts/test-web-console-activities-ghoul-bonestair.mjs scripts/test-web-console-activities-ghoul-heart.mjs scripts/test-web-console-activities-ghoul-ending.mjs scripts/test-web-console-activities-ghoul-ride.mjs scripts/test-web-console-activities-ghoul-cart.mjs scripts/test-web-console-activities-ghoul-sled.mjs scripts/test-web-console-activities-ghoul-banister.mjs scripts/test-web-console-activities-ghoul-gurney.mjs scripts/test-web-console-activities-ghoul-hearse.mjs scripts/test-web-console-activities-ghoul-wagon.mjs scripts/test-web-console-activities-ghoul-pew.mjs scripts/test-web-console-activities-ghoul-mower.mjs scripts/test-web-console-activities-ghoul-tray.mjs scripts/test-web-console-activities-ghoul-arms.mjs scripts/test-web-console-activities-ghoul-dice.mjs scripts/test-web-console-activities-ghoul-gameover.mjs scripts/test-web-console-activities-ghoul-intro.mjs scripts/test-web-console-activities-ghoul-bossintro.mjs scripts/test-web-console-activities-ghoul-story.mjs scripts/test-web-console-activities-ghoul-bones.mjs scripts/test-web-console-activities-ghoul-retry.mjs scripts/test-web-console-activities-bounce-cars.mjs scripts/test-web-console-activities-bounce-arcade.mjs scripts/test-web-console-tones.mjs scripts/test-web-console-skills.mjs scripts/test-web-console-spec-states.mjs scripts/test-web-console-card-rows.mjs scripts/test-spec-carry.mjs scripts/test-spec-carry-page.mjs scripts/test-web-console-state.mjs scripts/test-web-console-send-state.mjs scripts/test-web-console-strengths.mjs scripts/test-web-console-shape.mjs scripts/test-script-pathfinder.mjs scripts/test-skill-test-runs.mjs scripts/test-launcher.mjs scripts/test-agents-file.mjs scripts/test-agent-lookup.mjs scripts/test-web-console-source.mjs scripts/test-web-console-hardening.mjs scripts/test-web-console-embed.mjs scripts/test-web-console-in-app.mjs scripts/test-web-console-loop.mjs scripts/test-web-console-handoffs.mjs scripts/test-web-console-notepad.mjs scripts/test-script-xray.mjs scripts/test-script-finalize.mjs scripts/test-getting-started.mjs scripts/test-install-update.mjs scripts/test-browser-helper.mjs scripts/test-web-console-page-cards.mjs scripts/test-web-console-page-changes.mjs scripts/test-web-console-page-dashboard.mjs scripts/test-web-console-page-learning.mjs scripts/test-web-console-page-session.mjs scripts/test-web-console-page-ask.mjs scripts/test-Line truncated
|
||||
},
|
||||
"devDependencies": {
|
||||
"gpt-tokenizer": "2.9.0",
|
||||
|
||||
Generated
+2
-2
@@ -757,7 +757,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "fake-agent"
|
||||
version = "3.0.5"
|
||||
version = "3.1.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
"terminal_size",
|
||||
@@ -2371,7 +2371,7 @@ checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
|
||||
|
||||
[[package]]
|
||||
name = "plan2code-app"
|
||||
version = "3.0.5"
|
||||
version = "3.1.0"
|
||||
dependencies = [
|
||||
"chrono",
|
||||
"libc",
|
||||
|
||||
@@ -8,6 +8,8 @@ The app is optional. The Node web console and the skills never depend on it, so
|
||||
|
||||
**Agent picker.** The launch card lists Claude Code, Devin and Codex, then any custom agents from `~/.plan2code/agents.json` (added in the console's User Preferences → Agents & models, the same list the `plan2code` command uses). The app starts on an agent that is installed (your last pick when it still is), never assumes Claude Code, and a custom agent has no effort row; New Session reuses whichever agent you started. The Model dropdown offers the same list the `plan2code` launcher's model question does (the shipped `models.json` plus anything you added in User Preferences), a custom agent its own `models`, and it hides for an agent with none; `/plan2code` only does something in an agent that loads the installed Plan2Code skills.
|
||||
|
||||
**Project picker.** The app takes its folder from `--project` (what the `plan2code` command and the desktop shortcut pass) and never reopens the last one by itself. Started with no folder, and from **Change project**, it shows one picker: **Choose a folder** (focused, the default; it opens the system folder dialog) with the recent folders under it, newest first, leaving out the folder already open. The list is `recentFolders` in `~/.plan2code/launcher.json`, shared with the `plan2code` command, which keeps it by the same rule: `recent_folders` and `open_recent_folder` in `src-tauri/src/main.rs` over `project.rs`, held to `scripts/fixtures/recent-folders-cases.json` (the launcher's JS runs the same cases). A recent folder that has gone away is left out of the list (one that vanishes between the listing and the click shows an error on the picker), and Change project is refused while an Implementation Loop runs.
|
||||
|
||||
**No agent installed.** The first-run checklist and the launch card show what an agent CLI is, each built-in's install command and an **Install page** link, and a note that other agents are added under Agents. Install one, press **Check again** (the app looks at `PATH` and `agents.json` again), and Start works without restarting the app.
|
||||
|
||||
**Taskbar signal.** The console page tells the app when it is busy, your move, or needs attention (the same states as its tab icon), and the app shows it:
|
||||
|
||||
@@ -36,7 +36,7 @@ file directly after checking it against the release's checksum list.
|
||||
launch card or checklist shown first, and New Session keeps them
|
||||
- [ ] `plan2code --classic` runs the agent in the terminal with the app installed
|
||||
- [ ] Linux only: with `DISPLAY` and `WAYLAND_DISPLAY` unset, `plan2code` runs the terminal flow
|
||||
- [ ] The desktop shortcut opens the folder picker and then the app
|
||||
- [ ] The desktop shortcut opens the folder menu (Choose a folder first, recent folders under it) and then the app
|
||||
- [ ] macOS: the first start is stopped by Gatekeeper, **Open Anyway** in System Settings (Privacy &
|
||||
Security) lets it through, and `docs/desktop-app.md` describes what you saw
|
||||
- [ ] macOS and Linux: start the app from the Dock, Finder or a `.desktop` file (not a terminal) on
|
||||
@@ -75,7 +75,8 @@ file directly after checking it against the release's checksum list.
|
||||
- [ ] 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
|
||||
- [ ] **Change project** in the top bar's project menu, with an agent running: it asks first, then the folder
|
||||
picker opens; canceling the picker leaves the running agent and its project untouched
|
||||
picker (Choose a folder, then recent folders) opens; canceling the picker leaves the running agent and its project untouched
|
||||
- [ ] Start the app with no arguments: it shows the folder picker, not the last project; a recent folder opens in one click
|
||||
- [ ] Change project, pick a different folder: the old agent and console stop, the new folder opens
|
||||
on the launch card (or the checklist, if its own first run has not passed yet)
|
||||
- [ ] Reload the window (or navigate away and back) while an agent is running: the terminal redraws
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "fake-agent"
|
||||
version = "3.0.5"
|
||||
version = "3.1.0"
|
||||
description = "A stand-in agent program for the Plan2Code app's tests"
|
||||
edition = "2021"
|
||||
publish = false
|
||||
|
||||
Generated
+2
-2
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "plan2code-app",
|
||||
"version": "3.0.5",
|
||||
"version": "3.1.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "plan2code-app",
|
||||
"version": "3.0.5",
|
||||
"version": "3.1.0",
|
||||
"dependencies": {
|
||||
"@tauri-apps/api": "2.12.4",
|
||||
"@xterm/addon-fit": "0.11.0",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "plan2code-app",
|
||||
"version": "3.0.5",
|
||||
"version": "3.1.0",
|
||||
"private": true,
|
||||
"description": "Plan2Code desktop app (Tauri). Separate from the repo root so the root and the web console stay dependency-free.",
|
||||
"scripts": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "plan2code-app"
|
||||
version = "3.0.5"
|
||||
version = "3.1.0"
|
||||
description = "Plan2Code desktop app"
|
||||
edition = "2021"
|
||||
publish = false
|
||||
|
||||
@@ -1894,8 +1894,10 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn ids_round_trip() {
|
||||
for entry in [entry("claude"), entry("devin"), entry("codex")] {
|
||||
assert_eq!(builtin_entry(&entry.id), Some(entry));
|
||||
// Ids only: builtin_entry reads the installed agents.json first, which
|
||||
// can be older than the source on a machine with a release installed.
|
||||
for id in ["claude", "devin", "codex"] {
|
||||
assert_eq!(builtin_entry(id).map(|e| e.id), Some(id.to_string()));
|
||||
}
|
||||
assert!(builtin_entry("nope").is_none());
|
||||
}
|
||||
|
||||
@@ -268,6 +268,10 @@ pub struct Outcome {
|
||||
pub conflicts: Vec<String>,
|
||||
pub decisions: Vec<String>,
|
||||
pub subject: String,
|
||||
/// What the failing phase's agent suggests the person do next (a failed
|
||||
/// report only): shown on the stop screen and at the top of its report.
|
||||
#[serde(rename = "nextStep")]
|
||||
pub next_step: Option<String>,
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------- the record
|
||||
@@ -717,19 +721,44 @@ fn leftover(review: &ReviewPart, level: FixLevel) -> u32 {
|
||||
|
||||
/// Why a phase says it failed, for the stop line and the notification: what the
|
||||
/// agent wrote, which a person can read, else the contract's reason in words.
|
||||
///
|
||||
/// The reason leads and the agent's summary follows it: a failed report's
|
||||
/// summary often reads like success ("12 of 12 tasks, 77 tests pass"), so on
|
||||
/// its own it hides why the phase stopped.
|
||||
fn failed_words(outcome: &Outcome) -> String {
|
||||
let summary = outcome.summary.trim();
|
||||
if !summary.is_empty() {
|
||||
return summary.to_string();
|
||||
}
|
||||
match outcome.reason.as_deref() {
|
||||
let mut words = match outcome.reason.as_deref() {
|
||||
Some("tests") => "its tests failed",
|
||||
Some("findings") => "the review left findings it had to fix",
|
||||
Some("blocked") => "a task is blocked",
|
||||
Some("conflict") => "the spec conflicts with the code",
|
||||
_ => "it reported a failure",
|
||||
}
|
||||
.to_string()
|
||||
.to_string();
|
||||
if outcome.reason.as_deref() == Some("findings") {
|
||||
if let Some(review) = &outcome.review {
|
||||
let mut left = Vec::new();
|
||||
for (level, word) in [
|
||||
(FixLevel::Critical, "Critical"),
|
||||
(FixLevel::Warning, "Warning"),
|
||||
] {
|
||||
let n = leftover(review, level);
|
||||
if n > 0 {
|
||||
left.push(format!("{n} {word}"));
|
||||
}
|
||||
}
|
||||
if !left.is_empty() {
|
||||
words.push_str(&format!(" ({})", left.join(" / ")));
|
||||
}
|
||||
}
|
||||
}
|
||||
let summary = one_line(&outcome.summary);
|
||||
if summary.is_empty() {
|
||||
words
|
||||
} else if words.starts_with("it reported") {
|
||||
format!("{words}: {summary}")
|
||||
} else {
|
||||
format!("{words}. The agent said: {summary}")
|
||||
}
|
||||
}
|
||||
|
||||
/// The report's note about Suggestions the phase left unfixed, if any. They
|
||||
@@ -2984,7 +3013,20 @@ fn report_section(outcome: &Outcome, entry: Option<&Value>) -> String {
|
||||
/// The markdown behind "Why the loop stopped": what failed and the proof, by
|
||||
/// cause. Kept under 100 KB (output is trimmed to its tail).
|
||||
pub fn evidence_markdown(cause: &StopCause, line: &str, rec: &RunningRecord) -> String {
|
||||
let mut md = format!("## What happened\n\n{line}\n");
|
||||
let at = rec.current.min(rec.phases.len().saturating_sub(1));
|
||||
let (phase, built) = rec
|
||||
.phases
|
||||
.get(at)
|
||||
.map_or((1, false), |p| (p.n, p.status == PhaseStatus::Done));
|
||||
// The cause and what to do about it come before everything else, in boxes
|
||||
// the page colors (`> [!CAUTION]` red, `> [!TIP]` blue).
|
||||
let mut md = format!(
|
||||
"> [!CAUTION]\n> **Why it stopped:** {}\n>\n> {}\n\n> [!TIP]\n> **What to do next:** {}\n\n",
|
||||
stop_reason(cause, phase, built),
|
||||
one_line(line),
|
||||
stop_advice(cause, rec.last_outcome.as_ref())
|
||||
);
|
||||
md.push_str(&format!("## What happened\n\n{line}\n"));
|
||||
let phase_report = matches!(
|
||||
cause,
|
||||
StopCause::Refused(_)
|
||||
@@ -3118,6 +3160,7 @@ fn post_end(ctx: &Ctx, rec: &RunningRecord, patch: &Value) {
|
||||
}
|
||||
if let Some(end) = plain.get_mut("loopEnd").and_then(Value::as_object_mut) {
|
||||
end.remove("evidence");
|
||||
end.remove("advice");
|
||||
}
|
||||
let _ = loop_tools::console_post(&ctx.console_dir, &sid, &plain);
|
||||
}
|
||||
@@ -3216,6 +3259,11 @@ fn stop_loop(ctx: &Ctx, cause: StopCause, line: String, can: &[&str]) {
|
||||
"uncommitted": uncommitted,
|
||||
"can": stop_can(can),
|
||||
"reason": stop_reason(&cause, rec.phases[at].n, built),
|
||||
// The page refuses a longer line, and a refused end is never drawn.
|
||||
"advice": stop_advice(&cause, rec.last_outcome.as_ref())
|
||||
.chars()
|
||||
.take(300)
|
||||
.collect::<String>(),
|
||||
"recommend": stop_recommend(&cause, can),
|
||||
"phase": continue_phase(
|
||||
&rec.phases.iter().map(|p| p.n).collect::<Vec<_>>(),
|
||||
@@ -3274,6 +3322,44 @@ pub fn stop_reason(cause: &StopCause, phase: u32, built: bool) -> String {
|
||||
}
|
||||
}
|
||||
|
||||
/// What the person should do next, in one line. A phase that reported `failed`
|
||||
/// and refused to go on brings its own `nextStep` (the agent that just failed
|
||||
/// knows the most); without one, and for every other cause, plain words by cause.
|
||||
pub fn stop_advice(cause: &StopCause, outcome: Option<&Outcome>) -> String {
|
||||
let failed = outcome.filter(|o| o.result == "failed");
|
||||
if matches!(cause, StopCause::Refused(_)) {
|
||||
let own = failed
|
||||
.and_then(|o| o.next_step.as_deref())
|
||||
.map(one_line)
|
||||
.filter(|s| !s.is_empty());
|
||||
if let Some(step) = own {
|
||||
return step;
|
||||
}
|
||||
}
|
||||
match cause {
|
||||
StopCause::Refused(_) => match failed.and_then(|o| o.reason.as_deref()) {
|
||||
Some("tests") => "Press Fix together with an agent to work through the failing tests, then press Continue building.",
|
||||
Some("findings") => "Press Fix together with an agent to settle the findings listed below, then press Continue building.",
|
||||
Some("blocked") => "Unblock the task named below (the spec or the setup may need a change), then press Continue building.",
|
||||
Some("conflict") => "Settle the conflict between the spec and the code, together with an agent or by revising the plan, then press Continue building.",
|
||||
_ => "Press Fix together with an agent: it can read the report below, sort out the problem, and then you can press Continue building.",
|
||||
}
|
||||
.to_string(),
|
||||
StopCause::QuickCheck => "Fix what the quick check printed below (Fix together with an agent can do it), then press Continue building.".to_string(),
|
||||
StopCause::Commit => "Fix what git said below, then press Continue building to try the commit again.".to_string(),
|
||||
StopCause::MarkedNotCommitted(file) => format!(
|
||||
"Set the phase back to in progress in {file} by hand, or press Continue building: it checks every done mark against the commit log."
|
||||
),
|
||||
StopCause::UnsafeFiles(_) => "Remove the files listed below or add them to .gitignore, then press Continue building.".to_string(),
|
||||
StopCause::Question => "Press Fix together with an agent to answer the question, or settle it in the spec, then press Continue building.".to_string(),
|
||||
StopCause::Crash => "Press Continue building: nothing was undone. If it crashes again, press Fix together with an agent and read the terminal beside this page.".to_string(),
|
||||
StopCause::Silence => "Press Continue building to start the phase again. If it goes quiet again, raise the silence limit in the loop setup or press Fix together with an agent.".to_string(),
|
||||
StopCause::NoSession => "Press Continue building to try again. If the agent still never opens its page, press Fix together with an agent to see why.".to_string(),
|
||||
StopCause::WatcherFailed(_) => "Press Continue building to carry on from the spec. Whatever was committed stays committed.".to_string(),
|
||||
StopCause::StoppedByPerson => "Press Continue building when you are ready. Nothing was undone.".to_string(),
|
||||
}
|
||||
}
|
||||
|
||||
/// The one button the stop screen recommends, from `can` (the buttons it
|
||||
/// offers). A soft stop (the agent crashed or went quiet, the person stopped
|
||||
/// it, the watcher failed) recommends Continue building: nothing in the work
|
||||
@@ -3906,8 +3992,8 @@ mod tests {
|
||||
o.summary = "Opus misses the 40% target".into();
|
||||
assert_eq!(
|
||||
refused(judge_outcome(&o, &status(14, 0, 0, 0), &setup())),
|
||||
"Opus misses the 40% target",
|
||||
"the person is told what the agent found, not a contract word"
|
||||
"its tests failed. The agent said: Opus misses the 40% target",
|
||||
"the reason leads, and the agent's own words follow it"
|
||||
);
|
||||
o.summary = " ".into();
|
||||
assert_eq!(
|
||||
@@ -3921,6 +4007,34 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_failed_report_that_reads_like_success_still_leads_with_why_it_failed() {
|
||||
let mut o = passed();
|
||||
o.result = "failed".into();
|
||||
o.reason = Some("findings".into());
|
||||
o.summary = "12 of 12 tasks, 77 tests pass; the re-check found 1 new warning".into();
|
||||
let review = o.review.as_mut().unwrap();
|
||||
review.left = Left {
|
||||
critical: 0,
|
||||
warning: 1,
|
||||
suggestion: 0,
|
||||
};
|
||||
let why = refused(judge_outcome(&o, &status(12, 0, 0, 0), &setup()));
|
||||
assert!(
|
||||
why.starts_with(
|
||||
"the review left findings it had to fix (1 Warning). The agent said: 12 of 12"
|
||||
),
|
||||
"{why}"
|
||||
);
|
||||
// A reason the contract has no words for takes the agent's summary alone.
|
||||
o.reason = Some("other".into());
|
||||
o.summary = "A plan change is waiting".into();
|
||||
assert_eq!(
|
||||
refused(judge_outcome(&o, &status(12, 0, 0, 0), &setup())),
|
||||
"it reported a failure: A plan change is waiting"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn marks_that_disagree_with_the_report_are_refused() {
|
||||
assert!(
|
||||
@@ -4776,7 +4890,15 @@ second line"
|
||||
"Phase 2 stopped: 1 Warning left after the re-check",
|
||||
&rec,
|
||||
);
|
||||
assert!(md.starts_with("## What happened"));
|
||||
// The cause and what to do about it come before everything else.
|
||||
assert!(md.starts_with("> [!CAUTION]\n"), "{md}");
|
||||
let caution = md.find("> [!CAUTION]").unwrap();
|
||||
let tip = md.find("> [!TIP]").expect("a what-to-do-next box");
|
||||
let happened = md.find("## What happened").unwrap();
|
||||
assert!(caution < tip && tip < happened, "{md}");
|
||||
assert!(md.contains("> **Why it stopped:** Phase 2 stopped on a problem"));
|
||||
assert!(md.contains("> Phase 2 stopped: 1 Warning left after the re-check"));
|
||||
assert!(md.contains("> **What to do next:**"));
|
||||
assert!(md.contains("- Summary: Built the screen"));
|
||||
assert!(md.contains("- Tests: 2 failed"));
|
||||
assert!(md.contains("0 Critical, 1 Warning, 2 Suggestion"));
|
||||
@@ -4785,6 +4907,76 @@ second line"
|
||||
assert!(md.contains("warning: Name the timer (src/x.js)"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_advice_is_the_failed_phases_own_next_step_or_built_in_words_for_the_cause() {
|
||||
let mut o = passed();
|
||||
o.result = "failed".into();
|
||||
o.reason = Some("tests".into());
|
||||
o.next_step =
|
||||
Some(" Run test-deps.mjs, fix the failing range check, then continue ".into());
|
||||
let refused = StopCause::Refused("its tests failed".into());
|
||||
assert_eq!(
|
||||
stop_advice(&refused, Some(&o)),
|
||||
"Run test-deps.mjs, fix the failing range check, then continue"
|
||||
);
|
||||
// No next step from the agent: words for its reason, then for the cause.
|
||||
o.next_step = None;
|
||||
assert!(stop_advice(&refused, Some(&o)).contains("failing tests"));
|
||||
o.reason = Some("findings".into());
|
||||
assert!(stop_advice(&refused, Some(&o)).contains("findings"));
|
||||
assert!(stop_advice(&refused, None).contains("Fix together with an agent"));
|
||||
// A next step belongs to a failed report that refused the phase, never to a
|
||||
// passed one that stopped later on a failed check.
|
||||
o.result = "passed".into();
|
||||
o.next_step = Some("Do not show this".into());
|
||||
assert!(!stop_advice(&StopCause::QuickCheck, Some(&o)).contains("Do not show this"));
|
||||
assert!(!stop_advice(&refused, Some(&o)).contains("Do not show this"));
|
||||
for cause in [
|
||||
StopCause::Crash,
|
||||
StopCause::Silence,
|
||||
StopCause::NoSession,
|
||||
StopCause::StoppedByPerson,
|
||||
StopCause::WatcherFailed("x".into()),
|
||||
refused,
|
||||
StopCause::QuickCheck,
|
||||
StopCause::Commit,
|
||||
StopCause::MarkedNotCommitted("phase-3.md".into()),
|
||||
StopCause::UnsafeFiles(vec![".env".into()]),
|
||||
StopCause::Question,
|
||||
] {
|
||||
let advice = stop_advice(&cause, None);
|
||||
assert!(!advice.is_empty(), "{cause:?}");
|
||||
assert!(!advice.contains('\u{2014}'), "{advice}");
|
||||
}
|
||||
assert!(
|
||||
stop_advice(&StopCause::MarkedNotCommitted("phase-3.md".into()), None)
|
||||
.contains("phase-3.md")
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_failed_phases_next_step_leads_the_evidence_box() {
|
||||
let mut rec = record("specs/x", vec![phase(2)]);
|
||||
let mut o = passed();
|
||||
o.result = "failed".into();
|
||||
o.reason = Some("findings".into());
|
||||
o.summary = "Built it; the re-check found 1 new warning".into();
|
||||
o.next_step = Some("Fix the unreadable range in deps.mjs, then continue".into());
|
||||
rec.last_outcome = Some(o);
|
||||
let cause = StopCause::Refused("the review left findings it had to fix".into());
|
||||
let md = evidence_markdown(
|
||||
&cause,
|
||||
"Phase 2 stopped: the review left findings it had to fix",
|
||||
&rec,
|
||||
);
|
||||
assert!(
|
||||
md.contains(
|
||||
"> **What to do next:** Fix the unreadable range in deps.mjs, then continue"
|
||||
),
|
||||
"{md}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_evidence_of_an_approved_phase_that_stopped_later_shows_the_suggestion_warning() {
|
||||
let mut rec = record("specs/x", vec![phase(2)]);
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
// Hide the extra console window on Windows release builds.
|
||||
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
|
||||
|
||||
use std::path::Path;
|
||||
use std::sync::atomic::{AtomicBool, Ordering};
|
||||
use std::sync::{Arc, Mutex, OnceLock};
|
||||
|
||||
@@ -812,8 +813,8 @@ async fn update_skills(
|
||||
Ok(UpdateOutcome { message, status })
|
||||
}
|
||||
|
||||
/// The OS folder picker, shown when no folder is known; a choice becomes the
|
||||
/// launcher's remembered folder.
|
||||
/// 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.
|
||||
#[tauri::command(async)]
|
||||
fn pick_project_folder(
|
||||
app: tauri::AppHandle,
|
||||
@@ -886,6 +887,68 @@ fn change_project(
|
||||
Ok(Some(text))
|
||||
}
|
||||
|
||||
/// The recent project folders that still exist, newest first, for the page's
|
||||
/// folder picker: `{ dir, name }` each, `name` the folder's own name (the full
|
||||
/// path for a root, which has none). The project already open is left out
|
||||
/// (none on a bare start), since picking it would change nothing. Off the
|
||||
/// main thread: each row checks the disk, and a saved folder on an
|
||||
/// unreachable share must not freeze the window.
|
||||
#[tauri::command(async)]
|
||||
fn recent_folders(state: State<'_, AppState>) -> Vec<serde_json::Value> {
|
||||
let current = state
|
||||
.project
|
||||
.lock()
|
||||
.ok()
|
||||
.and_then(|p| p.as_ref().map(|p| p.dir.clone()));
|
||||
project::recent_folders(current.as_deref())
|
||||
.into_iter()
|
||||
.map(|dir| {
|
||||
let full = dir.to_string_lossy().into_owned();
|
||||
let name = dir
|
||||
.file_name()
|
||||
.map(|n| n.to_string_lossy().into_owned())
|
||||
.unwrap_or_else(|| full.clone());
|
||||
serde_json::json!({ "dir": full, "name": name })
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// Whether opening `dir` must first tear the current project down: only when
|
||||
/// a project is set and it is a different folder (`same_folder`'s rule, so a
|
||||
/// trailing separator, and case on Windows, do not count).
|
||||
fn needs_teardown(current: Option<&Path>, dir: &Path, windows: bool) -> bool {
|
||||
current.is_some_and(|cur| {
|
||||
!project::same_folder(&cur.to_string_lossy(), &dir.to_string_lossy(), windows)
|
||||
})
|
||||
}
|
||||
|
||||
/// Open one of the recent folders from the folder picker. A different folder
|
||||
/// than the open project tears the old one down first (as `change_project`
|
||||
/// does) and goes to the top of the recent folders; the same folder is kept
|
||||
/// as it is, with nothing torn down.
|
||||
#[tauri::command(async)]
|
||||
fn open_recent_folder(state: State<'_, AppState>, dir: String) -> Result<Option<String>, String> {
|
||||
refuse_while_looping(&state, "project")?;
|
||||
let path = Path::new(&dir);
|
||||
if !path.is_dir() {
|
||||
return Err(format!("{dir} is not a folder"));
|
||||
}
|
||||
let current = state
|
||||
.project
|
||||
.lock()
|
||||
.map_err(|e| e.to_string())?
|
||||
.as_ref()
|
||||
.map(|p| p.dir.clone());
|
||||
match current {
|
||||
Some(cur) if !needs_teardown(Some(&cur), path, cfg!(windows)) => return Ok(Some(dir)),
|
||||
Some(_) => teardown_project(&state)?,
|
||||
None => {}
|
||||
}
|
||||
let choice = project::remember_folder(path)?;
|
||||
*state.project.lock().map_err(|e| e.to_string())? = Some(choice);
|
||||
Ok(Some(dir))
|
||||
}
|
||||
|
||||
/// The console the agent opened, alive and as it is now, or restarted on the
|
||||
/// same session when it died. The app never starts a dashboard of its own:
|
||||
/// the agent does, by running the skill, and announces it. The one exception
|
||||
@@ -1362,6 +1425,8 @@ fn main() {
|
||||
check_new_release,
|
||||
update_skills,
|
||||
pick_project_folder,
|
||||
recent_folders,
|
||||
open_recent_folder,
|
||||
change_project,
|
||||
console_start,
|
||||
console_status,
|
||||
@@ -1927,4 +1992,21 @@ mod tests {
|
||||
"unexpected message: {err:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn opening_a_recent_folder_tears_down_only_a_different_project() {
|
||||
let dir = Path::new("/work/b");
|
||||
// No project yet: nothing to tear down.
|
||||
assert!(!needs_teardown(None, dir, false));
|
||||
// The same folder, as written or with a trailing separator.
|
||||
assert!(!needs_teardown(Some(Path::new("/work/b")), dir, false));
|
||||
assert!(!needs_teardown(Some(Path::new("/work/b/")), dir, false));
|
||||
// A different folder.
|
||||
assert!(needs_teardown(Some(Path::new("/work/a")), dir, false));
|
||||
// Case counts outside Windows, not on it.
|
||||
assert!(needs_teardown(Some(Path::new("/work/B")), dir, false));
|
||||
let win = Path::new(r"C:\Work\B");
|
||||
assert!(!needs_teardown(Some(Path::new(r"c:\work\b\")), win, true));
|
||||
assert!(needs_teardown(Some(Path::new(r"C:\Work\A")), win, true));
|
||||
}
|
||||
}
|
||||
@@ -1,20 +1,24 @@
|
||||
//! Which project folder the app works on: the folder the launcher passes in,
|
||||
//! else the one the launcher remembers, else the person picks. The launcher's
|
||||
//! memory is `~/.plan2code/launcher.json` (`lastFolder`, `lastCli`), shared so
|
||||
//! the app and `plan2code` agree on both.
|
||||
//! else the one the person picks from the page's folder picker (the recent
|
||||
//! folders, or the OS dialog). The launcher's memory is
|
||||
//! `~/.plan2code/launcher.json` (`lastFolder`, `lastCli`), shared so the app
|
||||
//! and `plan2code` agree on both. `recentFolders` (newest first, at
|
||||
//! most 5) holds the folders worked on; `lastFolder` is always its first entry.
|
||||
//! The rule for that list is written twice, here and in `src/launcher/plan2code.js`,
|
||||
//! and both are held to `scripts/fixtures/recent-folders-cases.json`.
|
||||
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use serde::Serialize;
|
||||
use serde_json::Value;
|
||||
|
||||
use crate::agents;
|
||||
|
||||
/// Where the project folder came from, in the order it is tried.
|
||||
/// Where the project folder came from: the launcher's argument, or the picker.
|
||||
#[derive(Clone, Copy, Serialize)]
|
||||
#[serde(rename_all = "lowercase")]
|
||||
pub enum ProjectSource {
|
||||
Argument,
|
||||
Remembered,
|
||||
Picked,
|
||||
}
|
||||
|
||||
@@ -36,17 +40,103 @@ fn launcher_file() -> Option<PathBuf> {
|
||||
)
|
||||
}
|
||||
|
||||
fn read_launcher() -> serde_json::Map<String, serde_json::Value> {
|
||||
launcher_file()
|
||||
.and_then(|file| std::fs::read_to_string(file).ok())
|
||||
fn read_launcher_from(file: &Path) -> serde_json::Map<String, Value> {
|
||||
std::fs::read_to_string(file)
|
||||
.ok()
|
||||
.and_then(|text| serde_json::from_str(&text).ok())
|
||||
.unwrap_or_default()
|
||||
}
|
||||
|
||||
/// The folder the launcher remembers, when it is still a directory.
|
||||
fn remembered_folder() -> Option<PathBuf> {
|
||||
let dir = PathBuf::from(read_launcher().get("lastFolder")?.as_str()?);
|
||||
dir.is_dir().then_some(dir)
|
||||
fn read_launcher() -> serde_json::Map<String, Value> {
|
||||
launcher_file()
|
||||
.map(|file| read_launcher_from(&file))
|
||||
.unwrap_or_default()
|
||||
}
|
||||
|
||||
/// How many recent project folders the list keeps.
|
||||
const RECENT_FOLDERS_MAX: usize = 5;
|
||||
|
||||
/// One trailing `\` or `/` off a path, but never off a root (`C:\` or `/`).
|
||||
fn trim_folder(p: &str) -> &str {
|
||||
let b = p.as_bytes();
|
||||
let drive_root = b.len() == 3 && b[1] == b':' && b[0].is_ascii_alphabetic();
|
||||
if b.len() > 1 && matches!(b[b.len() - 1], b'\\' | b'/') && !drive_root {
|
||||
&p[..p.len() - 1]
|
||||
} else {
|
||||
p
|
||||
}
|
||||
}
|
||||
|
||||
/// Whether two paths name the same folder: a trailing separator is ignored,
|
||||
/// and case is on Windows. Twin of `sameFolder` in the launcher.
|
||||
pub fn same_folder(a: &str, b: &str, windows: bool) -> bool {
|
||||
let (x, y) = (trim_folder(a), trim_folder(b));
|
||||
if windows {
|
||||
x.to_lowercase() == y.to_lowercase()
|
||||
} else {
|
||||
x == y
|
||||
}
|
||||
}
|
||||
|
||||
/// The recent folders in the launcher's state: `recentFolders`, else
|
||||
/// `[lastFolder]`, else none. Twin of `readRecent`.
|
||||
fn read_recent(state: &serde_json::Map<String, Value>) -> Vec<String> {
|
||||
if let Some(Value::Array(items)) = state.get("recentFolders") {
|
||||
return items
|
||||
.iter()
|
||||
.filter_map(Value::as_str)
|
||||
.filter(|s| !s.is_empty())
|
||||
.take(RECENT_FOLDERS_MAX)
|
||||
.map(str::to_string)
|
||||
.collect();
|
||||
}
|
||||
match state.get("lastFolder").and_then(Value::as_str) {
|
||||
Some(last) if !last.is_empty() => vec![last.to_string()],
|
||||
_ => Vec::new(),
|
||||
}
|
||||
}
|
||||
|
||||
/// A new list with `dir` first, an earlier entry for the same folder removed,
|
||||
/// cut to the max. Twin of `pushRecent`.
|
||||
fn push_recent(list: &[String], dir: &str, windows: bool) -> Vec<String> {
|
||||
std::iter::once(dir.to_string())
|
||||
.chain(
|
||||
list.iter()
|
||||
.filter(|x| !same_folder(x, dir, windows))
|
||||
.cloned(),
|
||||
)
|
||||
.take(RECENT_FOLDERS_MAX)
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// The folders of `list` worth offering: ones that still exist, minus the one
|
||||
/// in `exclude`. Twin of `listRecent`.
|
||||
fn list_recent(
|
||||
list: &[String],
|
||||
exists: impl Fn(&str) -> bool,
|
||||
exclude: Option<&str>,
|
||||
windows: bool,
|
||||
) -> Vec<String> {
|
||||
list.iter()
|
||||
.filter(|x| exists(x) && !exclude.is_some_and(|e| same_folder(x, e, windows)))
|
||||
.cloned()
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// The folders the person worked on lately that are still folders, newest
|
||||
/// first, minus `exclude` (the project already open, by `same_folder`'s
|
||||
/// rule). The page's folder picker draws them.
|
||||
pub fn recent_folders(exclude: Option<&Path>) -> Vec<PathBuf> {
|
||||
let exclude = exclude.map(|p| p.to_string_lossy().into_owned());
|
||||
list_recent(
|
||||
&read_recent(&read_launcher()),
|
||||
|p| Path::new(p).is_dir(),
|
||||
exclude.as_deref(),
|
||||
cfg!(windows),
|
||||
)
|
||||
.into_iter()
|
||||
.map(PathBuf::from)
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// The id of the agent the launcher last ran (it may be a custom one). The
|
||||
@@ -127,41 +217,44 @@ pub fn launch_choice_in(args: &[String], agents_file: Option<&Path>) -> LaunchCh
|
||||
LaunchChoice { agent, model }
|
||||
}
|
||||
|
||||
/// The folder to open on: the launcher's argument wins, then its memory, then
|
||||
/// nothing (the page asks with the folder picker).
|
||||
/// The folder to open on: only the launcher's argument. Without one the page
|
||||
/// shows its folder picker; the last folder is the picker's first recent row,
|
||||
/// never reopened silently.
|
||||
pub fn resolve(args: &[String]) -> Option<ProjectDir> {
|
||||
if let Some(dir) = argument_folder(args) {
|
||||
return Some(ProjectDir {
|
||||
dir,
|
||||
source: ProjectSource::Argument,
|
||||
});
|
||||
}
|
||||
remembered_folder().map(|dir| ProjectDir {
|
||||
argument_folder(args).map(|dir| ProjectDir {
|
||||
dir,
|
||||
source: ProjectSource::Remembered,
|
||||
source: ProjectSource::Argument,
|
||||
})
|
||||
}
|
||||
|
||||
/// A folder the person picked becomes the remembered one, so the next start
|
||||
/// (app or launcher) opens on it. The launcher's other keys are kept.
|
||||
/// A folder the person picked goes to the top of the recent folders and
|
||||
/// becomes `lastFolder`, so the next start (app or launcher) lists it first.
|
||||
/// The launcher's other keys are kept.
|
||||
pub fn remember_folder(dir: &Path) -> Result<ProjectDir, String> {
|
||||
let file = launcher_file().ok_or("no home folder found")?;
|
||||
let mut state = read_launcher();
|
||||
state.insert(
|
||||
"lastFolder".to_string(),
|
||||
serde_json::Value::String(dir.to_string_lossy().into_owned()),
|
||||
);
|
||||
if let Some(parent) = file.parent() {
|
||||
std::fs::create_dir_all(parent).map_err(err)?;
|
||||
}
|
||||
let json = serde_json::to_string_pretty(&serde_json::Value::Object(state)).map_err(err)?;
|
||||
crate::loop_driver::write_atomic(&file, &json)?;
|
||||
remember_folder_in(&file, dir)?;
|
||||
Ok(ProjectDir {
|
||||
dir: dir.to_path_buf(),
|
||||
source: ProjectSource::Picked,
|
||||
})
|
||||
}
|
||||
|
||||
/// `remember_folder`'s write, into `file`.
|
||||
fn remember_folder_in(file: &Path, dir: &Path) -> Result<(), String> {
|
||||
let mut state = read_launcher_from(file);
|
||||
let recent = push_recent(&read_recent(&state), &dir.to_string_lossy(), cfg!(windows));
|
||||
state.insert("lastFolder".to_string(), Value::String(recent[0].clone()));
|
||||
state.insert(
|
||||
"recentFolders".to_string(),
|
||||
Value::Array(recent.into_iter().map(Value::String).collect()),
|
||||
);
|
||||
if let Some(parent) = file.parent() {
|
||||
std::fs::create_dir_all(parent).map_err(err)?;
|
||||
}
|
||||
let json = serde_json::to_string_pretty(&Value::Object(state)).map_err(err)?;
|
||||
crate::loop_driver::write_atomic(file, &json)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -286,4 +379,112 @@ mod tests {
|
||||
assert_eq!(found, Some(cwd.join("codex")));
|
||||
let _ = std::fs::remove_dir_all(&cwd);
|
||||
}
|
||||
|
||||
const CASES: &str = include_str!("../../../scripts/fixtures/recent-folders-cases.json");
|
||||
|
||||
/// Each case of the fixture group `group` with the platform values it runs under:
|
||||
/// `true` for Windows. Both platform sets run on every OS; a case with none runs under both.
|
||||
fn cases(group: &str) -> Vec<(Value, bool)> {
|
||||
let all: Value = serde_json::from_str(CASES).unwrap();
|
||||
let mut out = Vec::new();
|
||||
for case in all[group].as_array().unwrap() {
|
||||
let winds: &[bool] = match case.get("platform").and_then(Value::as_str) {
|
||||
Some("win32") => &[true],
|
||||
Some("posix") => &[false],
|
||||
_ => &[true, false],
|
||||
};
|
||||
for &windows in winds {
|
||||
out.push((case.clone(), windows));
|
||||
}
|
||||
}
|
||||
assert!(!out.is_empty(), "no {group} cases");
|
||||
out
|
||||
}
|
||||
|
||||
fn strings(value: &Value) -> Vec<String> {
|
||||
value
|
||||
.as_array()
|
||||
.unwrap()
|
||||
.iter()
|
||||
.map(|v| v.as_str().unwrap().to_string())
|
||||
.collect()
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn read_recent_follows_the_shared_cases() {
|
||||
for (case, _) in cases("read") {
|
||||
let state = case["state"].as_object().unwrap();
|
||||
assert_eq!(
|
||||
read_recent(state),
|
||||
strings(&case["expect"]),
|
||||
"{}",
|
||||
case["name"]
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn push_recent_follows_the_shared_cases() {
|
||||
for (case, windows) in cases("push") {
|
||||
let got = push_recent(
|
||||
&strings(&case["list"]),
|
||||
case["dir"].as_str().unwrap(),
|
||||
windows,
|
||||
);
|
||||
assert_eq!(
|
||||
got,
|
||||
strings(&case["expect"]),
|
||||
"{} (windows: {windows})",
|
||||
case["name"]
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn list_recent_follows_the_shared_cases() {
|
||||
for (case, windows) in cases("list") {
|
||||
let exists = strings(&case["exists"]);
|
||||
let got = list_recent(
|
||||
&strings(&case["list"]),
|
||||
|p| exists.iter().any(|e| e == p),
|
||||
case["exclude"].as_str(),
|
||||
windows,
|
||||
);
|
||||
assert_eq!(
|
||||
got,
|
||||
strings(&case["expect"]),
|
||||
"{} (windows: {windows})",
|
||||
case["name"]
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn remember_folder_keeps_the_other_keys_and_writes_both_lists() {
|
||||
let home =
|
||||
std::env::temp_dir().join(format!("p2c-project-remember-{}", std::process::id()));
|
||||
let _ = std::fs::remove_dir_all(&home);
|
||||
std::fs::create_dir_all(&home).unwrap();
|
||||
let file = home.join(".plan2code").join("launcher.json");
|
||||
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
|
||||
std::fs::write(
|
||||
&file,
|
||||
r#"{"lastFolder":"/old","lastCli":"codex","lastModels":{"codex":"m1"}}"#,
|
||||
)
|
||||
.unwrap();
|
||||
|
||||
remember_folder_in(&file, Path::new("/new")).unwrap();
|
||||
let state = read_launcher_from(&file);
|
||||
assert_eq!(state["lastCli"], "codex");
|
||||
assert_eq!(state["lastModels"]["codex"], "m1");
|
||||
assert_eq!(state["lastFolder"], "/new");
|
||||
assert_eq!(state["recentFolders"], serde_json::json!(["/new", "/old"]));
|
||||
|
||||
// Picking the older folder again moves it up, with no duplicate.
|
||||
remember_folder_in(&file, Path::new("/old")).unwrap();
|
||||
let state = read_launcher_from(&file);
|
||||
assert_eq!(state["lastFolder"], "/old");
|
||||
assert_eq!(state["recentFolders"], serde_json::json!(["/old", "/new"]));
|
||||
let _ = std::fs::remove_dir_all(&home);
|
||||
}
|
||||
}
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"$schema": "https://schema.tauri.app/config/2",
|
||||
"productName": "Plan2Code",
|
||||
"version": "3.0.5",
|
||||
"version": "3.1.0",
|
||||
"identifier": "com.plan2code.desktop",
|
||||
"build": {
|
||||
"frontendDist": "../ui",
|
||||
@@ -15,6 +15,7 @@
|
||||
"width": 1280,
|
||||
"height": 800,
|
||||
"maximized": true,
|
||||
"dragDropEnabled": false,
|
||||
"url": "index.html"
|
||||
}
|
||||
],
|
||||
|
||||
+159
-27
@@ -3,7 +3,7 @@
|
||||
// request) with a drag handle.
|
||||
|
||||
import { mountTerminal } from './terminal.js';
|
||||
import { NEW_RELEASE_COMMAND, attentionSignal, barNextSteps, continueKeys, defaultRightFraction, folderName, lastAgentNotice, pickDefaultAgent, taskbarSwitch, windowTitleFor, deadConsoleAction, loopBanner, loopLocks, loopStopLabels, loopWindowTitle, helloRetryAction, retryLabel, RETRY_AFTER_SECONDS } from './meter.js';
|
||||
import { NEW_RELEASE_COMMAND, attentionSignal, barNextSteps, continueKeys, defaultRightFraction, folderName, lastAgentNotice, pickDefaultAgent, taskbarSwitch, windowTitleFor, deadConsoleAction, folderPickerRows, loopBanner, loopLocks, loopStopLabels, loopWindowTitle, helloRetryAction, retryLabel, RETRY_AFTER_SECONDS } from './meter.js';
|
||||
|
||||
const { invoke, Channel } = window.__TAURI__.core;
|
||||
|
||||
@@ -57,6 +57,11 @@ const launchEffortEl = document.getElementById('launch-effort');
|
||||
const launchBypassEl = document.getElementById('launch-bypass');
|
||||
const launchBypassWarningEl = document.getElementById('launch-bypass-warning');
|
||||
const launchStartBtn = document.getElementById('launch-start');
|
||||
const folderPickerEl = document.getElementById('folder-picker');
|
||||
const folderPickerPanelEl = document.getElementById('folder-picker-panel');
|
||||
const folderPickerListEl = document.getElementById('folder-picker-list');
|
||||
const folderPickerErrorEl = document.getElementById('folder-picker-error');
|
||||
const folderPickerCancelBtn = document.getElementById('folder-picker-cancel');
|
||||
const firstRunEl = document.getElementById('first-run');
|
||||
const firstRunListEl = document.getElementById('first-run-list');
|
||||
const firstRunStartBtn = document.getElementById('first-run-start');
|
||||
@@ -950,7 +955,10 @@ function stopRetryCountdown() {
|
||||
stateButton.disabled = false;
|
||||
}
|
||||
|
||||
function showState(text, buttonLabel, onButton, onCancel, { tired = false, retryAfter = 0 } = {}) {
|
||||
// One automatic Try reconnecting per run of trouble (cleared when a new page is announced).
|
||||
let autoReconnected = false;
|
||||
|
||||
function showState(text, buttonLabel, onButton, onCancel, { tired = false, retryAfter = 0, autoRetry = false } = {}) {
|
||||
// The poll repeats the same waiting message every tick: that must not
|
||||
// restart a countdown that is already running (or its button).
|
||||
if (retryAfter > 0 && !stateBox.hidden && stateText.textContent === text && stateButton.textContent.startsWith('Try reconnecting')) return;
|
||||
@@ -975,7 +983,15 @@ function showState(text, buttonLabel, onButton, onCancel, { tired = false, retry
|
||||
retryTimer = setInterval(() => {
|
||||
left -= 1;
|
||||
stateButton.textContent = retryLabel(left);
|
||||
if (left <= 0) stopRetryCountdown();
|
||||
if (left <= 0) {
|
||||
stopRetryCountdown();
|
||||
// The button is on now: press it once for the person. If that try
|
||||
// fails, the button stays for them.
|
||||
if (autoRetry && onButton) {
|
||||
autoReconnected = true;
|
||||
onButton();
|
||||
}
|
||||
}
|
||||
}, 1000);
|
||||
}
|
||||
}
|
||||
@@ -1020,7 +1036,7 @@ async function pollConsole() {
|
||||
if (action === 'wait-for-phase') {
|
||||
// Covers the old phase's page and its "Lost contact" until the new one
|
||||
// says hello. Never over a question the box is already asking.
|
||||
if (stateCancelEl.hidden) showState(loopDetailEl.textContent, 'Try reconnecting', reconnectConsole, undefined, { retryAfter: RETRY_AFTER_SECONDS });
|
||||
if (stateCancelEl.hidden) showState(loopDetailEl.textContent, 'Try reconnecting', reconnectConsole, undefined, { retryAfter: RETRY_AFTER_SECONDS, autoRetry: !autoReconnected });
|
||||
return;
|
||||
}
|
||||
markConsoleDead();
|
||||
@@ -1110,6 +1126,7 @@ function showAnnounced(notice) {
|
||||
restarting = false;
|
||||
// A new page is a new start: the budget is per run of trouble, not per launch.
|
||||
reconnects = 0;
|
||||
autoReconnected = false;
|
||||
if (!consoleKnown) {
|
||||
consoleKnown = true;
|
||||
if (!pollTimer) pollTimer = setInterval(pollConsole, STATUS_POLL_MS);
|
||||
@@ -1349,25 +1366,138 @@ function setProjectDir(dir) {
|
||||
window.__TAURI__.window.getCurrentWindow().setTitle(windowTitleFor(dir)).catch(() => {});
|
||||
}
|
||||
|
||||
// The state `main()` read at startup: `pickFolder()` and the first-run
|
||||
// The state `main()` read at startup: the folder picker and the first-run
|
||||
// checklist both need it once a folder lands, after the fact.
|
||||
let appState = null;
|
||||
|
||||
// Opens the OS folder picker. A canceled pick (or a failed one) lands on the
|
||||
// "No project folder chosen" state with a button that tries again.
|
||||
async function pickFolder() {
|
||||
try {
|
||||
const dir = await invoke('pick_project_folder');
|
||||
if (!dir) {
|
||||
showState('No project folder chosen', 'Choose folder', pickFolder);
|
||||
return;
|
||||
}
|
||||
setProjectDir(dir);
|
||||
if (appState) appState.projectDir = dir;
|
||||
afterProjectKnown();
|
||||
} catch (error) {
|
||||
showState(`Could not open the folder picker: ${error}`, 'Choose folder', pickFolder);
|
||||
// The open folder picker's way back to its caller (null while none is open).
|
||||
let folderPickerResolve = null;
|
||||
|
||||
function hideFolderPicker() {
|
||||
folderPickerEl.hidden = true;
|
||||
folderPickerEl.classList.remove('is-dialog');
|
||||
folderPickerListEl.replaceChildren();
|
||||
}
|
||||
|
||||
function closeFolderPicker(dir) {
|
||||
const resolve = folderPickerResolve;
|
||||
folderPickerResolve = null;
|
||||
hideFolderPicker();
|
||||
if (resolve) resolve(dir);
|
||||
}
|
||||
|
||||
function setFolderPickerError(text) {
|
||||
folderPickerErrorEl.textContent = text || '';
|
||||
folderPickerErrorEl.hidden = !text;
|
||||
}
|
||||
|
||||
function folderPickerButtons() {
|
||||
return [...folderPickerListEl.querySelectorAll('.folder-picker-row')];
|
||||
}
|
||||
|
||||
// One picker for a bare start (`dialog: false`, full screen) and Change
|
||||
// project (`dialog: true`, over the page, with Cancel and Escape). Choose a
|
||||
// folder runs the OS dialog; a recent row opens that folder. Resolves with
|
||||
// the folder opened, or null when the person cancels the dialog. A canceled
|
||||
// OS dialog comes back here, and an error shows inline with the rows usable.
|
||||
async function showFolderPicker({ dialog }) {
|
||||
if (folderPickerResolve) closeFolderPicker(null);
|
||||
stopRetryCountdown();
|
||||
stateBox.hidden = true;
|
||||
if (!dialog) {
|
||||
hideLaunchCard();
|
||||
hideFirstRun();
|
||||
}
|
||||
setFolderPickerError('');
|
||||
folderPickerCancelBtn.hidden = !dialog;
|
||||
folderPickerEl.classList.toggle('is-dialog', dialog);
|
||||
if (dialog) folderPickerPanelEl.setAttribute('aria-modal', 'true');
|
||||
else folderPickerPanelEl.removeAttribute('aria-modal');
|
||||
// The project already open is left out by the command itself.
|
||||
let recent = [];
|
||||
try {
|
||||
recent = (await invoke('recent_folders')) || [];
|
||||
} catch (error) {
|
||||
setFolderPickerError(`Could not read the recent folders: ${error}`);
|
||||
}
|
||||
folderPickerListEl.replaceChildren(
|
||||
...folderPickerRows(recent).map((row) => {
|
||||
const li = document.createElement('li');
|
||||
const button = document.createElement('button');
|
||||
button.type = 'button';
|
||||
button.className = `folder-picker-row is-${row.kind}`;
|
||||
const label = document.createElement('span');
|
||||
label.className = 'folder-picker-label';
|
||||
label.textContent = row.label;
|
||||
button.append(label);
|
||||
if (row.detail) {
|
||||
const detail = document.createElement('span');
|
||||
detail.className = 'folder-picker-detail';
|
||||
detail.textContent = row.detail;
|
||||
button.append(detail);
|
||||
}
|
||||
button.onclick = () => chooseFolderRow(row, button, dialog);
|
||||
li.append(button);
|
||||
return li;
|
||||
})
|
||||
);
|
||||
folderPickerEl.hidden = false;
|
||||
folderPickerButtons()[0].focus();
|
||||
return new Promise((resolve) => {
|
||||
folderPickerResolve = resolve;
|
||||
});
|
||||
}
|
||||
|
||||
// One row pressed: the OS dialog for Choose a folder (`change_project` from
|
||||
// Change project, which tears the old project down), else that recent
|
||||
// folder. Nothing chosen keeps the picker up, focus back on the row.
|
||||
async function chooseFolderRow(row, button, dialog) {
|
||||
const buttons = folderPickerButtons();
|
||||
buttons.forEach((b) => { b.disabled = true; });
|
||||
folderPickerCancelBtn.disabled = true;
|
||||
setFolderPickerError('');
|
||||
let dir = null;
|
||||
try {
|
||||
if (row.kind === 'browse') dir = await invoke(dialog ? 'change_project' : 'pick_project_folder');
|
||||
else dir = await invoke('open_recent_folder', { dir: row.dir });
|
||||
} catch (error) {
|
||||
setFolderPickerError(row.kind === 'browse' ? `Could not open the folder picker: ${error}` : `Could not open ${row.dir}: ${error}`);
|
||||
}
|
||||
buttons.forEach((b) => { b.disabled = false; });
|
||||
folderPickerCancelBtn.disabled = false;
|
||||
if (dir) {
|
||||
closeFolderPicker(dir);
|
||||
return;
|
||||
}
|
||||
button.focus();
|
||||
}
|
||||
|
||||
folderPickerCancelBtn.onclick = () => closeFolderPicker(null);
|
||||
// Escape is heard on the document: a click on the backdrop or the heading
|
||||
// leaves focus on the page, where a listener on the picker never sees it.
|
||||
document.addEventListener('keydown', (event) => {
|
||||
if (event.key !== 'Escape' || folderPickerEl.hidden) return;
|
||||
if (folderPickerCancelBtn.hidden || folderPickerCancelBtn.disabled) return;
|
||||
event.preventDefault();
|
||||
closeFolderPicker(null);
|
||||
});
|
||||
folderPickerEl.addEventListener('keydown', (event) => {
|
||||
if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
|
||||
const buttons = folderPickerButtons();
|
||||
const at = buttons.indexOf(document.activeElement);
|
||||
if (at < 0) return;
|
||||
event.preventDefault();
|
||||
const next = event.key === 'ArrowDown' ? Math.min(at + 1, buttons.length - 1) : Math.max(at - 1, 0);
|
||||
buttons[next].focus();
|
||||
});
|
||||
|
||||
// A bare start: the picker, full screen, until a folder is opened.
|
||||
async function chooseStartFolder() {
|
||||
const dir = await showFolderPicker({ dialog: false });
|
||||
if (!dir) return;
|
||||
setProjectDir(dir);
|
||||
if (appState) appState.projectDir = dir;
|
||||
afterProjectKnown();
|
||||
}
|
||||
|
||||
// Once a project folder is known: the first-run checklist (once, until it
|
||||
@@ -1380,17 +1510,19 @@ function afterProjectKnown() {
|
||||
}
|
||||
}
|
||||
|
||||
// Switches to a folder picked fresh: the Rust side tears the old project's
|
||||
// agent and console down before the new one is remembered, so nothing from
|
||||
// it carries over. Picking nothing (canceled) leaves the current project as
|
||||
// it was.
|
||||
// Switches to a folder picked in the folder picker's dialog: the Rust side
|
||||
// tears the old project's agent and console down before the new one is
|
||||
// remembered, so nothing from it carries over. Cancel (or Escape) leaves
|
||||
// the current project as it was; the folder already open is not listed.
|
||||
async function doChangeProject() {
|
||||
showState('Choose the new project folder...');
|
||||
try {
|
||||
const dir = await invoke('change_project');
|
||||
const dir = await showFolderPicker({ dialog: true });
|
||||
if (!dir) {
|
||||
if (agentActive()) hideState();
|
||||
// Cancel leaves the page as it was: a running agent gets the keyboard
|
||||
// back, and a dashboard still on screen is never covered.
|
||||
if (agentActive() || frameReady) hideState();
|
||||
else afterProjectKnown();
|
||||
if (agentActive()) terminal.focus();
|
||||
return;
|
||||
}
|
||||
setProjectDir(dir);
|
||||
@@ -1521,7 +1653,7 @@ async function main() {
|
||||
setProjectDir(state.projectDir);
|
||||
afterProjectKnown();
|
||||
} else {
|
||||
pickFolder();
|
||||
chooseStartFolder();
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -216,6 +216,42 @@
|
||||
#launch-start:hover { background: #357a5c; }
|
||||
#launch-start:disabled { background: #444; color: #888; cursor: not-allowed; }
|
||||
|
||||
/* The folder picker: full screen on a bare start, a dialog over the page
|
||||
(with Cancel) from Change project. Choose a folder comes first; each
|
||||
recent folder shows its name with the full path muted under it. */
|
||||
#folder-picker {
|
||||
position: absolute; inset: 0; z-index: 2; display: flex; align-items: center; justify-content: center;
|
||||
background: #1e1e1e; padding: 24px; box-sizing: border-box;
|
||||
}
|
||||
#folder-picker[hidden] { display: none; }
|
||||
#folder-picker.is-dialog { background: rgba(0, 0, 0, 0.55); }
|
||||
#folder-picker-panel { display: flex; flex-direction: column; gap: 12px; width: min(440px, 100%); max-height: 100%; }
|
||||
#folder-picker.is-dialog #folder-picker-panel {
|
||||
background: var(--panel); border: 1px solid var(--rule-2); border-radius: 10px; padding: 18px; box-sizing: border-box;
|
||||
}
|
||||
#folder-picker h2 { margin: 0; font-size: 17px; text-align: center; }
|
||||
#folder-picker-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; overflow-y: auto; }
|
||||
.folder-picker-row {
|
||||
appearance: none; width: 100%; text-align: left; font: inherit; cursor: pointer;
|
||||
display: flex; flex-direction: column; gap: 2px; padding: 8px 12px; border-radius: 8px;
|
||||
border: 1px solid var(--rule-2); background: var(--panel); color: var(--ink);
|
||||
}
|
||||
.folder-picker-row:hover:not(:disabled) { background: var(--panel-2); border-color: var(--accent-line); }
|
||||
.folder-picker-row:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
|
||||
.folder-picker-row:disabled { opacity: 0.6; cursor: default; }
|
||||
.folder-picker-row.is-browse { font-weight: 600; background: var(--accent); border-color: var(--accent); color: var(--accent-ink); }
|
||||
.folder-picker-row.is-browse:hover:not(:disabled) { background: var(--accent); border-color: var(--accent); filter: brightness(1.08); }
|
||||
.folder-picker-label { font-size: 13.5px; }
|
||||
.folder-picker-detail { font-size: 12px; color: var(--ink-3); overflow-wrap: anywhere; }
|
||||
#folder-picker-error { margin: 0; font-size: 12px; color: #d7ba7d; }
|
||||
#folder-picker-error[hidden], #folder-picker-cancel[hidden] { display: none; }
|
||||
#folder-picker-cancel {
|
||||
align-self: center; appearance: none; font: inherit; font-size: 13.5px; font-weight: 600; padding: 7px 13px;
|
||||
border-radius: 8px; cursor: pointer; border: 1px solid var(--rule-2); background: var(--panel); color: var(--ink);
|
||||
}
|
||||
#folder-picker-cancel:hover { background: var(--panel-2); }
|
||||
#folder-picker-cancel:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
|
||||
|
||||
#first-run {
|
||||
position: absolute; inset: 0; z-index: 1; display: flex; flex-direction: column;
|
||||
align-items: stretch; justify-content: center; gap: 14px; background: #1e1e1e;
|
||||
@@ -359,6 +395,14 @@
|
||||
<button id="dashboard-state-cancel" hidden>Cancel</button>
|
||||
</span>
|
||||
</div>
|
||||
<div id="folder-picker" hidden>
|
||||
<div id="folder-picker-panel" role="dialog" aria-labelledby="folder-picker-title">
|
||||
<h2 id="folder-picker-title">Open a project</h2>
|
||||
<ul id="folder-picker-list"></ul>
|
||||
<p id="folder-picker-error" role="alert" hidden></p>
|
||||
<button id="folder-picker-cancel" type="button" hidden>Cancel</button>
|
||||
</div>
|
||||
</div>
|
||||
<div id="first-run" hidden>
|
||||
<h2>Before you start</h2>
|
||||
<ul id="first-run-list"></ul>
|
||||
|
||||
@@ -280,6 +280,18 @@ export function folderName(dir) {
|
||||
return lastSegment(dir) || String(dir || "").trim();
|
||||
}
|
||||
|
||||
/**
|
||||
* The folder picker's rows: Choose a folder first (the OS dialog), then one
|
||||
* row per recent folder from the `recent_folders` command, newest first,
|
||||
* named by the folder with its full path as the detail.
|
||||
*/
|
||||
export function folderPickerRows(recent) {
|
||||
return [
|
||||
{ kind: 'browse', label: 'Choose a folder...' },
|
||||
...(recent || []).map((r) => ({ kind: 'folder', dir: r.dir, label: r.name, detail: r.dir })),
|
||||
];
|
||||
}
|
||||
|
||||
function lastSegment(dir) {
|
||||
return String(dir || "")
|
||||
.trim()
|
||||
|
||||
Generated
+16
-21
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "plan2code-bot",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "plan2code-bot",
|
||||
"version": "1.0.0",
|
||||
"version": "1.1.0",
|
||||
"dependencies": {
|
||||
"@anthropic-ai/claude-agent-sdk": "^0.2.63",
|
||||
"chalk": "^5.6.2",
|
||||
@@ -1551,7 +1551,6 @@
|
||||
"dev": true,
|
||||
"hasInstallScript": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"esbuild": "bin/esbuild"
|
||||
},
|
||||
@@ -1831,9 +1830,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/nanoid": {
|
||||
"version": "3.3.11",
|
||||
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
|
||||
"integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
|
||||
"version": "3.3.20",
|
||||
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.20.tgz",
|
||||
"integrity": "sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==",
|
||||
"dev": true,
|
||||
"funding": [
|
||||
{
|
||||
@@ -1922,12 +1921,11 @@
|
||||
"license": "ISC"
|
||||
},
|
||||
"node_modules/picomatch": {
|
||||
"version": "4.0.3",
|
||||
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
|
||||
"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
|
||||
"version": "4.0.7",
|
||||
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",
|
||||
"integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
},
|
||||
@@ -1958,9 +1956,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/postcss": {
|
||||
"version": "8.5.6",
|
||||
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz",
|
||||
"integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==",
|
||||
"version": "8.5.33",
|
||||
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.33.tgz",
|
||||
"integrity": "sha512-RVHEU9/Pp1Fnjr/MpAJsZoADukCKhfIi15OunEYiGktIkYLkPVvC1sioWolGDS7XByMTx9m/IGbro0Js13zhnQ==",
|
||||
"dev": true,
|
||||
"funding": [
|
||||
{
|
||||
@@ -1977,11 +1975,10 @@
|
||||
}
|
||||
],
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"nanoid": "^3.3.11",
|
||||
"nanoid": "^3.3.20",
|
||||
"picocolors": "^1.1.1",
|
||||
"source-map-js": "^1.2.1"
|
||||
"source-map-js": "^1.2.2"
|
||||
},
|
||||
"engines": {
|
||||
"node": "^10 || ^12 || >=14"
|
||||
@@ -2145,9 +2142,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/source-map-js": {
|
||||
"version": "1.2.1",
|
||||
"resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
|
||||
"integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
|
||||
"version": "1.2.2",
|
||||
"resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
|
||||
"integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==",
|
||||
"dev": true,
|
||||
"license": "BSD-3-Clause",
|
||||
"engines": {
|
||||
@@ -2374,7 +2371,6 @@
|
||||
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
|
||||
"dev": true,
|
||||
"license": "Apache-2.0",
|
||||
"peer": true,
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
@@ -2412,7 +2408,6 @@
|
||||
"integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"peer": true,
|
||||
"dependencies": {
|
||||
"esbuild": "^0.27.0",
|
||||
"fdir": "^6.5.0",
|
||||
|
||||
@@ -132,7 +132,7 @@ plan2code-metrics
|
||||
|
||||
Pick **"Collect metrics"** and point it at your spec directory (`specs/<feature>/` or `specs--completed/<feature>/`). It reads your artifacts, extracts ~30 metrics, and writes a run JSON. Takes about 5 seconds.
|
||||
|
||||
The data stays local to that project in `.plan2code-metrics/runs/`. To aggregate across multiple projects, use **"Import"** to copy run files into one central location.
|
||||
The data stays local to that project in `.plan2code/metrics/runs/`. To aggregate across multiple projects, use **"Import"** to copy run files into one central location.
|
||||
|
||||
### Cross-Project Aggregation
|
||||
|
||||
@@ -142,7 +142,7 @@ If you use plan2code across several repos, you can consolidate all run data in o
|
||||
# From your central repo (e.g., the plan2code repo itself):
|
||||
plan2code-metrics
|
||||
# → "Import run data"
|
||||
# → Paste path to: /path/to/other-project/.plan2code-metrics/runs/run-xxx.json
|
||||
# → Paste path to: /path/to/other-project/.plan2code/metrics/runs/run-xxx.json
|
||||
```
|
||||
|
||||
Imported runs are copied locally and included in all future aggregations, analyses, and comparisons.
|
||||
@@ -205,7 +205,7 @@ Green checkmark = meeting target. Red X = below target (with the target shown).
|
||||
|
||||
### 1. Collect
|
||||
|
||||
Reads completed project artifacts from `specs/` or `specs--completed/` and extracts metrics for each workflow step. Output: `.plan2code-metrics/runs/run-<timestamp>.json`
|
||||
Reads completed project artifacts from `specs/` or `specs--completed/` and extracts metrics for each workflow step. Output: `.plan2code/metrics/runs/run-<timestamp>.json`
|
||||
|
||||
### 2. Aggregate
|
||||
|
||||
@@ -215,7 +215,7 @@ Merges all run files into `aggregated.json`, grouped by **prompt generation**
|
||||
|
||||
Sends aggregated metrics to an AI model with an analyst prompt. The AI produces a diagnosis identifying the weakest workflow steps and root causes. No edits are proposed at this stage.
|
||||
|
||||
Output: `.plan2code-metrics/proposals/<timestamp>-diagnosis.md`
|
||||
Output: `.plan2code/metrics/proposals/<timestamp>-diagnosis.md`
|
||||
|
||||
### 4. Improve
|
||||
|
||||
@@ -224,7 +224,7 @@ Sends the diagnosis plus current prompt file contents to an AI model. The AI pro
|
||||
- The `old_text` actually exists in the target file
|
||||
- The edited file stays under the 20,000 character limit
|
||||
|
||||
Output: `.plan2code-metrics/proposals/prop-<timestamp>.json`
|
||||
Output: `.plan2code/metrics/proposals/prop-<timestamp>.json`
|
||||
|
||||
### 5. Apply
|
||||
|
||||
@@ -232,10 +232,10 @@ Interactive diff review for each proposed edit. Accept, reject, or skip individu
|
||||
|
||||
## Data Directory
|
||||
|
||||
All metrics data lives in `.plan2code-metrics/` (add to `.gitignore` if desired):
|
||||
All metrics data lives in `.plan2code/metrics/` (add to `.gitignore` if desired):
|
||||
|
||||
```
|
||||
.plan2code-metrics/
|
||||
.plan2code/metrics/
|
||||
├── runs/ # Individual run JSONs
|
||||
│ ├── run-20260215-120000-a1b2.json
|
||||
│ └── run-20260220-090000-c3d4.json
|
||||
|
||||
@@ -50,7 +50,7 @@ function saveUserConfig(config: UserConfig): void {
|
||||
|
||||
// ── Defaults ──────────────────────────────────────────────────────────────────
|
||||
|
||||
const DEFAULT_METRICS_DIR = '.plan2code-metrics';
|
||||
const DEFAULT_METRICS_DIR = '.plan2code/metrics';
|
||||
const DEFAULT_RUNS_SUBDIR = 'runs';
|
||||
const DEFAULT_AGGREGATED_FILE = 'aggregated.json';
|
||||
const DEFAULT_PROPOSALS_SUBDIR = 'proposals';
|
||||
@@ -283,7 +283,7 @@ async function flowImport(): Promise<void> {
|
||||
console.log();
|
||||
|
||||
const sourcePath = await input({
|
||||
message: 'Path to run JSON file (e.g., /path/to/project/.plan2code-metrics/runs/run-xxx.json):',
|
||||
message: 'Path to run JSON file (e.g., /path/to/project/.plan2code/metrics/runs/run-xxx.json):',
|
||||
validate: (v) => {
|
||||
if (!fs.existsSync(v)) return 'File not found';
|
||||
if (!v.endsWith('.json')) return 'Must be a .json file';
|
||||
@@ -629,7 +629,7 @@ async function flowDelete(): Promise<void> {
|
||||
const { metricsDir, runsDir, aggregatedPath, proposalsDir } = getMetricsDirs();
|
||||
|
||||
if (!fs.existsSync(metricsDir)) {
|
||||
console.log(chalk.yellow('No metrics data found (.plan2code-metrics/ does not exist).'));
|
||||
console.log(chalk.yellow('No metrics data found (.plan2code/metrics/ does not exist).'));
|
||||
return;
|
||||
}
|
||||
|
||||
|
||||
@@ -6,14 +6,15 @@
|
||||
// [--out <dir>] [--compare]
|
||||
//
|
||||
// Every shot is staged with no agent: a throwaway sample project called
|
||||
// `task-api`, a throwaway console home (PLAN2CODE_CONSOLE_HOME), then
|
||||
// `task-api`, a throwaway console home (PLAN2CODE_CONSOLE_HOME) and Learning
|
||||
// store (PLAN2CODE_LEARNING_DIR), then
|
||||
// `console.mjs open` and `post` with the payloads in scripts/screenshots/.
|
||||
// Each screen is saved light and dark, at 1280x800 and twice the pixel
|
||||
// density, as `<out>/<shot>-light.webp` and `<out>/<shot>-dark.webp`.
|
||||
// The shots use the console's Ocean highlight rather than its default orange:
|
||||
// it is the console's nearest to the Plan2Code blue the site and README use.
|
||||
//
|
||||
// Shots: dashboard, dashboard-utilities, question, doc, build, signoff, finish, ask, git.
|
||||
// Shots: dashboard, dashboard-plan, dashboard-utilities, question, doc, build, signoff, finish, ask, git.
|
||||
// --compare adds workspace, stop, delete, help, prefs and cleanup: screens the
|
||||
// docs never show, for checking a change by eye against a "before" set. Its
|
||||
// --out must be outside docs/screenshots/, so the set is never published.
|
||||
@@ -64,6 +65,15 @@ const SHOTS = {
|
||||
scrollTo: ".dash-toggle",
|
||||
mustShow: ".dash-card:has(.pill.suggested)",
|
||||
},
|
||||
// The same dashboard in a project with no specs yet, where Plan is the
|
||||
// suggested card: the landing page's first step, before the questions.
|
||||
"dashboard-plan": {
|
||||
workflow: "dashboard",
|
||||
posts: ["dashboard-plan"],
|
||||
fresh: true,
|
||||
scrollTo: ".dash-toggle",
|
||||
mustShow: ".dash-card:has(.pill.suggested)",
|
||||
},
|
||||
// The utility cards sit even lower: scroll until the Git card is the
|
||||
// last row in frame ("cmd:" picks a card by its command).
|
||||
"dashboard-utilities": {
|
||||
@@ -285,6 +295,15 @@ function makeSampleProject() {
|
||||
return project;
|
||||
}
|
||||
|
||||
// The dashboard-plan shot's project: the same name and AGENTS.md, nothing
|
||||
// planned yet. It sits in its own folder so both can be called task-api.
|
||||
function makeFreshProject() {
|
||||
const project = path.join(SCRATCH, "fresh", "task-api");
|
||||
fs.mkdirSync(project, { recursive: true });
|
||||
fs.copyFileSync(path.join(SCRATCH, "task-api", "AGENTS.md"), path.join(project, "AGENTS.md"));
|
||||
return project;
|
||||
}
|
||||
|
||||
// The Workspace shot's second folder, beside the sample project.
|
||||
function makeExtraFolder() {
|
||||
const dir = path.join(SCRATCH, "task-web");
|
||||
@@ -517,10 +536,17 @@ async function captureAsk(browser, project, sid, url, question) {
|
||||
if (send) send.click();
|
||||
});
|
||||
|
||||
// `chat` hands over only the message's seq (its text goes in `reply`) and
|
||||
// moves its cursor past it, so the first seq seen is the one; the entry
|
||||
// itself, with its conversation, is read from the session's chat log.
|
||||
let entry = null;
|
||||
for (let i = 0; i < 40 && !entry; i++) {
|
||||
const r = cli(project, "chat", "--session", sid);
|
||||
if (r.code === 0 && r.out && r.out.chat) entry = r.out.chat.find((c) => c.kind === "message");
|
||||
const seq = r.code === 0 && r.out && Array.isArray(r.out.chat) ? r.out.chat[0] : undefined;
|
||||
if (Number.isInteger(seq)) {
|
||||
const log = path.join(HOME, "sessions", sid, "chat.ndjson");
|
||||
entry = fs.readFileSync(log, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l)).find((e) => e.seq === seq) || null;
|
||||
}
|
||||
if (!entry) await sleep(250);
|
||||
}
|
||||
if (!entry) throw new Error("the Ask question never reached the console");
|
||||
@@ -564,7 +590,15 @@ async function main() {
|
||||
|
||||
SCRATCH = fs.mkdtempSync(path.join(SCRATCH_ROOT, "p2c-shots-"));
|
||||
HOME = path.join(SCRATCH, "console-home");
|
||||
ENV = { ...process.env, PLAN2CODE_CONSOLE_HOME: HOME, PLAN2CODE_NOTEPADS_DIR: path.join(SCRATCH, "notepads"), PLAN2CODE_NO_BROWSER: "1" };
|
||||
// A throwaway Learning store too, and no sample project has a .plan2code/settings.json,
|
||||
// so the dashboard's Learning row reads Not set up with nothing waiting in every shot.
|
||||
ENV = {
|
||||
...process.env,
|
||||
PLAN2CODE_CONSOLE_HOME: HOME,
|
||||
PLAN2CODE_NOTEPADS_DIR: path.join(SCRATCH, "notepads"),
|
||||
PLAN2CODE_LEARNING_DIR: path.join(SCRATCH, "learning"),
|
||||
PLAN2CODE_NO_BROWSER: "1",
|
||||
};
|
||||
fs.mkdirSync(HOME, { recursive: true });
|
||||
fs.mkdirSync(OUT, { recursive: true });
|
||||
let browser = null;
|
||||
@@ -580,7 +614,7 @@ async function main() {
|
||||
args: ["--no-first-run", "--no-default-browser-check", "--mute-audio"],
|
||||
});
|
||||
for (const name of names) {
|
||||
const where = table[name].repo ? makeGitProject() : project;
|
||||
const where = table[name].repo ? makeGitProject() : table[name].fresh ? makeFreshProject() : project;
|
||||
const { sid, url } = stage(where, table[name]);
|
||||
try {
|
||||
if (table[name].ask) await captureAsk(browser, where, sid, url, table[name].ask);
|
||||
|
||||
@@ -76,7 +76,7 @@ export function check(srcDir) {
|
||||
if (!note) problems.push(`${file}: names no <D>/notes/<workflow>.md file`);
|
||||
else if (!fs.existsSync(path.join(notesDir, `${note[1]}.md`))) problems.push(`${file}: notes file ${note[1]}.md is not in src/web-console/notes/`);
|
||||
}
|
||||
if (seen !== 19) problems.push(`expected 19 skills with a console opening, found ${seen}`);
|
||||
if (seen !== 21) problems.push(`expected 21 skills with a console opening, found ${seen}`);
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -87,5 +87,5 @@ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.me
|
||||
for (const p of problems) console.error(` FAIL ${p}`);
|
||||
process.exit(1);
|
||||
}
|
||||
console.log("All 19 console openings share their sentences.");
|
||||
console.log("All 21 console openings share their sentences.");
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
{"database":{"advisory-count":1012,"last-commit":"4f2c9a1e7b3d5c8f0a6e2b9d1c4f7a3e5b8d0c2f","last-updated":"2026-11-12T18:04:11Z"},"lockfile":{"dependency-count":5},"settings":{"target_arch":[],"target_os":[],"severity":null,"ignore":[],"informational_warnings":["unmaintained","unsound","notice"]},"vulnerabilities":{"found":true,"count":1,"list":[{"advisory":{"id":"RUSTSEC-2099-0001","package":"itoa","title":"Fixture advisory: out-of-bounds write when formatting i128::MIN","description":"Hand-written fixture advisory (not a real RustSec entry). Versions of itoa before 1.0.11 could write past the end of the buffer when formatting i128::MIN.","date":"2099-01-01","aliases":["CVE-2099-0001"],"related":[],"collection":"crates","categories":["memory-corruption"],"keywords":["buffer-overflow"],"cvss":null,"informational":null,"references":[],"source":null,"url":"https://example.invalid/RUSTSEC-2099-0001","withdrawn":null,"license":"CC0-1.0","expect-deleted":false},"versions":{"patched":[">=1.0.11"],"unaffected":[]},"affected":null,"package":{"name":"itoa","version":"1.0.9","source":"registry+https://github.com/rust-lang/crates.io-index","checksum":"af150ab688ff2122fcef229be89cb50dd66af9e01a4ff320cc137eecc9bacc38","replace":null}}]},"warnings":{}}
|
||||
@@ -0,0 +1,8 @@
|
||||
Updating crates.io index
|
||||
Locking 2 packages to highest compatible versions
|
||||
Unchanged bitflags v1.3.2 (available: v2.13.2)
|
||||
Unchanged cfg-if v0.1.10 (available: v1.0.5)
|
||||
Updating hex v0.4.2 -> v0.4.3
|
||||
Updating itoa v1.0.9 -> v1.0.19
|
||||
note: to see how you depend on a package, run `cargo tree --invert <dep>@<ver>`
|
||||
warning: not updating lockfile due to dry run
|
||||
@@ -0,0 +1,37 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "1.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
|
||||
|
||||
[[package]]
|
||||
name = "cfg-if"
|
||||
version = "0.1.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4785bdd1c96b2a846b2bd7cc02e86b6b3dbf14e7e53446c4f54c92a361040822"
|
||||
|
||||
[[package]]
|
||||
name = "fixture"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"cfg-if",
|
||||
"hex",
|
||||
"itoa",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hex"
|
||||
version = "0.4.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "644f9158b2f133fd50f5fb3242878846d9eb792e445c893805ff0e3824006e35"
|
||||
|
||||
[[package]]
|
||||
name = "itoa"
|
||||
version = "1.0.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4a5f13b858c8d314ee3e8f639011f7ccefe71f97f96e50151fb991f267928e2c"
|
||||
@@ -0,0 +1 @@
|
||||
{"packages":[{"name":"a","version":"0.1.0","id":"path+file:///C:/fixture/cargo/workspace/crates/a#0.1.0","license":null,"license_file":null,"description":null,"source":null,"dependencies":[{"name":"itoa","source":"registry+https://github.com/rust-lang/crates.io-index","req":"^1.0","kind":null,"rename":null,"optional":false,"uses_default_features":true,"features":[],"target":null,"registry":null}],"targets":[{"kind":["lib"],"crate_types":["lib"],"name":"a","src_path":"C:\\fixture\\cargo\\workspace\\crates\\a\\src\\lib.rs","edition":"2021","doc":true,"doctest":true,"test":true}],"features":{},"manifest_path":"C:\\fixture\\cargo\\workspace\\crates\\a\\Cargo.toml","metadata":null,"publish":null,"authors":[],"categories":[],"keywords":[],"readme":null,"repository":null,"homepage":null,"documentation":null,"edition":"2021","links":null,"default_run":null,"rust_version":null},{"name":"b","version":"0.1.0","id":"path+file:///C:/fixture/cargo/workspace/crates/b#0.1.0","license":null,"license_file":null,"description":null,"source":null,"dependencies":[{"name":"bitflags","source":"registry+https://github.com/rust-lang/crates.io-index","req":"^1","kind":null,"rename":null,"optional":false,"uses_default_features":true,"features":[],"target":null,"registry":null}],"targets":[{"kind":["lib"],"crate_types":["lib"],"name":"b","src_path":"C:\\fixture\\cargo\\workspace\\crates\\b\\src\\lib.rs","edition":"2021","doc":true,"doctest":true,"test":true}],"features":{},"manifest_path":"C:\\fixture\\cargo\\workspace\\crates\\b\\Cargo.toml","metadata":null,"publish":null,"authors":[],"categories":[],"keywords":[],"readme":null,"repository":null,"homepage":null,"documentation":null,"edition":"2021","links":null,"default_run":null,"rust_version":null}],"workspace_members":["path+file:///C:/fixture/cargo/workspace/crates/a#0.1.0","path+file:///C:/fixture/cargo/workspace/crates/b#0.1.0"],"workspace_default_members":["path+file:///C:/fixture/cargo/workspace/crates/a#0.1.0","path+file:///C:/fixture/cargo/workspace/crates/b#0.1.0"],"resolve":null,"target_directory":"C:\\fixture\\cargo\\workspace\\target","build_directory":"C:\\fixture\\cargo\\workspace\\target","version":1,"workspace_root":"C:\\fixture\\cargo\\workspace","metadata":null}
|
||||
@@ -0,0 +1 @@
|
||||
{"packages":[{"name":"fixture","version":"0.1.0","id":"path+file:///C:/fixture/cargo/fixture#0.1.0","license":null,"license_file":null,"description":null,"source":null,"dependencies":[{"name":"bitflags","source":"registry+https://github.com/rust-lang/crates.io-index","req":"^1","kind":null,"rename":null,"optional":false,"uses_default_features":true,"features":[],"target":null,"registry":null},{"name":"cfg-if","source":"registry+https://github.com/rust-lang/crates.io-index","req":"^0.1","kind":null,"rename":null,"optional":false,"uses_default_features":true,"features":[],"target":null,"registry":null},{"name":"hex","source":"registry+https://github.com/rust-lang/crates.io-index","req":"^0.4","kind":null,"rename":null,"optional":false,"uses_default_features":true,"features":[],"target":null,"registry":null},{"name":"itoa","source":"registry+https://github.com/rust-lang/crates.io-index","req":"^1.0","kind":null,"rename":null,"optional":false,"uses_default_features":true,"features":[],"target":null,"registry":null}],"targets":[{"kind":["bin"],"crate_types":["bin"],"name":"fixture","src_path":"C:\\fixture\\cargo\\fixture\\src\\main.rs","edition":"2021","doc":true,"doctest":false,"test":true}],"features":{},"manifest_path":"C:\\fixture\\cargo\\fixture\\Cargo.toml","metadata":null,"publish":null,"authors":[],"categories":[],"keywords":[],"readme":null,"repository":null,"homepage":null,"documentation":null,"edition":"2021","links":null,"default_run":null,"rust_version":null}],"workspace_members":["path+file:///C:/fixture/cargo/fixture#0.1.0"],"workspace_default_members":["path+file:///C:/fixture/cargo/fixture#0.1.0"],"resolve":null,"target_directory":"C:\\fixture\\cargo\\fixture\\target","build_directory":"C:\\fixture\\cargo\\fixture\\target","version":1,"workspace_root":"C:\\fixture\\cargo\\fixture","metadata":null}
|
||||
@@ -0,0 +1 @@
|
||||
{"crate_name":"fixture","dependencies":[{"name":"bitflags","project":"1.3.2","compat":"---","latest":"2.13.2","kind":"Normal","platform":null},{"name":"cfg-if","project":"0.1.10","compat":"---","latest":"1.0.5","kind":"Normal","platform":null},{"name":"hex","project":"0.4.2","compat":"0.4.3","latest":"0.4.3","kind":"Normal","platform":null},{"name":"itoa","project":"1.0.9","compat":"1.0.19","latest":"1.0.19","kind":"Normal","platform":null}]}
|
||||
@@ -0,0 +1,37 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "1.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
|
||||
|
||||
[[package]]
|
||||
name = "cfg-if"
|
||||
version = "0.1.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "4785bdd1c96b2a846b2bd7cc02e86b6b3dbf14e7e53446c4f54c92a361040822"
|
||||
|
||||
[[package]]
|
||||
name = "fixture"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"cfg-if",
|
||||
"hex",
|
||||
"itoa",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "hex"
|
||||
version = "0.4.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "644f9158b2f133fd50f5fb3242878846d9eb792e445c893805ff0e3824006e35"
|
||||
|
||||
[[package]]
|
||||
name = "itoa"
|
||||
version = "1.0.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "af150ab688ff2122fcef229be89cb50dd66af9e01a4ff320cc137eecc9bacc38"
|
||||
@@ -0,0 +1,10 @@
|
||||
[package]
|
||||
name = "fixture"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
itoa = "1.0"
|
||||
bitflags = "1"
|
||||
cfg-if = "0.1"
|
||||
hex = "0.4"
|
||||
@@ -0,0 +1 @@
|
||||
fn main() {}
|
||||
@@ -0,0 +1 @@
|
||||
rustc 1.99.1 (58cf8f9c3 2026-10-13)
|
||||
@@ -0,0 +1,29 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "a"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"itoa",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "b"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "1.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
|
||||
|
||||
[[package]]
|
||||
name = "itoa"
|
||||
version = "1.0.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "af150ab688ff2122fcef229be89cb50dd66af9e01a4ff320cc137eecc9bacc38"
|
||||
@@ -0,0 +1,3 @@
|
||||
[workspace]
|
||||
members = ["crates/a", "crates/b"]
|
||||
resolver = "2"
|
||||
@@ -0,0 +1,7 @@
|
||||
[package]
|
||||
name = "a"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
itoa = "1.0"
|
||||
@@ -0,0 +1 @@
|
||||
pub fn a() {}
|
||||
@@ -0,0 +1,7 @@
|
||||
[package]
|
||||
name = "b"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
bitflags = "1"
|
||||
@@ -0,0 +1 @@
|
||||
pub fn b() {}
|
||||
@@ -0,0 +1,10 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
|
||||
</PropertyGroup>
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
|
||||
<PackageReference Include="Serilog" Version="3.1.1" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
@@ -0,0 +1,3 @@
|
||||
# .NET fixtures (from documentation)
|
||||
|
||||
No .NET SDK was installed on the recording machine, so these files follow the JSON shape `dotnet list package --format json` prints per the .NET docs and NuGet.Client's `ListPackageJsonRenderer.cs`, not a recorded run. Re-record them from a real SDK when one is available.
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"version": 1,
|
||||
"parameters": "--outdated",
|
||||
"sources": [
|
||||
"https://api.nuget.org/v3/index.json"
|
||||
],
|
||||
"projects": [
|
||||
{
|
||||
"path": "C:\\work\\fixture\\App.csproj",
|
||||
"frameworks": [
|
||||
{
|
||||
"framework": "net8.0",
|
||||
"topLevelPackages": [
|
||||
{
|
||||
"id": "Microsoft.NET.ILLink.Tasks",
|
||||
"requestedVersion": "[8.0.11, )",
|
||||
"resolvedVersion": "8.0.11",
|
||||
"autoReferenced": "true",
|
||||
"latestVersion": "10.0.0"
|
||||
},
|
||||
{
|
||||
"id": "Newtonsoft.Json",
|
||||
"requestedVersion": "13.0.1",
|
||||
"resolvedVersion": "13.0.1",
|
||||
"latestVersion": "13.0.4"
|
||||
},
|
||||
{
|
||||
"id": "Serilog",
|
||||
"requestedVersion": "3.1.1",
|
||||
"resolvedVersion": "3.1.1",
|
||||
"latestVersion": "4.3.0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"version": 1,
|
||||
"dependencies": {
|
||||
"net8.0": {
|
||||
"Newtonsoft.Json": {
|
||||
"type": "Direct",
|
||||
"requested": "[13.0.4, )",
|
||||
"resolved": "13.0.4",
|
||||
"contentHash": "pdgNNMai3zv51W5aq268sujXUyx7SNdE2bj1wZcWjAQrKMFZV260lbqYop1d2GM67JI1huLRwxo9ZqnfF/lC6A=="
|
||||
},
|
||||
"Serilog": {
|
||||
"type": "Direct",
|
||||
"requested": "[3.1.1, )",
|
||||
"resolved": "3.1.1",
|
||||
"contentHash": "P6G4/4Kt9bT635bhuwdXlJ2SCqqn2nhh4gqFqQueCOr9bK/e7W9ll/IoX1Ter948cV2Z/5+5v8pAfJYUISY03A=="
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net8.0</TargetFramework>
|
||||
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
|
||||
</PropertyGroup>
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
|
||||
<PackageReference Include="Serilog" Version="3.1.1" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"version": 1,
|
||||
"dependencies": {
|
||||
"net8.0": {
|
||||
"Newtonsoft.Json": {
|
||||
"type": "Direct",
|
||||
"requested": "[13.0.1, )",
|
||||
"resolved": "13.0.1",
|
||||
"contentHash": "ppPFpBcvxdsfUonNcvITKqLl3bqxWbDCZIzDWHzjpdAHRFfZe0Dw9HmA0+za13IdyrgJwpkDTDA9fHaxOrt20A=="
|
||||
},
|
||||
"Serilog": {
|
||||
"type": "Direct",
|
||||
"requested": "[3.1.1, )",
|
||||
"resolved": "3.1.1",
|
||||
"contentHash": "P6G4/4Kt9bT635bhuwdXlJ2SCqqn2nhh4gqFqQueCOr9bK/e7W9ll/IoX1Ter948cV2Z/5+5v8pAfJYUISY03A=="
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
{
|
||||
"version": 1,
|
||||
"parameters": "--vulnerable --include-transitive",
|
||||
"sources": [
|
||||
"https://api.nuget.org/v3/index.json"
|
||||
],
|
||||
"projects": [
|
||||
{
|
||||
"path": "C:\\work\\fixture\\App.csproj",
|
||||
"frameworks": [
|
||||
{
|
||||
"framework": "net8.0",
|
||||
"topLevelPackages": [
|
||||
{
|
||||
"id": "Newtonsoft.Json",
|
||||
"requestedVersion": "13.0.1",
|
||||
"resolvedVersion": "13.0.1",
|
||||
"vulnerabilities": [
|
||||
{
|
||||
"severity": "High",
|
||||
"advisoryurl": "https://github.com/advisories/GHSA-0000-fixture-0001"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"transitivePackages": [
|
||||
{
|
||||
"id": "System.Text.RegularExpressions",
|
||||
"resolvedVersion": "4.3.0",
|
||||
"vulnerabilities": [
|
||||
{
|
||||
"severity": "Moderate",
|
||||
"advisoryurl": "https://github.com/advisories/GHSA-0000-fixture-0002"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
go version go1.27.3 windows/amd64
|
||||
@@ -0,0 +1,10 @@
|
||||
module example.com/fixture
|
||||
|
||||
go 1.26.0
|
||||
|
||||
require golang.org/x/mod v0.43.0
|
||||
|
||||
require (
|
||||
golang.org/x/net v0.20.0
|
||||
golang.org/x/text v0.14.0 // indirect
|
||||
)
|
||||
@@ -0,0 +1,10 @@
|
||||
module example.com/fixture
|
||||
|
||||
go 1.22
|
||||
|
||||
require golang.org/x/mod v0.17.0
|
||||
|
||||
require (
|
||||
golang.org/x/net v0.21.0
|
||||
golang.org/x/text v0.14.0 // indirect
|
||||
)
|
||||
@@ -0,0 +1,6 @@
|
||||
golang.org/x/mod v0.43.0 h1:MFuq5J6s35W9D3IjkwyWc9vHh0nENOrt5K8Iof4ofmg=
|
||||
golang.org/x/mod v0.43.0/go.mod h1:4ec1JnuyBz5+FIVhg86UsA39YG8BpnrZdJYSNHmGzHY=
|
||||
golang.org/x/net v0.20.0 h1:aCL9BSgETF1k+blQaYUBx9hJ9LOGP3gAVemcZlf1Kpo=
|
||||
golang.org/x/net v0.20.0/go.mod h1:z8BVo6PvndSri0LbOE3hAn0apkU+1YvI6E70E9jsnvY=
|
||||
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
||||
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
|
||||
@@ -0,0 +1,6 @@
|
||||
golang.org/x/mod v0.17.0 h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=
|
||||
golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
|
||||
golang.org/x/net v0.21.0 h1:AQyQV4dYCvJ7vGmJyKki9+PBdyvhkSd8EIx/qb0AYv4=
|
||||
golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
|
||||
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
||||
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
|
||||
@@ -0,0 +1,7 @@
|
||||
{"config":{"protocol_version":"v1.0.0","scanner_name":"govulncheck","scanner_version":"v1.9.0","db":"https://vuln.go.dev","go_version":"go1.27.3","scan_level":"symbol"}}
|
||||
{"progress":{"message":"Scanning your code and 4 packages across 3 dependent modules for known vulnerabilities..."}}
|
||||
{"osv":{"schema_version":"1.3.1","id":"GO-2099-0001","summary":"Fixture advisory in golang.org/x/net","affected":[{"package":{"name":"golang.org/x/net","ecosystem":"Go"},"ranges":[{"type":"SEMVER","events":[{"introduced":"0"},{"fixed":"0.23.0"}]}]}]}}
|
||||
{"osv":{"schema_version":"1.3.1","id":"GO-2099-0002","summary":"Fixture advisory in golang.org/x/text with no fix","affected":[{"package":{"name":"golang.org/x/text","ecosystem":"Go"},"ranges":[{"type":"SEMVER","events":[{"introduced":"0"}]}]}]}}
|
||||
{"finding":{"osv":"GO-2099-0001","fixed_version":"v0.23.0","trace":[{"module":"golang.org/x/net","version":"v0.20.0","package":"golang.org/x/net/idna","function":"ToASCII"},{"module":"example.com/fixture","package":"example.com/fixture","function":"main"}]}}
|
||||
{"finding":{"osv":"GO-2099-0001","fixed_version":"v0.23.0","trace":[{"module":"golang.org/x/net","version":"v0.20.0","package":"golang.org/x/net/idna"}]}}
|
||||
{"finding":{"osv":"GO-2099-0002","trace":[{"module":"golang.org/x/text","version":"v0.14.0","package":"golang.org/x/text/unicode/norm"}]}}
|
||||
@@ -0,0 +1,97 @@
|
||||
{
|
||||
"Path": "example.com/fixture",
|
||||
"Main": true,
|
||||
"Dir": "C:\\work\\fixture",
|
||||
"GoMod": "C:\\work\\fixture\\go.mod",
|
||||
"GoVersion": "1.22"
|
||||
}
|
||||
{
|
||||
"Path": "golang.org/x/crypto",
|
||||
"Version": "v0.18.0",
|
||||
"Time": "2024-01-08T16:44:29Z",
|
||||
"Update": {
|
||||
"Path": "golang.org/x/crypto",
|
||||
"Version": "v0.59.0",
|
||||
"Time": "2026-11-11T07:23:42Z"
|
||||
},
|
||||
"Indirect": true
|
||||
}
|
||||
{
|
||||
"Path": "golang.org/x/mod",
|
||||
"Version": "v0.17.0",
|
||||
"Time": "2024-03-15T15:59:16Z",
|
||||
"Update": {
|
||||
"Path": "golang.org/x/mod",
|
||||
"Version": "v0.43.0",
|
||||
"Time": "2026-11-09T16:29:06Z"
|
||||
},
|
||||
"Dir": "C:\\Users\\dev\\go\\pkg\\mod\\golang.org\\x\\mod@v0.17.0",
|
||||
"GoMod": "C:\\Users\\dev\\go\\pkg\\mod\\cache\\download\\golang.org\\x\\mod\\@v\\v0.17.0.mod",
|
||||
"GoVersion": "1.18",
|
||||
"Sum": "h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=",
|
||||
"GoModSum": "h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c="
|
||||
}
|
||||
{
|
||||
"Path": "golang.org/x/net",
|
||||
"Version": "v0.20.0",
|
||||
"Time": "2024-01-08T18:08:52Z",
|
||||
"Update": {
|
||||
"Path": "golang.org/x/net",
|
||||
"Version": "v0.62.0",
|
||||
"Time": "2026-10-27T19:00:16Z"
|
||||
},
|
||||
"Dir": "C:\\Users\\dev\\go\\pkg\\mod\\golang.org\\x\\net@v0.20.0",
|
||||
"GoMod": "C:\\Users\\dev\\go\\pkg\\mod\\cache\\download\\golang.org\\x\\net\\@v\\v0.20.0.mod",
|
||||
"GoVersion": "1.18",
|
||||
"Sum": "h1:aCL9BSgETF1k+blQaYUBx9hJ9LOGP3gAVemcZlf1Kpo=",
|
||||
"GoModSum": "h1:z8BVo6PvndSri0LbOE3hAn0apkU+1YvI6E70E9jsnvY="
|
||||
}
|
||||
{
|
||||
"Path": "golang.org/x/sys",
|
||||
"Version": "v0.16.0",
|
||||
"Time": "2024-01-03T06:57:32Z",
|
||||
"Update": {
|
||||
"Path": "golang.org/x/sys",
|
||||
"Version": "v0.50.0",
|
||||
"Time": "2026-11-06T19:57:40Z"
|
||||
},
|
||||
"Indirect": true
|
||||
}
|
||||
{
|
||||
"Path": "golang.org/x/term",
|
||||
"Version": "v0.16.0",
|
||||
"Time": "2024-01-04T15:06:34Z",
|
||||
"Update": {
|
||||
"Path": "golang.org/x/term",
|
||||
"Version": "v0.48.0",
|
||||
"Time": "2026-11-09T16:29:12Z"
|
||||
},
|
||||
"Indirect": true
|
||||
}
|
||||
{
|
||||
"Path": "golang.org/x/text",
|
||||
"Version": "v0.14.0",
|
||||
"Time": "2023-10-11T21:58:48Z",
|
||||
"Update": {
|
||||
"Path": "golang.org/x/text",
|
||||
"Version": "v0.44.0",
|
||||
"Time": "2026-11-09T16:29:39Z"
|
||||
},
|
||||
"Indirect": true,
|
||||
"Dir": "C:\\Users\\dev\\go\\pkg\\mod\\golang.org\\x\\text@v0.14.0",
|
||||
"GoMod": "C:\\Users\\dev\\go\\pkg\\mod\\cache\\download\\golang.org\\x\\text\\@v\\v0.14.0.mod",
|
||||
"GoVersion": "1.18",
|
||||
"Sum": "h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=",
|
||||
"GoModSum": "h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU="
|
||||
}
|
||||
{
|
||||
"Path": "golang.org/x/tools",
|
||||
"Version": "v0.13.0",
|
||||
"Time": "2023-09-05T16:59:35Z",
|
||||
"Update": {
|
||||
"Path": "golang.org/x/tools",
|
||||
"Version": "v0.52.0",
|
||||
"Time": "2026-10-10T19:29:17Z"
|
||||
},
|
||||
"Indirect": true
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
module example.com/fixture
|
||||
|
||||
go 1.22
|
||||
|
||||
require golang.org/x/mod v0.17.0
|
||||
|
||||
require (
|
||||
golang.org/x/net v0.20.0
|
||||
golang.org/x/text v0.14.0 // indirect
|
||||
)
|
||||
@@ -0,0 +1,6 @@
|
||||
golang.org/x/mod v0.17.0 h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=
|
||||
golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
|
||||
golang.org/x/net v0.20.0 h1:aCL9BSgETF1k+blQaYUBx9hJ9LOGP3gAVemcZlf1Kpo=
|
||||
golang.org/x/net v0.20.0/go.mod h1:z8BVo6PvndSri0LbOE3hAn0apkU+1YvI6E70E9jsnvY=
|
||||
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
||||
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
|
||||
@@ -0,0 +1,13 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
|
||||
"golang.org/x/mod/semver"
|
||||
"golang.org/x/net/idna"
|
||||
)
|
||||
|
||||
func main() {
|
||||
s, _ := idna.ToASCII("example.com")
|
||||
fmt.Println(semver.IsValid("v1.0.0"), s)
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project are written here.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
- Nothing yet.
|
||||
|
||||
## [1.3.0] - 2018-04-13
|
||||
|
||||
### Changed
|
||||
|
||||
- Pads with any string, not only one character.
|
||||
|
||||
## [1.2.0] - 2017-11-30
|
||||
|
||||
### Added
|
||||
|
||||
- TypeScript types.
|
||||
|
||||
```md
|
||||
## 9.9.9
|
||||
A heading inside a code block is not a version.
|
||||
```
|
||||
|
||||
## [1.1.3] - 2016-11-10
|
||||
|
||||
- Fixes padding with a zero.
|
||||
|
||||
## 1.1.0
|
||||
|
||||
- First release with a changelog.
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"crate": {
|
||||
"id": "serde",
|
||||
"name": "serde",
|
||||
"max_version": "1.0.210",
|
||||
"repository": "https://github.com/serde-rs/serde",
|
||||
"homepage": "https://serde.rs",
|
||||
"documentation": "https://docs.rs/serde"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"info": {
|
||||
"name": "requests",
|
||||
"version": "2.32.3",
|
||||
"home_page": "https://requests.readthedocs.io",
|
||||
"project_urls": {
|
||||
"Documentation": "https://requests.readthedocs.io",
|
||||
"Homepage": "https://requests.readthedocs.io",
|
||||
"Source": "https://github.com/psf/requests"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,74 @@
|
||||
[
|
||||
{
|
||||
"tag_name": "v5.4.0",
|
||||
"name": "v5.4.0",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/v5.4.0",
|
||||
"body": "- Adds a level option."
|
||||
},
|
||||
{
|
||||
"tag_name": "v5.3.0",
|
||||
"name": "v5.3.0",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/v5.3.0",
|
||||
"body": "- Adds the overline style."
|
||||
},
|
||||
{
|
||||
"tag_name": "v5.2.0",
|
||||
"name": "v5.2.0",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/v5.2.0",
|
||||
"body": "- Adds supportsColorStderr."
|
||||
},
|
||||
{
|
||||
"tag_name": "v5.1.0",
|
||||
"name": "v5.1.0",
|
||||
"draft": true,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/v5.1.0",
|
||||
"body": "- Not published yet."
|
||||
},
|
||||
{
|
||||
"tag_name": "chalk-template@1.0.0",
|
||||
"name": "chalk-template 1.0.0",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/chalk-template@1.0.0",
|
||||
"body": "- Another package in the same repository."
|
||||
},
|
||||
{
|
||||
"tag_name": "v5.0.0",
|
||||
"name": "Chalk 5",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/v5.0.0",
|
||||
"body": "### Breaking\n\n- Chalk is now ESM only. Use chalk 4 from CommonJS."
|
||||
},
|
||||
{
|
||||
"tag_name": "v4.1.2",
|
||||
"name": "v4.1.2",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/v4.1.2",
|
||||
"body": "- Fixes a TypeScript definition."
|
||||
},
|
||||
{
|
||||
"tag_name": "v4.1.0",
|
||||
"name": "v4.1.0",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/v4.1.0",
|
||||
"body": "- Adds hex colors."
|
||||
},
|
||||
{
|
||||
"tag_name": "nightly",
|
||||
"name": "Nightly build",
|
||||
"draft": false,
|
||||
"prerelease": false,
|
||||
"html_url": "https://github.com/chalk/chalk/releases/tag/nightly",
|
||||
"body": "- Not a version."
|
||||
}
|
||||
]
|
||||
@@ -0,0 +1,17 @@
|
||||
[
|
||||
{ "id": "r1", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 2, "calls": [] },
|
||||
{ "id": "r2", "notes": "read", "source": "GitHub releases", "breaking": ["Removed the legacy() export."], "files": 1, "calls": [] },
|
||||
{ "id": "r3", "notes": "read", "source": "CHANGELOG.md", "breaking": [], "files": 1, "calls": [] },
|
||||
{ "id": "r4", "notes": "read", "source": "GitHub releases", "breaking": ["Drops Node 18 support."], "files": 2, "calls": [] },
|
||||
{ "id": "r5", "notes": "read", "source": "GitHub releases", "breaking": ["Drops CommonJS."], "files": 14, "calls": [{ "file": "src/log.js", "line": 3, "api": "require('chalk')" }] },
|
||||
{ "id": "r6", "notes": "could not read", "source": "none", "breaking": [], "files": 7, "calls": [] },
|
||||
{ "id": "r7", "notes": "could not read", "source": "none", "breaking": [], "files": 3, "calls": [] },
|
||||
{ "id": "r9", "notes": "could not read", "source": "none", "breaking": [], "files": 1, "calls": [] },
|
||||
{ "id": "r10", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 1, "calls": [] },
|
||||
{ "id": "r11", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 4, "calls": [] },
|
||||
{ "id": "r12", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 1, "calls": [] },
|
||||
{ "id": "r13", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 9, "calls": [] },
|
||||
{ "id": "r15", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 1, "calls": [] },
|
||||
{ "id": "r16", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 1, "calls": [] },
|
||||
{ "id": "r20", "notes": "read", "source": "GitHub releases", "breaking": [], "files": 1, "calls": [] }
|
||||
]
|
||||
@@ -0,0 +1,36 @@
|
||||
{
|
||||
"noChecks": false,
|
||||
"lockfiles": [
|
||||
{
|
||||
"lockfile": "package-lock.json",
|
||||
"ecosystem": "npm",
|
||||
"checks": { "rows": ["Root"], "discovered": [] },
|
||||
"rows": [
|
||||
{ "id": "r1", "package": "patch-clean", "current": "1.2.3", "target": "1.2.9", "jump": "patch", "inRange": true, "range": null, "pinned": false, "security": null },
|
||||
{ "id": "r2", "package": "minor-breaking", "current": "2.1.0", "target": "2.4.0", "jump": "minor", "inRange": true, "range": null, "pinned": false, "security": null },
|
||||
{ "id": "r3", "package": "zero-minor", "current": "0.8.2", "target": "0.9.0", "inRange": false, "range": { "from": "^0.8.2", "to": "^0.9.0" }, "pinned": false, "security": null },
|
||||
{ "id": "r4", "package": "major-clean", "current": "9.6.1", "target": "10.2.1", "jump": "major", "inRange": false, "range": { "from": "^9.6.1", "to": "^10.2.1" }, "pinned": false, "security": null },
|
||||
{ "id": "r5", "package": "major-called", "current": "5.6.2", "target": "6.0.1", "jump": "major", "inRange": false, "range": { "from": "^5.6.2", "to": "^6.0.1" }, "pinned": false, "security": null },
|
||||
{ "id": "r6", "package": "major-unread-wide", "current": "3.0.0", "target": "4.0.0", "jump": "major", "inRange": false, "range": { "from": "^3.0.0", "to": "^4.0.0" }, "pinned": false, "security": null },
|
||||
{ "id": "r7", "package": "major-unread-narrow", "current": "3.0.0", "target": "4.0.0", "jump": "major", "inRange": false, "range": { "from": "^3.0.0", "to": "^4.0.0" }, "pinned": false, "security": null },
|
||||
{ "id": "r8", "package": "no-record", "current": "1.0.0", "target": "1.1.0", "jump": "minor", "inRange": true, "range": null, "pinned": false, "security": null },
|
||||
{ "id": "r9", "package": "minor-unread", "current": "1.0.0", "target": "1.1.0", "jump": "minor", "inRange": true, "range": null, "pinned": false, "security": null },
|
||||
{ "id": "r10", "package": "hand-written", "current": "3.9.0", "target": "4.1.0", "jump": "major", "inRange": false, "range": { "from": ">=2 <4", "to": null }, "pinned": false, "security": null },
|
||||
{ "id": "r11", "package": "pinned-minor", "current": "1.64.1", "target": "1.66.0", "jump": "minor", "inRange": false, "range": { "from": "1.64.1", "to": "1.66.0" }, "pinned": true, "security": null },
|
||||
{ "id": "r12", "package": "pinned-major", "current": "6.0.0", "target": "7.0.0", "jump": "major", "inRange": false, "range": { "from": "6.0.0", "to": "7.0.0" }, "pinned": true, "security": null },
|
||||
{ "id": "r13", "package": "security-patch", "current": "4.17.20", "target": "4.17.21", "jump": "patch", "inRange": true, "range": null, "pinned": false, "security": { "severity": "high", "ids": ["GHSA-aaaa-bbbb-cccc"] } },
|
||||
{ "id": "r14", "package": "security-major", "current": "1.9.0", "target": "2.0.0", "jump": "major", "inRange": false, "range": { "from": "^1.9.0", "to": "^2.0.0" }, "pinned": false, "security": { "severity": null, "ids": ["GHSA-dddd-eeee-ffff"] } },
|
||||
{ "id": "r15", "package": "unreadable-output", "current": "1.0.0", "target": "1.0.1", "jump": "patch", "inRange": true, "range": null, "pinned": false, "security": null, "unreadable": "npm audit" },
|
||||
{ "id": "r16", "package": "minor-out-of-range", "current": "1.2.0", "target": "1.3.0", "jump": "minor", "inRange": false, "range": { "from": "~1.2.0", "to": "~1.3.0" }, "pinned": false, "security": null }
|
||||
]
|
||||
},
|
||||
{
|
||||
"lockfile": "tools/package-lock.json",
|
||||
"ecosystem": "npm",
|
||||
"checks": { "rows": [], "discovered": [] },
|
||||
"rows": [
|
||||
{ "id": "r20", "package": "uncovered-patch", "current": "2.0.0", "target": "2.0.1", "jump": "patch", "inRange": true, "range": null, "pinned": false, "security": null }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
running 2 tests
|
||||
test math::adds ... ok
|
||||
test math::divides ... FAILED
|
||||
@@ -0,0 +1,2 @@
|
||||
Passed MyApp.Tests.Adds [1 ms]
|
||||
Failed MyApp.Tests.Divides [3 ms]
|
||||
@@ -0,0 +1,5 @@
|
||||
=== RUN TestAdds
|
||||
--- PASS: TestAdds (0.00s)
|
||||
=== RUN TestDivides
|
||||
--- FAIL: TestDivides (0.00s)
|
||||
FAIL example.com/m 0.01s
|
||||
@@ -0,0 +1,5 @@
|
||||
PASS src/a.test.js
|
||||
FAIL src/b.test.js
|
||||
math
|
||||
✓ adds (2 ms)
|
||||
✕ divides by zero (5 ms)
|
||||
@@ -0,0 +1,10 @@
|
||||
✔ adds numbers (1.2ms)
|
||||
✖ parses dates (3.4ms)
|
||||
ℹ tests 2
|
||||
ℹ pass 1
|
||||
ℹ fail 1
|
||||
|
||||
✖ failing tests:
|
||||
|
||||
test at scripts/a.mjs:3:1
|
||||
✖ parses dates (3.4ms)
|
||||
@@ -0,0 +1,3 @@
|
||||
tests/test_a.py::test_adds PASSED
|
||||
FAILED tests/test_b.py::test_divides - ZeroDivisionError: division by zero
|
||||
==================== 1 failed, 1 passed in 0.12s ====================
|
||||
@@ -0,0 +1,9 @@
|
||||
TAP version 13
|
||||
ok 1 - adds numbers
|
||||
not ok 2 - parses dates
|
||||
---
|
||||
message: 'expected 2 to equal 3'
|
||||
...
|
||||
not ok 3 - writes the cache # TODO later
|
||||
ok 4 - reads the cache # SKIP no disk
|
||||
1..4
|
||||
@@ -0,0 +1,2 @@
|
||||
Error: something broke
|
||||
at main (build.js:1:1)
|
||||
@@ -0,0 +1,2 @@
|
||||
✓ src/a.test.ts (1 test) 2ms
|
||||
FAIL src/b.test.ts > math > divides by zero
|
||||
Loaded 100 of 400 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user