@turri-dev/cli 0.1.6-next.336dd6e → 0.1.7-next.8f13f3a

package/dist/regenerate/audit.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The audit after every agent command, on every platform: the net under the command check and the OS sandbox.
+ *
+ * Inside the project, what the command's role may not change is put back as it was before it ran - a changed file
+ * restored, a new one removed, a deleted one brought back: the specs, the config, the testing scripts, every credential
+ * file, the code record, the module's lineage, the other modules, and the folders the role only reads. Small files are
+ * kept before the command and put back from that copy; another module is put back as its last commit has it - unless a
+ * pulse is at work in it, whose writes are not this command's to undo. The role's own work is left alone, and the pulse
+ * goes on. Outside the project nothing can be put back: that is the OS sandbox's. Nor is a change the conversation
+ * itself made while the command ran - the person's model editing a spec beside a pulse (`conversation-writes.ts`): that
+ * is left, not taken for the command's.
+ *
+ * What changed is seen cheaply: each file's size and modification time before and after, skipping dependencies and
+ * build output, and contents compared only where those differ.
+ */
+export interface AuditScope {
+    /** The project: the folder holding the specs, the config, the testing scripts and plain_modules. */
+    project: string;
+    /** The module the agent works in: `plain_modules/<module>`. */
+    module: string;
+    /** The role's roots it may write - its own work, left alone but for the record and credential files in it. */
+    write: string[];
+    /** The role's roots it only reads: put back whole. */
+    readOnly: string[];
+    /** Whether a pulse is at work in another module - what changes there is that pulse's, and left. */
+    busy?: (moduleDir: string) => boolean;
+}
+export interface AuditResult {
+    /** Put back as it was, by path from the project. */
+    putBack: string[];
+    /** Changed where a pulse is at work, and left - for the job log. */
+    left: string[];
+    /** Changed, and nothing to put it back from. */
+    lost: string[];
+    /** Changed by the conversation itself while the command ran, and left. */
+    conversation: string[];
+}
+interface Seen {
+    size: number;
+    mtimeMs: number;
+}
+/** A tree's files by path, with their size and time - and, where kept, what they held. */
+interface Tree {
+    root: string;
+    files: Map<string, Seen>;
+    /** What the files held, for those put back from a copy. */
+    kept?: Map<string, Buffer>;
+    /** How it is put back: from the copy, or from the module's last commit. */
+    from: "copy" | {
+        lineage: string;
+    };
+    /** Only its record and credential files are watched: the role writes the rest. */
+    watchOnly?: boolean;
+    /** Another module a pulse is at work in: what changes there is left. */
+    busy?: boolean;
+}
+export interface AuditSnapshot {
+    scope: AuditScope;
+    trees: Tree[];
+    /** When it was taken: a change the conversation made since is the conversation's, not the command's. */
+    at: number;
+}
+/** Take what the audit compares against, before a command runs. */
+export declare function beforeCommand(scope: AuditScope): AuditSnapshot;
+/** After the command: put back what it changed that its role may not, and say what. */
+export declare function afterCommand(snapshot: AuditSnapshot): AuditResult;
+/** What the agent is told in its command's result, or nothing when the audit put nothing back. */
+export declare function auditMessage(result: AuditResult): string | undefined;
+export {};

package/dist/regenerate/cases.d.ts

@@ -0,0 +1,9 @@
+import type { JobCases } from "./drift.ts";
+/** What the coding agent does, case by case. */
+export declare function codeCasesBlock(cases: JobCases): string[];
+/** What the unit reviewer holds the work to, case by case - in place of its checks, when the job is mechanical. */
+export declare function codeReviewCasesBlock(cases: JobCases): string[];
+/** What the conformance agent does, case by case. */
+export declare function conformanceCasesBlock(cases: JobCases): string[];
+/** What the conformance test reviewer holds the tests to, when the job is mechanical: in place of its checks. */
+export declare function conformanceReviewCasesBlock(cases: JobCases): string[];

package/dist/regenerate/change-view.d.ts

