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

package/dist/regenerate/release.d.ts

@@ -0,0 +1,123 @@
+import { type ChainEntry } from "./requires.ts";
+/**
+ * Deploy: a module's code, as its last commit has it, put out in `dist/<module>` for the person to try.
+ *
+ * A render works in `plain_modules/<module>/code` while the person asks to try what is there, so what
+ * is there is half-written. Its last commit is not: every unit of work starts from one and ends with
+ * one, and both are runnable. So the commit is exported - git's own list of what it tracks, and
+ * nothing else - which is a copy of the working tree with every unstaged and untracked change put
+ * back, without a list of what each stack leaves lying around (`node_modules`, `.venv`, `target`). The
+ * working tree itself is never read or touched.
+ *
+ * What starts it runs here, on the person's machine, unfenced: a server the person opens in their
+ * browser, with their toolchains. The agent that releases it installs and runs what it needs itself,
+ * as any agent with a shell would - nothing is put to the person - and everything started is the
+ * harness's to stop: on a redeploy, on /halt, and when turri exits.
+ */
+/**
+ * How a module is released - always from its last commit, exported to `dist/<module>` first. `dist`, the default: started
+ * from there. `guided`: taken on from there as there is guidance to - the person's, the project's AGENTS.md, a skill -
+ * into the host codebase, say.
+ */
+export type ReleaseWay = "dist" | "guided";
+export interface Deployment {
+    moduleName: string;
+    plainFile: string;
+    way: ReleaseWay;
+    /** `dist/<module>`, in the project: the module's last commit, exported. */
+    dir: string;
+    /** Guided: the host codebase the guidance takes the code into, and what release runs and starts runs from. */
+    hostDir?: string;
+    /** Where the module's code is built: `plain_modules/<module>/code`. */
+    buildDir: string;
+    commit: string;
+    /** The commit's subject: what the last unit of work that landed did. */
+    subject: string;
+    /** When, as git says it: "3 minutes ago". */
+    when: string;
+    /** Work under way in the module - changes nobody committed yet - left out. */
+    unfinished: boolean;
+    /** The module the spec's code lives in had nothing committed yet: the nearest one below it that had, instead. */
+    instead?: string;
+}
+/**
+ * Which module to deploy for a spec: the tip of its codebase - code accumulates up a requires chain, so
+ * the top module holds everything below it. Before the tip has anything committed, the nearest module
+ * below it that has.
+ */
+export declare function deployTarget(plainFile: string, inModule?: string): {
+    entry: ChainEntry;
+    commit: string;
+    instead?: string;
+};
+/**
+ * Export the module's code at its last commit into `dist/<module>` - or `into`, `turri regenerate --build-dir` -
+ * replacing whatever was there, the harness's own files (what the code is built from, the agents' notes) left out.
+ */
+export declare function exportModule(plainFile: string, inModule?: string, into?: string): Deployment;
+/**
+ * The host codebase a guided release works in: the git repository the project is in - an embedded project's host -
+ * or else `fallback`, where turri runs.
+ */
+export declare function hostDirOf(plainFile: string, fallback: string): string;
+/** Where a path is, said from the current directory when it is below it. */
+export declare function shortPath(path: string): string;
+/** What was deployed, in a line or three. */
+export declare function describeDeployment(deployment: Deployment): string;
+export interface DeployedProcess {
+    name: string;
+    moduleName: string;
+    command: string;
+    /** Where it runs. */
+    dir: string;
+    url?: string;
+    /** Its output, both streams. */
+    log: string;
+    pid: number;
+    startedAt: number;
+    /** Set once it has ended. */
+    exited?: {
+        code: number | null;
+        signal: string | null;
+    };
+}
+/** Everything deploy started, running or ended, oldest first. */
+export declare function listDeployed(): DeployedProcess[];
+/** The ones still running. */
+export declare function runningDeployed(moduleName?: string): DeployedProcess[];
+/** Where a project's deployed processes write their output: its scratch, not the code in dist. */
+export declare function deployLogDir(projectDir: string): string;
+/** The end of a log, for when something did not come up. */
+export declare function logTail(log: string, lines?: number, chars?: number): string;
+/** Stop one deployed process, or every one of a module, or every one: politely, then not. Returns the names stopped. */
+export declare function stopDeployed(which?: {
+    name?: string;
+    moduleName?: string;
+}): Promise<string[]>;
+/** Stop everything at once, without waiting: for when turri itself is going. */
+export declare function stopAllDeployedNow(): void;
+/** How long a server is given to answer at its URL, and to stay up when it has none. */
+export declare const READY_TIMEOUT_MS: number;
+export interface StartResult {
+    ok: boolean;
+    /** What happened, for the agent and the person. */
+    text: string;
+    process?: DeployedProcess;
+}
+/**
+ * Start something that keeps running - a server, a frontend's dev server - in `dir`, on this machine,
+ * in its own process group, its output to a log. One already running under the name is stopped first.
+ *
+ * With a URL, it is ready once something answers there - any answer - and not when it exits first or
+ * nothing answers in time. A port something else holds already is said, with what holds it, and
+ * nothing is started: an app moved to a port of the harness's choosing would not be the one the
+ * person was told about. With no URL, it only has to still be running a few seconds on.
+ */
+export declare function startDeployed(input: {
+    name: string;
+    command: string;
+    dir: string;
+    moduleName: string;
+    logDir: string;
+    url?: string;
+}): Promise<StartResult>;

