@turri-dev/cli 0.1.6-next.336dd6e → 0.1.7-next.9aec40e

package/.pi/themes/turri-dark.json

@@ -45,7 +45,7 @@
     "mdHeading": "white",
     "mdLink": "neon",
     "mdLinkUrl": "path",
-    "mdCode": "siestaTan",
+    "mdCode": "neonHover",
     "mdCodeBlock": "white",
     "mdCodeBlockBorder": "lines",
     "mdQuote": "grauzone",

package/README.md

@@ -190,7 +190,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | | |
 | --- | --- |
 | [Installation](docs/installation.md) | doctor, what turri needs of this machine, **turri** and `pi`, environment variables |
-| [Examples](examples/README.md) | projects to build with turri step by step: cognio from an empty folder, a CLI, a backend service with conformance tests, a REST API integration |
+| [Examples](examples/README.md) | projects to build with turri step by step: cognio from an empty folder, guestbook - a backend and a frontend in minutes - a CLI, a backend service with conformance tests, a REST API integration |
 | [Using **turri**](docs/using.md) | the conversation, skills, tools, pulses and regen, choosing models, the command line |
 | [The project config](docs/config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](docs/deploy.md) | trying what is built: the last commit in `dist/<module>`, started on your machine, nothing installed without asking |

package/dist/ask.d.ts

@@ -0,0 +1,83 @@
+/**
+ * How a skill step puts a question to the person running it.
+ *
+ * The interaction policy lives here rather than in the extension so it is the same from
+ * the TUI and the CLI, and so it can be tested without a terminal.
+ */
+export interface AskUserRequest {
+    question: string;
+    /** Concrete choices. Selecting beats typing whenever the answer space is known. */
+    options?: string[];
+    /** Let the user pick several: each option a box to tick and untick. Their picks come back comma-separated. */
+    multiSelect?: boolean;
+    /** Deliberately asking without options, for a genuinely open question. */
+    freeForm?: boolean;
+    /**
+     * What the person must read to answer - the brief to confirm, the plan to approve - shown above the question, as the
+     * asker gives it. A skill's agent talks in a session of its own that nobody sees, so without it "Is this the right
+     * brief?" arrives with no brief.
+     */
+    context?: string;
+    /**
+     * What the asker said last before asking - its account of the work, a probe, a regeneration - kept with the answer in the
+     * run's record and the transcript, never shown in the dialog.
+     */
+    said?: string;
+    /**
+     * Offer "Chat about this": an agent asked, and can answer what the person says about the question before they answer
+     * it. Not for a question the harness asks itself - nobody would answer.
+     */
+    chattable?: boolean;
+}
+export type AskUser = (request: AskUserRequest) => Promise<string>;
+/**
+ * The two dialogs an implementation has to provide. `context` is what to read to answer, given apart from the question so
+ * a dialog can show a long one without losing the question and its options under it - the TUI's scrolls it.
+ */
+export interface AskUserIO {
+    /** `at`: the option the cursor starts on - the one just ticked, in a question of several. */
+    select(title: string, options: string[], context?: string, at?: number): Promise<string | undefined>;
+    input(title: string, context?: string): Promise<string | undefined>;
+}
+export declare const OTHER_OPTION = "Something else\u2026";
+export declare const CHAT_OPTION = "Chat about this";
+export declare const DONE_OPTION = "Done \u2014 that's all of them";
+/** An option's box in a question of several, ticked and not. */
+export declare const TICKED = "\u2611";
+export declare const UNTICKED = "\u2610";
+export declare const DISMISSED = "The user dismissed the question without answering.";
+/** How an answer that is no answer starts: the person chose to talk about the question first. */
+export declare const CHAT_PREFIX = "The user has not answered this question yet: they chose to talk about it first.";
+/** What comes back when the person chose "Chat about this": what they said, and what they had picked so far. */
+export declare function chatAnswer(said: string, picked?: string[]): string;
+/** Whether an answer is the person choosing to talk about the question, rather than answering it. */
+export declare function isChat(answer: string): boolean;
+/**
+ * A question with no options and no `free_form` is refused rather than asked.
+ *
+ * Offering choices is the thing that makes an interview quick to answer, and an optional
+ * field is one a model quietly skips. Making the free-form case explicit means asking
+ * without options is a decision rather than an omission.
+ */
+export declare function missingOptions(request: AskUserRequest): string | null;
+/**
+ * The request as the person should see it: tool-call markup cut out of the question and the
+ * options - an option that was nothing but markup dropped - and a `multi_select` that leaked into
+ * the text taken as the argument it was meant to be. `leaked` when there was any.
+ */
+export declare function cleanRequest(request: AskUserRequest): {
+    request: AskUserRequest;
+    leaked: boolean;
+};
+export declare function runAsk(asked: AskUserRequest, io: AskUserIO): Promise<string>;
+/**
+ * While a question is open, what catches ctrl+h on the terminal's input: pi gives an extension's shortcut only the keys
+ * its editor sees, and a question has the focus. It opens the side panel - the question waits under it - unless the
+ * panel shows already: its own listener has ctrl+h then, to close it. A key's release and its repeats are left alone.
+ */
+export declare function peekKeyListener(panel: {
+    open(): void;
+    shown(): boolean;
+}): (data: string) => {
+    consume: true;
+} | undefined;

