@turri-dev/cli 0.1.6 → 0.1.7-next.ccadaa0

package/dist/stdlib.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The ***plain standard library, as the agents that write specs are told it: every stack's import name,
+ * its conformance template and what it is, and where the files are - read from `stdlib/` each time, so
+ * what they are told is what is there. Sorted, so the rules block it goes into is the same every turn and
+ * stays cached.
+ */
+export interface StdlibTemplate {
+    /** What a spec imports it as: `stdlib/backend/python-fastapi`. */
+    name: string;
+    description: string;
+    text: string;
+}
+export declare function stdlibTemplates(dir?: string): StdlibTemplate[];
+/** A stack to import - not a kind's `common`, not a conformance template, and not a language's. */
+export declare function isStack(template: StdlibTemplate): boolean;
+/** A stack's conformance template: `stdlib/backend/python-fastapi` has `stdlib/backend/conformance/python-fastapi`. */
+export declare function conformanceOf(stack: string): string;
+/**
+ * The catalogue appended to the stdlib rule: every stack with its conformance template and what it is, the
+ * shared templates, and the folder they are all in - an absolute path, so an agent reads the one it imports
+ * instead of looking for it. The text of each is not in it: there are too many to carry in every prompt.
+ */
+export declare function stdlibCatalogue(templates?: StdlibTemplate[], dir?: string): string;
+/** How many stacks the standard library has, for the banner. */
+export declare function stdlibStackCount(templates?: StdlibTemplate[]): number;
+/** The standard library as the person reads it, with `/stdlib`: each kind's stacks, what each is, and how to import one. */
+export declare function describeStdlib(templates?: StdlibTemplate[], dir?: string): string;

package/dist/terminal-images.d.ts

@@ -0,0 +1,2 @@
+/** What PI_IMAGE_PROTOCOL turri sets for this terminal: none where it shows no images, kitty for an iTerm2 that speaks it, else nothing. */
+export declare function imageProtocolFor(env?: NodeJS.ProcessEnv): "none" | "kitty" | undefined;

package/dist/tools.d.ts

@@ -0,0 +1,101 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import type { Questioning } from "./questioning.ts";
+/**
+ * Personal tools.
+ *
+ * `write_artifact` is the executor's only way to produce output: it can read the
+ * repo, but everything it makes lands in one sandboxed directory under a name the
+ * graph chose. That is what lets the gate know exactly what to review - there is
+ * no "find the thing the agent probably changed" step.
+ */
+export declare function createWriteArtifactTool(runDir: string): ToolDefinition<Type.TObject<{
+    path: Type.TString;
+    content: Type.TString;
+}>, {
+    path: string;
+    bytes: number;
+}, any> & ToolDefinition<any, any, any>;
+export declare const VerdictSchema: Type.TObject<{
+    verdict: Type.TUnion<[Type.TLiteral<"pass">, Type.TLiteral<"fail">]>;
+    violations: Type.TArray<Type.TObject<{
+        criterion: Type.TString;
+        evidence: Type.TString;
+        fix: Type.TString;
+    }>>;
+}>;
+export type Verdict = Static<typeof VerdictSchema>;
+/**
+ * The judge's only tool. Forcing the verdict through a schema is the difference
+ * between a decision the graph can branch on and a paragraph someone has to read.
+ * `terminate` stops the judge session as soon as the verdict lands.
+ */
+export declare function createVerdictTool(onVerdict: (v: Verdict) => void): ToolDefinition<Type.TObject<{
+    verdict: Type.TUnion<[Type.TLiteral<"pass">, Type.TLiteral<"fail">]>;
+    violations: Type.TArray<Type.TObject<{
+        criterion: Type.TString;
+        evidence: Type.TString;
+        fix: Type.TString;
+    }>>;
+}>, {
+    verdict: "pass" | "fail";
+    violations: {
+        fix: string;
+        evidence: string;
+        criterion: string;
+    }[];
+}, any> & ToolDefinition<any, any, any>;
+import { runAsk, type AskUser, type AskUserRequest } from "./ask.ts";
+import { type LiveReviewer } from "./review/live.ts";
+export type { AskUser, AskUserRequest };
+/**
+ * Lets a skill step put a question to the person running it.
+ *
+ * A gated skill otherwise runs to completion with nobody to ask, which is fine for work
+ * that is fully specified and useless for an interview. The harness still owns the
+ * sequence - the step decides what to ask, not whether the gate afterwards runs.
+ */
+/**
+ * `gate`, for an interview that holds its questions to rules - the questioning level's cap (questioning.ts), an answer
+ * written as a spec change before the next question: a question it refuses is not asked, and `confirms_phase` marks a
+ * phase's closing confirmation, which the cap never counts.
+ *
+ * `talks`: where the asker answers a person who chose "Chat about this" - `"reply"`, the conversation's agent, in its
+ * reply; `"context"`, a skill's agent, whose replies nobody sees, as the `context` of the question asked again. Such a
+ * choice is no answer: neither the cap nor `onAnswered` counts it.
+ */
+export declare function createAskUserTool(ask: AskUser, onAnswered?: (answer: string, confirmsPhase: boolean) => void, said?: () => string, gate?: Pick<Questioning, "refusal" | "answered">, talks?: "reply" | "context"): ToolDefinition<Type.TObject<{
+    confirms_phase?: Type.TOptional<Type.TBoolean> | undefined;
+    question: Type.TString;
+    options: Type.TOptional<Type.TArray<Type.TString>>;
+    multi_select: Type.TOptional<Type.TBoolean>;
+    context: Type.TOptional<Type.TString>;
+    free_form: Type.TOptional<Type.TBoolean>;
+}>, {
+    question: string;
+    answer: string;
+}, any> & ToolDefinition<any, any, any>;
+export { runAsk };
+/** Ends the questions of a phase the questioning level caps: what is left, the agent decides itself. */
+export declare function createEndQuestionsTool(questioning: Pick<Questioning, "end">): ToolDefinition<Type.TObject<{}>, {}, any> & ToolDefinition<any, any, any>;
+/**
+ * Everything the reviewer has to say since the last tool call.
+ *
+ * It rides along on the tool results the interviewer is already getting, so a finding
+ * lands between two questions without the interviewer having to remember to go looking
+ * for one.
+ */
+export declare function reviewNote(liveReview: LiveReviewer | undefined): string;
+export type { LiveReviewer };
+/**
+ * With a live reviewer, a way to answer the reviewer's questions. How the builds stand, a skill reads with the
+ * conversation's own drift (loop-tools.ts), the reviewer's findings riding along on it (`withReviewNote`).
+ */
+export declare function createReviewTools(liveReview?: LiveReviewer): (ToolDefinition<Type.TObject<{
+    question_id: Type.TString;
+    answer: Type.TString;
+}>, {
+    accepted: boolean;
+}, any> & ToolDefinition<any, any, any>)[];
+/** A tool whose every result carries what the reviewer has said since the last one. */
+export declare function withReviewNote(tool: ToolDefinition<any, any, any>, liveReview: LiveReviewer | undefined): ToolDefinition<any, any, any>;