package/dist/regenerate/requires.d.ts

@@ -0,0 +1,96 @@
+import { type ParseOptions } from "../plain/parser.ts";
+/**
+ * `requires` chains.
+ *
+ * A module that `requires` another is built on top of that module's code: the required
+ * module must be finished first, and its codebase is copied into the build before this
+ * module starts. So rendering a module means rendering its chain, bottom first, carrying
+ * the code forward at each step.
+ *
+ * What has already been built is not tracked here: each codebase's record says what it is built
+ * from - see `records.ts`.
+ */
+export interface ChainEntry {
+    moduleName: string;
+    plainFile: string;
+    buildDir: string;
+    /** The module whose code is copied in before this one is built. */
+    requires: string | null;
+    frids: string[];
+}
+/**
+ * The chain to build, bottom first.
+ *
+ * Depth-first, post-order: everything a module requires is listed before the module
+ * itself. The parser has already rejected circular requires, and a module reached twice is
+ * emitted once.
+ */
+export declare function resolveRequiresChain(plainFile: string, templateDirs?: string[], buildRoot?: string, 
+/** Accept the named module without functional specs yet. Those it requires must have them. */
+options?: ParseOptions): ChainEntry[];
+/**
+ * Whether a .plain file is an import module - one a .plain file imports, or one kept in a `template/` folder - rather than
+ * a module of its own. It is no codebase: its reqs and definitions are built in the modules that import it.
+ */
+export declare function isImportModule(plainFile: string): boolean;
+/** The modules of their own that import an import module, through any import modules between. */
+export declare function importingModules(plainFile: string): string[];
+/**
+ * The codebase a change to `plainFile`'s module lands in: the furthest-built module whose
+ * requires chain includes it, with that chain.
+ *
+ * Code accumulates up a chain, so once modules have been built on top of this one, its own
+ * build is only an early snapshot - the living codebase is the one at the tip. A change to
+ * this module's spec is made there, where everything built since can be kept working, not
+ * in the snapshot, where it would have to be copied up over newer work.
+ *
+ * Found by reading every .plain file beside this one. Where built descendants sit on
+ * different branches there is no single tip, and choosing one is a decision: `inModule`
+ * names it, and without it this refuses rather than guesses.
+ */
+export declare function findCodebaseTip(plainFile: string, options?: {
+    templateDirs?: string[];
+    buildRoot?: string;
+    inModule?: string;
+    allowNoFunctionalities?: boolean;
+}): {
+    tip: ChainEntry;
+    chain: ChainEntry[];
+};
+/**
+ * The chains of the built modules whose requires chain includes `plainFile`'s module, and that no other
+ * built module is built on - where its code lives now, one chain per branch. Empty when nothing built is
+ * built on it. Found by reading every .plain file beside it.
+ */
+export declare function builtTips(plainFile: string, options?: {
+    templateDirs?: string[];
+    buildRoot?: string;
+}): ChainEntry[][];
+/**
+ * Copy a required module's codebase into the build that is about to be created.
+ *
+ * What the code is built from comes too, converted: what the source module built becomes what
+ * the new one inherits, while the new module's own functional specs start empty. Copied as-is, it would claim the source's work as the new
+ * module's own. And the conformance tests come, into the new module's tests directory.
+ */
+export declare function copyRequiredCode(from: string, to: string, toModule: string, 
+/** The module the code comes from: its functional specs are what the new one inherits. */
+fromModule: string): string[];
+/**
+ * A module the chain requires now that a module built in it was not built on: one required for
+ * the first time - a new module the specs were split into, say - and the built modules above it,
+ * whose code was started without it and so has to start again from scratch.
+ *
+ * A module was built on what its record lists as inherited; one with nothing recorded, on what it
+ * was started from, as its history says. A module below it with nothing built was never under it.
+ */
+export declare function newlyRequired(chain: ChainEntry[]): {
+    modules: string[];
+    rebuild: ChainEntry[];
+} | undefined;
+/**
+ * Take a module back to nothing - its code, its conformance tests and what they were built from -
+ * so it is built again from the start, on the module it now requires. Committed, so the code that
+ * was there is in its history.
+ */
+export declare function startFromScratch(entry: ChainEntry, why: string): void;

