@turri-dev/cli 0.1.13 → 0.1.14-next.678847f

package/dist/plain/module-concepts.js

@@ -0,0 +1,79 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { resolveTemplateDirs } from "../regenerate/paths.js";
+import { DEFAULT_CONCEPT_DEFINITIONS, definitionText, extractConceptsFromDefinition } from "./concepts.js";
+import { renderToMarkdown } from "./markdown.js";
+import { exportedDefinitionsOf, IMPORT_DIRECTIVE, parsePlainFile, parsePlainSource, PLAIN_SOURCE_FILE_EXTENSION, readPlainSourceMetadata, REQUIRES_DIRECTIVE, restoreStrippedLines, } from "./parser.js";
+import { DEFINITIONS } from "./spec.js";
+/**
+ * A module read for what it can name, as the parser builds its definitions: its own, its imports' (`import`), and its
+ * required modules' `exported_concepts` with the definitions they use. Never throws: a module that does not parse
+ * gives its own definitions read without its imports, and what of those it names is there.
+ */
+export function readModule(moduleName, plainFile, templateDirs) {
+    const parse = (name) => attempt(() => parsePlainFile(name, {}, templateDirs, [], []));
+    const definitions = [];
+    const add = (result, nodes, module) => {
+        for (const node of nodes)
+            definitions.push({ node, module: result.importedFrom.get(node) ?? module });
+    };
+    const definitionsOf = (result) => result.plainSource[DEFINITIONS]?.children ?? [];
+    let requires;
+    let parsed = parse(moduleName);
+    if (parsed !== undefined) {
+        add(parsed, definitionsOf(parsed), moduleName);
+        requires = parsed.requiredModules;
+    }
+    else {
+        // What its front matter names, each read on its own, and its own text without them.
+        const text = attempt(() => readFileSync(plainFile, "utf8"));
+        const front = text === undefined ? undefined : attempt(() => readPlainSourceMetadata(text));
+        for (const name of namesIn(front?.metadata[IMPORT_DIRECTIVE])) {
+            const imported = parse(name);
+            if (imported !== undefined)
+                add(imported, definitionsOf(imported), name);
+        }
+        parsed = front && attempt(() => parsePlainSource(restoreStrippedLines(text, front.content), {}, templateDirs, [], [moduleName]));
+        if (parsed !== undefined)
+            add(parsed, definitionsOf(parsed), moduleName);
+        requires = namesIn(front?.metadata[REQUIRES_DIRECTIVE]);
+    }
+    for (const name of requires) {
+        const required = parse(name);
+        const exported = required && attempt(() => exportedDefinitionsOf(required));
+        if (required !== undefined && exported !== undefined)
+            add(required, exported, name);
+    }
+    return { ...(parsed !== undefined ? { parsed } : {}), definitions };
+}
+/**
+ * Every concept a module can name: its own definitions, those its imports bring, those its required modules export,
+ * and ***plain's own - read as the parser reads them. A module that does not parse gives what can be read of it.
+ */
+export function conceptsOf(plainFile, templateDirs = resolveTemplateDirs(plainFile)) {
+    const found = [];
+    const seen = new Set();
+    for (const { node, module } of readModule(basename(plainFile, PLAIN_SOURCE_FILE_EXTENSION), plainFile, templateDirs).definitions) {
+        const text = renderToMarkdown(node);
+        for (const concept of extractConceptsFromDefinition(text)[0]) {
+            if (seen.has(`${concept}\0${module}`))
+                continue;
+            seen.add(`${concept}\0${module}`);
+            found.push({ concept, definition: definitionText(text), module });
+        }
+    }
+    for (const [concept, definition] of Object.entries(DEFAULT_CONCEPT_DEFINITIONS))
+        found.push({ concept, definition, module: null });
+    return found;
+}
+export function attempt(run) {
+    try {
+        return run();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function namesIn(value) {
+    return Array.isArray(value) ? value.filter((name) => typeof name === "string") : [];
+}

package/dist/plain/parser.d.ts

@@ -16,6 +16,8 @@ export interface PlainFileParseResult {
     plainSourceObj: FrontmatterPost;
     requiredModules: string[];
     requiredConcepts: string[];
+    /** The items its imports brought into its sections, each with the module it is written in. turri's: the Python parser does not keep it. */
+    importedFrom: Map<AnyNode, string>;
 }
 export declare function getFilenameFromModuleName(moduleName: string): string;
 export declare function getModuleNameFromFilename(filename: string): string;
@@ -57,9 +59,16 @@ export declare function normalizeLineEndings(plainSourceText: string): string;
 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;
+/**
+ * The file a module name is read from, as `readModulePlainSource` reads it - a standard library module's in turri's
+ * `stdlib/`, any other's in the first template folder that has it - or null when there is none.
+ */
+export declare function modulePlainFile(moduleName: string, templateDirs: string[]): string | null;
 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[];
+/** The definitions a required module exports: those of its `exported_concepts`, with the definitions they use. */
+export declare function exportedDefinitionsOf(result: PlainFileParseResult): AnyNode[];
 export declare function processExportedDefinitions(plainSource: ParsedPlainSource, exportedDefinitions: AnyNode[]): void;
 /**
  * Parse a .plain file into the marshalled tree.

package/dist/plain/parser.js

@@ -4,9 +4,9 @@ import { extname, isAbsolute, basename, resolve } from "node:path";
 import { load as loadYaml } from "js-yaml";
 import { extractConceptsFromDefinition, findConceptDefinitionsInPlainSource, sortDefinitions, validateConcepts, DEFAULT_CONCEPTS, } from "./concepts.js";
 import { ImportedModuleWithFunctionalitiesError, MissingFunctionalitiesError, ModuleDoesNotExistError, PlainSyntaxError, UnsupportedBase64Content, } from "./errors.js";
-import { findLargeBase64Blob, getLoadedTemplates, openFrom } from "./files.js";
+import { findIn, findLargeBase64Blob, getLoadedTemplates, openFrom } from "./files.js";
 import { renderPlainSource } from "./liquid.js";
-import { isStdlibModule, readStdlibModule } from "./stdlib.js";
+import { isStdlibModule, readStdlibModule, stdlibModuleFile } from "./stdlib.js";
 import { getRawText, lineNumber, parseMarkdown, removeQuotes, renderToMarkdown, traverse, } from "./markdown.js";
 import { ACCEPTANCE_TESTS, ACCEPTANCE_TEST_HEADING, ALLOWED_IMPORT_SPECIFICATION_HEADINGS, ALLOWED_SPECIFICATION_HEADINGS, DEFINITIONS, FUNCTIONAL_REQUIREMENTS, NON_FUNCTIONAL_REQUIREMENTS, TEST_REQUIREMENTS, getSpecificationItems, REQUIRED_FUNCTIONAL_SPECS, } from "./spec.js";
 export const IMPORT_DIRECTIVE = "import";
@@ -366,7 +366,7 @@ export function readPlainSourceMetadata(plainSourceText) {
     }
     return { metadata, content };
 }
-function processImports(plainSource, imports, codeVariables, templateDirs, importedModules, modulesTrace) {
+function processImports(plainSource, imports, codeVariables, templateDirs, importedModules, modulesTrace, importedFrom) {
     const requiredConcepts = [];
     for (const moduleName of imports) {
         if (modulesTrace.includes(moduleName)) {
@@ -380,6 +380,10 @@ function processImports(plainSource, imports, codeVariables, templateDirs, impor
                 "Imported modules may only provide definitions, implementation reqs, and test reqs — " +
                 "use 'requires' instead of 'import' if this module's functionalities should be built on.");
         }
+        for (const section of Object.values(result.plainSource)) {
+            for (const item of section?.children ?? [])
+                importedFrom.set(item, result.importedFrom.get(item) ?? moduleName);
+        }
         for (const heading of Object.keys(result.plainSource)) {
             if (!ALLOWED_IMPORT_SPECIFICATION_HEADINGS.includes(heading)) {
                 throw new PlainSyntaxError(`Plain syntax error: Invalid specification heading (\`${heading}\`). ` +
@@ -411,8 +415,9 @@ export function parsePlainSource(plainSourceText, codeVariables, templateDirs, i
     const plainSourceObj = readPlainSourceMetadata(plainSourceText);
     const plainSource = newPlainSource();
     let requiredConcepts = [];
+    const importedFrom = new Map();
     if (IMPORT_DIRECTIVE in plainSourceObj.metadata) {
-        requiredConcepts = processImports(plainSource, plainSourceObj.metadata[IMPORT_DIRECTIVE], codeVariables, templateDirs, importedModules, modulesTrace);
+        requiredConcepts = processImports(plainSource, plainSourceObj.metadata[IMPORT_DIRECTIVE], codeVariables, templateDirs, importedModules, modulesTrace, importedFrom);
     }
     const [, loadedTemplates] = getLoadedTemplates(templateDirs, plainSourceText);
     const plainSourceContent = restoreStrippedLines(plainSourceText, plainSourceObj.content);
@@ -490,7 +495,14 @@ export function parsePlainSource(plainSourceText, codeVariables, templateDirs, i
         }
     }
     const requiredModules = plainSourceObj.metadata[REQUIRES_DIRECTIVE] ?? [];
-    return { plainSource, plainSourceObj, requiredModules, requiredConcepts };
+    return { plainSource, plainSourceObj, requiredModules, requiredConcepts, importedFrom };
+}
+/**
+ * The file a module name is read from, as `readModulePlainSource` reads it - a standard library module's in turri's
+ * `stdlib/`, any other's in the first template folder that has it - or null when there is none.
+ */
+export function modulePlainFile(moduleName, templateDirs) {
+    return isStdlibModule(moduleName) ? stdlibModuleFile(moduleName) : findIn(templateDirs, moduleName + PLAIN_SOURCE_FILE_EXTENSION);
 }
 export function readModulePlainSource(moduleName, templateDirs) {
     // `stdlib/...` is turri's standard library, and only that - see stdlib.ts.
@@ -536,27 +548,29 @@ export function processRequiredModules(requiredModules, codeVariables, templateD
                 moduleName,
             ]);
         }
-        if (EXPORTED_CONCEPTS_DIRECTIVE in result.plainSourceObj.metadata) {
-            const exportedConcepts = [];
-            for (const concept of result.plainSourceObj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]) {
-                if (typeof concept === "string" && DEFAULT_CONCEPTS.has(concept)) {
-                    throw new PlainSyntaxError(`Plain syntax error: Default concept cannot be exported: ${concept}. Only user-defined concepts can be exported.`);
-                }
-                if (typeof concept === "string") {
-                    exportedConcepts.push(...extractConceptsFromDefinition(concept)[0]);
-                }
-                else {
-                    throw new PlainSyntaxError(`Plain syntax error: Invalid exported concept: ${concept}.`);
-                }
-            }
-            for (const exportedConcept of exportedConcepts) {
-                exportedDefinitions.push(...findConceptDefinitionsInPlainSource(exportedConcept, result.plainSource[DEFINITIONS] ?? null));
-            }
-        }
+        exportedDefinitions.push(...exportedDefinitionsOf(result));
         allRequiredModules.push(moduleName);
     }
     return exportedDefinitions;
 }