package/dist/brand.d.ts

@@ -0,0 +1,13 @@
+export declare const brand: {
+    /** turri's accent: what to look at - a heading, a choice's number, the command to run. */
+    accent: (text: string) => string;
+    /** Done, and what was written. */
+    success: (text: string) => string;
+    /** What is wrong: what stops turri. */
+    error: (text: string) => string;
+    /** What works, with limits. */
+    warning: (text: string) => string;
+    /** What goes with it, and can be skimmed. */
+    muted: (text: string) => string;
+    bold: (text: string) => string;
+};

package/dist/btw.d.ts

@@ -0,0 +1,67 @@
+/**
+ * /btw: a question on the side, answered while the conversation is busy - a skill's interview, its long steps - without
+ * waiting for it, and without changing it.
+ *
+ * A skill runs inside one tool call, so the chat model can answer nothing until the skill returns, and whatever the
+ * person types meanwhile waits for it as a message. pi runs an extension's command at once, even mid-turn: /btw starts
+ * an agent of its own - fresh, read only - that is shown the conversation, what the running skill has done and said so
+ * far, and what is regenerating, and answers. Its answer is shown and kept out of every model's context: the
+ * conversation and the skill go on as if nothing was asked. While a question of the skill's has the keys, the same is
+ * typed into its "Something else…" - answered, and the question asked again with the answer above it.
+ */
+import type { AskUser, AskUserRequest } from "./ask.ts";
+/** How many tool calls the side agent may make before it is told to answer. */
+export declare const SIDE_CALLS = 20;
+/** "/btw what is a frid?" -> "what is a frid?"; "/btw" alone -> ""; anything else is not a side question. */
+export declare function sideQuestionOf(text: string): string | undefined;
+/** The skill running now, as the side agent is told of it. */
+export interface SkillRunNow {
+    skill: string;
+    /** Its folder: turri's own, or the project's. */
+    dir: string;
+    /** The step it is in, and its attempt - "" before the first. */
+    step(): string;
+    /** Its trace so far: steps, gates, each question and answer. */
+    trace(): string[];
+    /** Its run folder: run.json there names the agent's saved session. */
+    runDir: string;
+}
+/** Says a skill is running, until the function it returns is called. */
+export declare function skillRunStarted(run: SkillRunNow): () => void;
+export declare function runningSkill(): SkillRunNow | undefined;
+/**
+ * A session's messages as plain text - who said what, tool calls named - its last `maxChars`. Thinking and tool
+ * results are left out: what was said, and what was done, is what a side question is about.
+ */
+export declare function transcriptOf(entries: unknown[], maxChars: number): string;
+/** The running skill's agent's session, as text: its last turns, read from the session file run.json names. */
+export declare function skillSessionText(runDir: string, maxChars?: number): string;
+export interface SideQuestion {
+    question: string;
+    /** The conversation so far, as text. */
+    conversation: string;
+    /** The skill running now, if one is. */
+    skill?: {
+        name: string;
+        dir: string;
+        step: string;
+        trace: string[];
+        session: string;
+    };
+    /** What is regenerating and has been regenerated this session, a line a pulse. */
+    pulses: string[];
+    projectDir: string;
+    /** turri's own folder: its source, skills, rules and docs. */
+    harnessDir: string;
+}
+export declare function sideQuestionPrompt(side: SideQuestion): string;
+/** Answers a side question with an agent of its own, read only, on `model`. */
+export declare function answerSideQuestion(side: SideQuestion, model?: string): Promise<string>;
+/** The answer to a side question, as it is shown above the question it was asked under. */
+export declare function asideBlock(question: string, answer: string): string;
+export declare const BTW_HOW = "Type your question after /btw - /btw what does this step do?";
+/**
+ * A question put to the person, where "/btw ..." typed as the answer is a side question: answered, and the same
+ * question asked again with the answer above it - the asker never sees it. Only the latest is kept above the question.
+ */
+export declare function askWithAsides(request: AskUserRequest, askUser: AskUser, aside: (question: string) => Promise<string>): Promise<string>;

