@turri-dev/cli 0.1.27 → 0.2.0

package/dist/regenerate/activity.d.ts

@@ -44,10 +44,16 @@ export interface ActivitySink {
     /** The functional spec being built now, or nothing when none is. */
     spec?(spec: BuildingSpec | undefined): void;
 }
-/** A functional spec as it is being built: where it sits, and its text as the spec has it. */
+/** A functional spec as it is being built: which it is, where it sits, and its text as the spec has it. */
 export interface BuildingSpec {
-    /** E.g. "rt_tuples functionality 2 of 5". */
+    /** The functional spec, as data: for a host to light it without reading the label. */
+    spec: {
+        module: string;
+        funcId: string;
+    };
+    /** For a person: "core:add-task, functional spec of 3". */
     label: string;
+    /** Its text, with its scenarios after it. */
     text: string;
     /**
      * When work on it began - set by the job, and kept while the same one goes on to its next stage
@@ -66,12 +72,12 @@ export interface SpecConflict {
     moduleName: string;
     plainFile: string;
     /**
-     * The two functionalities - in that module, or in one it requires - each with its module, its
-     * id there, the .plain file it is in, and its functional spec as that file has it.
+     * The two functional specs - in that module, or in one it requires - each with its module, its
+     * func-id there, the .plain file it is in, and its functional spec as that file has it.
      */
     specs: Array<{
         module: string;
-        frid: string;
+        funcId: string;
         plainFile: string;
         text: string;
     }>;
@@ -134,10 +140,10 @@ export interface UsageReport {
     cost: number;
 }
 /**
- * What a stage is about, said so the person knows what the name is: "module backend", or "module
- * backend, functionality 2". A stage leads with it: `${unitOf(moduleName, frid)}: running the tests`.
+ * What a stage is about, said so the person knows what the name is: "module backend", or "functional spec
+ * backend:add-task". A stage leads with it: `${unitOf(moduleName, funcId)}: running the tests`.
  */
-export declare function unitOf(moduleName: string, frid?: string): string;
+export declare function unitOf(moduleName: string, funcId?: string): string;
 export declare function reportUsage(usage: UsageReport): void;
 /** What one agent of a job did, added to what it did before: counted by its label. */
 export interface AgentReport {
@@ -163,7 +169,7 @@ export declare function describeAgents(tallies: AgentTally[]): string[];
 /** "1.2k tok · $0.03", or "" when nothing has been spent yet. */
 export declare function describeUsage(usage: UsageReport | undefined): string;
 /**
- * Something an agent did with its model, wherever it ran - in a pulse or not, the planner and the chooser too: what a
+ * Something an agent did with its model, wherever it ran - in a pulse or not, the planner too: what a
  * headless run's report adds up (run-report.ts). A call is one model response; a turn, one request of the harness's
  * to an agent, as many calls as it takes; a compaction, its work summed up - a call of its own. A provider retry is a
  * request the provider failed for a moment, waited out and tried again - by pi, or by turri after pi gave up; a provider
@@ -199,6 +205,11 @@ export declare function onModelEvent(listener: (event: ModelEvent) => void): ()
 export declare function describeTurnIncident(event: ModelEvent): string | undefined;
 export declare function reportModelEvent(event: Omit<ModelEvent, "job">): void;
 export declare function withActivity<T>(sink: ActivitySink, run: () => Promise<T>): Promise<T>;
+/**
+ * Run work for no job, whatever job the code that starts it runs for - and clear of any stop signal: the test
+ * advisor's, started as the loop looks at a codebase, perhaps as a pulse ends. A pulse's panel, log and stop never reach it.
+ */
+export declare function outsideJobs<T>(run: () => T): T;
 export declare function reportStage(label: string): void;
 export declare function reportActivity(line: string): void;
 /** Say something about the machinery under the work: shown as activity, and kept in the job's log, which the activity is not. */

package/dist/regenerate/activity.js

@@ -58,11 +58,11 @@ export function reportTranscript(entry) {
     store.getStore()?.transcript(entry);
 }
 /**
- * What a stage is about, said so the person knows what the name is: "module backend", or "module
- * backend, functionality 2". A stage leads with it: `${unitOf(moduleName, frid)}: running the tests`.
+ * What a stage is about, said so the person knows what the name is: "module backend", or "functional spec
+ * backend:add-task". A stage leads with it: `${unitOf(moduleName, funcId)}: running the tests`.
  */
-export function unitOf(moduleName, frid) {
-    return frid === undefined ? `module ${moduleName}` : `module ${moduleName}, functionality ${frid}`;
+export function unitOf(moduleName, funcId) {
+    return funcId === undefined ? `module ${moduleName}` : `functional spec ${moduleName}:${funcId}`;
 }
 export function reportUsage(usage) {
     store.getStore()?.usage(usage);
@@ -159,6 +159,13 @@ export function reportModelEvent(event) {
 export function withActivity(sink, run) {
     return store.run(sink, run);
 }
+/**
+ * Run work for no job, whatever job the code that starts it runs for - and clear of any stop signal: the test
+ * advisor's, started as the loop looks at a codebase, perhaps as a pulse ends. A pulse's panel, log and stop never reach it.
+ */
+export function outsideJobs(run) {
+    return store.exit(() => stops.exit(run));
+}
 export function reportStage(label) {
     store.getStore()?.stage(label);
 }

package/dist/regenerate/advisor-records.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The test advisor's file: `.turri/advisor/<module>.json` in the project - what it made of each functional spec of the
+ * module it looked at, by func-id, keyed by a hash of its text (docs/test-advisor.md). Local to this machine: `.turri`
+ * ignores itself, so it is never committed - another machine starts with none, and classifies only what changes there.
+ *
+ * An entry is current while its hash is the functional spec's text's: a text that changes makes it stale, and the
+ * functional spec is looked at again. `pending` is written the moment the advisor sees a functional spec, so quitting
+ * loses nothing: the next start in the chat or a host picks it up.
+ */
+export declare const ADVISOR_DIR = "advisor";
+/** The four questions, each a yes or a no: could it fail silently, be read two ways, be built on later, cost much when wrong. */
+export declare const ADVISOR_QUESTIONS: readonly ["silent-failure", "divergence", "revisited", "cost"];
+export type AdvisorQuestion = (typeof ADVISOR_QUESTIONS)[number];
+/** A question that was a yes, with its evidence in a line: the wrong output, the input read two ways, what would change, the consequence. */
+export interface AdvisorAnswer {
+    question: AdvisorQuestion;
+    evidence: string;
+}
+/** An input to cover: one the readers agreed on, with its output, or one they split on, with each reading the verifier kept. */
+export type AdvisorInput = {
+    input: string;
+    agreed: string;
+} | {
+    input: string;
+    readings: string[];
+};
+/** What the advisor made of a functional spec: its verdict, the questions that were a yes, and on a yes the inputs to cover. */
+export interface AdvisorReport {
+    verdict: "yes" | "no";
+    questions: AdvisorAnswer[];
+    inputs: AdvisorInput[];
+}
+/** Where an entry is: seen and not finished, classified yes or no, or failed - tried again only once its text changes. */
+export type AdvisorState = "pending" | "yes" | "no" | "failed";
+export interface AdvisorEntry {
+    funcId: string;
+    /** The hash of the functional spec's text the entry is about (textHash). */
+    hash: string;
+    state: AdvisorState;
+    report?: AdvisorReport;
+    /** The model the advisor ran on. */
+    model?: string;
+    /** When the entry was last written, ISO. */
+    at: string;
+    /** Why it failed, for a failed one. */
+    reason?: string;
+    /** The tip's .plain file, from the project: where the chain's scenarios are tested. */
+    tip?: string;
+    /** A yes not yet handed to a chat: delivered at the next start, as `pending` work is picked up. */
+    undelivered?: boolean;
+    /** Pending at the chat's asking (evaluate_tests), with why: picked up at the next start whatever `test-advisor` says. */
+    asked?: {
+        reason?: string;
+    };
+}
+export interface AdvisorFile {
+    module: string;
+    /** The module's .plain file, from the project. */
+    plainFile: string;
+    entries: Record<string, AdvisorEntry>;
+}
+/** The hash a functional spec's text is known by: its text, trimmed. */
+export declare function textHash(text: string): string;
+/** The folder of a project's advisor files. */
+export declare function advisorDir(project: string): string;
+/** A module's advisor file. */
+export declare function advisorPath(project: string, module: string): string;
+/** A module's advisor file, or nothing when there is none or it does not read. */
+export declare function readAdvisor(project: string, module: string): AdvisorFile | undefined;
+/** A functional spec's entry, or nothing. */
+export declare function advisorEntry(project: string, module: string, funcId: string): AdvisorEntry | undefined;
+/** Whether an entry is about the text as it is now: one that is not, or none, is stale, and the functional spec is looked at again. */
+export declare function isCurrent(entry: AdvisorEntry | undefined, hash: string): entry is AdvisorEntry;
+/** Write a functional spec's entry, in place of the one it had. `plainFile` is the module's, from the project. */
+export declare function putAdvisorEntry(project: string, module: string, plainFile: string, entry: Omit<AdvisorEntry, "at"> & {
+    at?: string;
+}): AdvisorEntry;
+/** Take a functional spec's entry out - its functional spec is gone. */
+export declare function removeAdvisorEntry(project: string, module: string, funcId: string): void;
+/** Every pending entry of a project's advisor files, with the module and its .plain file - what a start picks up. */
+export declare function pendingEntries(project: string): Array<{
+    module: string;
+    plainFile: string;
+    entry: AdvisorEntry;
+}>;
+/** Every yes of a project's advisor files not yet handed to a chat - what a start delivers. */
+export declare function undeliveredEntries(project: string): Array<{
+    module: string;
+    plainFile: string;
+    entry: AdvisorEntry;
+}>;
+/** A yes handed to a chat: the entry for that text no longer kept for the next start. */
+export declare function markDelivered(project: string, module: string, funcId: string, hash: string): void;

package/dist/regenerate/advisor-records.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ensureInScratch } from "./paths.js";
+/**
+ * The test advisor's file: `.turri/advisor/<module>.json` in the project - what it made of each functional spec of the
+ * module it looked at, by func-id, keyed by a hash of its text (docs/test-advisor.md). Local to this machine: `.turri`
+ * ignores itself, so it is never committed - another machine starts with none, and classifies only what changes there.
+ *
+ * An entry is current while its hash is the functional spec's text's: a text that changes makes it stale, and the
+ * functional spec is looked at again. `pending` is written the moment the advisor sees a functional spec, so quitting
+ * loses nothing: the next start in the chat or a host picks it up.
+ */
+export const ADVISOR_DIR = "advisor";
+/** The four questions, each a yes or a no: could it fail silently, be read two ways, be built on later, cost much when wrong. */
+export const ADVISOR_QUESTIONS = ["silent-failure", "divergence", "revisited", "cost"];
+/** The hash a functional spec's text is known by: its text, trimmed. */
+export function textHash(text) {
+    return createHash("sha256").update(text.trim()).digest("hex").slice(0, 16);
+}
+/** The folder of a project's advisor files. */
+export function advisorDir(project) {
+    return join(resolve(project), ".turri", ADVISOR_DIR);
+}
+/** A module's advisor file. */
+export function advisorPath(project, module) {
+    return join(advisorDir(project), `${module}.json`);
+}
+/** A module's advisor file, or nothing when there is none or it does not read. */
+export function readAdvisor(project, module) {
+    try {
+        const parsed = JSON.parse(readFileSync(advisorPath(project, module), "utf8"));
+        return parsed !== null && typeof parsed === "object" && typeof parsed.entries === "object" && parsed.entries !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A functional spec's entry, or nothing. */
+export function advisorEntry(project, module, funcId) {
+    return readAdvisor(project, module)?.entries[funcId];
+}
+/** Whether an entry is about the text as it is now: one that is not, or none, is stale, and the functional spec is looked at again. */
+export function isCurrent(entry, hash) {
+    return entry !== undefined && entry.hash === hash;
+}
+/** Write a functional spec's entry, in place of the one it had. `plainFile` is the module's, from the project. */
+export function putAdvisorEntry(project, module, plainFile, entry) {
+    const file = readAdvisor(project, module) ?? { module, plainFile, entries: {} };
+    const written = { ...entry, at: entry.at ?? new Date().toISOString() };
+    file.plainFile = plainFile;
+    file.entries[entry.funcId] = written;
+    writeAdvisor(project, file);
+    return written;
+}
+/** Take a functional spec's entry out - its functional spec is gone. */
+export function removeAdvisorEntry(project, module, funcId) {
+    const file = readAdvisor(project, module);
+    if (file === undefined || file.entries[funcId] === undefined)
+        return;
+    delete file.entries[funcId];
+    writeAdvisor(project, file);
+}
+function writeAdvisor(project, file) {
+    const scratch = join(resolve(project), ".turri");
+    ensureInScratch(scratch, advisorDir(project));
+    const path = advisorPath(project, file.module);
+    // Written whole, then moved in place: a turri killed part-way never leaves half a file.
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(file, null, 2)}\n`);
+    renameSync(temporary, path);
+}
+/** Every pending entry of a project's advisor files, with the module and its .plain file - what a start picks up. */
+export function pendingEntries(project) {
+    return entriesWhere(project, (entry) => entry.state === "pending");
+}
+/** Every yes of a project's advisor files not yet handed to a chat - what a start delivers. */
+export function undeliveredEntries(project) {
+    return entriesWhere(project, (entry) => entry.state === "yes" && entry.undelivered === true);
+}
+/** A yes handed to a chat: the entry for that text no longer kept for the next start. */
+export function markDelivered(project, module, funcId, hash) {
+    const file = readAdvisor(project, module);
+    const entry = file?.entries[funcId];
+    if (file === undefined || entry === undefined || entry.hash !== hash || entry.undelivered !== true)
+        return;
+    const { undelivered: _delivered, ...rest } = entry;
+    file.entries[funcId] = rest;
+    writeAdvisor(project, file);
+}
+function entriesWhere(project, wanted) {
+    const dir = advisorDir(project);
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir).filter((name) => name.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    return names.flatMap((name) => {
+        const file = readAdvisor(project, name.slice(0, -".json".length));
+        if (file === undefined)
+            return [];
+        return Object.values(file.entries)
+            .filter(wanted)
+            .map((entry) => ({ module: file.module, plainFile: file.plainFile, entry }));
+    });
+}

package/dist/regenerate/advisor-runs.d.ts

@@ -0,0 +1,87 @@
+import { type AdvisorReport } from "./advisor-records.ts";
+import type { SeenSpec } from "./loop.ts";
+import { type AdvisorCallOptions, type AdvisorSubject } from "./test-advisor.ts";
+/**
+ * When the test advisor runs, and on what (docs/test-advisor.md). It watches what the work loop looks at - every
+ * ***plain change the loop sees, as it sees it - and takes each functional spec that is new or whose text changed since
+ * its code was built (its code record), has no scenarios, and has no entry in the advisor's file for that text. A
+ * project already built, with no advisor file, is looked at not at all: only what changes from now on is.
+ *
+ * Each is marked `pending` in the advisor's file then and there, and judged in the background - two at a time at most,
+ * outside `parallel-jobs` and the lanes: no pulse waits for it, and it never steers or stops one. Its work is clear of
+ * any pulse: no panel, no log, no stop of a pulse's reaches it. A functional spec whose text changes while it is judged
+ * has that work thrown away - whoever changed it - and the new text starts again. What `pending` is left as turri quits,
+ * the next start in the chat or a host picks up.
+ *
+ * The advisor decides and writes nothing in the ***plain: what it made of a functional spec is kept in its file and
+ * handed on (`onVerdict`) to the chat the person looks at, which writes the scenarios on a yes. A yes not yet handed to a
+ * chat stays marked undelivered, and is handed on again at the next start.
+ *
+ * It is made only where the session starts in the chat or a host (extension.ts) - never for a headless command, nor
+ * pi's print, json and rpc modes - and does nothing in a project whose `test-advisor:` is false.
+ */
+/** How many functional specs the advisor works on at once. */
+export declare const ADVISOR_PARALLEL = 2;
+/** A finished verdict, handed on to the chat: the functional spec, what was made of it, and where its scenarios go. */
+export interface AdvisorVerdict {
+    project: string;
+    module: string;
+    funcId: string;
+    /** The module's .plain file. */
+    plainFile: string;
+    /** The tip's .plain file: where the chain's scenarios are tested, and its test reqs and conformance testing script are. */
+    tip: string;
+    /** The test plain file its scenarios go in, from the project: `<test-dir>/<module>/<func-id>.plain`. */
+    testFile: string;
+    /** The hash of the text it judged. */
+    hash: string;
+    report: AdvisorReport;
+    /** Whether it is still about the functional spec as it is now: its text the same, and still with no scenarios. */
+    current(): boolean;
+    /** Handed to a chat: no longer kept for the next start. */
+    delivered(): void;
+}
+export interface TestAdvisorOptions {
+    /** Whether a project wants the advisor now. Default: its `test-advisor:` is not false. */
+    enabled?: (project: string) => boolean;
+    /** The judgement of a functional spec. Default: the model calls of test-advisor.ts. */
+    advise?: (subject: AdvisorSubject, options: AdvisorCallOptions) => Promise<AdvisorReport>;
+    /** The conversation's own words on what matters for a module - its steering. */
+    context?: (plainFile: string) => string[];
+    /** A verdict finished - or a yes left undelivered, at the next start: for the chat the person looks at. Not given: only kept. */
+    onVerdict?: (verdict: AdvisorVerdict) => void;
+    /** How many functional specs at once. Default: ADVISOR_PARALLEL. */
+    parallel?: number;
+}
+export interface TestAdvisor {
+    /** What the loop looked at: the functional specs to take, and the work whose text changed under it to drop. */
+    seen(look: SeenSpec): void;
+    /** Pick up what a project's advisor file has pending - the work turri quit in the middle of - and hand on its undelivered yeses. */
+    resume(project: string): void;
+    /** Resolves once nothing is queued or running. */
+    idle(): Promise<void>;
+    /** Stop everything, leaving what was running pending. */
+    stop(): void;
+    /** The functional specs it is judging for now, or about to - `module:func-id`, a project's alone when named. */
+    taking(project?: string): string[];
+    /**
+     * The chat's own way in (evaluate_tests): a functional spec evaluated now - even a text already judged, and whatever
+     * `test-advisor` says - its verdict handed on as any is. `already`: it is being evaluated now; `scenarios`: it has some,
+     * and is not evaluated; `missing`: its module has no such functional spec.
+     */
+    evaluate(asked: EvaluateRequest): "started" | "already" | "scenarios" | "missing";
+}
+/** A functional spec the chat asks the advisor to evaluate. */
+export interface EvaluateRequest {
+    module: string;
+    funcId: string;
+    /** The module's .plain file. */
+    plainFile: string;
+    /** The tip its scenarios are tested in. Default: the one the advisor last knew, else the module at the top of a chain it is in, else itself. */
+    tip?: string;
+    /** Why the chat asks - "the coding agent failed three times to implement it" - for the classifier, as context. */
+    reason?: string;
+}
+/** Whether a functional spec has scenarios of any kind: then it is tested as the person wants, and today's review covers it. */
+export declare function hasScenarios(item: unknown): boolean;
+export declare function createTestAdvisor(options?: TestAdvisorOptions): TestAdvisor;