package/dist/validate-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/docs/README.md

@@ -31,6 +31,7 @@ turri implements regenerative software: the \*\*\*plain specs are the durable de
 | what the agents can and cannot reach | [the sandbox](sandbox.md) |
 | how skill review gates and judges work | [skills and gates](skills-and-gates.md) |
 | how the parser matches the reference implementation | [the \*\*\*plain parser](parser.md) |
+| how a desktop app or an editor runs turri's conversation itself | [running turri in a host](hosting.md) |
 | where the code for something lives | [development](development.md#layout) |
 
 ## All pages
@@ -48,4 +49,5 @@ turri implements regenerative software: the \*\*\*plain specs are the durable de
 | [Skills and gates](skills-and-gates.md) | the gate syntax, what the harness enforces, what a step can do, the rules, trying the gates |
 | [The \*\*\*plain parser](parser.md) | the TypeScript port, `turri validate`, inheritance, the iterator, fidelity |
 | [Theming](theming.md) | the turri themes, contrast, backgrounds, the font |
+| [Running turri in a host](hosting.md) | `@turri-dev/cli/host`: the conversation in a host's own window - its jobs, its questions - and what a host shows beside it |
 | [Development](development.md) | tests, the source layout, known edges |

package/docs/hosting.md

@@ -0,0 +1,52 @@
+# Running turri in a host
+
+`turri` runs its conversation in a terminal. A host - a desktop app, an editor - can run the same conversation itself, in its own window, and show what turri's terminal would draw in its own way: the jobs, the questions, the spec. It imports turri from npm as `@turri-dev/cli/host`.
+
+## What the host entry gives
+
+`@turri-dev/cli/host` is turri's compiled code (`dist/host.js`, with its types) - the conversation and what a host shows beside it:
+
+| export | what it is |
+| --- | --- |
+| `createTurriExtension(host)` | turri's conversation as an extension of pi's: every tool, slash command, rule and skill the terminal has. The host is told of its jobs and asks its questions - see below. |
+| `pi` | pi itself, as turri's extension is built against it. Make the session with this one - `pi.createAgentSession`, `pi.DefaultResourceLoader` - not another copy. |
+| `readProjectConfig`, `projectModels`, `modelSpec`, `configForSpec`, `hasProjectConfig`, `stacksOf` | the project's settings, as [config.turri.yaml](config.md) has them. |
+| `initConfig(dir, { vendor, bedrock, force })`, `VENDORS`, `BEDROCK_REGIONS`, `BEDROCK_DEFAULT`, `bedrockModels` | a project's first config.turri.yaml, as `turri init-config` writes it: the host asks which vendor's models - `VENDORS` has each one's label and its two models, `BEDROCK_REGIONS` where Bedrock serves each maker's - and `initConfig` writes it, saying what it did. One already there keeps everything but its two models. |
+| `checkPlainFile`, `plainFileParser`, `resolveTemplateDirs`, `iterateFunctionalSpecs`, `FUNCTIONAL_REQUIREMENTS` | a spec checked and parsed, its functional specs one by one - as `turri validate` reads it. |
+| `highlightLines`, `roleOf` | a spec's lines coloured by turri's own \*\*\*plain grammar. |
+| `functionalityCompletion`, `createWorkLoop`, `createJobRegistry`, `promptOf`, `describeModules` | how far each functional spec is built, and - on a loop of the host's own with `dryRun` - the work a spec change would plan, as `turri glimpse` does. |
+| `onModelEvent`, `describeTurnIncident` | a provider failing and waited out, a turn turri ended itself. |
+| `sweepOrphanedGroups` | stop what a turri killed outright left running, before anything starts. |
+
+It is turri's own code, as the terminal runs it: a 0.x release may change any of it.
+
+## The conversation in a host
+
+```js
+import { createTurriExtension, pi } from "@turri-dev/cli/host";
+
+const loader = new pi.DefaultResourceLoader({
+  cwd,
+  agentDir: pi.getAgentDir(),
+  extensionFactories: [
+    createTurriExtension({
+      onJobs: (jobs) => {},        // the conversation's job registry: every pulse it starts
+      onWorkLoop: (loop) => {},    // its work loop, once work is first asked for
+      onJobChange: (job) => {},    // a job started, moved on, did something, or ended
+      onPlanChange: () => {},      // what is planned changed with no job
+      dialogs: { select, input },  // ask_user's questions, put in the host's own dialogs
+    }),
+  ],
+});
+await loader.reload();
+const { session } = await pi.createAgentSession({ cwd, resourceLoader: loader });
+await session.bindExtensions({ uiContext, mode: "tui" });
+```
+
+- **The jobs.** The pulses the conversation starts - its tools, `/regenerate`, a spec change - run in its own job registry and work loop, the project's one. The host is handed both as they are made, and told of each job as it changes, so it shows the very jobs the conversation runs. Its buttons are best the conversation's commands - `session.prompt("/regenerate app.plain")` - so there is never a second loop on the same project.
+- **The questions.** `dialogs` is `ask_user`'s two dialogs: `select(title, options, context, at)` and `input(title, context)`, each resolving with the answer, or undefined when the person dismissed it. Given, the conversation's questions and a skill's interview are put in them; without it, in the terminal's own dialog.
+- **The mode.** `mode: "tui"` runs the work in the background and keeps the conversation free, as the terminal does; `rpc`, `json` and `print` wait for each job. The extension's other UI calls - its notices, its working line, a confirm - come to the host's `uiContext`, as pi's [SDK](https://github.com/earendil-works/pi) describes it.
+
+## Running it
+
+The host entry is compiled JavaScript, so any Node from 22.19 runs it - Electron's own included; nothing strips types. It finds turri's own folders - `genome/`, `stdlib/`, `.pi/` - beside `dist/` in the package, wherever npm installed it.

package/docs/theming.md

@@ -14,7 +14,7 @@ Bad input fails quietly - an unknown `--use-theme` name and a malformed theme fi
 
 ## The palette
 
-Both themes, the command line's colours, the spec diff's, the banner's jellyfish and the docs' diagram are drawn from turri's design system and nothing else: dark, quiet surfaces, one pink thing to press, neon for anything you can follow. These are all the colours turri has - none is mixed, tinted or added.
+Both themes, the command line's colours, the spec diff's, the banner's jellyfish and the docs' diagram are drawn from turri's design system and nothing else: dark, quiet surfaces, one pink thing to press, neon for anything you can follow. These are all the colours turri has - none is mixed, tinted or added, but for the jellyfish's tentacles, every other pixel of which the design draws half seen.
 
 | name | value | in `turri-dark` |
 |---|---|---|
@@ -25,13 +25,15 @@ Both themes, the command line's colours, the spec diff's, the banner's jellyfish
 | lines | `#22344a` | rules, dividers, frames: `borderMuted`, `mdHr` |
 | path | `#3e5a6b` | the editor's border, what is dim: `dim`, line numbers |
 | grauzone | `#85a3b2` | body text, and what can be skimmed: `text`, `muted` |
-| white | `#f4f7f9` | headings, tool titles, what you typed, the jellyfish's shine |
+| white | `#f4f7f9` | headings, tool titles, what you typed |
 | siesta tan | `#e9d8c8` | strings in code, \*\*\*plain's text in quotes or backticks |
-| eggplant | `#732553` | a removed line's fill in a spec diff |
+| eggplant | `#732553` | a removed line's fill in a spec diff, the jellyfish's rim |
 | neon | `#5ce1e6` | links, focus, the selection, section labels, \*\*\*plain's concepts in a spec diff: `accent`, `mdLink`, regen's `◆` |
 | neon hover | `#8eebee` | inline code - siesta tan beside white text was too close to tell apart, and tiring to read - types in code, an added line's fill in a light theme's spec diff: `mdCode` |
 | pink | `#ff5c8d` | the wordmark, the jellyfish's bell, and what is done - its `✓`, the spec map's `◇` and `◆`: `success` |
-| pink hover | `#ff7fa6` | \*\*\*plain's section headers, a removed line's `-`, keywords in code |
+| pink hover | `#ff7fa6` | the glint on the jellyfish's bell, \*\*\*plain's section headers, a removed line's `-`, keywords in code |
+| orchid | `#a9479a` | the jellyfish's bell, between its pink and its indigo - nowhere else |
+| indigo | `#5b57d9` | the jellyfish's bell, at its rim - nowhere else |
 | orange | `#ff7a3d` | the jellyfish's gut, the `$` of bash mode, and everything that asks for you - what failed (`✗`), what works with limits, what needs you (the spec map's `!`): `error`, `warning` |
 
 The design system keeps pink for the one thing to press and orange for the `$` prompt alone. A terminal has no buttons, but it needs status colours, so pink carries what is done and orange everything that asks for you - what failed, what works with limits, what waits on you - the mark (`✗`, `!`, `■`) telling them apart. The palette has no red.