@@ -0,0 +1,18 @@
+import type { DiffWhere } from "./diff-view.ts";
+import { type SpecChange } from "./spec-steps.ts";
+/**
+ * `changes` as a diff of `file` - the module's .plain file, which the diff names - section by section: a removed
+ * item's lines taken out, an added one's put in, a changed one's both. A change to what a linked file holds
+ * follows, as the step's own diff has it.
+ */
+export declare function changeDiff(changes: SpecChange[], file: string): string;
+/**
+ * `changeDiff`, each section's items in the order they are written - by file, then by line - rather than in the
+ * order the spec is read in, which puts a concept after those it uses: placed by `locate`, as the panels place it.
+ */
+export declare function changeDiffInFiles(changes: SpecChange[], file: string, locate: (diff: string) => DiffWhere): {
+    diff: string;
+    where: DiffWhere;
+};
+/** The changes a job's agent works from: a code job's leave out the test reqs, which are the conformance job's. */
+export declare function agentChanges(changes: SpecChange[], track: "code" | "conformance"): SpecChange[];

package/dist/regenerate/choose-conformance.d.ts

@@ -0,0 +1,32 @@
+import type { TouchedSpec } from "./drift.ts";
+/**
+ * Which functional specs get conformance tests, under `conformance-tests: chosen` or `module`, is this agent's to choose -
+ * in the chat and on the command line alike, on the chooser's model. Under chosen it is asked as each code pulse ends,
+ * of what that pulse regenerated; under module once, when the whole module is regenerated, and it plans the conformance
+ * pulses too. It reads the module's spec and names the ones worth black-box tests, and why. Being asked inside the pulse,
+ * the choice is made before anything can be built on the module: nothing has to be stopped for it.
+ */
+export interface ConformanceChoice {
+    frids: string[];
+    why: string;
+    /** Under module: the conformance pulses, each the functional specs it tests together. */
+    groups?: string[][];
+}
+/** What the chooser is asked: the module's spec, and the functional specs to choose from. */
+export declare function choicePrompt(plainFile: string, specs: TouchedSpec[], spec: string, budget?: number, when?: "pulse" | "module"): string;
+/** Ask the chooser, on `model`. Nothing chosen when it does not answer, or answers with numbers not offered. */
+export declare function chooseConformance(options: {
+    plainFile: string;
+    specs: TouchedSpec[];
+    model?: string;
+    budget?: number;
+    when?: "pulse" | "module";
+}): Promise<ConformanceChoice>;
+/**
+ * The work loop's chooser, the chat's and the command line's alike: asked as a pulse ends, it asks chooseConformance on
+ * the harness model. A functional spec passed over is not offered again for the same text - only once it changes.
+ */
+export declare function conformanceChooser(options: {
+    model: () => string | undefined;
+    dryRun?: boolean;
+}): (plainFile: string, specs: TouchedSpec[], budget: number | undefined, when: "pulse" | "module") => Promise<ConformanceChoice | undefined>;

package/dist/regenerate/chunk-plan.d.ts