+/** The definitions a required module exports: those of its `exported_concepts`, with the definitions they use. */
+export function exportedDefinitionsOf(result) {
+    if (!(EXPORTED_CONCEPTS_DIRECTIVE in result.plainSourceObj.metadata))
+        return [];
+    const exportedConcepts = [];
+    for (const concept of result.plainSourceObj.metadata[EXPORTED_CONCEPTS_DIRECTIVE]) {
+        if (typeof concept === "string" && DEFAULT_CONCEPTS.has(concept)) {
+            throw new PlainSyntaxError(`Plain syntax error: Default concept cannot be exported: ${concept}. Only user-defined concepts can be exported.`);
+        }
+        if (typeof concept === "string") {
+            exportedConcepts.push(...extractConceptsFromDefinition(concept)[0]);
+        }
+        else {
+            throw new PlainSyntaxError(`Plain syntax error: Invalid exported concept: ${concept}.`);
+        }
+    }
+    return exportedConcepts.flatMap((exportedConcept) => findConceptDefinitionsInPlainSource(exportedConcept, result.plainSource[DEFINITIONS] ?? null));
+}
 export function processExportedDefinitions(plainSource, exportedDefinitions) {
     if (exportedDefinitions.length === 0)
         return;

package/dist/plain/stdlib.d.ts

@@ -10,5 +10,7 @@ export declare const STDLIB_PREFIX = "stdlib/";
 /** The folder `stdlib/` is in: turri's own. */
 export declare const STDLIB_ROOT: string;
 export declare function isStdlibModule(moduleName: string): boolean;
+/** A standard library module's file, or null when the standard library has no such module. */
+export declare function stdlibModuleFile(moduleName: string): string | null;
 /** A standard library module's text - refused when a folder the spec is resolved from has a module of that name too. */
 export declare function readStdlibModule(moduleName: string, templateDirs: string[]): string;

package/dist/plain/stdlib.js

@@ -2,7 +2,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ModuleDoesNotExistError, PlainSyntaxError } from "./errors.js";
-import { openFrom } from "./files.js";
+import { findIn, openFrom } from "./files.js";
 /**
  * The ***plain standard library's names. `stdlib/` is a reserved prefix: `stdlib/backend/python-fastapi`
  * is always turri's own template, in its `stdlib/` folder - never a module of the project's. A
@@ -25,6 +25,10 @@ function sameFile(a, b) {
         return false;
     }
 }
+/** A standard library module's file, or null when the standard library has no such module. */
+export function stdlibModuleFile(moduleName) {
+    return findIn([STDLIB_ROOT], `${moduleName.replace(/^\.\//, "")}.plain`);
+}
 /** A standard library module's text - refused when a folder the spec is resolved from has a module of that name too. */
 export function readStdlibModule(moduleName, templateDirs) {
     const name = moduleName.replace(/^\.\//, "");

package/dist/regenerate/requires.d.ts

@@ -18,6 +18,8 @@ export interface ChainEntry {
     requires: string | null;
     frids: string[];
 }
+/** A required module's file: the first template folder that has it. */
+export declare function locateModule(moduleName: string, templateDirs: string[]): string;
 /**
  * The chain to build, bottom first.
  *

package/dist/regenerate/requires.js

@@ -8,7 +8,8 @@ import { resolveTemplateDirs } from "./paths.js";
 import { inheritedRecord, readRecord, RECORD_FILE, writeCodeRecord } from "./records.js";
 import { head, historyLog, recordHistory } from "./lineage.js";
 import { listFiles } from "./testing.js";
-function locateModule(moduleName, templateDirs) {
+/** A required module's file: the first template folder that has it. */
+export function locateModule(moduleName, templateDirs) {
     for (const dir of templateDirs) {
         const candidate = join(dir, moduleName + PLAIN_SOURCE_FILE_EXTENSION);
         if (existsSync(candidate))

package/dist/setup.d.ts

@@ -35,6 +35,7 @@ export declare function checkSandbox(wall?: Wall, platform?: NodeJS.Platform): C
 export declare function checkProject(project: string, machine?: {
     has?: (command: string) => boolean;
     exists?: (path: string) => boolean;
+    jdk?: () => boolean;
 }): Check[];
 /**
  * In a project: each model its config names - with the stack chosen, that stack's over it - tried with one short

package/dist/setup.js

@@ -66,7 +66,7 @@ export function checkSandbox(wall = sandboxAvailable(), platform = process.platf
  */
 export function checkProject(project, machine = {}) {
     const checks = [];
-    for (const { module, needs, missing } of stackOnMachine(project, machine.has)) {
+    for (const { module, needs, missing } of stackOnMachine(project, machine.has, machine.jdk)) {
         if (needs.length === 0)
             continue;
         checks.push(missing.length === 0

package/dist/skills.d.ts

@@ -42,3 +42,13 @@ export declare function createCommandGate(): {
 };
 /** What cultivate says of a command-only skill the person did not start. */
 export declare function startedByCommandOnly(name: string): string;
+/**
+ * What the model is told when the person picked a skill: start it now, with what they asked for - word for word, as the
+ * message that set off the question - so they never type its command after picking it.
+ */
+export declare function startPicked(name: string, request: string): string;
+/**
+ * The command-only skill an answer picks: an option offered to the person that starts with its command - `/brood - an
+ * interview` - is the person starting it, as if they typed it.
+ */
+export declare function chosenCommand(answer: string, skills: ReadonlyArray<Pick<FoundSkill, "name" | "commandOnly">>): string | undefined;

package/dist/skills.js

@@ -61,8 +61,8 @@ export function discoverSkills(packageRoot, projectDir) {
 /** A skill's line in cultivate's list: a project's says so, and where it is. */
 export function catalogueLine(skill) {
     const whose = skill.origin === "turri" ? "" : ` (this project's, ${skill.origin.project})`;
-    // One the person starts themselves: the model points them to its command rather than running it.
-    const byCommand = skill.commandOnly ? ` Started only by the person, with /${skill.name}: never run it unasked - when it fits, tell them to type /${skill.name}.` : "";
+    // One the person starts themselves - typed, or picked among the options the model offers: never run unasked.
+    const byCommand = skill.commandOnly ? ` Started only by the person, with /${skill.name} or by picking it when you offer it with ask_user: never run it unasked.` : "";
     return `- ${skill.name}${whose}: ${skill.description}${byCommand}`;
 }
 /** What is said under the list about the skills it leaves out. */
@@ -88,5 +88,22 @@ export function createCommandGate() {
 }
 /** What cultivate says of a command-only skill the person did not start. */
 export function startedByCommandOnly(name) {
-    return `Not started: ${name} is started only by the person, with /${name}. If it fits what they want, tell them to type /${name} - with what they want after it, if they like.`;
+    return `Not started: ${name} is started only by the person, with /${name} or by picking an option starting /${name} that you offer them with ask_user. For a new project, ask them as <new-project> says; otherwise do what they asked yourself, in the conversation.`;
+}
+/**
+ * What the model is told when the person picked a skill: start it now, with what they asked for - word for word, as the
+ * message that set off the question - so they never type its command after picking it.
+ */
+export function startPicked(name, request) {
+    const asked = request.trim();
+    return (`They picked ${name}, and it may start now: call cultivate with skill "${name}" at once, before anything else, and never ask them to type /${name}. ` +
+        `Pass as its context everything they have told you${asked !== "" ? `, starting with what they asked for, word for word: ${JSON.stringify(asked)}` : ""}.`);
+}
+/**
+ * The command-only skill an answer picks: an option offered to the person that starts with its command - `/brood - an
+ * interview` - is the person starting it, as if they typed it.
+ */
+export function chosenCommand(answer, skills) {
+    const typed = /^\s*\/([\w-]+)/.exec(answer)?.[1];
+    return skills.find((skill) => skill.commandOnly && skill.name === typed)?.name;
 }

package/dist/stack.d.ts

@@ -19,8 +19,11 @@ export declare function projectImplementationReqs(project: string): Array<{
     module: string;
     reqs: string[];
 }>;
-/** What a project's modules need of this machine, and which of it the machine lacks. */
-export declare function stackOnMachine(project: string, has?: (command: string) => boolean): Array<{
+/**
+ * What a project's modules need of this machine, and which of it the machine lacks - `has` finding a command, and on
+ * macOS a JDK behind `java` (`toolchainCheck`), asked at most once.
+ */
+export declare function stackOnMachine(project: string, has?: (command: string) => boolean, jdk?: () => boolean): Array<{
     module: string;
     needs: StackNeed[];
     missing: StackNeed[];
@@ -34,6 +37,11 @@ export declare const STDLIB_LANGUAGES: Array<{
     language: string;
     commands: string[];
 }>;
+/**
+ * Whether a toolchain's command is really there: `has` finds it - and Java has a JDK behind it as well, for macOS keeps a
+ * `/usr/bin/java` that only asks to install one.
+ */
+export declare function toolchainCheck(has: (command: string) => boolean, jdk?: () => boolean): (command: string) => boolean;
 /** Which of the standard library's languages this machine can build and test now, and which it lacks a command of. */
 export declare function languagesOnMachine(has?: (command: string) => boolean): {
     ready: typeof STDLIB_LANGUAGES;

package/dist/stack.js

@@ -57,11 +57,16 @@ export function projectImplementationReqs(project) {
 }
 /** Whether a command is on this machine's PATH. */
 const onPath = (command) => onThisMachine(command) !== undefined;
-/** What a project's modules need of this machine, and which of it the machine lacks. */
-export function stackOnMachine(project, has = onPath) {
+/**
+ * What a project's modules need of this machine, and which of it the machine lacks - `has` finding a command, and on
+ * macOS a JDK behind `java` (`toolchainCheck`), asked at most once.
+ */
+export function stackOnMachine(project, has = onPath, jdk = jdkHere) {
+    let found;
+    const here = toolchainCheck(has, () => (found ??= jdk()));
     return projectImplementationReqs(project).map(({ module, reqs }) => {
         const needs = stackOf(reqs.join("\n"));
-        return { module, needs, missing: needs.filter((need) => !need.commands.some(has)) };
+        return { module, needs, missing: needs.filter((need) => !need.commands.some(here)) };
     });
 }
 /**
@@ -76,17 +81,18 @@ export const STDLIB_LANGUAGES = [
     { language: "Rust", commands: ["cargo"] },
     { language: "Java", commands: ["java"] },
 ];
+/** Whether this machine has a JDK behind `java`: anywhere but macOS, java found says so; on macOS, `java_home` finding one. */
+function jdkHere() {
+    return process.platform !== "darwin" || spawnSync("/usr/libexec/java_home", [], { stdio: "ignore" }).status === 0;
+}
 /**
- * Whether a toolchain's command is really there: on the PATH - and Java on macOS, which keeps a `/usr/bin/java` that only
- * asks to install a JDK, by `java_home` finding one.
+ * Whether a toolchain's command is really there: `has` finds it - and Java has a JDK behind it as well, for macOS keeps a
+ * `/usr/bin/java` that only asks to install one.
  */
-function toolchainHere(command) {
-    if (!onPath(command))
-        return false;
-    if (command === "java" && process.platform === "darwin")
-        return spawnSync("/usr/libexec/java_home", [], { stdio: "ignore" }).status === 0;
-    return true;
+export function toolchainCheck(has, jdk = jdkHere) {
+    return (command) => has(command) && (command !== "java" || jdk());
 }
+const toolchainHere = toolchainCheck(onPath);
 /** Which of the standard library's languages this machine can build and test now, and which it lacks a command of. */
 export function languagesOnMachine(has = toolchainHere) {
     const ready = STDLIB_LANGUAGES.filter(({ commands }) => commands.every(has));

package/dist/stdlib.d.ts

@@ -7,14 +7,30 @@
 export interface StdlibTemplate {
     /** What a spec imports it as: `stdlib/backend/python-fastapi`. */
     name: string;
+    /** Where it is: turri's `stdlib/backend/python-fastapi.plain`. */
+    file: string;
+    /** The kind of software it is for - `backend`, `frontend`, `cli`, `library` - or `lang`, a language's. */
+    kind: StdlibKind;
     description: string;
     text: string;
+    /** The modules its front matter imports, as the parser reads it. */
+    imports: string[];
+    /** A stack's conformance template, when it has one: `stdlib/backend/conformance/python-fastapi`. */
+    conformance?: string;
+    /** A conformance template's stack, when it is one's: `stdlib/backend/python-fastapi`. */
+    tests?: string;
 }
+export type StdlibKind = "backend" | "frontend" | "cli" | "library" | "lang";
 export declare function stdlibTemplates(dir?: string): StdlibTemplate[];
 /** A stack to import - not a kind's `common`, not a conformance template, and not a language's. */
 export declare function isStack(template: StdlibTemplate): boolean;
 /** A stack's conformance template: `stdlib/backend/python-fastapi` has `stdlib/backend/conformance/python-fastapi`. */
 export declare function conformanceOf(stack: string): string;
+/** The standard library's kinds, in the order they are listed, each with its title. Only the first four have stacks. */
+export declare const STDLIB_KINDS: ReadonlyArray<{
+    kind: StdlibKind;
+    title: string;
+}>;
 /**
  * The catalogue appended to the stdlib rule: every stack with its conformance template and what it is, the
  * shared templates, and the folder they are all in - an absolute path, so an agent reads the one it imports

package/dist/stdlib.js

@@ -1,5 +1,6 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join, relative, sep } from "node:path";
+import { IMPORT_DIRECTIVE, readPlainSourceMetadata } from "./plain/parser.js";
 import { STDLIB_DIR } from "./regenerate/paths.js";
 export function stdlibTemplates(dir = STDLIB_DIR) {
     const found = [];
@@ -19,16 +20,31 @@ export function stdlibTemplates(dir = STDLIB_DIR) {
         }
     };
     walk(dir);
-    return found
+    const templates = found
         .map((file) => {
         const text = readFileSync(file, "utf8").trim();
-        return {
-            name: `stdlib/${relative(dir, file).split(sep).join("/").replace(/\.plain$/, "")}`,
-            description: /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "",
-            text,
-        };
+        const name = `stdlib/${relative(dir, file).split(sep).join("/").replace(/\.plain$/, "")}`;
+        return { name, file, kind: name.split("/")[1], description: /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "", text, imports: importsOf(text) };
     })
         .sort((a, b) => a.name.localeCompare(b.name));
+    const names = new Set(templates.map((template) => template.name));
+    for (const template of templates) {
+        if (isStack(template) && names.has(conformanceOf(template.name)))
+            template.conformance = conformanceOf(template.name);
+        const stack = template.name.replace("/conformance/", "/");
+        if (template.name.includes("/conformance/") && templates.some((other) => other.name === stack && isStack(other)))
+            template.tests = stack;
+    }
+    return templates;
+}
+function importsOf(text) {
+    try {
+        const imports = readPlainSourceMetadata(text).metadata[IMPORT_DIRECTIVE];
+        return Array.isArray(imports) ? imports.filter((name) => typeof name === "string") : [];
+    }
+    catch {
+        return [];
+    }
 }
 /** A stack to import - not a kind's `common`, not a conformance template, and not a language's. */
 export function isStack(template) {
@@ -39,11 +55,13 @@ export function conformanceOf(stack) {
     const slash = stack.lastIndexOf("/");
     return `${stack.slice(0, slash)}/conformance/${stack.slice(slash + 1)}`;
 }
-const KINDS = [
+/** The standard library's kinds, in the order they are listed, each with its title. Only the first four have stacks. */
+export const STDLIB_KINDS = [
     { kind: "backend", title: "Backends" },
     { kind: "frontend", title: "Frontends" },
     { kind: "cli", title: "Command-line tools" },
     { kind: "library", title: "Libraries" },
+    { kind: "lang", title: "Languages" },
 ];
 /**
  * The catalogue appended to the stdlib rule: every stack with its conformance template and what it is, the
@@ -61,7 +79,7 @@ export function stdlibCatalogue(templates = stdlibTemplates(), dir = STDLIB_DIR)
         "",
         `Every template is a file in ${dir}: \`stdlib/backend/python-fastapi\` is \`${dir}/backend/python-fastapi.plain\`. Read the ones a module imports - the stack, its language, its kind's \`common\`, and their conformance templates - before writing its specs.`,
         "",
-        ...KINDS.flatMap(({ kind, title }) => {
+        ...STDLIB_KINDS.flatMap(({ kind, title }) => {
             const stacks = templates.filter((template) => isStack(template) && template.name.startsWith(`stdlib/${kind}/`));
             return stacks.length === 0 ? [] : [`### ${title}`, "", "| import | its conformance tests | what it is |", "| --- | --- | --- |", ...stacks.map(row), ""];
         }),
@@ -85,7 +103,7 @@ export function describeStdlib(templates = stdlibTemplates(), dir = STDLIB_DIR)
     const width = Math.max(...templates.filter(isStack).map((template) => template.name.length));
     return [
         `The ***plain standard library - ${stdlibStackCount(templates)} stacks a spec can import instead of writing its implementation reqs:`,
-        ...KINDS.flatMap(({ kind, title }) => {
+        ...STDLIB_KINDS.flatMap(({ kind, title }) => {
             const stacks = templates.filter((template) => isStack(template) && template.name.startsWith(`stdlib/${kind}/`));
             return stacks.length === 0 ? [] : ["", `${title}:`, ...stacks.map((template) => `  ${template.name.padEnd(width)}  ${template.description}`)];
         }),

package/docs/authoring-plain.md

@@ -122,7 +122,7 @@ The ones that shape \*\*\*plain most:
 
 ## Writing \*\*\*plain with turri
 
-In a conversation (`turri`), say what you want and the matching skill runs - but the three that start a project or a feature you start yourself, by their commands: `/brood`, `/spawn` or `/bud`, with what you want after it. Two build a project from scratch, and write each \*\*\*plain change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes \*\*\*plain as you answer; `spawn`, its quick twin, gets something running as soon as it can - the smallest thing that runs first, then the product a slice at a time - asking only what your message leaves open:
+In a conversation (`turri`), say what you want and the matching skill runs - but the three that start a project or a feature you start yourself, by their commands: `/brood`, `/spawn` or `/bud`, with what you want after it. Asked for new software without one - `create a small server in Java Spring Boot` - turri offers `/brood`, `/spawn` or `Just do it`, with no skill; a skill picked there starts at once with what you asked for, and Just do it starts the project in the conversation as `spawn` would, writing the module, its config and its unit testing script, then the smallest thing that runs, regenerated at once, and the first slices of what you described (see [using turri](using.md)). Two build a project from scratch, and write each \*\*\*plain change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes \*\*\*plain as you answer; `spawn`, its quick twin, gets something running as soon as it can - the smallest thing that runs first, then the product a slice at a time - asking only what your message leaves open:
 
 | skill | phases | how a \*\*\*plain change is written |
 | --- | --- | --- |
@@ -145,13 +145,13 @@ Every skill in `genome/skills/` can be run from a conversation; most are also us
 
 | to… | skills |
 | --- | --- |
-| start a project | `brood`, `spawn` |
+| start a project | `brood`, `spawn` - or ask, and choose `Just do it` for no skill |
 | make rough \*\*\*plain build | `mature` |
 | add to \*\*\*plain | `bud`, `add-functional-spec`, `add-functional-specs`, `add-concept`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`, `add-resource`, `add-template` |
 | check what is written | `analyze-if-func-spec-too-complex`, `analyze-2-func-specs`, `analyze-func-specs`, `resolve-section-ownership` |
 | fix what is written | `break-down-func-spec`, `resolve-spec-conflict`, `debug-specs` |
-| restructure modules | `create-import-module`, `create-requires-module`, `refactor-module`, `consolidate-concepts` |
-| set up the project to build | `implement-unit-testing-script`, `implement-conformance-testing-script`, `check-plain-env` |
+| restructure modules | `refactor-module`, `consolidate-concepts` |
+| set up the project to build | `implement-unit-testing-script`, `implement-conformance-testing-script` |
 
 `debug-specs` is the one for a running application that misbehaves: it reads the generated code to find the cause, traces it back to \*\*\*plain, and fixes only the `.plain` files.
 

package/docs/hosting.md

@@ -18,6 +18,9 @@
 | `bedrockAwsRegion`, `bedrockNeedsAwsRegion` | the AWS region to set `AWS_REGION` to for a Bedrock geography, and whether it has to be set. |
 | `checkPlainFile`, `plainFileParser`, `resolveTemplateDirs`, `iterateFunctionalSpecs`, `FUNCTIONAL_REQUIREMENTS` | \*\*\*plain checked and parsed, its functional specs one by one - as `turri validate` reads it. |
 | `highlightLines`, `roleOf` | \*\*\*plain's lines coloured by turri's own [\*\*\*plain](https://plainlang.org/docs/) grammar. |
+| `plainGraph(projectDir)` | a project's \*\*\*plain as a graph to move around in: its modules with what each imports and requires and what imports and requires it, each item of their sections with its line, and the concepts - an item linked to those it names and to where each is defined - see [\*\*\*plain for a host](#plain-for-a-host). |
+| `conceptsOf(plainFile)`, `findConcepts(text)`, `conceptBeingTyped(text)` | the concepts a module can name, with what each is and the module that defines it; the concepts written in a piece of text; the one being typed at its end. |
+| `stdlibTemplates()`, `isStack`, `STDLIB_KINDS` | turri's standard library: every template with its kind, file, text, imports and its conformance template or the stack it tests, and the kinds in order with their titles. |
 | `functionalityCompletion`, `createWorkLoop`, `createJobRegistry`, `promptOf`, `describeModules` | how far each functional spec is built, and - on a loop of the host's own with `dryRun` - the work a \*\*\*plain change would plan, as `turri glimpse` does. |
 | `onModelEvent`, `describeTurnIncident` | a provider failing and waited out, a turn turri ended itself. |
 | `onLedgerEvent`, `readLedger`, `ledgerDir`, `runViews`, `pulseView`, `describePulseView`, `describeRuns`, `ledgerProjects`, `earlierPulses`, `asJob` | what turri did, as facts - the [ledger](using.md#the-ledger): each event heard as it is recorded, and every run and pulse read back, earlier sessions' too - see [the ledger in a host](#the-ledger-in-a-host). |
@@ -108,6 +111,27 @@ the chat, and the toolbar's buttons send them too.
 - The Run button releases what is built and opens it.`;
 ```
 
+## \*\*\*plain for a host
+
+```js
+import { conceptBeingTyped, conceptsOf, findConcepts, plainGraph, stdlibTemplates, STDLIB_KINDS } from "@turri-dev/cli/host";
+
+const { modules, items, concepts } = plainGraph(projectDir);
+const app = modules.find((module) => module.module === "app");
+app.requires;      // [{ name: "base", file: "/…/base.plain" }] - and imports, importedBy, requiredBy, the same way
+app.items;         // ["/…/app.plain:11", "/…/app.plain:15"] - its own items, in order
+items.find((item) => item.id === app.items[1]);
+// { id, file, module: "app", section: "functional specs", line: 15, frid: "1", text: "- :User: can fill :Cart:.",
+//   defines: [], uses: [{ concept: ":User:", definition: "/…/base.plain:8" }, { concept: ":Cart:", definition: "/…/app.plain:11" }] }
+concepts.find((concept) => concept.definition === "/…/base.plain:8");
+// { concept: ":User:", definition: "/…/base.plain:8", module: "base", text: "is a person who signs up.", usedBy: [...] }
+```
+
+- **The graph.** `plainGraph` reads every .plain file in the project's folder and its `template/` folder, and every module they import or require, wherever the parser finds it - the standard library's templates too. A **module** is a file: its imports, resolved as the parser reads an import (a `stdlib/` module from turri's own folder), its required modules, resolved as the requires chain finds them - `file: null` when one is not found - and the reverse of both, `importedBy` and `requiredBy`, so a host goes up and down the requires chain without inverting anything. An **item** is one item of a section - a definition, an implementation req, a test req, a functional spec with its acceptance tests - with its file, the line it starts on, its text, a functional spec's `frid`, the concepts a definition defines, and each concept it names with the item that defines it: its own module's definitions, its imports', and those its required modules export, as the parser sees them from that module. `definition` is null for \*\*\*plain's own concepts, and for one defined nowhere the module can see. A **concept** is one definition of it - or \*\*\*plain's own, `definition: null` - with every item that names it there. An item's id is `<file>:<line>`: the file to open and the line to go to.
+- **What does not parse.** Nothing throws. A file that does not parse has `error`, the parser's message; its links are what its front matter says, and its items what of its own text reads without its imports. A file whose items Liquid moves keeps the lines of its own text.
+- **Concepts.** `conceptsOf(plainFile)` is what one module can name - `{ concept, definition, module }`, `definition` the text after its concepts, `module` null for \*\*\*plain's own - for suggestions as the person types. `findConcepts(text)` is every concept written in a piece of text, `{ concept, start, end }`, and `conceptBeingTyped(text)` the one at its end still open - `{ typed: ":Us", start }`, or undefined - both with the parser's own pattern.
+- **The standard library.** `stdlibTemplates()` is every template in turri's `stdlib/`, sorted: `name` - what a module imports it as - `file`, `kind` (`backend`, `frontend`, `cli`, `library` or `lang`), `description`, `text`, `imports` as the parser reads its front matter, a stack's `conformance` template when it has one, and a conformance template's stack as `tests`. `isStack(template)` says whether it is a stack to import; `STDLIB_KINDS` is the kinds in order, each with its title.
+
 ## The ledger in a host
 
 The conversation's extension starts the ledger itself, in the folder the host made the session in - so a host that runs it there, the project's, needs nothing to have one: its pulses are recorded as `host` runs, and the conversation's `pulses` and `diagnose` already tell the model of earlier sessions' pulses. What the host can do with it is show it.

package/docs/installation.md

@@ -54,7 +54,7 @@ In a project - a folder with `config.turri.yaml` (or the old `config.yaml`) or `
 
 | what | |
 | --- | --- |
-| each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH: the agents use this machine's toolchains and install none, so a missing one is yours to install |
+| each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH - and Java against a JDK, for macOS keeps a `/usr/bin/java` that only asks to install one: the agents use this machine's toolchains and install none, so a missing one is yours to install |
 | the testing scripts | what in them this machine does not have: a program named by its whole path that is not here (a macOS-only `/usr/libexec/java_home` on Linux), a toolchain they run that is not on the PATH |
 | the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through [pi](https://pi.dev), with the credentials turri's agents will use, for any provider [pi](https://pi.dev) supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials [pi](https://pi.dev) reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids [pi](https://pi.dev) knows for one it does not. `--harness-model`, `--coding-model` (`--model`) and `--judge-model` name models as the config's keys, as `turri regenerate` reads them - checked in a project or not. `--no-models` skips it |
 

package/docs/parser.md

@@ -10,6 +10,7 @@
 | `src/plain/markdown.ts` | mistletoe's AST + `PlainRenderer` (mdast + a matching serializer) |
 | `src/plain/liquid.ts` | the reference implementation's Liquid nodes + the two filters in `plain_spec.py` (liquidjs) |
 | `src/plain/files.ts` | `file_utils.open_from` / `get_loaded_templates`, base64 blob detection |
+| `src/plain/module-concepts.ts`, `src/plain/graph.ts` | nothing - turri's own, for a host: the concepts a module can name and where each is defined, and a project's \*\*\*plain as a graph of modules, items and concepts (see [hosting](hosting.md#plain-for-a-host)). The parser keeps, beside the reference's result, which module each item an import brought is written in (`importedFrom`) |
 | `src/plain/stdlib.ts` | nothing - turri's own: `stdlib/` is a reserved import prefix, read from turri's standard library only, and a project module at such a path is an error (see [the standard library](authoring-plain.md#the-standard-library)) |
 
 ## Checking \*\*\*plain

package/docs/skills-and-gates.md

@@ -37,7 +37,7 @@ metadata:
 
 A skill declares its steps with a `## Steps` section whose `###` headings are the steps; without it the whole skill is one step, which is what most skills are. Steps are never inferred from `###` headings elsewhere in the body - prose skills are full of those. Each gate becomes a conditional edge after its step; a single-step skill is gated by naming the skill itself. None of the skills turri ships declares a gate today - `brood`'s phases end on the person's confirmation alone - but a project's own skill can.
 
-`command-only: true` under `metadata:` keeps a skill from the model: it is started only by the person, with its slash command - `/brood`, `/spawn` and `/bud` are. turri registers the command for every such skill, the project's own too. Typed, the command puts what was typed in the chat as the person's message, and lets `cultivate` start the skill once; the run starting uses that up, so the model cannot start it again later on its own. Without the command, `cultivate` refuses it and the model is told to name the command to the person instead - the skill's line in `cultivate`'s list says so too.
+`command-only: true` under `metadata:` keeps a skill from the model: it is started only by the person, with its slash command - `/brood`, `/spawn` and `/bud` are. turri registers the command for every such skill, the project's own too. Typed, the command puts what was typed in the chat as the person's message, and lets `cultivate` start the skill once - and so does an option starting with the command, `/brood - an interview`, picked in the conversation's `ask_user`, which is how the chat offers `/brood`, `/spawn` or starting a project itself with no skill (`chosenCommand` in `src/skills.ts`, `src/new-project.ts`). The answer tells the model to call `cultivate` for it at once, with the person's request word for word as its context (`startPicked`), so they never type the command after picking it; the run starting uses that up, so the model cannot start it again later on its own. Without either, `cultivate` refuses it and the model is told how the person starts it - for a new project, by the choice it offers; the skill's line in `cultivate`'s list says so too.
 
 `paced: false` under `metadata:` lets a skill write \*\*\*plain changes one after another on its own: `change_plain` otherwise refuses a new change until the user has answered a question since the last one - one answer, one change, as an interview writes them. `spawn` is unpaced: the tool tells it so, and after each change to write the next at once, not to carry on with an interview it does not have.