package/dist/regenerate/resources.d.ts

@@ -0,0 +1,53 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type MarshalledPlainSource } from "../plain/spec.ts";
+export interface LoadedResource {
+    text: string;
+    target: string;
+    /** What the agent reads in <linked resources>: the file's text, or - an image - where to find it. */
+    content: string;
+    /** An image: sent to the agent with its first message, not as text. */
+    image?: ResourceImage;
+    /** Where the file is: copy_resource copies it whole from here. */
+    source?: string;
+    /** Its text was cut for the prompt: how long it is whole. */
+    cutFrom?: number;
+}
+/** A linked image as a model is sent it. */
+export interface ResourceImage {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+/** The MIME type of a linked image, by its extension; undefined for any other file. */
+export declare function imageTypeOf(target: string): string | undefined;
+/** A linked image too large to send, or unreadable: the job stops, saying which file and why. */
+export declare class LinkedImageError extends Error {
+}
+/**
+ * Load the resources linked from the specifications in scope for one functionality.
+ *
+ * `collectLinkedResources` stops at the requested FRID, so a resource introduced by a
+ * later functionality is not pulled into this prompt.
+ */
+export declare function loadLinkedResources(tree: MarshalledPlainSource, 
+/** Up to and including this functionality. Null: the whole module. */
+frid: string | null, templateDirs: string[]): LoadedResource[];
+/**
+ * A linked resource that is code - a source file, or a build manifest: the specification points at code that lives
+ * elsewhere, a host's module the code plugs into, for the code to build on as it says. It is never copied into the
+ * codebase, nor recreated there; a resource that is data - a fixture, a schema, a sample - is.
+ */
+export declare function isCodeResource(target: string): boolean;
+/** Where in a codebase a linked resource's one copy goes: its path, without the steps up and the leading `./`. */
+export declare function codeCopyOf(target: string): string;
+/**
+ * `copy_resource`: a linked resource copied whole into the agent's own folder - at its code-copy path, or where it
+ * says - by the harness, byte for byte. The agent's prompt shows a long resource cut short, and the file itself is
+ * outside its walls: copied, it reads the whole of it there, and the code or the tests use that one copy.
+ */
+export declare function createCopyResourceTool(options: {
+    resources: LoadedResource[];
+    dir: string;
+}): ToolDefinition;
+/** The images among loaded resources, in the order the prompt numbers them. */
+export declare function resourceImages(resources: LoadedResource[]): ResourceImage[];

package/dist/regenerate/self-check.d.ts

@@ -0,0 +1,29 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+/**
+ * Tools an agent checks its own work with, before the harness and the reviewer do: the diff the reviewer is shown, and
+ * whether a test catches a change to the code. Neither decides anything - the testing scripts, run by the harness, still do.
+ */
+/** The work so far, as the reviewer is shown it: a diff of the folder from the commit the job started from. */
+export declare function createMyDiffTool(options: {
+    dir: string;
+    what: "code" | "tests";
+}): ToolDefinition;
+/** How many times can_it_fail runs in one session, by default: each is a run of the unit testing script. */
+export declare const CAN_IT_FAIL_RUNS = 6;
+/**
+ * How long a can_it_fail run may take: three times the last passing run of the unit tests on this code, within 15 and
+ * 60 seconds - 60 before one has passed. A bug put in the code often makes it loop or wait for ever: that is found out
+ * in a short time, not the whole limit of a test run, and well within the agent's turn.
+ */
+export declare function canItFailLimitMs(buildDir: string, script: string): number;
+/**
+ * Whether the unit tests catch a change to the code: the change made to a fresh copy - never to the code itself - and
+ * the unit testing script run on it. A test that passes whatever the code does tests nothing.
+ */
+export declare function createCanItFailTool(options: {
+    buildDir: string;
+    script: string;
+    runs?: number;
+}): ToolDefinition;
+/** When the coding agent checks its own work, by the tools it has: before the unit tests, and before it hands the work in. */
+export declare function selfCheckNote(tools: string[]): string[];

package/dist/regenerate/services.d.ts

@@ -0,0 +1,28 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type AgentShell } from "./agent-shell.ts";
+/**
+ * What an agent starts and keeps running while it works - a server, a worker - to try the software as someone would,
+ * from outside: with curl, or what the stack's own client is. Whatever the stack: the agent gives the command that
+ * starts it, and how to tell it is up - a port that answers, or a line in its log. It runs on this machine behind the
+ * same walls as the agent's own shell - the command check, the module's environment, the OS sandbox, the audit while it
+ * starts - in a process group of its own, so it outlives the command that started it; it is stopped - it and everything
+ * it started - when the agent asks, when the agent's session ends, and in any case when its pulse ends.
+ */
+/** How many services one agent may have running at once. */
+export declare const MAX_SERVICES = 3;
+export interface ServiceTools {
+    tools: ToolDefinition[];
+    names: string[];
+    /** Stop everything still running. Called when the agent's session ends, whatever ended it. */
+    stopAll(): Promise<void>;
+}
+/**
+ * Start, read and stop services from `dir` - the folder the agent works in - fenced as its role is: what it may read and
+ * write (its workdir when not given), or the shell given.
+ */
+export declare function createServiceTools(options: {
+    dir: string;
+    read?: string[];
+    write?: string[];
+    shell?: AgentShell;
+}): ServiceTools;