@@ -0,0 +1,164 @@
+import { type MarshalledPlainSource } from "../plain/spec.ts";
+import { type Steering } from "./steer.ts";
+import { type SpecChange, type SpecStep } from "./spec-steps.ts";
+/**
+ * The queue's work, cut into jobs of a size worth rendering.
+ *
+ * A spec diff that renders the whole of a new spec is one job too big to build well, and a render per functional
+ * spec, the first carrying every definition and req of the spec, is no better: most of the work lands in one job,
+ * and the rest are a line each. So the work from what the code will be built from to the spec now is cut from the
+ * functional specs outward, in three steps:
+ *
+ * 1. Which new functional specs go together - next to each other, as the spec orders them, at most
+ *    `max-specs-per-pulse` in a job (MAX_SPECS_PER_JOB unset): what builds one feature goes together, and only what
+ *    stands on its own goes alone. An agent judges it: "builds the same thing" is a judgement.
+ * 2. The definitions each group uses: the concepts its functional specs name, and the concepts those
+ *    definitions name in turn. A definition goes with the first group that uses it; later ones have it built.
+ *    Code, not an agent: it is a lookup.
+ * 3. Where each new implementation req goes - the group it is about, or the first, when it is about
+ *    everything - and each new test req: the group whose conformance tests need it first. An agent judges it.
+ *
+ * Changes to what is built already - an item edited or taken out, a functional spec built changed - go first, in a
+ * job of their own. Every answer is checked; one that does not hold goes back to its agent, twice at most, and then
+ * the plan falls back to a functional spec a job. A job past `max-lines-per-pulse` (MAX_LINES_PER_JOB unset) is split. The plan is the queue
+ * master's proposal: it reviews it, and may change it, held to the same checks.
+ */
+/** What the planner cuts: the work from `base` to `current`, and the module's .plain file for how the diffs read. */
+export interface PlanInput {
+    /** What the work starts from: the record, or what the job running lands. */
+    base: MarshalledPlainSource;
+    /** What it ends on: the spec as the track sees it now. */
+    current: MarshalledPlainSource;
+    /** How the person wants the work cut and ordered. */
+    steering?: Steering[];
+    /** The module whose codebase it is: its own functional specs are given with it. */
+    moduleName?: string;
+    /** The module's .plain file, as the diffs name it, and its text - for the diffs' layout. */
+    specFile: string;
+    specText: string;
+    /**
+     * Which work it is. The conformance tests' is anchored on functional specs: a job of theirs tests at least one -
+     * the definitions and reqs they are written against go with the functional specs whose tests need them.
+     * Default: the code's.
+     */
+    track?: "code" | "conformance";
+    /**
+     * For the conformance tests: a job a functional spec, as the person asked. Otherwise every functional spec tested is
+     * in one job, as far as the guardrail (`max-lines-per-pulse`) lets.
+     */
+    separately?: boolean;
+    /**
+     * For the conformance tests: the functional specs asked for together, a group a request - `conform` called for 1-3, then
+     * for 4-6. Never two groups in one job; the functional specs in none are tested together, as before.
+     */
+    groups?: string[][];
+    /** How big a pulse may be - the config's `max-specs-per-pulse` and `max-lines-per-pulse`; unset, MAX_SPECS_PER_JOB and MAX_LINES_PER_JOB. */
+    limits?: PulseLimits;
+}
+/** How big a pulse may be: how many functional specs, and how many lines of spec with the definitions they bring. */
+export interface PulseLimits {
+    specs: number;
+    lines: number;
+}
+/** One job of a plan: a title, why, and the changes it makes, by id. */
+export interface DraftJob {
+    title: string;
+    reason: string;
+    changes: string[];
+}
+/** The work the queue does: every change from the base to the spec as it is now, numbered. */
+export declare function netChanges(base: MarshalledPlainSource, current: MarshalledPlainSource): SpecChange[];
+/**
+ * What is wrong with a reworked queue, or nothing: every change in exactly one job, no job without
+ * one, and each job, applied after the ones before it, leaving a spec that holds together - the last
+ * exactly the spec as it is now.
+ */
+export declare function checkDraft(input: PlanInput, draft: DraftJob[]): string[];
+/** A checked draft, as the queue runs it: each job's diff and the spec it leaves. */
+export declare function stepsOf(input: PlanInput, draft: DraftJob[]): Array<DraftJob & {
+    step: SpecStep;
+}>;
+export declare const MAX_SPECS_PER_JOB = 3;
+export declare const MAX_LINES_PER_JOB = 120;
+/**
+ * A functional spec to build, for the grouping: the number the agent answers with, its text, and whether it is built
+ * already and regenerated again. `id` and `module` say which it is: each module numbers its own from 1, and a codebase
+ * regenerates again the functional specs of the modules it is built on too. No module: the codebase's own. No id: the
+ * number.
+ */
+export interface NewSpec {
+    number: number;
+    text: string;
+    again?: boolean;
+    id?: string;
+    module?: string;
+}
+export interface GroupAnswer {
+    groups: Array<{
+        specs: number[];
+        title: string;
+    }>;
+    /** What of the person's wishes it did not follow, and why. */
+    notes?: string;
+}
+export interface PlaceInput {
+    /** How the person or the harness wants the queue planned. */
+    steering?: Steering[];
+    groups: Array<{
+        number: number;
+        title: string;
+        specs: string[];
+        definitions: string[];
+    }>;
+    /** What is built already changes too: a job for that goes first, and a req can go with it. */
+    built: boolean;
+    implementationReqs: Array<{
+        number: number;
+        text: string;
+    }>;
+    testReqs: Array<{
+        number: number;
+        text: string;
+    }>;
+}
+/** Where a req goes: a group's number, "all" - the first job, it is about everything - or "built", with the changes to what is built. */
+export type Target = number | "all" | "built";
+export interface PlaceAnswer {
+    implementationReqs: Array<{
+        req: number;
+        to: Target;
+    }>;
+    testReqs: Array<{
+        req: number;
+        to: Target;
+    }>;
+    /** What of the person's wishes it did not follow, and why. */
+    notes?: string;
+}
+/**
+ * The two judgements, each asked again with what was wrong with its answer - the last answer given, whether it holds
+ * or not: the plan checks it again. Injectable, so the plan is testable without a model.
+ */
+export interface ChunkAgents {
+    group(specs: NewSpec[], check: (answer: GroupAnswer) => string[], steering?: Steering[], maxSpecs?: number): Promise<GroupAnswer | undefined>;
+    place(input: PlaceInput, check: (answer: PlaceAnswer) => string[]): Promise<PlaceAnswer | undefined>;
+}
+/** What is wrong with a grouping: every new functional spec once, in order, next to each other, none too big. */
+export declare function groupProblems(specs: NewSpec[], answer: GroupAnswer, maxSpecs?: number): string[];
+/** What is wrong with a placement: every new req once, each where there is such a job. */
+export declare function placeProblems(input: PlaceInput, answer: PlaceAnswer): string[];
+/**
+ * Cut the queue's work - from `input.base` to `input.current` - into jobs, as the three steps say. Returns the draft
+ * the work loop runs: checked (checkDraft), or, when nothing holds, the whole work as one job. `notes` is given what
+ * the plan did not do as asked - the person's wishes an agent did not follow and why, an answer that did not hold, a
+ * group split for its size - for the conversation to say, rather than guess.
+ */
+export declare function planChunks(input: PlanInput, agents?: ChunkAgents, notes?: string[]): Promise<DraftJob[]>;
+export declare function groupPrompt(specs: NewSpec[], steering?: Steering[], maxSpecs?: number): string;
+export declare function placePrompt(input: PlaceInput): string;
+/** The chunking's two agents, on a model - fresh for every plan. */
+export declare function llmChunkAgents(options: {
+    cwd: string;
+    model?: string;
+    label?: string;
+}): ChunkAgents;

