nylorun 0.18.3-beta → 0.20.0-beta

package/dist/client/folder.js

@@ -0,0 +1,177 @@
+/**
+ * Agent folders (track T6, D79) on the command line, offline: `nylorun check [dir…]` compiles each
+ * agent folder with the compiler the Runtime runs (`@nylorun/core/folder`) and prints every
+ * diagnostic by file, line and column (`--json` for CI), and `--fix` makes the edits the fixable
+ * ones carry (track T7); `nylorun init <path>` (`init.ts`) writes a new folder. Neither reads a
+ * Runtime. `nylorun apply` saves a folder (`apply.ts`).
+ */
+import { createHash } from "node:crypto";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { AGENT_FOLDER_FILE, FolderError, checkFolder, diagnosticLine, isAgentFolder, packFolder, } from "@nylorun/agents";
+import { applyFolderFixes } from "@nylorun/core/folder";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { usageError } from "./runtime.js";
+export { initCommand, initUsage } from "./init.js";
+export const checkUsage = `nylorun check [<dir>...] [--fix] [--json]
+
+Compiles each agent folder (default .) offline, with the compiler the Runtime runs, and prints
+every problem by file, line and column. A folder holds AGENT.md; a folder without one checks each
+subfolder that has one. Exits 1 when a folder does not compile. Reads no Runtime.
+
+A problem one edit fixes says (fixable with --fix): an unknown key with one did-you-mean, CRLF
+line ends, and secrets in a SKILL.md, which go in AGENT.md's skills block.
+
+  --fix                               make those edits in the folder's files, print each, then
+                                      check again; nothing is written without it, and a file
+                                      that changed since it was checked is left as it is
+  --json                              print { "folders": [{ path, ok, manifest?, diagnostics }] }
+                                      for CI: whether each folder compiles, the manifest it
+                                      compiles to, and every diagnostic, each fixable one with
+                                      its fix; with --fix, also what was fixed and what was not`;
+/** The agent folders under `dir`: `dir` when it holds an `AGENT.md`, else each subfolder that does. */
+export async function agentFolders(dir) {
+    const root = resolve(dir);
+    if (await isAgentFolder(root))
+        return [root];
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const found = [];
+    for (const entry of entries.filter((item) => item.isDirectory()).sort((a, b) => (a.name < b.name ? -1 : 1)))
+        if (await isAgentFolder(join(root, entry.name)))
+            found.push(join(root, entry.name));
+    return found;
+}
+/** Packs the folder, or a `CliError` naming why it cannot be. */
+export async function packed(folder) {
+    return packFolder(folder).catch((error) => {
+        if (error instanceof FolderError)
+            throw new CliError(error.message, 1);
+        throw error;
+    });
+}
+/** A folder's diagnostics as lines, each path relative to `cwd`; `fixable` marks those with a fix. */
+export function diagnosticLines(folder, cwd, diagnostics, fixable = false) {
+    const prefix = relative(cwd, folder);
+    return diagnostics.map((item) => diagnosticLine(item.file && prefix ? { ...item, file: `${prefix}/${item.file}` } : item) + (fixable && item.fix ? " (fixable with --fix)" : ""));
+}
+/** How many times `check --fix` fixes and checks one folder, at most. */
+const FIX_ROUNDS = 5;
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const sameBytes = (a, b) => a.byteLength === b.byteLength && a.every((byte, index) => byte === b[index]);
+/**
+ * Makes the fix-its `diagnostics` carry in the folder's files (`applyFolderFixes`). A file is
+ * edited only when its bytes on disk are the ones checked, and written only when they still are:
+ * when one has changed by then, nothing is written.
+ */
+async function fixFolder(pack, diagnostics, cwd) {
+    const fixes = diagnostics.flatMap((item) => (item.fix ? [item.fix] : []));
+    if (fixes.length === 0)
+        return { fixed: [], unfixed: [] };
+    const filesOf = (fix) => (fix.kind === "move_skill_secrets" ? [fix.file, AGENT_FOLDER_FILE] : [fix.file]);
+    const read = new Map();
+    const texts = new Map();
+    const unreadable = new Map();
+    for (const path of new Set(fixes.flatMap(filesOf))) {
+        if (path === "runtime.json" && pack.extended) {
+            unreadable.set(path, "runtime.json extends another file, and was checked merged with it: fix it by hand");
+            continue;
+        }
+        const entry = pack.entries.find((item) => item.path === path);
+        const bytes = entry
+            ? await readFile(join(pack.dir, ...path.split("/"))).then((data) => new Uint8Array(data), () => undefined)
+            : undefined;
+        if (!entry || !bytes || sha256Hex(bytes) !== entry.sha256) {
+            unreadable.set(path, "the file changed since it was checked: check again");
+            continue;
+        }
+        read.set(path, bytes);
+        // A byte-order mark stays: the fixes keep it.
+        texts.set(path, new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes));
+    }
+    const unfixed = [];
+    const applicable = fixes.filter((fix) => {
+        const blocked = filesOf(fix).find((path) => unreadable.has(path));
+        if (blocked)
+            unfixed.push({ file: fix.file, reason: unreadable.get(blocked) });
+        return !blocked;
+    });
+    const result = applyFolderFixes(texts, applicable);
+    unfixed.push(...result.skipped.map(({ fix, reason }) => ({ file: fix.file, reason })));
+    const encoder = new TextEncoder();
+    const writes = [...result.files].map(([path, text]) => ({ target: join(pack.dir, ...path.split("/")), before: read.get(path), after: encoder.encode(text) }));
+    for (const { target, before } of writes)
+        if (!sameBytes(new Uint8Array(await readFile(target)), before))
+            throw new CliError(`${relative(cwd, target)} changed while it was being fixed: nothing was written. Check again.`, 1);
+    for (const { target, after } of writes)
+        await writeFile(target, after);
+    return { fixed: result.changes, unfixed };
+}
+/** `nylorun check [dir…] [--fix] [--json]` */
+export async function checkCommand(deps, args) {
+    const flags = parseStackFlags(args, { booleans: ["--json", "--fix"] }, checkUsage);
+    const json = flags.booleans.has("--json");
+    const fix = flags.booleans.has("--fix");
+    const cwd = deps.cwd ?? process.cwd();
+    const folders = [];
+    for (const dir of flags.rest.length > 0 ? flags.rest : ["."]) {
+        const found = await agentFolders(resolve(cwd, dir));
+        if (found.length === 0)
+            throw usageError(`${dir} holds no ${AGENT_FOLDER_FILE}, and no subfolder does.`);
+        folders.push(...found);
+    }
+    let failed = false;
+    const report = [];
+    for (const folder of folders) {
+        let pack = await packed(folder);
+        let compiled = await checkFolder(pack);
+        const fixed = { fixed: [], unfixed: [] };
+        // Checked again after each round, so what is printed is the folder as it is now. The compiler
+        // stops at a stage with errors, so a fix can show the next stage's: a few rounds take them.
+        for (let round = 0; fix && round < FIX_ROUNDS; round++) {
+            const made = await fixFolder(pack, compiled.diagnostics, cwd);
+            fixed.fixed.push(...made.fixed);
+            fixed.unfixed = made.unfixed;
+            if (made.fixed.length === 0)
+                break;
+            pack = await packed(folder);
+            compiled = await checkFolder(pack);
+        }
+        if (!compiled.manifest)
+            failed = true;
+        if (json) {
+            report.push({
+                path: relative(cwd, folder) || ".",
+                ok: compiled.manifest !== undefined,
+                ...(compiled.manifest ? { manifest: compiled.manifest } : {}),
+                diagnostics: compiled.diagnostics,
+                ...(pack.skipped.length > 0 ? { skipped: pack.skipped } : {}),
+                ...(fix ? { fixed: fixed.fixed, unfixed: fixed.unfixed } : {}),
+            });
+            continue;
+        }
+        const shown = (file) => relative(cwd, join(folder, file));
+        for (const item of fixed.fixed)
+            deps.out(`fixed ${shown(item.file)}: ${item.change}`);
+        for (const item of fixed.unfixed)
+            deps.err(`not fixed ${shown(item.file)}: ${item.reason}`);
+        for (const skipped of pack.skipped)
+            deps.err(`${relative(cwd, folder) || "."}: skipped ${skipped}`);
+        for (const line of diagnosticLines(folder, cwd, compiled.diagnostics, !fix))
+            if (compiled.manifest)
+                deps.out(line);
+            else
+                deps.err(line);
+        const label = relative(cwd, folder) || basename(folder);
+        const files = `${pack.entries.length} ${pack.entries.length === 1 ? "file" : "files"}`;
+        if (compiled.manifest)
+            deps.out(`${label}: ok, agent manifest ${compiled.manifest.name} (${files}, ${compiled.compiler})`);
+        else {
+            const errors = compiled.diagnostics.filter((item) => item.severity === "error").length;
+            deps.err(`${label}: ${errors} ${errors === 1 ? "error" : "errors"}`);
+        }
+    }
+    if (json)
+        deps.out(JSON.stringify({ folders: report }, null, 2));
+    return failed ? 1 : 0;
+}