package/dist/regenerate/shell.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The one way a command runs on this machine - an agent's, a testing script, a service.
+ *
+ * Each command runs in a process group of its own, so the time limit and a stop end it with everything it started, a
+ * server put in the background included. What a command leaves running when it ends - a server for the tests to talk
+ * to - is the pulse's: it runs on until the pulse ends (`withPulse`), and is killed then, as everything still running is
+ * when turri exits. turri killed outright cannot do that itself, so a watcher - one small shell for each turri - does it
+ * within two seconds; and the groups a turri left that nothing killed (the watcher gone too) are swept when turri next
+ * starts (`sweepOrphanedGroups`).
+ *
+ * On Windows there are no process groups: a command's process tree is killed with `taskkill /T /F`, which reaches what
+ * is still a child of it - best effort, and nothing watches a turri killed outright.
+ */
+export interface RunResult {
+    exitCode: number;
+    output: string;
+    /** Stopped by its time limit, rather than ending on its own. */
+    timedOut?: boolean;
+}
+export interface RunOptions {
+    /** Where it runs from. */
+    cwd: string;
+    /** Its time limit: COMMAND_TIMEOUT_MS when not given. */
+    timeoutMs?: number;
+    /** What the output says when the time limit stops it; the note for a command, by default. */
+    timeoutNote?: (timeoutMs: number) => string;
+    /** Ends it at once - as the job's own stop signal does, given or not. */
+    signal?: AbortSignal;
+    /** Its output, as it comes. */
+    onData?: (data: Buffer) => void;
+    /** Its whole environment: this process's when not given. */
+    env?: NodeJS.ProcessEnv;
+    /** The command line turned into another that runs it - an OS sandbox around it. */
+    wrap?: (argv: string[]) => string[];
+}
+/**
+ * How long a command may run before it is stopped - an agent's own, its tests, the harness's runs. Nothing an agent
+ * starts may hang a build: a server started in the foreground, a watcher, a prompt waiting for input would otherwise
+ * hold the agent's turn, and the job, forever. TURRI_COMMAND_TIMEOUT sets it, in seconds.
+ */
+export declare const COMMAND_TIMEOUT_MS: number;
+/** The longest an agent may ask one of its own commands to run for. */
+export declare const MAX_COMMAND_TIMEOUT_MS: number;
+/** What a command that ran out of time leaves in its output, for the agent to act on. */
+export declare function timedOutNote(timeoutMs: number): string;
+/**
+ * Whether a pulse other than the current one is at work in `moduleDir` - what changes there is that pulse's, and the
+ * audit leaves it.
+ */
+export declare function anotherPulseIn(moduleDir: string): boolean;
+/** Where each running turri records its groups, a file named for its process id: for its watcher, and the sweep. */
+export declare function groupRecordsDir(): string;
+/**
+ * Run `work` - a pulse - and kill every group it started when it ends, however it ends: what an agent left running in
+ * the background is the pulse's, and goes with it. Groups of a pulse running beside it are left alone. `modules`: the
+ * module folders it works in - its lanes - which the audit of another pulse's commands leaves to it.
+ */
+export declare function withPulse<T>(work: () => Promise<T>, options?: {
+    modules?: string[];
+}): Promise<T>;
+/** Kill every group this turri started. Called as it exits; the tests call it between files. */
+export declare function killAllGroups(): void;
+/**
+ * Kill the groups turris that are gone left behind - killed outright, their watcher gone too - from their records in
+ * `dir`. A running turri's are its own. Returns how many groups were still there to kill.
+ */
+export declare function sweepOrphanedGroups(dir?: string): number;
+/**
+ * Run `command` with bash on this machine, from `cwd`, in a process group of its own.
+ *
+ * It has a time limit - COMMAND_TIMEOUT_MS unless given another - and ends at once when it is stopped, by the caller's
+ * signal or the job's; either way its whole group is killed. Ended on its own, what it left in the background runs on
+ * until its pulse ends.
+ */
+export declare function runCommand(command: string, options: RunOptions): Promise<RunResult>;
+/**
+ * Start `command` in the background, in a process group of its own, its output to `logFile` - a server an agent starts
+ * to try from outside. It is its pulse's: running until stopped (`stopGroup`), and killed when the pulse ends.
+ */
+export declare function startInBackground(command: string, options: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    wrap?: (argv: string[]) => string[];
+    logFile: string;
+}): {
+    pid: number;
+};
+/** Whether a process is still running. */
+export declare function isRunning(pid: number): boolean;
+/** Stop a group started in the background: asked to end, then - after `graceMs` - made to. */
+export declare function stopGroup(group: number, graceMs?: number): Promise<void>;