package/docs/using.md

@@ -7,7 +7,7 @@ cd ~/my-project
 turri
 ```
 
-That is pi, with turri's tools, skills and themes loaded - `turri` alone, or with pi's options (`turri -c`, `turri --harness-model <m>`). It opens with turri's own banner - the jellyfish it is named after, swimming until the conversation fills the screen: a pixel jellyfish - a pink bell, an orange gut, neon tentacles coming apart into code at their tips - swimming a stroke a loop, its bell shutting and rising, its tentacles following: a picture in a terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn smaller in half blocks in any other, tmux included (`src/jellyfish.ts` draws it, `scripts/jellyfish-frames.mjs` writes the pictures) - turri's version (and, run from a clone, the commit it is on, and whether the clone has changes) and where its settings are changed - and only when something is wrong, skills that failed to load or agents' commands less fenced than they should be - rather than pi's startup header and resource list; `turri --verbose` shows those too. pi's "Update Available" notice is left out - turri's pi is a pinned dependency `pi update` never touches - and the terminal's tab reads `🪼 turri - <folder>`, not pi's `π`. Talk to it: ask it to start a project, add a feature, render a module, fix a spec. It decides which skill or tool applies - but not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the gates and the judges (see [skills and gates](skills-and-gates.md)).
+That is pi, with turri's tools, skills and themes loaded - `turri` alone, or with pi's options (`turri -c`, `turri --harness-model <m>`). It opens with turri's own banner - the jellyfish it is named after, regenerating until the conversation fills the screen: a pixel polyp on the sea floor grows into the jellyfish - a bell from pink down to indigo, an orange gut, neon tentacles - which swims a while, sinks back to the floor, and the polyp grows again, round and round: a picture in a terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn at a third of the size in half blocks in any other, tmux included (`src/jellyfish.ts` draws it, ported from the design system's pixel kit, `scripts/jellyfish-frames.mjs` writes the pictures) - turri's version (and, run from a clone, the commit it is on, and whether the clone has changes) and where its settings are changed - and only when something is wrong, skills that failed to load or agents' commands less fenced than they should be - rather than pi's startup header and resource list; `turri --verbose` shows those too. pi's "Update Available" notice is left out - turri's pi is a pinned dependency `pi update` never touches - and the terminal's tab reads `🪼 turri - <folder>`, not pi's `π`. Talk to it: ask it to start a project, add a feature, render a module, fix a spec. It decides which skill or tool applies - but not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the gates and the judges (see [skills and gates](skills-and-gates.md)).
 
 The skills that build from scratch:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.6",
+  "version": "0.1.7-next.ccadaa0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -16,6 +16,13 @@
   "bin": {
     "turri": "bin/turri.mjs"
   },
+  "exports": {
+    "./host": {
+      "types": "./dist/host.d.ts",
+      "import": "./dist/host.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "cultivate": "tsx src/cultivate-cli.ts",
     "typecheck": "tsc --noEmit",