package/dist/client/init.d.ts

@@ -0,0 +1,21 @@
+import { type StackDeps } from "../stack/commands.js";
+export declare const initUsage = "nylorun init <path> [--description <text>] [--example]\n\nWrites <path>/AGENT.md, the smallest agent folder: frontmatter with its name (the path's last\nsegment, so init agents/hello names it hello) and description, and its instructions below.\n\n  --example                           also write tools/get_order.json, mcp.json and\n                                      triggers/new-order.md, with a README.md that explains each\n\nThe first run in a project (the nearest directory with .git, else this one) also writes\n.gitattributes (* text=auto eol=lf), ignores .nylorun/credentials.json in .gitignore, and maps the\nfolder files to their JSON Schemas in .vscode/settings.json, each only when it is missing.";
+/** Where the editor finds each agent folder file's schema (design §3.10). */
+export declare const SCHEMA_BASE = "https://docs.nylorun.com/schemas/agent-folder/v1";
+/** The project `init` sets up: the nearest directory from `cwd` up with `.git`, else `cwd`. */
+export declare function projectRootOf(cwd: string): string;
+/** `json.schemas` entries for the agent folders that sit where `folder` does, under `root`. */
+export declare function schemaMappings(root: string, folder: string): {
+    fileMatch: string[];
+    url: string;
+}[];
+/**
+ * `settings` with `mappings` merged into its `json.schemas`: a mapping whose URL is there already
+ * gains the patterns it lacks. Undefined when nothing changes.
+ */
+export declare function mergeSchemaSettings(settings: Record<string, unknown>, mappings: readonly {
+    fileMatch: string[];
+    url: string;
+}[]): Record<string, unknown> | undefined;
+/** `nylorun init <path> [--description <text>] [--example]` */
+export declare function initCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/init.js