package/dist/regenerate/side-panel.d.ts

@@ -0,0 +1,57 @@
+import { type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import type { Job } from "./jobs.ts";
+import { type JobsTreeState } from "./jobs-tree.ts";
+import type { MarkedPage } from "./spec-map.ts";
+import { type SpecMapState } from "./spec-map-view.ts";
+import type { TranscriptStyle } from "./transcript-view.ts";
+/**
+ * The side panel: the spec and how far the code has been regenerated, beside the conversation rather than instead of
+ * it.
+ *
+ * Two views. The regeneration (spec-map-view.ts), shown first: every item of the spec with where it stands - built,
+ * regenerating, planned, waiting, being taken out - under a row for each module, the one in focus open. And the
+ * pulses, as a tree - running, queued, finished, a line per pulse and all of what it builds once opened (see
+ * jobs-tree.ts). `p` goes from one to the other, the cursor with it: from an item to the pulse that regenerates it, and
+ * back. What the agents said and did is not shown here: it is in each pulse's log (job-log.ts).
+ */
+export interface SidePanelOptions {
+    /** Every job, oldest first. */
+    jobs: () => Job[];
+    /** The regeneration's pages. Not given: the pulse list alone. */
+    map?: () => MarkedPage[];
+    /** Rows the panel may use. */
+    rows: () => number;
+    style: TranscriptStyle;
+    /** Back to the conversation: the panel closes. */
+    back: () => void;
+    /** Whether something in the conversation waits for the person - a question asked while the panel showed. */
+    waiting?: () => boolean;
+    /** Close the panel. */
+    close: () => void;
+    /**
+     * A module needs the person - `!`: the panel closes, and the chat takes it up with them - what went wrong, and what
+     * to do about it. Not given: the key is not offered.
+     */
+    discuss?: (page: MarkedPage) => void;
+    /** The key that opens and closes it, shown in the footer. */
+    key: string;
+    /**
+     * The panel over the whole screen, or beside the chat - `s` goes from one to the other. Beside it, `esc` gives the
+     * keys back to the chat and the panel stays. Not given: the key is not offered.
+     */
+    dock?: {
+        docked(): boolean;
+        toggle(): void;
+    };
+    /** The pulse list's tree - what is open, where the cursor is - kept across openings of the panel. */
+    tree?: JobsTreeState;
+    /** The regeneration's view - which page, what is open, where the cursor is, which view shows - kept the same way. */
+    mapState?: SpecMapState;
+}
+export declare function createSidePanel(options: SidePanelOptions): {
+    render(width: number): string[];
+    handleInput(data: string): void;
+    /** The wheel scrolls the panel wherever the keyboard is. */
+    handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+    invalidate(): void;
+};

package/dist/regenerate/spec-map-view.d.ts

@@ -0,0 +1,139 @@
+import type { Job } from "./jobs.ts";
+import { type Mark, type MarkedItem, type MarkedPage } from "./spec-map.ts";
+import type { TranscriptStyle } from "./transcript-view.ts";
+/**
+ * The regeneration drawn: a page a module, an item a row - see spec-map.ts for what each mark means.
+ *
+ * Each item's first line, with its one mark in the gutter - its rung on the ladder; a changed item's changed
+ * sub-bullets under it, word by word; an item taken out as a struck-through ghost. Enter opens an item: all of it, its
+ * acceptance tests, the pulse that brings it, its conformance tests, and - a definition - the built specs that use it.
+ * One module is shown at a time, a tab a module of the chain - ←→ go from one to the next: the module regenerating now, until
+ * another tab is chosen, and again once another module starts regenerating. Under its own text, the files it imports, a
+ * folded block each. A chain of many modules nested one in another was too deep to read, and too much to draw.
+ */
+export interface SpecMapState {
+    /** Which view the side panel shows: the map, or the pulse list. */
+    view: "map" | "pulses";
+    /** The row the cursor is on, and the key of what is there - it stays on the item when rows move. */
+    cursor: number;
+    cursorKey?: string;
+    /** The first line shown. */
+    top: number;
+    /** The items opened, by key. */
+    open: Set<string>;
+    /** Import blocks opened by hand, by where they are and file: the rest closed. */
+    imports: Map<string, boolean>;
+    /** The tab chosen by hand - its .plain file - and the module in focus when it was: another in focus, or it starts regenerating, the view follows that. */
+    tab?: {
+        file: string;
+        focus?: string;
+    };
+    /** An item to show - in its module and import block, opened for it - and put the cursor on: by .plain file and key. */
+    reveal?: {
+        file: string;
+        key: string;
+    };
+}
+export declare function createSpecMapState(): SpecMapState;
+/** A row: a group's heading; an import block; an item. */
+export type MapRow = {
+    kind: "group";
+    page: MarkedPage;
+    key: string;
+    label: string;
+    depth: number;
+} | {
+    kind: "import";
+    page: MarkedPage;
+    file: string;
+    key: string;
+    open: boolean;
+    depth: number;
+} | {
+    kind: "item";
+    page: MarkedPage;
+    item: MarkedItem;
+    key: string;
+};
+/** What a line shows, for the minimap: the mark of the item it belongs to. */
+type LineMark = Mark | "removed" | undefined;
+/**
+ * The module in focus: the one regenerating now, else the last the loop looks after - the module asked for, at the top of its
+ * chain - else the first.
+ */
+export declare function focusOf(pages: MarkedPage[]): MarkedPage | undefined;
+/** The module shown: the tab chosen by hand while the module in focus is as it was then, else the one in focus. */
+export declare function shownPage(pages: MarkedPage[], state: SpecMapState): MarkedPage | undefined;
+/** The tab `by` along from the one shown - the chain's order, the module it is built on to the left - its cursor at its top. */
+export declare function switchTab(pages: MarkedPage[], state: SpecMapState, by: number): void;
+/**
+ * The tabs, a module each in the chain's order, the one shown marked - those regenerating spin, those stuck say so - fitted to
+ * `width` around the one shown, what does not fit counted at either end.
+ */
+export declare function tabBar(pages: MarkedPage[], shown: MarkedPage | undefined, width: number, style: TranscriptStyle, now: number): string;
+/**
+ * Where an item stands, as one mark on a ladder every item climbs: planned, working, regenerated, validating, conform - and needs
+ * you, off it - named in the legend in the panel's corner. The same mark means the same thing whatever the config says
+ * of conformance tests: a functional spec regenerated and not conformed is hollow whether its tests are on, off or not
+ * chosen, so changing that changes no mark.
+ */
+export declare const LADDER: {
+    readonly toRegenerate: "○";
+    readonly regenerated: "◇";
+    readonly conform: "◆";
+    readonly needsYou: "!";
+    readonly takenOut: "−";
+};
+/**
+ * An item's rung: what its one mark shows. Working is regenerating or taking out alike; validating, its conformance tests
+ * being written and run - a spinner of its own colour, the green of the rungs it is between.
+ */
+export type Rung = "toRegenerate" | "working" | "regenerated" | "validating" | "conform" | "needsYou" | "takenOut" | "none";
+export declare function rungOf(item: MarkedItem): Rung;
+/** The two columns' headings, over the map - status, and the module's file - and a line of space under them. */
+export declare function columnHeadings(page: MarkedPage, width: number, style: TranscriptStyle): string[];
+/**
+ * The legend's lines, for the panel's lower right corner: every rung of the ladder, always - what a mark means never
+ * depends on the page - and to take out only where the page has something to take out.
+ */
+export declare function legendLines(page: MarkedPage, style: TranscriptStyle): string[];
+/** What the person is needed for, and how: the line under a page's first `!`, and its top line's end. */
+export declare const DISCUSS_KEY = "d";
+/** A line of ***plain highlighted as plyn highlights it: the whole line read, so a span over several words keeps its colour. */
+export declare function highlighted(line: string, style: TranscriptStyle): string;
+/** One line become another, word by word: what is gone struck through in red, what is new in green, the rest as it is. */
+export declare function wordDiff(was: string, now: string, style: TranscriptStyle): string;
+/**
+ * An item's text against the code record's, line by line: each line kept, or changed - paired with the line it was -
+ * or only on one side. Lines are a functional spec's first line and its sub-bullets.
+ */
+export declare function lineDiff(was: string, now: string): Array<{
+    was?: string;
+    now?: string;
+}>;
+/**
+ * The rows of the module shown, top to bottom: its own items, then the files it imports, a block each under their
+ * heading, closed until opened. The modules it requires are tabs of their own.
+ */
+export declare function specMapRows(pages: MarkedPage[], state: SpecMapState): MapRow[];
+/**
+ * A page as lines: each row, the cursor's marked, a section's heading where one starts; where each row starts, for
+ * scrolling to it; and each line's mark, for the minimap.
+ */
+export declare function specMapLines(pages: MarkedPage[], state: SpecMapState, width: number, style: TranscriptStyle, _jobs?: Job[], now?: number): {
+    lines: string[];
+    rowStarts: number[];
+    rows: MapRow[];
+    marks: LineMark[];
+};
+/** The progress strip: the page's functional specs, built, regenerating, planned and waiting, in their colours. */
+export declare function progressStrip(page: MarkedPage, style: TranscriptStyle, cells?: number): string;
+/** A module's row: opened or closed, its file, its strip, how many of its functional specs are built, and its status. */
+/** The map's top line: the page's name, its strip and its count and status. */
+export declare function specMapHeader(page: MarkedPage, width: number, style: TranscriptStyle, waiting?: string): string;
+/**
+ * The minimap: a column down the right edge, a cell for each slice of the page - the most pressing mark in it - and
+ * the slice shown solid.
+ */
+export declare function minimap(marks: LineMark[], height: number, top: number, style: TranscriptStyle): string[];
+export {};