package/dist/regenerate/codebase.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a render agent is told about the code before it starts.
+ *
+ * Every render is a fresh session, and without this each one begins by rediscovering the
+ * codebase - listing directories, grepping for where things are - which on a long module is
+ * the same exploration repeated once per functionality, getting longer as the code does. The
+ * harness already knows the answers, and knows them exactly: the files, which
+ * functionality put which of them there, and the test command that passed. None of it is
+ * the agent's recollection, so none of it can be stale.
+ */
+/** Files by content, so a change is noticed whatever happened to its timestamp. */
+export declare function digestFiles(root: string): Map<string, string>;
+export declare function diffFiles(before: Map<string, string>, after: Map<string, string>): {
+    added: string[];
+    changed: string[];
+    removed: string[];
+};
+/** Whether the work has written nothing in `root` since `atStart` - its working notes and the build record aside. */
+export declare function wroteNothing(root: string, atStart: Map<string, string>): boolean;
+/** The map of the codebase as it stands - or null when there is no code yet. */
+export declare function codebaseMap(buildDir: string): string | null;

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

@@ -0,0 +1,40 @@
+/**
+ * The check every agent command passes before it runs, on every platform.
+ *
+ * A command is one string, and no check of its text can say for certain what it will read or write: a path built at
+ * run time, a script that reads one from a file, gets past any. So this is the first wall of three, not the only one -
+ * the OS sandbox stops what gets past it where the OS has one, and the audit after the command puts back what reached
+ * the project. What it is for is the honest mistake and the plain attempt, caught before anything runs, with a reason
+ * the agent can act on: a path outside its walls, the code record, a credential file written, software installed on
+ * the machine, a process killed that its pulse did not start. Pure: it reads the text and the fence, and runs nothing.
+ */
+export interface CommandFence {
+    /** Where the command starts: the agent's folder. */
+    cwd: string;
+    /** The role's roots it may read. */
+    read: string[];
+    /** The role's roots it may write. */
+    write: string[];
+    /** Its HOME, what `~` and `$HOME` mean. */
+    home?: string;
+    /** Its TMPDIR, what `$TMPDIR` means. */
+    tmp?: string;
+    /** Beside the roots: what its shell may write - the home, the TMPDIR, the package caches. Readable too. */
+    writable?: string[];
+    /** Beside the roots: what of the machine it may read - the system folders, the toolchains. */
+    readable?: string[];
+    /** Whose paths these are: drive letters, backslashes and any case on Windows. */
+    platform?: "posix" | "win32";
+}
+export type CheckRule = "path" | "record" | "credential" | "install" | "kill";
+export type CheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    rule: CheckRule;
+    reason: string;
+};
+/** What of the machine an agent's command may read, beside its roots and its toolchains: the system's own folders. */
+export declare function machineReadable(platform?: NodeJS.Platform): string[];
+/** Check one command line against a role's fence: `{ ok: true }`, or which rule it breaks and what to do instead. */
+export declare function checkCommand(command: string, fence: CommandFence): CheckResult;