package/dist/chat-models.d.ts

@@ -0,0 +1,22 @@
+import { type ProjectConfig } from "./config.ts";
+/**
+ * The two models of `turri`, from its arguments and the project's config.turri.yaml.
+ *
+ * The harness model is the one the person talks to: pi's own `--model`, which `--harness-model`
+ * is another name for, or else `harness-model:` in config.turri.yaml. The coding model is the one
+ * every render runs on: `--coding-model`, or else `coding-model:` in config.turri.yaml - pi knows
+ * nothing of it, so it reaches the extension through the environment. Either can still be
+ * changed in the conversation: pi's /model, engine.
+ */
+/** The environment variable a chat's --coding-model reaches the extension through. */
+export declare const CODING_MODEL_ENV = "TURRI_CODING_MODEL";
+/** Take a `--name value` or `--name=value` out of the arguments: its value, and the rest. The last one wins. */
+export declare function takeOption(args: string[], name: string): {
+    value?: string;
+    rest: string[];
+};
+/** pi's arguments, with the harness model in them, and the coding model for the extension. */
+export declare function chatModels(args: string[], config: Pick<ProjectConfig, "harnessModel" | "codingModel" | "judgeModel">): {
+    piArgs: string[];
+    codingModel?: string;
+};

package/dist/chat-skills.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The pi skills the conversation is not offered, because turri has them already.
+ *
+ * pi lists for the conversation every skill it finds: `~/.pi/agent/skills`, `~/.agents/skills`, and the `.agents/skills`
+ * of every folder from the one turri started in up to its git root - so a folder above a project can hand the chat
+ * another tool's ***plain skills, a `load-plain-reference` it then loads at the start of a session. turri needs none of
+ * them: the whole ***plain reference - the authoring rules - is in the conversation's system prompt already, and turri
+ * runs its own skills, and the project's, with `cultivate`, steps and gates and all. A skill the chat followed by hand
+ * instead would skip those gates, and one from another tool may say otherwise than turri's rules. So the conversation
+ * is offered neither: no skill turri runs itself, and none about ***plain. A skill about anything else - a commit
+ * message, a deploy - is offered as pi offers it.
+ */
+/** Whether turri has what a pi skill offers: it runs a skill of that name itself, or the skill is about ***plain. */
+export declare function supersededByTurri(skill: {
+    name: string;
+    description: string;
+}, turriRuns: ReadonlySet<string>): boolean;

