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

package/dist/pi.d.ts

@@ -0,0 +1,246 @@
+import { AgentSession, DefaultResourceLoader, ModelRegistry, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type AgentRole } from "./config.ts";
+type ThinkingLevel = Parameters<AgentSession["setThinkingLevel"]>[0];
+/**
+ * Where sub-agents take their thinking level from: the conversation that started them.
+ *
+ * The model is inherited explicitly, by name, all the way down. The thinking level is just
+ * as much a choice the person made - and left alone pi falls back to its own default, so a
+ * conversation turned down for speed would hand every render agent a slower one. Read at
+ * the moment each session starts, so a change mid-conversation applies to the next agent.
+ */
+export declare function inheritThinkingLevel(source: () => ThinkingLevel | undefined): void;
+/**
+ * How hard an agent thinks: the level the config or the model it is given names; else its role's (ROLE_THINKING) - the
+ * work thinks little, the judgement more; else the conversation's, for an agent with no role.
+ */
+export declare function agentThinking(named: ThinkingLevel | undefined, role: AgentRole | undefined, conversation: () => ThinkingLevel | undefined): ThinkingLevel | undefined;
+/**
+ * Where sub-agents take the providers pi's extensions registered from: the conversation that started them.
+ *
+ * A sub-agent is started without extensions (see subAgentResources), so its models are only what pi's own
+ * configuration has - models.json and auth.json. A provider an extension registers - a company's own LLM
+ * gateway, say - is in the conversation's model registry and nowhere else: the conversation could use its
+ * models and a render or skill agent told to use them could not find them. So every sub-agent's model
+ * runtime is given the providers the conversation's registry holds when the agent starts - the provider,
+ * not the extension that registered it.
+ */
+export declare function inheritProviders(source: () => ModelRegistry | undefined): void;
+/**
+ * What a sub-agent session is made of: pi's resources without any extensions.
+ *
+ * Left to itself, pi builds every session from the user's configuration - including every
+ * installed extension. When turri is installed globally, that means each render agent,
+ * judge and skill executor loads a whole second copy of turri inside itself: its
+ * tools, its hooks, its job registry, all bound to a session that is thrown away minutes
+ * later. That copy then outlives its session in module state and breaks the next one. A
+ * sub-agent is given exactly what it needs instead; for agents that work on specs, that
+ * includes the ***plain rules, which otherwise only reached them through that stray copy.
+ *
+ * Nor any context file. pi puts every AGENTS.md / CLAUDE.md from the agent's folder up - the
+ * project's, the user's ~/.pi/agent one - into its system prompt; a rendering agent works in
+ * plain_modules/<module>/code, so it would be given whatever the project says about itself. An
+ * agent turri starts sees only what turri gives it. The conversation still loads
+ * them, as pi does.
+ *
+ * Nor any of pi's skills. pi lists every skill it finds - the user's, the project's - in the system prompt, for the
+ * agent to load when one fits; an agent turri starts has one job, and turri runs its gated skills itself,
+ * giving each step to an agent as its task. The conversation keeps them.
+ */
+export declare function subAgentResources(cwd: string, withRules: boolean, system?: string): Promise<DefaultResourceLoader>;
+/** Raised when the provider itself failed, rather than the agent producing a poor answer. */
+export declare class ProviderError extends Error {
+    constructor(message: string);
+}
+/**
+ * End the agent's turn, turri's own doing - it is going round in a circle, its time is up. The turn ends as any turn
+ * does: what the agent said stands, and the harness goes on from there. Never a provider error.
+ */
+export declare function stopTurn(session: AgentSession | undefined, reason: string): void;
+/** A turn with one thing left to do: every tool but these is refused, the tools the session has left as they are. */
+export interface TurnOptions {
+    onlyTools?: string[];
+}
+/** How many calls a restricted turn may have refused before it is stopped. */
+export declare const REFUSED_BEFORE_STOP = 3;
+/**
+ * `run`, with every tool of the session but `names` refused (guardRepeats refuses them) until it ends. The tools
+ * themselves are left as they are, so the tools the model is sent - and its prompt cache - stay the same.
+ */
+export declare function withOnlyTools<T>(session: AgentSession, names: string[], run: () => Promise<T>): Promise<T>;
+export declare function ask(session: AgentSession, text: string, onDelta?: (delta: string) => void, turn?: TurnOptions): Promise<string>;
+/**
+ * How many times, after pi's own retries, a turn whose provider failed for a moment is tried again; the first wait,
+ * doubled each time up to the longest - 15s, 30s, 1m, 2m, 4m, 5m: an outage of about 13 minutes is waited out.
+ */
+export declare const PROVIDER_RETRIES = 6;
+export declare const PROVIDER_RETRY_DELAY_MS: number;
+export declare const PROVIDER_RETRY_MAX_DELAY_MS: number;
+/** The wait before try `attempt + 1`: doubled each time, up to the longest, with a tenth either way so parallel jobs do not all come back at once. */
+export declare function providerRetryDelay(attempt: number, random?: () => number): number;
+/** How long a request to the model may go without anything coming back before the provider is said to be stalling; 0 never. */
+export declare const PROVIDER_STALL_MS: number;
+/**
+ * How long one turn of an agent a render starts may take: past it, the turn ends where it is and
+ * the harness goes on as after any turn - it runs the tests, and judges. The config's `turn-limit:`
+ * sets it, in seconds, and each role's in `models:`; 0 turns it off.
+ */
+export declare const DEFAULT_TURN_LIMIT_MS: number;
+/** How long past the turn limit what is running then - the model answering, a tool - may take to finish. */
+export declare const TURN_GRACE_MS: number;
+/** An image an agent is sent with a message. */
+export interface AgentImage {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+/**
+ * Refuses, before any agent of a job starts, a named model that reads no images when the job's spec links some -
+ * rather than once the work is under way. Unnamed, the model is pi's default: `createExecutor` refuses it then.
+ */
+export declare function refuseIfModelIsBlind(modelSpec: string | undefined, count: number): Promise<void>;
+/** A model that cannot read images, given images to read. */
+export declare class ModelCannotReadImagesError extends Error {
+}
+/**
+ * Stops an agent whose model reads no images being given some: it would work blind from the spec's images. Says
+ * which model, and what to do - a coding model that reads images, or the images described in text instead.
+ */
+export declare function refuseIfBlind(model: {
+    provider: string;
+    id: string;
+    input?: readonly string[];
+} | undefined, count: number): void;
+/**
+ * What an agent opens with when its task is in its instructions. The task - the spec, how to read it, what to do
+ * and the rules - is its system prompt, not its first message: compaction sums up the conversation and never the
+ * system prompt, so what the agent works from stays word for word as it was, however long the work runs, and stays
+ * in the cached prefix of every call.
+ */
+export declare const BEGIN = "Begin. Your task is in your instructions.";
+/** How a session's work is summed up when it gets larger than the threshold: what the summary has to keep, for its role. */
+export interface Compaction {
+    instructions: string;
+    /** Tokens of conversation - past the system prompt - past which it is compacted. Default: the project's compact-at, else DEFAULT_COMPACT_AT. */
+    atTokens?: number;
+}
+/** Tokens of conversation past which a session that keeps working is compacted, when the project does not say. */
+export declare const DEFAULT_COMPACT_AT = 100000;
+/** Have a session compacted between turns, as `compaction` says: what createExecutor does for an agent given one. */
+export declare function keepCompacted(session: object, compaction: Required<Compaction>): void;
+/**
+ * Compact a session's work when its conversation - what it has done, not its instructions - has got larger than its
+ * threshold. An agent that keeps its session through a job re-reads everything it did on every call: this keeps
+ * that bounded, as pi's own compaction does only when the context window is nearly full. The summary keeps what
+ * its role needs; its instructions are untouched. A compaction that fails leaves the session as it was.
+ */
+export declare function compactIfDue(session: AgentSession): Promise<boolean>;
+/**
+ * Have this session's turns timed, as an agent a render starts has: `limitMs` each - its role's in the config - or
+ * the default.
+ */
+export declare function timeTurns(session: object, limitMs?: number): void;
+/** How many calls to one tool may fail in a row, nothing going through, before the agent's turn is stopped. */
+export declare const FAILURES_BEFORE_STOP = 10;
+/** How many times running the very same tool call is let through before it is refused, and before the turn is stopped. */
+export declare const REPEATS_ALLOWED = 3;
+export declare const REPEATS_BEFORE_STOP = 6;
+/** JSON with every object's keys in order, so two ways of writing the same arguments read the same. */
+export declare function canonicalJson(value: unknown): string;
+/** How many tool calls an agent that has one thing to decide may make before it is told to decide. */
+export interface CallBudget {
+    calls: number;
+    /** The tools that hand over the decision - still let through past the budget. */
+    finish: string[];
+}
+/**
+ * Tools that notice an agent going round in a circle. The same call again and again with nothing in
+ * between; or a look - read, grep, find, ls - made again with nothing changed since, however many
+ * other looks came between: the same answer comes back. The first few go through; after that the
+ * call is refused with what is happening, and if the agent carries on regardless its turn is
+ * stopped - the harness goes on from there, as after any turn.
+ *
+ * With a budget, an agent that has one thing to decide - a verdict, a review, an account - is told
+ * to decide once it has made that many calls: every tool but the one that hands it over refuses,
+ * and past twice the budget its turn is stopped. Handing it over starts the count again, and forgets
+ * the looks: a reviewer kept for the next review reads the files as they are by then.
+ */
+export declare function guardRepeats(tools: ToolDefinition[], session: () => AgentSession | undefined, budget?: CallBudget): ToolDefinition[];
+/**
+ * The executor. One session for the whole skill run, so a retry after a failed
+ * gate arrives as a follow-up turn with the critique in it rather than as a cold
+ * start that has forgotten what it just wrote.
+ */
+export declare function createExecutor(opts: {
+    cwd: string;
+    customTools: ToolDefinition[];
+    tools: string[];
+    /**
+     * "provider/model-id", with ":level" for how hard it thinks ("google/gemini-3.1-pro:high"), or
+     * ":level" alone for pi's default model. Omitted: whatever pi is configured to use.
+     */
+    model?: string;
+    /** Give it the ***plain rules - for agents that write or edit specs, not code. */
+    rules?: boolean;
+    /** Continue the session saved in this file, instead of starting a new one. */
+    resumeFrom?: string;
+    /** Added to its system prompt: its sandbox, above all - what it can reach (see confine.ts sandboxNote). */
+    system?: string;
+    /**
+     * Its task - everything its first prompt used to say: the spec, how to read it, what to do, the rules. It goes
+     * into its system prompt, after `system`, so compaction never sums it up; open the session with BEGIN.
+     */
+    task?: string;
+    /** Given, the session keeps working through a job and is compacted between turns once its work gets larger than the threshold. */
+    compaction?: Compaction;
+    /**
+     * What the agent is, e.g. "app 3 coding agent". Given, the agent is one a render started: its
+     * whole conversation is streamed to a log named after it (see debug-log.ts).
+     */
+    label?: string;
+    /** For an agent with one thing to decide: how many tool calls it has, and the tools that hand the decision over. */
+    budget?: CallBudget;
+    /**
+     * Images its task refers to - the spec's linked images. Sent with its first message, and again after each
+     * compaction, which sums them up with the rest. A model that cannot read images is refused, before any work.
+     */
+    images?: AgentImage[];
+    /**
+     * For an agent that writes and runs code: the harness's own run of the testing script, which an environment report it
+     * makes is checked against before the pulse stops (checkAgainstScript). Only an agent given it has
+     * report_environment_error at all.
+     */
+    checkEnvironment?: {
+        run: () => Promise<{
+            exitCode: number;
+            output: string;
+        }>;
+        script: string;
+    };
+    /**
+     * What the agent does: its role's model, thinking and turn limit in the config (`models:`) apply - the model over
+     * `model`, unless the config names none for the role.
+     */
+    role?: AgentRole;
+}): Promise<AgentSession>;
+/** A provider request with its thinking level sent as reasoning effort, where the model takes one turri sends itself. */
+export declare function withReasoningEffort(payload: unknown, model: unknown, thinkingLevel: string | undefined): unknown;
+/**
+ * A judge. Fresh session, one tool, and - deliberately - no access to the
+ * executor's transcript. A judge that inherits the actor's reasoning inherits
+ * its rationalisations, so it gets the artifact and the rubric, nothing else.
+ */
+export declare function createJudge(opts: {
+    cwd: string;
+    verdictTool: ToolDefinition;
+    modelSpec?: string;
+    borrowAuthFrom: AgentSession;
+    /** Read-only tools the rubric needs. Empty keeps the judge unable to touch anything. */
+    extraTools?: string[];
+    /** What it judges and by which rubric: its instructions, as an executor's task is. Open the session with BEGIN. */
+    task?: string;
+}): Promise<{
+    session: AgentSession;
+    modelNote: string;
+}>;
+export {};

package/dist/picture-row.d.ts

@@ -0,0 +1,10 @@
+/** What the banner puts between a row's text and the picture after it: back to the jellyfish's column, a column in from the screen's padding. */
+export declare const PICTURE_AT: string;
+/**
+ * The banner's picture row with an overlay drawn over its text, the picture after it - left out while the overlay
+ * reaches over the picture, `pictureRight` columns from the left edge. Undefined for a row that holds no picture.
+ *
+ * What follows the picture - the padding a row narrower than the screen is given, the chat's beside the docked panel -
+ * is the row's text: written after the picture, from the picture's column, it would blank the row.
+ */
+export declare function overPictureRow(base: string, overlay: string, col: number, width: number, total: number, pictureRight: number): string | undefined;

package/dist/plain/check.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Static validation of a .plain file, using this repo's own parser.
+ *
+ * This is the check that used to mean running the renderer with `--dry-run`: it parses the
+ * specification, resolves its imports and required modules, and reports every error the
+ * parser can see without generating anything. Nothing is rendered and nothing is spent.
+ */
+export interface CheckResult {
+    file: string;
+    ok: boolean;
+    moduleName?: string;
+    frids?: string[];
+    requiredModules?: string[];
+    /** The parser's own message, verbatim - it names the line and the construct. */
+    error?: string;
+    errorType?: string;
+}
+export declare function checkPlainFile(file: string, templateDirs?: string[]): CheckResult;
+/** Every `.plain` file directly in a directory, or the single file given. */
+export declare function resolvePlainTargets(target: string): string[];
+export declare function checkPlainTargets(target: string, templateDirs?: string[]): CheckResult[];
+/** One line per file, plus the parser's message under any that failed. */
+export declare function formatCheckResults(results: CheckResult[]): string;

package/dist/plain/concepts.d.ts

@@ -0,0 +1,11 @@
+import { type AnyNode, type Section } from "./markdown.ts";
+import { type MarshalledPlainSource, type SpecificationItem } from "./spec.ts";
+/** Port of concept_utils.py. */
+/** Reserved concept names that must not be redefined in the definitions section. */
+export declare const DEFAULT_CONCEPTS: Set<string>;
+export declare function extractConceptsFromDefinition(text: string): [string[], string[]];
+export declare function extractConceptsFromSpecText(text: string): string[];
+export declare function collectConcepts(plainSource: MarshalledPlainSource): [string[], string[]];
+export declare function validateConcepts(marshalled: MarshalledPlainSource): string[];
+export declare function findConceptDefinitionsInPlainSource(concept: string, definitions: Section | null): AnyNode[];
+export declare function sortDefinitions(definitions: SpecificationItem[]): void;

package/dist/plain/errors.d.ts

@@ -0,0 +1,22 @@
+/** Ports of the exception classes of the Python reference implementation that this parser raises. */
+export declare class PlainSyntaxError extends Error {
+    constructor(message: string);
+}
+export declare class UnsupportedBase64Content extends Error {
+    constructor(message: string);
+}
+export declare class ModuleDoesNotExistError extends Error {
+    constructor(message: string);
+}
+export declare class MissingFunctionalitiesError extends Error {
+    constructor(message: string);
+}
+export declare class ImportedModuleWithFunctionalitiesError extends Error {
+    constructor(message: string);
+}
+export declare class InvalidFridArgument extends Error {
+    constructor(message: string);
+}
+export declare class InvalidLiquidVariableName extends Error {
+    constructor(message: string);
+}

package/dist/plain/files.d.ts

@@ -0,0 +1,12 @@
+/** Ports of the Python reference implementation's file helpers this parser needs. */
+export declare function openFrom(dirs: string[], fileName: string): string | null;
+/** First contiguous base64 blob at or above the threshold, or null. */
+export declare function findLargeBase64Blob(text: string): string | null;
+/**
+ * Render once against the filesystem to discover which templates the source pulls in.
+ *
+ * The rendered text is discarded by the caller; what matters is the map of template
+ * name to raw source, which is what the second (real) render is given so that it does
+ * not touch the filesystem again.
+ */
+export declare function getLoadedTemplates(templateDirs: string[], plainSource: string): [string, Record<string, string>];

package/dist/plain/highlight.d.ts

@@ -0,0 +1,42 @@
+/** A rule, read: its expression compiled, its includes followed. */
+type Rule = {
+    kind: "match";
+    name?: string;
+    re: RegExp;
+    captures?: Record<string, string | undefined>;
+} | {
+    kind: "block";
+    name?: string;
+    begin: RegExp;
+    end: RegExp;
+    patterns: Rule[];
+    beginCaptures?: Record<string, string | undefined>;
+    endCaptures?: Record<string, string | undefined>;
+};
+/** A piece of a line, and the scopes it is in, outermost first. */
+export interface Token {
+    text: string;
+    scopes: string[];
+}
+/** Where the lines so far leave off: the blocks open at the end of the last one. */
+export type HighlightState = ReadonlyArray<Extract<Rule, {
+    kind: "block";
+}>>;
+/**
+ * One line of ***plain, highlighted: its tokens, and the state the next line starts from - the blocks
+ * still open at its end.
+ */
+export declare function highlightLine(line: string, state?: HighlightState): {
+    tokens: Token[];
+    state: HighlightState;
+};
+/** Lines of ***plain, highlighted one after another - a block opened on one carried to the next. */
+export declare function highlightLines(lines: string[]): Token[][];
+/**
+ * What a piece of ***plain is, for its colour: a section's header, a concept, a link, text in quotes or
+ * backticks, a front matter key, a module a front matter names, a comment, a list's bullet.
+ */
+export type PlainRole = "section" | "concept" | "link" | "literal" | "keyword" | "module" | "comment" | "bullet";
+/** A token's role: its innermost scope that has one. */
+export declare function roleOf(scopes: string[]): PlainRole | undefined;
+export {};

package/dist/plain/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The ***plain*** parser: a TypeScript port of the reference implementation.
+ *
+ * Mirrors plain_file.py, plain_spec.py, concept_utils.py and the file_utils.py
+ * helpers they depend on. The entry points are `plainFileParser` (a .plain file to a
+ * marshalled tree) and `iterateFunctionalSpecs` (the tree to one rendering context per
+ * functionality).
+ */
+export * from "./errors.ts";
+export * from "./markdown.ts";
+export * from "./concepts.ts";
+export * from "./files.ts";
+export * from "./liquid.ts";
+export * from "./parser.ts";
+export * from "./spec.ts";

package/dist/plain/liquid.d.ts

@@ -0,0 +1,22 @@
+import { Liquid } from "liquidjs";
+/**
+ * The Liquid layer: liquid2's Environment plus the project's customisations
+ * (the reference implementation's include tag and the two filters in plain_spec).
+ *
+ * Two behaviours matter and neither is stock Liquid:
+ *
+ * - An include inherits the indentation of the line it sits on, so a multi-line
+ *   template dropped into a nested list item stays inside that item.
+ * - An include on a `>` comment line is not expanded; the tag is written back out
+ *   verbatim, because comment lines are stripped later as block quotes.
+ */
+export type LoadTemplateSource = (name: string) => string | null;
+export interface PlainLiquidOptions {
+    loadTemplateSource: LoadTemplateSource;
+    /** Populated by the code_variable filter; absent means the filter is a pass-through. */
+    codeVariables?: Record<string, Record<string, string>>;
+    strictVariables?: boolean;
+}
+export declare function createEnvironment(options: PlainLiquidOptions): Liquid;
+/** Port of plain_file.render_plain_source. */
+export declare function renderPlainSource(plainSource: string, loadedTemplates: Record<string, string>, codeVariables: Record<string, Record<string, string>>): string;

package/dist/plain/markdown.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The markdown layer.
+ *
+ * The Python parser leans on mistletoe for two things: an AST with line numbers,
+ * and a MarkdownRenderer that round-trips a token back to markdown. mdast gives
+ * us the first. The second is `renderToMarkdown` below - a serializer for the
+ * subset of markdown the plain language uses, matching mistletoe's output
+ * (source indentation preserved, links rewritten as `[resource]` spans).
+ */
+export declare const RESOURCE_MARKER = "[resource]";
+/** Extra fields the parser hangs off AST nodes, as the Python code hangs them off tokens. */
+export interface PlainAnnotations {
+    acceptance_tests?: AnyNode[];
+    linked_resources?: LinkedResource[];
+    /** Set when `value` holds the original source slice rather than mdast's decoded text. */
+    raw?: boolean;
+    openDelimiter?: string;
+    closeDelimiter?: string;
+    /** List item geometry, in mistletoe's parent-stripped coordinates. */
+    leader?: string;
+    indentation?: number;
+    prepend?: number;
+}
+export interface LinkedResource {
+    text: string;
+    target: string;
+}
+/**
+ * A structural view of an mdast node. The mdast union types do not narrow well when
+ * the parser hangs its own fields off nodes, so the AST is handled structurally -
+ * every real mdast node satisfies this shape.
+ */
+export interface AnyNode extends PlainAnnotations {
+    type: string;
+    value?: string;
+    children?: AnyNode[];
+    position?: {
+        start: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+        end: {
+            line: number;
+            column: number;
+            offset?: number;
+        };
+    };
+    [key: string]: unknown;
+}
+export type Root = AnyNode;
+/** A parsed specification section: mistletoe's `Document` holding a flat list of list items. */
+export interface Section {
+    children: AnyNode[];
+}
+/**
+ * Parse markdown, then pin every inline node back to its original source text.
+ *
+ * mdast decodes inline syntax: `\"` becomes `"`, and an emphasis written with `_`
+ * loses the fact that it was not `*`. mistletoe's MarkdownRenderer round-trips the
+ * source instead, so re-serialising a decoded tree drifts from the Python output.
+ * Recording the raw slice for leaf nodes and the real delimiters for emphasis and
+ * strong keeps the two renderers in agreement.
+ */
+export declare function parseMarkdown(text: string): Root;
+export declare function lineNumber(node: AnyNode): number;
+/** Port of plain_file.remove_quotes: block quotes are comments and are dropped. */
+export declare function removeQuotes(node: AnyNode): void;
+/** Port of plain_file.get_raw_text. */
+export declare function getRawText(node: AnyNode): string;
+/** Port of mistletoe.utils.traverse restricted to a node type. */
+export declare function traverse(node: AnyNode, type: string): AnyNode[];
+/** Port of PlainRenderer.render. */
+export declare function renderToMarkdown(node: AnyNode): string;

package/dist/plain/parser.d.ts

@@ -0,0 +1,87 @@
+import { type AnyNode, type Section } from "./markdown.ts";
+import { type MarshalledPlainSource, type SpecificationItem } from "./spec.ts";
+export declare const IMPORT_DIRECTIVE = "import";
+export declare const REQUIRES_DIRECTIVE = "requires";
+export declare const REQUIRED_CONCEPTS_DIRECTIVE = "required_concepts";
+export declare const EXPORTED_CONCEPTS_DIRECTIVE = "exported_concepts";
+export declare const PLAIN_SOURCE_FILE_EXTENSION = ".plain";
+/** definitions / implementation reqs / test reqs always exist as keys; functional specs does not. */
+export type ParsedPlainSource = Record<string, Section | null | undefined>;
+export interface FrontmatterPost {
+    metadata: Record<string, unknown>;
+    content: string;
+}
+export interface PlainFileParseResult {
+    plainSource: ParsedPlainSource;
+    plainSourceObj: FrontmatterPost;
+    requiredModules: string[];
+    requiredConcepts: string[];
+}
+export declare function getFilenameFromModuleName(moduleName: string): string;
+export declare function getModuleNameFromFilename(filename: string): string;
+export declare function checkSectionForLinkedResources(section: AnyNode, dirs?: string[]): void;
+export declare function checkForLinkedResources(plainSource: ParsedPlainSource, dirs?: string[]): void;
+export declare function processSectionCodeVariables(section: SpecificationItem, codeVariables: Record<string, Record<string, string>>): void;
+export declare function processCodeVariables(marshalled: MarshalledPlainSource, codeVariables: Record<string, Record<string, string>>): void;
+/** Whether the module declares a ***functional specs*** section (even if it is empty). */
+export declare function hasFunctionalSpecsSection(plainSource: ParsedPlainSource): boolean;
+/** Number of functionalities under ***functional specs*** (0 if absent or empty). */
+export declare function countFunctionalities(plainSource: ParsedPlainSource): number;
+export declare function validateFunctionalitiesHaveImplementationReqs(plainSource: ParsedPlainSource, moduleName: string, hasRequires?: boolean): void;
+/**
+ * Is this token an `acceptance tests` heading?
+ *
+ * True only for a paragraph holding exactly one emphasis, holding exactly one strong,
+ * holding exactly one text node whose content is the heading. Anything that looks like
+ * a heading but reads differently comes back as a problem string rather than false, so
+ * the caller can reject a near miss instead of silently keeping it.
+ */
+export declare function isAcceptanceTestHeading(token: AnyNode): [boolean, string | null];
+/** Find an acceptance tests heading anywhere in a subtree. */
+export declare function findAcceptanceTestHeading(token: AnyNode): AnyNode | null;
+/**
+ * Pull the acceptance tests out of one functionality.
+ *
+ * A functionality with acceptance tests has three children: its own text, the
+ * `***acceptance tests***` heading, and the list of tests. The heading and list are
+ * lifted onto `acceptance_tests` and removed from the children.
+ */
+export declare function processSingleAcceptanceTestRequirement(functionalRequirement: AnyNode): void;
+export declare function processAcceptanceTests(plainSource: ParsedPlainSource): void;
+export declare function marshallPlainSource(input: ParsedPlainSource): MarshalledPlainSource;
+export declare function normalizeLineEndings(plainSourceText: string): string;
+/**
+ * Frontmatter parsing strips leading blank lines, which would shift every reported
+ * line number. Put them back so syntax errors point at the real line.
+ */
+export declare function restoreStrippedLines(plainSourceText: string, content: string): string;
+export declare function readPlainSourceMetadata(plainSourceText: string): FrontmatterPost;
+export declare function parsePlainSource(plainSourceText: string, codeVariables: Record<string, Record<string, string>>, templateDirs: string[], importedModules: string[], modulesTrace: string[]): PlainFileParseResult;
+export declare function readModulePlainSource(moduleName: string, templateDirs: string[]): string;
+export declare function parsePlainFile(moduleName: string, codeVariables: Record<string, Record<string, string>>, templateDirs: string[], importedModules: string[], modulesTrace: string[]): PlainFileParseResult;
+export declare function processRequiredModules(requiredModules: string[], codeVariables: Record<string, Record<string, string>>, templateDirs: string[], allRequiredModules: string[], modulesTrace: string[]): AnyNode[];
+export declare function processExportedDefinitions(plainSource: ParsedPlainSource, exportedDefinitions: AnyNode[]): void;
+/**
+ * Parse a .plain file into the marshalled tree.
+ *
+ * Returns the module name, the tree, and the modules it requires.
+ */
+export interface ParseOptions {
+    /**
+     * Accept a module with no functional specs yet. Not renderable one functionality at a
+     * time - there is none - but a spec change can already be built from it: a module whose
+     * product interview has so far given it definitions and reqs.
+     */
+    allowNoFunctionalities?: boolean;
+}
+export declare function plainFileParser(plainSourceFileName: string, templateDirs: string[], options?: ParseOptions): [string, MarshalledPlainSource, string[]];
+/**
+ * One parse per file for the length of `run`, however many times it is asked for.
+ *
+ * Walking a requires chain parses each module in it, and each parse gathers what it inherits
+ * by parsing the modules below - so looking across a project of long chains asks for the
+ * same files thousands of times. Inside `run` they are parsed once. Outside it nothing is
+ * kept, so an edit made between two calls is always seen: the cache is for one question
+ * about the specs, not for the life of the process.
+ */
+export declare function withParseCache<T>(run: () => T): T;