@@ -0,0 +1,210 @@
+/**
+ * `nylorun init <path>` (tracks T6 and T7): writes a new agent folder's `AGENT.md`, named after
+ * the path's last segment (`init agents/hello` names it `hello`). `--example` adds a tool, an
+ * MCP server and a trigger, each explained in the folder's README.md, and the result passes
+ * `nylorun check`. It also sets up the project, at the nearest directory with `.git` (else the
+ * working directory), once:
+ *
+ * - `.gitattributes` with `* text=auto eol=lf` when there is none, so a Windows checkout keeps
+ *   LF line endings;
+ * - `.nylorun/credentials.json` in `.gitignore` when nothing ignores it yet;
+ * - the editor's schema mapping (design §3.10): `.vscode/settings.json` `json.schemas`, merged into
+ *   the file, which is left alone when it is not plain JSON.
+ *
+ * It reads no Runtime.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { isAgentManifestName } from "@nylorun/core/contracts";
+import { AGENT_FOLDER_FILE, ignoreMatcher } from "@nylorun/agents";
+import { CliError } from "../errors.js";
+import { parseStackFlags } from "../stack/commands.js";
+import { usageError } from "./runtime.js";
+export const initUsage = `nylorun init <path> [--description <text>] [--example]
+
+Writes <path>/AGENT.md, the smallest agent folder: frontmatter with its name (the path's last
+segment, so init agents/hello names it hello) and description, and its instructions below.
+
+  --example                           also write tools/get_order.json, mcp.json and
+                                      triggers/new-order.md, with a README.md that explains each
+
+The first run in a project (the nearest directory with .git, else this one) also writes
+.gitattributes (* text=auto eol=lf), ignores .nylorun/credentials.json in .gitignore, and maps the
+folder files to their JSON Schemas in .vscode/settings.json, each only when it is missing.`;
+/** Where the editor finds each agent folder file's schema (design §3.10). */
+export const SCHEMA_BASE = "https://docs.nylorun.com/schemas/agent-folder/v1";
+/** The project `init` sets up: the nearest directory from `cwd` up with `.git`, else `cwd`. */
+export function projectRootOf(cwd) {
+    for (let directory = resolve(cwd);; directory = dirname(directory)) {
+        if (existsSync(join(directory, ".git")))
+            return directory;
+        if (dirname(directory) === directory)
+            return resolve(cwd);
+    }
+}
+/** `json.schemas` entries for the agent folders that sit where `folder` does, under `root`. */
+export function schemaMappings(root, folder) {
+    const parent = relative(root, dirname(folder)).split(sep).join("/");
+    // Folders under a parent (agents/) share one pattern; a folder at the root is named alone.
+    const base = parent === "" ? relative(root, folder).split(sep).join("/") : `${parent}/**`;
+    return [
+        { fileMatch: [`${base}/runtime.json`], url: `${SCHEMA_BASE}/runtime.json` },
+        { fileMatch: [`${base}/tools/*.json`], url: `${SCHEMA_BASE}/tool.json` },
+        { fileMatch: [`${base}/flow.json`], url: `${SCHEMA_BASE}/flow.json` },
+        { fileMatch: [`${base}/mcp.json`, `!${base}/plugins/**`], url: `${SCHEMA_BASE}/mcp.json` },
+    ];
+}
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/**
+ * `settings` with `mappings` merged into its `json.schemas`: a mapping whose URL is there already
+ * gains the patterns it lacks. Undefined when nothing changes.
+ */
+export function mergeSchemaSettings(settings, mappings) {
+    const existing = Array.isArray(settings["json.schemas"]) ? settings["json.schemas"] : [];
+    const schemas = existing.map((item) => (isObject(item) ? { ...item } : item));
+    let changed = !Array.isArray(settings["json.schemas"]);
+    for (const mapping of mappings) {
+        const found = schemas.find((item) => isObject(item) && item.url === mapping.url);
+        if (!found) {
+            schemas.push({ fileMatch: [...mapping.fileMatch], url: mapping.url });
+            changed = true;
+            continue;
+        }
+        const patterns = Array.isArray(found.fileMatch) ? found.fileMatch : [];
+        const missing = mapping.fileMatch.filter((pattern) => !patterns.includes(pattern));
+        if (missing.length === 0)
+            continue;
+        found.fileMatch = [...patterns, ...missing];
+        changed = true;
+    }
+    return changed ? { ...settings, "json.schemas": schemas } : undefined;
+}
+/** A file's text, or undefined when there is none. */
+const textOf = (path) => readFile(path, "utf8").catch(() => undefined);
+/** Sets up the project at `root` for the agent folder `folder`; each line says what it wrote. */
+async function setUpProject(root, folder, show) {
+    const notes = [];
+    const attributes = join(root, ".gitattributes");
+    if (!existsSync(attributes)) {
+        await writeFile(attributes, "* text=auto eol=lf\n", { flag: "wx" });
+        notes.push(`Wrote ${show(attributes)} (* text=auto eol=lf), so a Windows checkout keeps LF line endings.`);
+    }
+    const ignore = join(root, ".gitignore");
+    const ignoreText = (await textOf(ignore)) ?? "";
+    if (!ignoreMatcher(ignoreText)(".nylorun/credentials.json")) {
+        const separator = ignoreText === "" || ignoreText.endsWith("\n") ? "" : "\n";
+        await writeFile(ignore, `${ignoreText}${separator}.nylorun/credentials.json\n`);
+        notes.push(`Added .nylorun/credentials.json to ${show(ignore)}.`);
+    }
+    const settingsPath = join(root, ".vscode", "settings.json");
+    const settingsText = await textOf(settingsPath);
+    let settings = {};
+    if (settingsText !== undefined) {
+        try {
+            settings = JSON.parse(settingsText);
+        }
+        catch {
+            settings = undefined;
+        }
+    }
+    const mappings = schemaMappings(root, folder);
+    const merged = isObject(settings) ? mergeSchemaSettings(settings, mappings) : undefined;
+    if (!isObject(settings))
+        notes.push(`${show(settingsPath)} is not plain JSON, so it was left alone: add the agent folder schemas to its json.schemas (${SCHEMA_BASE}/<kind>.json).`);
+    else if (merged) {
+        await mkdir(dirname(settingsPath), { recursive: true });
+        await writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`);
+        notes.push(`Mapped the agent folder files to their JSON Schemas in ${show(settingsPath)}.`);
+    }
+    return notes;
+}
+/** The files `--example` adds, by path in the folder. */
+function exampleFiles(name) {
+    const tool = {
+        description: "Look up one order by its id: its status, items and total.",
+        inputSchema: {
+            type: "object",
+            properties: { orderId: { type: "string", description: "The order's id, such as A-1001." } },
+            required: ["orderId"],
+            additionalProperties: false,
+        },
+        http: { url: "https://orders.example.com/lookup", method: "POST", timeoutMs: 15000, credential: "ORDERS_TOKEN" },
+    };
+    const mcp = {
+        mcpServers: {
+            orders: {
+                type: "streamable-http",
+                url: "https://orders.example.com/mcp",
+                headers: { Authorization: "Bearer ${ORDERS_MCP_TOKEN}" },
+            },
+        },
+    };
+    const trigger = `---
+# A trigger starts a turn with no person in the chat. This one is a webhook: the Runtime gives it
+# a URL and a signing secret (nylorun agents triggers new-secret ${name} new-order), and each signed
+# POST runs the prompt below.
+# On a schedule instead: schedule: "0 9 * * 1-5" with timezone: Europe/London, and no webhook.
+# Once, at a set time: at: 2026-11-01T09:00:00+05:30, and no webhook.
+webhook: standard-webhooks
+# Each run opens a new session. A session id here sends every run to that one session.
+session: new
+---
+A new order arrived. Look it up with get_order and summarize it in two sentences.
+`;
+    const readme = `# ${name}
+
+An agent folder (\`nylorun init --example\`). \`nylorun check\` compiles it offline, and
+\`nylorun apply --agent\` saves it and makes the Agent \`${name}\`. Every file but this one is part
+of the agent; the example ones are placeholders to replace or delete.
+
+- \`AGENT.md\`: the name and description (frontmatter), then the instructions.
+- \`tools/get_order.json\`: an HTTP tool. The file name is the tool's name; the model reads its
+  \`description\` and \`inputSchema\`. \`http.credential\` names a secret slot, \`ORDERS_TOKEN\`, sent as
+  a bearer token: set it with \`nylorun agents secrets put ${name} ORDERS_TOKEN\` (piped in).
+- \`mcp.json\`: MCP servers, in Agent Plugins syntax. \`\${ORDERS_MCP_TOKEN}\` in a header is a secret
+  slot too, never a value: never write a literal token here.
+- \`triggers/new-order.md\`: a trigger. The frontmatter says when it fires (\`webhook\`, \`schedule\` or
+  \`at\`) and which session it runs in; the body is the prompt. Its comments show the other kinds.
+
+Until a required secret is set, the Agent lists it under \`attention\` (\`nylorun agents get ${name}\`).
+`;
+    return {
+        "tools/get_order.json": `${JSON.stringify(tool, null, 2)}\n`,
+        "mcp.json": `${JSON.stringify(mcp, null, 2)}\n`,
+        "triggers/new-order.md": trigger,
+        "README.md": readme,
+    };
+}
+/** `nylorun init <path> [--description <text>] [--example]` */
+export async function initCommand(deps, args) {
+    const flags = parseStackFlags(args, { values: ["--description"], booleans: ["--example"] }, initUsage);
+    const [path, ...rest] = flags.rest;
+    if (path === undefined || rest.length > 0)
+        throw usageError(`Usage: ${initUsage.split("\n")[0]}`);
+    const cwd = deps.cwd ?? process.cwd();
+    const dir = resolve(cwd, path);
+    const name = basename(dir);
+    if (!isAgentManifestName(name))
+        throw usageError(`${name} is not an agent's name: 1-64 letters, digits, '.', '_' and '-', starting with a letter or digit.`);
+    const show = (file) => relative(cwd, file) || ".";
+    const file = join(dir, AGENT_FOLDER_FILE);
+    const example = flags.booleans.has("--example");
+    const files = {
+        [AGENT_FOLDER_FILE]: `---\nname: ${name}\ndescription: ${JSON.stringify(flags.values.get("--description") ?? `Describe what ${name} does in one sentence.`)}\n---\nYou are ${name}. Write the agent's instructions here, in Markdown.\n${example ? "\nLook an order up with get_order before you answer a question about it.\n" : ""}`,
+        ...(example ? exampleFiles(name) : {}),
+    };
+    for (const relativePath of Object.keys(files))
+        if (existsSync(join(dir, relativePath)))
+            throw new CliError(`${show(join(dir, relativePath))} exists already.`, 1);
+    for (const [relativePath, text] of Object.entries(files)) {
+        await mkdir(dirname(join(dir, relativePath)), { recursive: true });
+        await writeFile(join(dir, relativePath), text, { flag: "wx" });
+    }
+    deps.out(example ? `Wrote ${show(dir)}/: ${Object.keys(files).join(", ")}.` : `Wrote ${show(file)}.`);
+    for (const note of await setUpProject(projectRootOf(cwd), dir, show))
+        deps.out(note);
+    const at = show(dir);
+    deps.out(`Next: nylorun check ${at}, then nylorun apply ${at} --agent to save it and make the Agent ${name}, then nylorun chat ${name}.`);
+    return 0;
+}

package/dist/client/migrate.js

@@ -13,6 +13,9 @@
  *
  * It writes nothing over an existing file, reads nothing from a Runtime, and prints the gaps
  * `nylorun apply` would refuse, to fix in the files first.
+ *
+ * `nylorun migrate folder <dir>` (`convert.ts`, track T7) writes the agent folder of a three-file
+ * folder.
  */
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
@@ -22,6 +25,7 @@ import { AgentManifestSchema, RuntimeManifestFileSchema, WorkflowManifestSchema,
 import { harnessSectionOf, sectionGaps } from "@nylorun/core/define";
 import { CliError } from "../errors.js";
 import { parseStackFlags } from "../stack/commands.js";
+import { migrateFolderCommand, migrateFolderUsage } from "./convert.js";
 import { readJson, usageError } from "./runtime.js";
 export const migrateUsage = `nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]
 
@@ -65,11 +69,13 @@ function hasSkills(loop) {
 export async function migrateCommand(deps, args) {
     const [version, ...rest] = args;
     if (version === "--help" || version === "-h") {
-        deps.out(migrateUsage);
+        deps.out(`${migrateUsage}\n\n${migrateFolderUsage}`);
         return 0;
     }
+    if (version === "folder")
+        return migrateFolderCommand(deps, rest);
     if (version !== "v8")
-        throw usageError(version === undefined ? migrateUsage : `nylorun migrate knows v8 only.\n${migrateUsage}`);
+        throw usageError(version === undefined ? migrateUsage : `nylorun migrate knows v8 and folder only.\n${migrateUsage}\n\n${migrateFolderUsage}`);
     const flags = parseStackFlags(rest, { values: ["--runtime", "--name", "--out"] }, migrateUsage);
     if (flags.rest.length !== 1)
         throw usageError(`Usage: ${migrateUsage.split("\n")[0]}`);

package/dist/client/plan-diff.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The text diff `nylorun apply` prints under a plan's change to the instructions (track T7): the
+ * plan carries the instructions before and after (`from`, `to`), and the lines that differ print
+ * as `-` and `+`, without the lines both keep. Pure.
+ */
+import type { AgentManifestPlan } from "@nylorun/agents";
+/**
+ * The lines that differ between `before` and `after`, in order: `- line` for a removed one and
+ * `+ line` for an added one, with `…` between changes that are apart. A longest common
+ * subsequence of lines, so a moved block shows as removed and added.
+ */
+export declare function lineDiff(before: string, after: string): string[];
+/** The diff lines to print under one of a plan's changes: the instructions' text, else none. */
+export declare function changeDiffLines(change: AgentManifestPlan["changes"][number], indent?: string): string[];

package/dist/client/plan-diff.js

@@ -0,0 +1,86 @@
+/** The most diff lines one change prints. */
+const MAX_LINES = 40;
+/** Instructions as text: a string, or each block of an array, a blank line between. */
+function textOf(value) {
+    if (value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string"))
+        return value.join("\n\n");
+    return undefined;
+}
+/**
+ * The lines that differ between `before` and `after`, in order: `- line` for a removed one and
+ * `+ line` for an added one, with `…` between changes that are apart. A longest common
+ * subsequence of lines, so a moved block shows as removed and added.
+ */
+export function lineDiff(before, after) {
+    const a = before === "" ? [] : before.split("\n");
+    const b = after === "" ? [] : after.split("\n");
+    // Lines both start and end with stay out of the table.
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start += 1;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA -= 1;
+        endB -= 1;
+    }
+    const x = a.slice(start, endA);
+    const y = b.slice(start, endB);
+    const ops = [];
+    if (x.length * y.length > 4_000_000) {
+        ops.push(...x.map((line) => ({ op: "-", line })), ...y.map((line) => ({ op: "+", line })));
+    }
+    else {
+        // lengths[i][j]: the longest common subsequence of x[i..] and y[j..].
+        const lengths = Array.from({ length: x.length + 1 }, () => new Uint32Array(y.length + 1));
+        for (let i = x.length - 1; i >= 0; i -= 1)
+            for (let j = y.length - 1; j >= 0; j -= 1)
+                lengths[i][j] = x[i] === y[j] ? lengths[i + 1][j + 1] + 1 : Math.max(lengths[i + 1][j], lengths[i][j + 1]);
+        let i = 0;
+        let j = 0;
+        while (i < x.length || j < y.length) {
+            if (i < x.length && j < y.length && x[i] === y[j]) {
+                ops.push({ op: "=", line: x[i] });
+                i += 1;
+                j += 1;
+            }
+            else if (i < x.length && (j === y.length || lengths[i + 1][j] >= lengths[i][j + 1])) {
+                ops.push({ op: "-", line: x[i] });
+                i += 1;
+            }
+            else {
+                ops.push({ op: "+", line: y[j] });
+                j += 1;
+            }
+        }
+    }
+    const lines = [];
+    let gap = false;
+    for (const { op, line } of ops) {
+        if (op === "=") {
+            gap = lines.length > 0;
+            continue;
+        }
+        if (gap)
+            lines.push("…");
+        gap = false;
+        lines.push(`${op} ${line}`.trimEnd());
+    }
+    return lines;
+}
+/** The diff lines to print under one of a plan's changes: the instructions' text, else none. */
+export function changeDiffLines(change, indent = "    ") {
+    if (change.section !== "harness" || change.path !== "instructions")
+        return [];
+    const before = textOf(change.from);
+    const after = textOf(change.to);
+    if (before === undefined || after === undefined)
+        return [];
+    const lines = lineDiff(before, after);
+    const shown = lines.length > MAX_LINES ? [...lines.slice(0, MAX_LINES), `… ${lines.length - MAX_LINES} more lines`] : lines;
+    return shown.map((line) => `${indent}${line}`);
+}

package/dist/client/watch.d.ts

@@ -0,0 +1,23 @@
+import type { StackDeps } from "../stack/commands.js";
+/** Watches `paths` (folders recursively, or files), calling `onChange` with a path that changed. */
+export type FolderWatcher = (paths: readonly string[], onChange: (path: string) => void) => {
+    close(): void;
+};
+/** `node:fs` `watch`, recursive for a folder. */
+export declare const nodeWatcher: FolderWatcher;
+export interface WatchOptions {
+    watcher?: FolderWatcher;
+    /** Ends the watch; by default SIGINT or SIGTERM. */
+    signal?: AbortSignal;
+    /** How long changes settle before a cycle (default 200 ms). */
+    debounceMs?: number;
+}
+/**
+ * Checks and plans `dirs` (apply's other flags in `args`) now and on each change, saving with
+ * `save`, until the signal ends it.
+ */
+export declare function watchApply(deps: StackDeps, run: {
+    dirs: readonly string[];
+    args: readonly string[];
+    save: boolean;
+}, options?: WatchOptions): Promise<number>;

package/dist/client/watch.js

@@ -0,0 +1,87 @@
+/**
+ * `nylorun apply --watch [--save]` (track T7, design §6): checks the folders and plans their
+ * manifests at once, then again on each change to them (debounced), until interrupted. It saves
+ * only with `--save`: each save is a new immutable version that moves the Agents tracking the
+ * name, so `--watch --save` is for a development manifest. A cycle that fails (a Runtime that
+ * refuses, a folder that does not pack) prints why and the watch goes on. The file a
+ * `runtime.json` `extends` is watched too.
+ */
+import { watch as watchFiles } from "node:fs";
+import { relative, resolve } from "node:path";
+import { applyCommand } from "./apply.js";
+import { agentFolders, checkCommand, packed } from "./folder.js";
+/** `node:fs` `watch`, recursive for a folder. */
+export const nodeWatcher = (paths, onChange) => {
+    const watchers = paths.map((path) => watchFiles(path, { recursive: true }, (_event, file) => onChange(file ? resolve(path, String(file)) : path)));
+    return { close: () => watchers.forEach((watcher) => watcher.close()) };
+};
+/** What changes that never start a cycle: version control and dependencies. */
+const QUIET = /(^|[\\/])(\.git|node_modules|\.hg|\.svn)([\\/]|$)/;
+/**
+ * Checks and plans `dirs` (apply's other flags in `args`) now and on each change, saving with
+ * `save`, until the signal ends it.
+ */
+export async function watchApply(deps, run, options = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const dirs = run.dirs.length > 0 ? run.dirs : ["."];
+    const controller = new AbortController();
+    const signal = options.signal ?? controller.signal;
+    const stop = () => controller.abort();
+    if (!options.signal) {
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    }
+    const cycle = async () => {
+        try {
+            if ((await checkCommand(deps, dirs)) === 0)
+                await applyCommand(deps, run.args, { planOnly: !run.save, checked: true });
+        }
+        catch (error) {
+            deps.err(error instanceof Error ? error.message : String(error));
+        }
+        deps.out(`Watching ${dirs.join(", ")} for changes${run.save ? ", saving each" : ""} (Ctrl-C stops).`);
+    };
+    // The folders, and the files their runtime.json extends.
+    const paths = new Set(dirs.map((dir) => resolve(cwd, dir)));
+    for (const dir of dirs)
+        for (const folder of await agentFolders(resolve(cwd, dir)).catch(() => []))
+            for (const file of (await packed(folder).catch(() => undefined))?.extended ?? [])
+                paths.add(file);
+    let running = cycle();
+    let timer;
+    let changed;
+    const watcher = (options.watcher ?? nodeWatcher)([...paths], (path) => {
+        if (QUIET.test(path))
+            return;
+        changed = path;
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            const what = changed;
+            running = running.then(async () => {
+                if (signal.aborted)
+                    return;
+                deps.out("");
+                deps.out(`${what === undefined ? "A file" : relative(cwd, what) || "."} changed: checking again.`);
+                await cycle();
+            });
+        }, options.debounceMs ?? 200);
+    });
+    try {
+        await new Promise((done) => {
+            if (signal.aborted)
+                done();
+            else
+                signal.addEventListener("abort", () => done(), { once: true });
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        watcher.close();
+        if (!options.signal) {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+        }
+    }
+    await running;
+    return 0;
+}