package/dist/cli-options.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The command line of turri's commands: their words, and the options that stand for the config's own keys - kept apart
+ * from the commands that use them, so a light one (doctor) reads them as a regenerate does without loading it.
+ */
+/**
+ * A command's arguments: the positional ones, `--flag`s and `--name value` options (`--name=value` too) -
+ * `--coding-model` is `--model`. An option it does not take is refused, rather than taking the word after it, and so is an
+ * option with no value - the end of the words, or another option where its value should be.
+ */
+export declare function parseArgs(argv: string[], flags: string[], usage: string, valued?: string[]): {
+    positional: string[];
+    options: Record<string, string | undefined>;
+};
+/** An option's value, as parseArgs left it: refused when it was given with none. */
+export declare function optionValue(options: Record<string, string | undefined>, name: string): string | undefined;
+/**
+ * The options that stand for the config's own keys - `--harness-model`, `--coding-model` (`--model`), `--judge-model`
+ * and, as asked, `--review`, `--mutation-testing` and `--conformance-tests` - read as if config.turri.yaml had them, in their place in the
+ * order the config resolves them in (overrideConfig): a run, or doctor, with them is the same as one with them in the
+ * file. Exits on a value it cannot read.
+ */
+export declare function configKeyOptions(options: Record<string, string | undefined>, take?: {
+    conformance?: boolean;
+    review?: boolean;
+}): void;

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * One entry point, so the tools can be used from wherever the specification lives.
+ *
+ * Paths are resolved against the current working directory, and a .plain file's linked
+ * resources are too - so the intended use is to `cd` to the module and name the file,
+ * rather than to run from this repo and reach across with absolute paths.
+ */
+export {};

package/dist/cli.js

@@ -19,7 +19,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CODING_MODEL_ENV, chatModels } from "./chat-models.js";
 import { readProjectConfig } from "./config.js";
-import { extensionInstalledGlobally, PACKAGE_ROOT, themesInstalledGlobally } from "./environment.js";
+import { extensionInstalledGlobally, PACKAGE_ROOT, themesInstalledGlobally, versionLine } from "./environment.js";
 import { dropNoise } from "./quiet.js";
 /**
  * Start pi with this project's extension and themes already wired in.
@@ -92,6 +92,7 @@ const SETUP_COMMANDS = {
 const USAGE = [
     "usage: turri [options]          open the conversation here: pi, with turri's tools and themes loaded",
     "       turri <command> [args]",
+    "       turri --version          turri's version, and pi's",
     "",
     `  ${"options".padEnd(12)} --harness-model <m>  the model you chat with   --coding-model <m>  the model renders run on`,
     `  ${"".padEnd(12)} --stack <name>  build with config.turri.<name>.yaml over config.turri.yaml - here and in every command`,
@@ -139,6 +140,11 @@ if (command === "-h" || command === "--help") {
     console.log(USAGE);
     process.exit(0);
 }
+// turri's version, not pi's alone: pi's --version would answer for it.
+if (command === "-v" || command === "--version") {
+    console.log(versionLine());
+    process.exit(0);
+}
 // turri alone is the conversation, and so is turri with pi's options - `turri -c`, `turri --harness-model <m>`. A word
 // turri does not know is an error below, not a conversation started on it.
 if (command === undefined || command.startsWith("-"))

package/dist/config-command.d.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+/**
+ * `/turri-config`: every setting of the project's config.turri.yaml from the chat - `/turri-config` alone lists them,
+ * `/turri-config review` asks for review's value, `/turri-config review false` sets it. Each is written into the file
+ * and takes effect as it says - now, at your next message, at the next pulse - never only once turri starts again:
+ * what turri fixes at its start is changed live here (live).
+ */
+/** What a change does to turri as it runs, beside the file: each says what it did, or nothing. */
+export interface LiveHooks {
+    /** The chat's model is now this - provider/id:thinking - or, undefined, no longer set in the file. */
+    chatModel(spec: string | undefined, ctx: ExtensionContext): Promise<string | undefined>;
+    /** The coding model changed in the file: one chosen this session - --coding-model, engine - gives way to it. */
+    codingModel(): string | undefined;
+    /** How many pulses run at once: the number, or the machine's default. */
+    parallelJobs(count: number | undefined): string | undefined;
+}
+export interface TurriConfigOptions {
+    /** The folder whose config.turri.yaml the chat reads. */
+    cwd: string;
+    /** The ***plain rules there are, by name - what rules-off takes. */
+    rules: () => string[];
+    /** The chat's model, provider/id:thinking, after a change - read as the file has it now. */
+    chatSpec: () => string | undefined;
+    live: LiveHooks;
+}
+export declare function registerTurriConfig(pi: ExtensionAPI, options: TurriConfigOptions): void;