package/dist/regenerate/compaction.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What an agent's work is summed up to when its session gets long - one set of instructions per role.
+ *
+ * An agent that keeps its session through a job is compacted between turns once its conversation - what it has
+ * done, not its instructions - passes the project's compact-at (see pi.ts compactIfDue). Its task is its system
+ * prompt and is never summed up, so these say only what of the work the summary must keep for it to go on.
+ */
+/** The coding agent, and the code fixer of a conformance run: what is done, what is not, and why. */
+export declare const CODER_COMPACTION: string;
+/** The conformance agent: the tests written, what they cover, and what is still open. */
+export declare const CONFORMANCE_COMPACTION: string;
+/** A reviewer: what it raised, and where each problem stands. */
+export declare const REVIEWER_COMPACTION: string;

package/dist/regenerate/confine.d.ts

@@ -0,0 +1,62 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type AgentShell } from "./agent-shell.ts";
+import type { BashOperations } from "@earendil-works/pi-coding-agent";
+/**
+ * Keeping a rendering agent inside its own directory.
+ *
+ * pi's `cwd` is where relative paths start from, not a fence: an absolute path resolves to
+ * itself and `bash` can `cd` anywhere. That is fine for an agent working on the repo it was
+ * launched in, and wrong for these - a render agent is building one module and has no
+ * business reading the rest of the project, let alone writing to it.
+ *
+ * So the tools are rebuilt from pi's own factories with a check in front of every path, and
+ * `bash` runs on this machine behind every wall at once (see `agent-shell.ts`): the command check,
+ * the module's own environment, the OS sandbox where one is up, the audit. Both reach the agent's
+ * own folder - its module's `code/`, unless the role is given others - and nothing else: not another
+ * module, not turri's scratch area or the module's lineage, not the specs, not the rest of the project.
+ */
+export interface Confinement {
+    /** Where the agent starts and where relative paths resolve - and, unless `read` and `write` say otherwise, all its file tools reach. */
+    workdir: string;
+    /** The only folders its file tools may read: its workdir when not given. */
+    read?: string[];
+    /** The only folders they may write - its workdir when not given; none, and it has no write or edit tool at all. */
+    write?: string[];
+    /** No shell either - for an agent that only reads. */
+    noBash?: boolean;
+    /**
+     * It may report that the machine lacks what the work needs (report_environment_error) - only the agents that write
+     * and run code: the coding agents and the conformance agent. Observers, explorers and judges never do.
+     */
+    reportsEnvironment?: boolean;
+}
+export declare class ConfinementError extends Error {
+    constructor(message: string);
+}
+export declare function insideAny(path: string, roots: string[]): boolean;
+type AnyTool = ToolDefinition<any, any, any>;
+export interface ConfinedTools {
+    tools: AnyTool[];
+    /** Tool names, for the session's `tools` list. */
+    names: string[];
+    /** One line for the log: what is enforced and how. */
+    description: string;
+    /** The agent's sandbox, as it is told it in its system prompt: what it can reach, and that nothing else exists. */
+    note: string;
+}
+/**
+ * An agent's walls, in words, for its system prompt - from its fence itself, so it says exactly what is enforced, the
+ * same on every platform. An agent that does not know where its walls are spends its turns walking into them. Its own
+ * folders by absolute path and no other; matter-of-fact about what happens on a reach outside - refused, or put back -
+ * and no warning. `environmentTool`: the tool an agent reports a missing piece of the machine with, when it has one.
+ */
+export declare function sandboxNote(fence: {
+    read: string[];
+    write: string[];
+    shell: boolean;
+    environmentTool?: string;
+}): string;
+/** pi's bash tool over an agent's shell: each command checked, run behind its walls, audited. */
+export declare function hostBashOperations(shell: AgentShell): BashOperations;
+export declare function confinedTools(c: Confinement): ConfinedTools;
+export {};

