@turri-dev/cli 0.1.4-next.4f471db → 0.1.4-next.5255d82

package/README.md

@@ -101,17 +101,17 @@ With **turri** you work on the durable intent. You say what the software must do
 
 ## How it works
 
+<p align="center"><img src="docs/images/turri-screenshot.png" width="900" alt="turri in the terminal: on the left the conversation, where /regenerate plans a project's modules and a coding agent works through one of them; on the right the spec map of that module's ***plain, each functionality marked as regenerated or being worked on"></p>
+
 **turri** captures the durable intent in [\*\*\*plain](https://plainlang.org/), a language for saying what software should do. \*\*\*plain breaks the intent down into functionalities - small units, each a single thing the software does - and **turri** regenerates the code from them piece by piece.
 
-1. **Define.** Write \*\*\*plain with **turri**
+1. **Define.** You say what the software should do; **turri** writes it down as \*\*\*plain.
 2. **Review and refine.** You review \*\*\*plain and change it with **turri** until it says what you mean.
 3. **Regenerate.** Agents write the code; **turri** decides what they write and when, step by step, the same way every time.
 4. **Validate.** Agents write conformance tests from \*\*\*plain; **turri** runs them, and keeps the code only when it does what \*\*\*plain says.
 
 These are not phases, one after the other: you don't spend hours writing \*\*\*plain and then hours waiting for the code. You go round the loop in small steps, in conversation with **turri** - while you refine the next functionality, the one before it is already being regenerated and validated. A bug is fixed in \*\*\*plain; a new behaviour goes into \*\*\*plain; and the next regeneration carries it. Ask to try it at any time: **turri** puts what is built in `dist` and starts it on your machine - an app, and it tells you where to open your browser.
 
-<p align="center"><img src="docs/images/turri-screenshot.png" width="900" alt="turri in the terminal: on the left the conversation, where /regenerate plans a project's modules and a coding agent works through one of them; on the right the spec map of that module's ***plain, each functionality marked as regenerated or being worked on"></p>
-
 ## The name
 
 **turri** is short for [*Turritopsis dohrnii*](https://en.wikipedia.org/wiki/Turritopsis_dohrnii), the immortal jellyfish, which, when injured or old, turns back into its young self and regenerates - the same jellyfish, from the same genes, again and again.

package/dist/extension.js

@@ -34,6 +34,7 @@ import { halfBlocks, JELLYFISH_FRAME_MS, JELLYFISH_TEXT_FRAMES } from "./jellyfi
 import { createJobPanel, didNotPass, keyPressed, PANEL_KEY, spinner } from "./regenerate/job-panel.js";
 import { clickToFocus, dockedWidth, narrowChat, shade, shadeChat } from "./regenerate/panel-dock.js";
 import { overPictureRow, PICTURE_AT } from "./picture-row.js";
+import { padScreen, paddedColumns, paddedRows, SCREEN_PADDING } from "./screen-padding.js";
 import { skillAboutLine, skillProgressLine } from "./skill-progress.js";
 import { createSidePanel } from "./regenerate/side-panel.js";
 import { createSpecMapSource, defaultMapFiles } from "./regenerate/spec-map.js";
@@ -97,7 +98,7 @@ aside) {
                     ...(context !== undefined ? { context } : {}),
                     ...(options !== undefined ? { options } : {}),
                     ...(selected !== undefined ? { selected } : {}),
-                    rows: () => tui.terminal.rows,
+                    rows: () => paddedRows(tui.terminal.rows),
                     style: { accent: (text) => theme.fg("accent", text), muted: (text) => theme.fg("muted", text), bold: (text) => theme.bold(text) },
                     done: (answer) => {
                         if (questionShown === shown)
@@ -1527,7 +1528,7 @@ function registerJobTools(pi, jobs, cwd) {
     // The terminal the panel is drawn on, for its width: set as it opens.
     let panelTerminal;
     /** The columns the panel takes beside the chat - 0 over the whole screen, or when the terminal is too narrow to share. */
-    const panelBeside = () => (panelDocked && panelTerminal !== undefined ? dockedWidth(panelTerminal.columns) : 0);
+    const panelBeside = () => (panelDocked && panelTerminal !== undefined ? dockedWidth(paddedColumns(panelTerminal.columns)) : 0);
     // What is open in the pulse list and the map, and where their cursors are: the conversation's, as left each time it opens.
     const jobsTree = createJobsTreeState();
     const mapState = createSpecMapState();
@@ -1585,7 +1586,7 @@ function registerJobTools(pi, jobs, cwd) {
             const layOut = () => {
                 if (panelDocked && undock === undefined) {
                     const widen = narrowChat(tui, panelBeside);
-                    const unwatch = clickToFocus(tui, () => tui.terminal.columns - panelBeside(), (side) => {
+                    const unwatch = clickToFocus(tui, () => tui.terminal.columns - SCREEN_PADDING.right - panelBeside(), (side) => {
                         if (panelBeside() === 0)
                             return;
                         if (side === "chat")
@@ -1626,7 +1627,7 @@ function registerJobTools(pi, jobs, cwd) {
                 tree: jobsTree,
                 map: () => specMap.read(),
                 mapState,
-                rows: () => tui.terminal.rows,
+                rows: () => paddedRows(tui.terminal.rows),
                 key: PANEL_KEY,
                 dock: {
                     docked: () => panelBeside() > 0,
@@ -1757,14 +1758,15 @@ function registerJobTools(pi, jobs, cwd) {
             return component;
         }, {
             overlay: true,
-            // The whole screen, or the columns on the right beside the chat - read at each frame, so it follows the terminal.
+            // The whole screen, or the columns on the right beside the chat - read at each frame, so it follows the terminal -
+            // inside the screen's padding.
             overlayOptions: {
                 get width() {
                     return panelBeside() > 0 ? panelBeside() : "100%";
                 },
                 maxHeight: "100%",
                 anchor: "top-right",
-                margin: 0,
+                margin: { ...SCREEN_PADDING },
             },
             onHandle: (handle) => {
                 if (panel !== undefined)
@@ -2323,8 +2325,10 @@ function registerBranding(pi, skills) {
         return new Banner(lines, (rule) => theme.fg("borderMuted", rule), jellyfishArt(theme.appearance, (theme.getColorMode?.() ?? "truecolor") === "truecolor"));
     });
     pi.on("session_start", (_event, ctx) => {
-        if (ctx.hasUI)
+        if (ctx.hasUI) {
+            padTheScreen(ctx);
             animateJellyfish(ctx);
+        }
         try {
             const identity = turriIdentity();
             pi.appendEntry(BANNER_ENTRY, {
@@ -2376,6 +2380,24 @@ function animateJellyfish(ctx) {
     }, { placement: "belowEditor" });
 }
 const JELLYFISH_CLOCK_KEY = "turri-jellyfish";
+/**
+ * The whole screen inside its padding (`screen-padding.ts`). An extension is given pi's screen only through what it
+ * draws, so an empty widget below the editor hands it over - at each frame, as pi starts a new screen when it changes
+ * how it draws.
+ */
+function padTheScreen(ctx) {
+    ctx.ui.setWidget(SCREEN_PADDING_KEY, (tui) => {
+        padScreen(tui);
+        return {
+            render: () => {
+                padScreen(tui);
+                return [];
+            },
+            invalidate: () => { },
+        };
+    }, { placement: "belowEditor" });
+}
+const SCREEN_PADDING_KEY = "turri-padding";
 /** The columns the banner's picture takes from the left edge, while it shows one; 0 when it does not. */
 let pictureRight = 0;
 /**
@@ -2434,7 +2456,7 @@ class Banner {
             return line !== undefined ? `${before}${line}` : placed?.kind === "text" ? ` ${jellyfish}` : "";
         });
         // The side panel is drawn beside the picture (drawOverlaysBesidePicture), which goes on showing.
-        pictureRight = placed?.kind === "image" ? 1 + placed.columns : 0;
+        pictureRight = placed?.kind === "image" ? SCREEN_PADDING.left + 1 + placed.columns : 0;
         if (placed?.kind === "image") {
             const at = placed.onLastRow ? placed.rows - 1 : 0;
             rows[at] = `${rows[at]}${PICTURE_AT}${placed.sequence}`;

package/dist/picture-row.js

@@ -1,6 +1,7 @@
 import { compositeTuiLine } from "@earendil-works/pi-tui";
-/** What the banner puts between a row's text and the picture after it: back to the jellyfish's column. */
-export const PICTURE_AT = "\x1b[2G";
+import { SCREEN_PADDING } from "./screen-padding.js";
+/** What the banner puts between a row's text and the picture after it: back to the jellyfish's column, a column in from the screen's padding. */
+export const PICTURE_AT = `\x1b[${SCREEN_PADDING.left + 2}G`;
 /** The picture's escape sequence, as the banner writes it after PICTURE_AT: Kitty's, in chunks, or iTerm2's - climbing first on iTerm2. */
 const PICTURE = /^(?:\x1b\[\d+A)?(?:(?:\x1b_G[^\x1b]*\x1b\\)+|\x1b\]1337;File=[^\x07]*\x07)/;
 /**

package/dist/regenerate/panel-dock.js

@@ -1,15 +1,16 @@
 import { HStack } from "@earendil-works/pi-tui";
+import { unpadded } from "../screen-padding.js";
 /**
  * The side panel beside the chat rather than over it: the chat drawn on the left in what the panel leaves it, the panel
  * laid over the columns on the right.
  *
  * pi draws its screen one of two ways, and the chat is narrowed in each as it is drawn: full screen (pi's default), a
  * layout - its root put in a row beside a filler as wide as the panel; the regular screen, the lines its render gives -
- * asked for in fewer columns.
+ * asked for in fewer columns. Either way inside the screen's padding (`screen-padding.ts`), when it has one.
  */
 /** Narrower than this, the chat and the panel have no room side by side: the panel takes the whole screen. */
 const SHARED_FROM = 100;
-/** The columns the panel takes beside the chat: half the screen, the rule between them in the middle - 0 when the terminal is too narrow to share. */
+/** The columns the panel takes beside the chat: half of what they share, the rule between them in the middle - 0 when that is too narrow to share. */
 export function dockedWidth(columns) {
     return columns < SHARED_FROM ? 0 : Math.floor(columns / 2);
 }
@@ -20,14 +21,15 @@ export function dockedWidth(columns) {
 export function narrowChat(tui, panelWidth) {
     const screen = tui;
     if (typeof screen.setLayoutRoot === "function" && screen.layoutRoot !== undefined) {
-        const root = screen.layoutRoot;
+        // What the padding pads: the row goes inside it, and is padded as it is set.
+        const root = unpadded(screen.layoutRoot);
         // A line as wide as the panel: the row gives the filler what it measures, the chat the rest.
         const filler = { render: () => [" ".repeat(panelWidth())], invalidate() { } };
         screen.setLayoutRoot(new HStack([{ component: root, basis: 0, grow: 1 }, { component: filler }]));
         return () => screen.setLayoutRoot(root);
     }
-    // Read from the prototype: the screen's own render, not one laid over it.
-    const render = Object.getPrototypeOf(tui).render;
+    // The render the screen has now - padded, when it is.
+    const render = screen.render;
     screen.render = function (width) {
         return render.call(this, Math.max(1, width - panelWidth()));
     };

package/dist/screen-padding.js

@@ -0,0 +1,72 @@
+import { HStack, Spacer, VStack } from "@earendil-works/pi-tui";
+/**
+ * Room around the whole of turri's screen: a row above and below, two columns either side - a cell is about twice as
+ * tall as it is wide.
+ *
+ * pi draws its screen one of two ways, and each is padded as it is drawn: full screen (pi's default), a layout - its
+ * root put in the middle of blank rows and columns; the regular screen, the lines its render gives - asked for in fewer
+ * columns, indented, with blank lines above and below. Overlays are laid over the whole terminal, so one that should
+ * keep to the padding is given it as its margin.
+ */
+export const SCREEN_PADDING = { top: 1, right: 2, bottom: 1, left: 2 };
+/** The columns inside the padding. */
+export function paddedColumns(columns) {
+    return Math.max(1, columns - SCREEN_PADDING.left - SCREEN_PADDING.right);
+}
+/** The rows inside the padding. */
+export function paddedRows(rows) {
+    return Math.max(1, rows - SCREEN_PADDING.top - SCREEN_PADDING.bottom);
+}
+/** Each padded layout root, to what it pads. */
+const content = new WeakMap();
+/** What a layout root pads - the root itself when it is not padded. */
+export function unpadded(root) {
+    return content.get(root) ?? root;
+}
+/** A blank column as wide as the padding on its side: the row gives it what it measures. */
+const blankColumns = (columns) => ({ render: () => [" ".repeat(columns)], invalidate() { } });
+function padded(root) {
+    const row = new HStack([
+        { component: blankColumns(SCREEN_PADDING.left), basis: SCREEN_PADDING.left },
+        { component: root, basis: 0, grow: 1 },
+        { component: blankColumns(SCREEN_PADDING.right), basis: SCREEN_PADDING.right },
+    ]);
+    const whole = new VStack([
+        { component: new Spacer(SCREEN_PADDING.top), basis: SCREEN_PADDING.top },
+        // As pi lays out its own transcript: the rows the padding leaves, whatever it measures.
+        { component: row, basis: 0, grow: 1, minSize: 1 },
+        { component: new Spacer(SCREEN_PADDING.bottom), basis: SCREEN_PADDING.bottom },
+    ]);
+    content.set(whole, root);
+    return whole;
+}
+/**
+ * pi's screen drawn inside the padding, from its next frame - and every layout root it is given after, so the chat
+ * narrowed beside the docked panel (`narrowChat`) is padded too. Once a screen: pi starts a new one when it changes how
+ * it draws, which is padded when it is passed in.
+ */
+export function padScreen(tui) {
+    const screen = tui;
+    if (screen.turriPadded === true)
+        return;
+    if (typeof screen.setLayoutRoot === "function") {
+        // Full screen before pi has given it its layout: padded at a later frame.
+        if (screen.layoutRoot === undefined)
+            return;
+        screen.turriPadded = true;
+        const set = screen.setLayoutRoot;
+        screen.setLayoutRoot = function (root) {
+            set.call(this, root === undefined ? undefined : padded(unpadded(root)));
+        };
+        screen.setLayoutRoot(screen.layoutRoot);
+        return;
+    }
+    screen.turriPadded = true;
+    // Read from the prototype: the screen's own render, not one laid over it.
+    const render = Object.getPrototypeOf(tui).render;
+    const left = " ".repeat(SCREEN_PADDING.left);
+    screen.render = function (width) {
+        const lines = render.call(this, paddedColumns(width)).map((line) => `${left}${line}`);
+        return [...new Array(SCREEN_PADDING.top).fill(""), ...lines, ...new Array(SCREEN_PADDING.bottom).fill("")];
+    };
+}

package/docs/development.md

@@ -54,6 +54,7 @@ The workflow signs in to npm with npm's trusted publishing (OIDC), not a token:
 | `src/regenerate/engine.ts` | choosing and resolving render models |
 | `src/regenerate/job-panel.ts`, `src/regenerate/transcript-view.ts`, `src/regenerate/diff-view.ts` | the job panel, the side panel's colours, and a spec diff as they show it - highlighted and banded |
 | `src/regenerate/side-panel.ts`, `src/regenerate/panel-dock.ts` | the side panel, and the chat narrowed beside it when it is docked |
+| `src/screen-padding.ts` | the blank row above and below the whole screen and the two columns either side, in both of pi's ways of drawing it |
 | `src/regenerate/spec-map.ts`, `src/regenerate/spec-map-view.ts` | regen: each item's mark, from the records, the `.plain` files and the work loop's plan (`mapPlan`), and the map drawn |
 | `src/regenerate/debug-log.ts` | each render agent's whole conversation, always streamed to `.turri/debug/` |
 | `genome/` | what turri knows and can do: `genome/skills/`, the skill library, and `genome/rules/`, the \*\*\*plain authoring rules |

package/docs/using.md

@@ -58,7 +58,7 @@ A render takes minutes, so in the TUI every render tool starts the work as a pul
 - **The panel** above the input, while something runs, shows on top what finished - a line a module, its pulses oldest first, each with its mark (green, red or amber, as in the side panel), number and kind - what it regenerated is in the side panel - `cognio  … 2 earlier · ✓ 3 regenerate · ✓ 4 conformance`, the newest that fit the width - then a rule, and under it each running pulse - `cognio · regenerate pulse 5`, `cognio · conformance pulse 6` - its time and cost, and what its agents are doing. A module whose work is being planned into pulses shows at once, before any pulse runs - `shorty · planning the pulses · 12s` - the planner is an agent, and takes a while; a `/regenerate` says it began the moment it is sent. Pulses are numbered within their module, as regen numbers them. `ctrl+o` expands the agents' trace alone; what finished stays a line a module. The line of keys under it - `ctrl+o to expand the trace · ctrl+h to peek at regen` - has each key breathing, fully there to a little faint and back, until it is first pressed: once `ctrl+o` has opened the trace, or the side panel has been opened, that key is still for the rest of the session and the other breathes on. What waits is not in it, and it shows no spec diff - the side panel has both. With nothing running it is gone.
 - **A pulse's change** is what its agent works from, not a text diff of the module's file: the items `<spec change>` gives the agent - only what the pulse's functional specs use, an import's items as well as the module's own, a code pulse's without the test reqs - each in the file it is written in, under its section, in the file's order (`change-view.ts`).
 - **A spec diff**, in the side panel, reads as an editor shows a diff: its \*\*\*plain highlighted as [plyn](https://github.com/plainlang/plyn) highlights it - section headers, concepts, names in backticks, text in quotes, links, the front matter - each added line filled green and each removed one red, the text on top, the fill the width of the panel ([colours](theming.md#spec-diffs)). It is shown file by file, each file's lines together under its name, with what it adds and takes out - the module being rendered first, the rest by name, and none the diff does not change. Each line has its number in that file: a spec diff is of the spec as read, with what it imports laid in, so a line is placed in the file it is written in - its links read as the parser renders them - and a removed line, in no file now, goes with the change it is part of and has no number. A line is never put in a file on a guess: one that cannot be placed is listed last, under "not found in the spec's files". Where lines of a file are not in the diff, `↕ 28 lines` says how many, as GitHub does - `↑` above the first - and names the section the lines under it are in when it is another than the one above, `↕ 28 lines · ***functional specs***`, as GitHub names a hunk's function: each section is named once.
-- **The side panel** (`ctrl+h`, as it was left - but on the pulse that last failed, stopped or did not pass, when one has since it was last opened: the live panel that showed it is gone with the last pulse, and its announcement in the chat says `ctrl+h shows this pulse`; **`/pulses`** on the pulses; not `ctrl+j`, which a terminal without the Kitty keyboard protocol sends as a line feed, the same as `shift+enter`, and which a dialog takes for `enter`; both stay pi's new-line keys. `ctrl+h` is the byte old terminals sent for backspace; a terminal set to send `^H` for its Backspace key would open the panel on it) takes the whole screen - the panel or the chat, one at a time - or, `s`, sits beside the chat: the chat on the left, the panel in the right half of the screen, and `s` again over the whole screen. It opens as it was last left, for the conversation; a terminal under 100 columns has no room for both and shows the panel over the whole screen. It opens on **regen**: the spec itself, in full, with how much of it the code has been regenerated from drawn onto it.
+- **The side panel** (`ctrl+h`, as it was left - but on the pulse that last failed, stopped or did not pass, when one has since it was last opened: the live panel that showed it is gone with the last pulse, and its announcement in the chat says `ctrl+h shows this pulse`; **`/pulses`** on the pulses; not `ctrl+j`, which a terminal without the Kitty keyboard protocol sends as a line feed, the same as `shift+enter`, and which a dialog takes for `enter`; both stay pi's new-line keys. `ctrl+h` is the byte old terminals sent for backspace; a terminal set to send `^H` for its Backspace key would open the panel on it) takes the whole screen - the panel or the chat, one at a time - or, `s`, sits beside the chat: the chat on the left, the panel in the right half of the screen, and `s` again over the whole screen. It opens as it was last left, for the conversation; a terminal under 104 columns - 100 inside the screen's padding, a blank row above and below everything and two columns either side - has no room for both and shows the panel over the whole screen. It opens on **regen**: the spec itself, in full, with how much of it the code has been regenerated from drawn onto it.
 
   Every item of the spec - a definition, a req, a functional spec with its sub-bullets and acceptance tests, what turri plans and diffs by - is a row in the file's order, its \*\*\*plain highlighted as plyn highlights it (as a spec diff is) and wrapped to the width, never cut short. The map has two columns, each headed on the line over it with a line of space under it: **status**, a mark a row - its rung on a ladder every item climbs - and the module's file, its spec. The top of the panel is where it is seen first: the top line, the module tabs, and the keys - each view's, `d talk it through in the chat` first when the module needs you - wrapped, never cut short, a line of space between the top line and the keys; then straight under them a rule, a line of space, and the columns' headings. The pulses view has its keys at the top too, and a line of space under its rule. The legend is a box of its own in the upper right corner, over what is under it, a line a mark, up the ladder. It names every rung, whatever the page shows - to take out only where something is - and a panel under 60 columns wide has none.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.4-next.4f471db",
+  "version": "0.1.4-next.5255d82",
   "license": "MIT",
   "type": "module",
   "repository": {