package/dist/config-edit.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `/turri-config`'s side of config.turri.yaml: every setting turri reads, what it takes - a yes or no, one of a few words, a
+ * number, a model, a list - and when a change to it takes effect, so the person knows whether to wait for the next
+ * pulse or not at all. A change is written into the file line by line, its comments and the commented-out examples
+ * kept; `models:` and `agent-env:`, which nest, are written again whole, their own comments lost.
+ */
+/** When a change takes effect. Nothing turri reads needs a restart: what is fixed at its start is changed live. */
+export type Effect = "now" | "next-message" | "next-pulse" | "next-plan" | "next-test-run" | "next-landing" | "next-regenerate";
+export type SettingKind = "boolean" | "choice" | "number" | "model" | "list" | "path" | "budget";
+export interface Setting {
+    /** As written in the file - a nested one by its path: `models.coding`, `models.coding.turn-limit`, `agent-env.files`. */
+    key: string;
+    /** What it does, in a line. */
+    about: string;
+    kind: SettingKind;
+    /** What it is when it is not set. */
+    unset: string;
+    effect: Effect;
+    /** The words it takes (choice), or the values offered first (number, budget, list). */
+    options?: string[];
+    /** The least a number may be. */
+    min?: number;
+    /** Set in the project's config.turri.yaml only: a stack's file does not change it. */
+    projectOnly?: boolean;
+}
+/** What each effect is, said to the person. */
+export declare const EFFECT_TEXT: Record<Effect, string>;
+/** Every setting, in the order the list shows them. */
+export declare function settings(rules?: string[]): Setting[];
+/** A setting by its key - `review`, `models.coding` - or nothing. */
+export declare function settingOf(key: string, rules?: string[]): Setting | undefined;
+/** A value read from what was typed: what to write, or that it is to be unset, or why it cannot be. */
+export type Parsed = {
+    value: unknown;
+} | {
+    unset: true;
+} | {
+    error: string;
+};
+/**
+ * What was typed for a setting, read as the file takes it: `true`/`false`, one of its words, a number at least its least,
+ * a model `provider/id` with an optional `:thinking`, a list by commas. `known`: whether a model can be reached here -
+ * when it is given, one that cannot is refused.
+ */
+export declare function parseValue(setting: Setting, typed: string, known?: (model: string) => boolean): Parsed;
+/** The file with a top-level key set to a value as it is - a block, such as `models:`, written whole - in its line, or under its commented-out example. */
+export declare function withTopLevelValue(text: string, key: string, value: unknown): string;
+/**
+ * The file with a setting set to a value, or unset (`undefined`). A top-level one is changed in its line; one under
+ * `models:` or `agent-env:` has that block written again whole.
+ */
+export declare function withSetting(text: string, key: string, value: unknown): string;
+/** A setting's value as the file has it - the raw value, before turri reads it - or undefined when it is not set. */
+export declare function currentValue(text: string, key: string): unknown;
+/** A value for showing: `true`, `anthropic/claude-opus-5-5:low`, `[.env, .env.local]`. */
+export declare function shownValue(value: unknown): string;
+/** The project's config.turri.yaml - or the config.yaml it is read from until it has one - its text, empty when there is neither. */
+export declare function readConfigText(dir: string): string;
+/** What a change does beside setting the value: the files and settings that win over it, said to the person. */
+export declare function overriddenBy(dir: string, text: string, setting: Setting): string[];
+/**
+ * Write a setting into the project's config.turri.yaml - made when it is not there, from config.yaml and each stack's
+ * file in the old naming when they are what the project is read from - and give back the file as written.
+ */
+export declare function writeSetting(dir: string, key: string, value: unknown): string;
+/** The files a path setting is offered: the testing scripts in the root and test_scripts/, or the .plain files of the folder. */
+export declare function pathOptions(dir: string, key: string): string[];
+/** The dotenv files of the project root, for agent-env.files. */
+export declare function dotenvFiles(dir: string): string[];