package/dist/regenerate/conform.d.ts

@@ -0,0 +1,63 @@
+import type { JobCases } from "./drift.ts";
+import { type RenderConformanceTestsResult } from "./conformance.ts";
+import { type RegressionResult } from "./regression.ts";
+import { type SpecSnapshot } from "./regenerate.ts";
+import { type SpecGap } from "./notes.ts";
+/**
+ * The conformance tests brought in line with a spec change: a conformance job of the work loop
+ * (docs/regenerating.md).
+ *
+ * Rendering the code and conformance are separate jobs. A spec change is built in the code first
+ * and its tests follow, or it is a change the code does not need at all - test reqs, an acceptance
+ * test - and only the tests follow it. Either way one agent is given the diff and the
+ * spec as it stands, and brings the tests in line: writes, changes and removes them. It can fix
+ * the code where a test shows the code does not do what the spec says, as it can when it writes a
+ * functionality's tests; nothing here renders the change itself.
+ *
+ * Nothing records which changes the tests have followed: the tests carry that themselves, each
+ * labelled with its functionality, and the agent reads them against the whole spec.
+ *
+ * The tests are written in the chain's current codebase - the furthest-built module whose chain
+ * includes the one the change is to - because that is where the code they check lives, and
+ * where they are carried up from as later modules are built. A change to a module low in the
+ * chain is tested in the latest module built on it.
+ */
+export interface RenderSpecDiffConformanceOptions {
+    /** What the job does to each functional spec (work.ts): its agents are told case by case. */
+    cases?: JobCases;
+    /** A .plain file of the module the change is for. */
+    plainFile: string;
+    /** The change, as a git diff of the .plain files. */
+    diff: string;
+    /** That change section by section, as the render that landed it worked it out: shown to the agents in place of the diff. */
+    change?: string;
+    /** Where the diff's paths are relative to. Default: the working directory. */
+    cwd?: string;
+    templateDirs?: string[];
+    /** The codebase to test in, when modules built on this one branch. */
+    inModule?: string;
+    /** The diff was already put in when the job was asked for, and how that went. */
+    applied?: "applied" | "already applied";
+    /** The spec as parsed with the diff in. Taken now, after applying it, when not given. */
+    spec?: SpecSnapshot;
+    model?: string;
+    onDelta?: (delta: string) => void;
+}
+export interface RenderSpecDiffConformanceResult {
+    /** The codebase the tests were written and run in. */
+    moduleName: string;
+    buildDir: string;
+    conformanceDir: string;
+    diff: "applied" | "already applied";
+    conformance: RenderConformanceTestsResult;
+    regression?: RegressionResult;
+    /** The functionalities the codebase has conformance tests for, as their labels say, after the change. */
+    tested: string[];
+    passed: boolean;
+    stoppedAt: "conformance" | "regression" | null;
+    /** Spec gaps its agents reported: what the spec should say and does not, for the person to decide. */
+    specGaps?: SpecGap[];
+}
+export declare function renderSpecDiffConformance(options: RenderSpecDiffConformanceOptions): Promise<RenderSpecDiffConformanceResult>;
+/** What the conformance for a spec change did, for the agent and the person. */
+export declare function describeSpecDiffConformance(result: RenderSpecDiffConformanceResult): string;