@warlock.js/core 5.29.0 → 5.31.0

package/esm/tooling/agents-md/agents-md-refresher.mjs

@@ -0,0 +1,72 @@
+import { writeAgentsMd } from "./write-agents-md.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/agents-md-refresher.ts
+/**
+* Keep AGENTS.md's generated section current while `warlock dev` runs: the
+* server calls `schedule()` on boot and after each reload that changed
+* routes or modules, and one refresh runs once the burst settles. Refreshes
+* never overlap; a request made during one runs after it.
+*
+* @example
+* const refresher = createAgentsMdRefresher({
+*   collect: () => inspectApp({ sections: ["routes", "models", "packages"] }),
+*   onError: (error) => devLogWarn(`AGENTS.md not refreshed: ${String(error)}`),
+* });
+* refresher.schedule();
+*/
+function createAgentsMdRefresher(options) {
+	const debounceMs = options.debounceMs ?? 1e3;
+	let timer;
+	let running = Promise.resolve();
+	let disposed = false;
+	const refresh = async () => {
+		try {
+			const report = await options.collect();
+			const result = writeAgentsMd({
+				cwd: options.cwd,
+				report,
+				create: options.create
+			});
+			options.onWrite?.(result);
+		} catch (error) {
+			options.onError?.(error);
+		}
+	};
+	const run = () => {
+		running = running.then(refresh);
+		return running;
+	};
+	return {
+		schedule() {
+			if (disposed) return;
+			if (timer !== void 0) clearTimeout(timer);
+			timer = setTimeout(() => {
+				timer = void 0;
+				run();
+			}, debounceMs);
+			timer.unref?.();
+		},
+		async flush() {
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				timer = void 0;
+			}
+			if (disposed) {
+				await running;
+				return;
+			}
+			await run();
+		},
+		dispose() {
+			disposed = true;
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				timer = void 0;
+			}
+		}
+	};
+}
+
+//#endregion
+export { createAgentsMdRefresher };
+//# sourceMappingURL=agents-md-refresher.mjs.map

package/esm/tooling/agents-md/agents-md-refresher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md-refresher.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/agents-md-refresher.ts"],"sourcesContent":["import type { InspectReport } from \"../inspect/inspect-report.types\";\nimport { writeAgentsMd, type WriteAgentsMdResult } from \"./write-agents-md\";\n\n/** Options of {@link createAgentsMdRefresher}. */\nexport type AgentsMdRefresherOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** Produce a fresh report (the dev server calls `inspectApp()` in-process). */\n  collect: () => Promise<InspectReport>;\n  /** Quiet period after the last `schedule()` before a refresh runs. Default: 1000 ms. */\n  debounceMs?: number;\n  /** Create AGENTS.md when it is missing. Default: `true`. */\n  create?: boolean;\n  /** Called with each refresh's result. */\n  onWrite?: (result: WriteAgentsMdResult) => void;\n  /** Called when a refresh fails; the error never escapes the timer. */\n  onError?: (error: unknown) => void;\n};\n\n/** A debounced AGENTS.md refresher. */\nexport type AgentsMdRefresher = {\n  /** Ask for a refresh; calls within `debounceMs` of each other collapse into one. */\n  schedule(): void;\n  /** Run a pending (or, with none pending, a fresh) refresh now and wait for it. */\n  flush(): Promise<void>;\n  /** Cancel a pending refresh; later `schedule()` calls do nothing. */\n  dispose(): void;\n};\n\n/**\n * Keep AGENTS.md's generated section current while `warlock dev` runs: the\n * server calls `schedule()` on boot and after each reload that changed\n * routes or modules, and one refresh runs once the burst settles. Refreshes\n * never overlap; a request made during one runs after it.\n *\n * @example\n * const refresher = createAgentsMdRefresher({\n *   collect: () => inspectApp({ sections: [\"routes\", \"models\", \"packages\"] }),\n *   onError: (error) => devLogWarn(`AGENTS.md not refreshed: ${String(error)}`),\n * });\n * refresher.schedule();\n */\nexport function createAgentsMdRefresher(options: AgentsMdRefresherOptions): AgentsMdRefresher {\n  const debounceMs = options.debounceMs ?? 1000;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let running: Promise<void> = Promise.resolve();\n  let disposed = false;\n\n  const refresh = async (): Promise<void> => {\n    try {\n      const report = await options.collect();\n      const result = writeAgentsMd({ cwd: options.cwd, report, create: options.create });\n\n      options.onWrite?.(result);\n    } catch (error) {\n      options.onError?.(error);\n    }\n  };\n\n  const run = (): Promise<void> => {\n    running = running.then(refresh);\n    return running;\n  };\n\n  return {\n    schedule() {\n      if (disposed) return;\n      if (timer !== undefined) clearTimeout(timer);\n\n      timer = setTimeout(() => {\n        timer = undefined;\n        void run();\n      }, debounceMs);\n      timer.unref?.();\n    },\n    async flush() {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n\n      if (disposed) {\n        await running;\n        return;\n      }\n\n      await run();\n    },\n    dispose() {\n      disposed = true;\n\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0CA,SAAgB,wBAAwB,SAAsD;CAC5F,MAAM,aAAa,QAAQ,cAAc;CACzC,IAAI;CACJ,IAAI,UAAyB,QAAQ,QAAQ;CAC7C,IAAI,WAAW;CAEf,MAAM,UAAU,YAA2B;EACzC,IAAI;GACF,MAAM,SAAS,MAAM,QAAQ,QAAQ;GACrC,MAAM,SAAS,cAAc;IAAE,KAAK,QAAQ;IAAK;IAAQ,QAAQ,QAAQ;GAAO,CAAC;GAEjF,QAAQ,UAAU,MAAM;EAC1B,SAAS,OAAO;GACd,QAAQ,UAAU,KAAK;EACzB;CACF;CAEA,MAAM,YAA2B;EAC/B,UAAU,QAAQ,KAAK,OAAO;EAC9B,OAAO;CACT;CAEA,OAAO;EACL,WAAW;GACT,IAAI,UAAU;GACd,IAAI,UAAU,QAAW,aAAa,KAAK;GAE3C,QAAQ,iBAAiB;IACvB,QAAQ;IACR,AAAK,IAAI;GACX,GAAG,UAAU;GACb,MAAM,QAAQ;EAChB;EACA,MAAM,QAAQ;GACZ,IAAI,UAAU,QAAW;IACvB,aAAa,KAAK;IAClB,QAAQ;GACV;GAEA,IAAI,UAAU;IACZ,MAAM;IACN;GACF;GAEA,MAAM,IAAI;EACZ;EACA,UAAU;GACR,WAAW;GAEX,IAAI,UAAU,QAAW;IACvB,aAAa,KAAK;IAClB,QAAQ;GACV;EACF;CACF;AACF"}

package/esm/tooling/agents-md/index.mjs

@@ -0,0 +1,7 @@
+import { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, upsertGeneratedSection } from "./agents-md-markers.mjs";
+import { listInstalledSkills, parseSkillFrontMatter, shortSkillLine } from "./installed-skills.mjs";
+import { listAppModules, renderAgentsMdSection } from "./render-agents-md.mjs";
+import { writeAgentsMd } from "./write-agents-md.mjs";
+import { createAgentsMdRefresher } from "./agents-md-refresher.mjs";
+
+export { AGENTS_MD_END, AGENTS_MD_FILE, AGENTS_MD_START, createAgentsMdRefresher, listAppModules, listInstalledSkills, parseSkillFrontMatter, renderAgentsMdSection, shortSkillLine, upsertGeneratedSection, writeAgentsMd };

package/esm/tooling/agents-md/installed-skills.d.mts

@@ -0,0 +1,30 @@
+//#region ../../packages/core/src/tooling/agents-md/installed-skills.d.ts
+/** One `SKILL.md` an installed `@warlock.js/*` package ships. */
+type InstalledSkill = {
+  /** The package, e.g. `@warlock.js/core`. */package: string; /** The skill folder name, e.g. `warlock-inspect`. */
+  slug: string; /** The `name` from the front matter (the slug when absent). */
+  name: string; /** The full `description` from the front matter (empty when absent). */
+  description: string; /** Project-relative POSIX path of the `SKILL.md`. */
+  file: string;
+};
+/** The `name` and `description` of a `SKILL.md`'s front matter. */
+declare function parseSkillFrontMatter(content: string): {
+  name?: string;
+  description?: string;
+};
+/**
+ * The first sentence of a skill description, capped at `max` characters —
+ * the one line an agent reads to decide whether to open the skill.
+ */
+declare function shortSkillLine(description: string, max?: number): string;
+/**
+ * Every skill the installed `@warlock.js/*` packages ship, read from
+ * `<cwd>/node_modules/@warlock.js/<package>/skills/<slug>/SKILL.md`.
+ * Sorted by package, then slug. Reads only the local install: no network.
+ *
+ * @param cwd The project root.
+ */
+declare function listInstalledSkills(cwd: string): InstalledSkill[];
+//#endregion
+export { InstalledSkill, listInstalledSkills, parseSkillFrontMatter, shortSkillLine };
+//# sourceMappingURL=installed-skills.d.mts.map

package/esm/tooling/agents-md/installed-skills.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installed-skills.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/installed-skills.ts"],"mappings":";;KAIY,cAAA;EAAc,4CAExB,OAAA,UAFwB;EAIxB,IAAA;EAEA,IAAA,UAEA;EAAA,WAAA,UAEI;EAAJ,IAAA;AAAA;;iBAiCc,qBAAA,CAAsB,OAAA;EAAoB,IAAA;EAAe,WAAA;AAAA;;;AAAW;AAepF;iBAAgB,cAAA,CAAe,WAAA,UAAqB,GAAS;;;AAAA;AAc7D;;;;iBAAgB,mBAAA,CAAoB,GAAA,WAAc,cAAc"}

package/esm/tooling/agents-md/installed-skills.mjs

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+
+//#region ../../packages/core/src/tooling/agents-md/installed-skills.ts
+function directories(directory) {
+	try {
+		return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() || entry.isSymbolicLink()).map((entry) => entry.name).sort();
+	} catch {
+		return [];
+	}
+}
+/** Read a front-matter scalar, unquoting YAML single/double-quoted values. */
+function frontMatterValue(frontMatter, key) {
+	const raw = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(frontMatter)?.[1]?.trim();
+	if (raw === void 0 || raw.length === 0) return void 0;
+	if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2) return raw.slice(1, -1).replace(/''/g, "'");
+	if (raw.startsWith("\"") && raw.endsWith("\"") && raw.length >= 2) return raw.slice(1, -1).replace(/\\"/g, "\"");
+	return raw;
+}
+/** The `name` and `description` of a `SKILL.md`'s front matter. */
+function parseSkillFrontMatter(content) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match?.[1]) return {};
+	return {
+		name: frontMatterValue(match[1], "name"),
+		description: frontMatterValue(match[1], "description")
+	};
+}
+/**
+* The first sentence of a skill description, capped at `max` characters —
+* the one line an agent reads to decide whether to open the skill.
+*/
+function shortSkillLine(description, max = 120) {
+	const compact = description.replace(/\s+/g, " ").trim();
+	const sentence = /^(.+?[.!?])(?:\s|$)/.exec(compact)?.[1] ?? compact;
+	return sentence.length > max ? `${sentence.slice(0, max - 1).trimEnd()}…` : sentence;
+}
+/**
+* Every skill the installed `@warlock.js/*` packages ship, read from
+* `<cwd>/node_modules/@warlock.js/<package>/skills/<slug>/SKILL.md`.
+* Sorted by package, then slug. Reads only the local install: no network.
+*
+* @param cwd The project root.
+*/
+function listInstalledSkills(cwd) {
+	const scope = path.join(cwd, "node_modules", "@warlock.js");
+	const skills = [];
+	for (const packageFolder of directories(scope)) {
+		const skillsRoot = path.join(scope, packageFolder, "skills");
+		for (const slug of directories(skillsRoot)) {
+			const file = path.join(skillsRoot, slug, "SKILL.md");
+			if (!existsSync(file)) continue;
+			let content;
+			try {
+				content = readFileSync(file, "utf8");
+			} catch {
+				continue;
+			}
+			const front = parseSkillFrontMatter(content);
+			skills.push({
+				package: `@warlock.js/${packageFolder}`,
+				slug,
+				name: front.name ?? slug,
+				description: front.description ?? "",
+				file: path.relative(cwd, file).split(path.sep).join("/")
+			});
+		}
+	}
+	return skills;
+}
+
+//#endregion
+export { listInstalledSkills, parseSkillFrontMatter, shortSkillLine };
+//# sourceMappingURL=installed-skills.mjs.map

package/esm/tooling/agents-md/installed-skills.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"installed-skills.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/installed-skills.ts"],"sourcesContent":["import { existsSync, readdirSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/** One `SKILL.md` an installed `@warlock.js/*` package ships. */\nexport type InstalledSkill = {\n  /** The package, e.g. `@warlock.js/core`. */\n  package: string;\n  /** The skill folder name, e.g. `warlock-inspect`. */\n  slug: string;\n  /** The `name` from the front matter (the slug when absent). */\n  name: string;\n  /** The full `description` from the front matter (empty when absent). */\n  description: string;\n  /** Project-relative POSIX path of the `SKILL.md`. */\n  file: string;\n};\n\nfunction directories(directory: string): string[] {\n  try {\n    return readdirSync(directory, { withFileTypes: true })\n      .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())\n      .map((entry) => entry.name)\n      .sort();\n  } catch {\n    return [];\n  }\n}\n\n/** Read a front-matter scalar, unquoting YAML single/double-quoted values. */\nfunction frontMatterValue(frontMatter: string, key: string): string | undefined {\n  const match = new RegExp(`^${key}:[ \\\\t]*(.*)$`, \"m\").exec(frontMatter);\n  const raw = match?.[1]?.trim();\n\n  if (raw === undefined || raw.length === 0) return undefined;\n\n  if (raw.startsWith(\"'\") && raw.endsWith(\"'\") && raw.length >= 2) {\n    return raw.slice(1, -1).replace(/''/g, \"'\");\n  }\n\n  if (raw.startsWith('\"') && raw.endsWith('\"') && raw.length >= 2) {\n    return raw.slice(1, -1).replace(/\\\\\"/g, '\"');\n  }\n\n  return raw;\n}\n\n/** The `name` and `description` of a `SKILL.md`'s front matter. */\nexport function parseSkillFrontMatter(content: string): { name?: string; description?: string } {\n  const match = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---/.exec(content);\n\n  if (!match?.[1]) return {};\n\n  return {\n    name: frontMatterValue(match[1], \"name\"),\n    description: frontMatterValue(match[1], \"description\"),\n  };\n}\n\n/**\n * The first sentence of a skill description, capped at `max` characters —\n * the one line an agent reads to decide whether to open the skill.\n */\nexport function shortSkillLine(description: string, max = 120): string {\n  const compact = description.replace(/\\s+/g, \" \").trim();\n  const sentence = /^(.+?[.!?])(?:\\s|$)/.exec(compact)?.[1] ?? compact;\n\n  return sentence.length > max ? `${sentence.slice(0, max - 1).trimEnd()}…` : sentence;\n}\n\n/**\n * Every skill the installed `@warlock.js/*` packages ship, read from\n * `<cwd>/node_modules/@warlock.js/<package>/skills/<slug>/SKILL.md`.\n * Sorted by package, then slug. Reads only the local install: no network.\n *\n * @param cwd The project root.\n */\nexport function listInstalledSkills(cwd: string): InstalledSkill[] {\n  const scope = path.join(cwd, \"node_modules\", \"@warlock.js\");\n  const skills: InstalledSkill[] = [];\n\n  for (const packageFolder of directories(scope)) {\n    const skillsRoot = path.join(scope, packageFolder, \"skills\");\n\n    for (const slug of directories(skillsRoot)) {\n      const file = path.join(skillsRoot, slug, \"SKILL.md\");\n\n      if (!existsSync(file)) continue;\n\n      let content: string;\n\n      try {\n        content = readFileSync(file, \"utf8\");\n      } catch {\n        continue;\n      }\n\n      const front = parseSkillFrontMatter(content);\n\n      skills.push({\n        package: `@warlock.js/${packageFolder}`,\n        slug,\n        name: front.name ?? slug,\n        description: front.description ?? \"\",\n        file: path.relative(cwd, file).split(path.sep).join(\"/\"),\n      });\n    }\n  }\n\n  return skills;\n}\n"],"mappings":";;;;AAiBA,SAAS,YAAY,WAA6B;CAChD,IAAI;EACF,OAAO,YAAY,WAAW,EAAE,eAAe,KAAK,CAAC,CAAC,CACnD,QAAQ,UAAU,MAAM,YAAY,KAAK,MAAM,eAAe,CAAC,CAAC,CAChE,KAAK,UAAU,MAAM,IAAI,CAAC,CAC1B,KAAK;CACV,QAAQ;EACN,OAAO,CAAC;CACV;AACF;;AAGA,SAAS,iBAAiB,aAAqB,KAAiC;CAE9E,MAAM,MADQ,IAAI,OAAO,IAAI,IAAI,gBAAgB,GAAG,CAAC,CAAC,KAAK,WAC3C,CAAC,GAAG,EAAE,EAAE,KAAK;CAE7B,IAAI,QAAQ,UAAa,IAAI,WAAW,GAAG,OAAO;CAElD,IAAI,IAAI,WAAW,GAAG,KAAK,IAAI,SAAS,GAAG,KAAK,IAAI,UAAU,GAC5D,OAAO,IAAI,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,OAAO,GAAG;CAG5C,IAAI,IAAI,WAAW,IAAG,KAAK,IAAI,SAAS,IAAG,KAAK,IAAI,UAAU,GAC5D,OAAO,IAAI,MAAM,GAAG,EAAE,CAAC,CAAC,QAAQ,QAAQ,IAAG;CAG7C,OAAO;AACT;;AAGA,SAAgB,sBAAsB,SAA0D;CAC9F,MAAM,QAAQ,8BAA8B,KAAK,OAAO;CAExD,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC;CAEzB,OAAO;EACL,MAAM,iBAAiB,MAAM,IAAI,MAAM;EACvC,aAAa,iBAAiB,MAAM,IAAI,aAAa;CACvD;AACF;;;;;AAMA,SAAgB,eAAe,aAAqB,MAAM,KAAa;CACrE,MAAM,UAAU,YAAY,QAAQ,QAAQ,GAAG,CAAC,CAAC,KAAK;CACtD,MAAM,WAAW,sBAAsB,KAAK,OAAO,CAAC,GAAG,MAAM;CAE7D,OAAO,SAAS,SAAS,MAAM,GAAG,SAAS,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,KAAK;AAC9E;;;;;;;;AASA,SAAgB,oBAAoB,KAA+B;CACjE,MAAM,QAAQ,KAAK,KAAK,KAAK,gBAAgB,aAAa;CAC1D,MAAM,SAA2B,CAAC;CAElC,KAAK,MAAM,iBAAiB,YAAY,KAAK,GAAG;EAC9C,MAAM,aAAa,KAAK,KAAK,OAAO,eAAe,QAAQ;EAE3D,KAAK,MAAM,QAAQ,YAAY,UAAU,GAAG;GAC1C,MAAM,OAAO,KAAK,KAAK,YAAY,MAAM,UAAU;GAEnD,IAAI,CAAC,WAAW,IAAI,GAAG;GAEvB,IAAI;GAEJ,IAAI;IACF,UAAU,aAAa,MAAM,MAAM;GACrC,QAAQ;IACN;GACF;GAEA,MAAM,QAAQ,sBAAsB,OAAO;GAE3C,OAAO,KAAK;IACV,SAAS,eAAe;IACxB;IACA,MAAM,MAAM,QAAQ;IACpB,aAAa,MAAM,eAAe;IAClC,MAAM,KAAK,SAAS,KAAK,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,GAAG;GACzD,CAAC;EACH;CACF;CAEA,OAAO;AACT"}

package/esm/tooling/agents-md/render-agents-md.d.mts

@@ -0,0 +1,33 @@
+import { InspectReport } from "../inspect/inspect-report.types.mjs";
+import { InstalledSkill } from "./installed-skills.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/render-agents-md.d.ts
+/** Options of {@link renderAgentsMdSection}. */
+type RenderAgentsMdOptions = {
+  /** Installed skills to list (see `listInstalledSkills`). Default: none listed. */skills?: readonly InstalledSkill[]; /** Module folder names under `src/app` (see `listAppModules`); merged with the ones routes and models name. */
+  modules?: readonly string[]; /** How many routes the compact list shows before pointing at `warlock inspect`. Default: 60. */
+  maxRoutes?: number;
+};
+/**
+ * The module folders under `<cwd>/src/app`, sorted. Empty when there is none.
+ *
+ * @param cwd The project root.
+ */
+declare function listAppModules(cwd: string): string[];
+/**
+ * Render the app-specific AGENTS.md section from an inspect report: the app
+ * and its Warlock packages, modules, a routes summary (unguarded writes
+ * flagged), models, the conventions `warlock check` enforces, the installed
+ * skills and the verify commands.
+ *
+ * Deterministic: no timestamps and stable ordering, so regenerating an
+ * unchanged app yields the same bytes and `writeAgentsMd` writes nothing.
+ * Returned without the markers.
+ *
+ * @param report An `inspectApp()` report (routes, models and packages are read when present).
+ * @param options Skills and module folders to include.
+ */
+declare function renderAgentsMdSection(report: InspectReport, options?: RenderAgentsMdOptions): string;
+//#endregion
+export { RenderAgentsMdOptions, listAppModules, renderAgentsMdSection };
+//# sourceMappingURL=render-agents-md.d.mts.map

package/esm/tooling/agents-md/render-agents-md.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-agents-md.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/render-agents-md.ts"],"mappings":";;;;;KAMY,qBAAA;EAAA,kFAEV,MAAA,YAAkB,cAAc;EAEhC,OAAA,sBAFA;EAIA,SAAA;AAAA;;;AAAS;AAcX;;iBAAgB,cAAA,CAAe,GAAW;;AAAA;AAqO1C;;;;;;;;;AAEqC;;iBAFrB,qBAAA,CACd,MAAA,EAAQ,aAAA,EACR,OAAA,GAAS,qBAA0B"}

package/esm/tooling/agents-md/render-agents-md.mjs

@@ -0,0 +1,195 @@
+import { shortSkillLine } from "./installed-skills.mjs";
+import path from "node:path";
+import { readdirSync } from "node:fs";
+
+//#region ../../packages/core/src/tooling/agents-md/render-agents-md.ts
+/** Methods that change state; one of these without an auth guard is flagged. */
+const MUTATING_METHODS = new Set([
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+/** Fixed method order for the per-method counts. */
+const METHOD_ORDER = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+];
+/**
+* The module folders under `<cwd>/src/app`, sorted. Empty when there is none.
+*
+* @param cwd The project root.
+*/
+function listAppModules(cwd) {
+	try {
+		return readdirSync(path.join(cwd, "src", "app"), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+	} catch {
+		return [];
+	}
+}
+/** The module a project-relative source path belongs to (`src/app/<module>/…`). */
+function moduleOf(file) {
+	return file ? /^src\/app\/([^/]+)\//.exec(file.split("\\").join("/"))?.[1] : void 0;
+}
+function compare(first, second) {
+	return first < second ? -1 : first > second ? 1 : 0;
+}
+function isUnguardedWrite(route) {
+	return MUTATING_METHODS.has(route.method.toUpperCase()) && !route.auth.required && !route.isPage;
+}
+function routeLine(route) {
+	const guard = route.auth.required ? " [auth]" : "";
+	const name = route.name ? ` ${route.name}` : "";
+	return `- \`${route.method} ${route.path}\`${guard}${name}`;
+}
+function sortRoutes(routes) {
+	return [...routes].sort((first, second) => compare(first.path, second.path) || METHOD_ORDER.indexOf(first.method) - METHOD_ORDER.indexOf(second.method) || compare(first.method, second.method));
+}
+function appSection(report) {
+	const lines = [`## ${report.app.name ?? "This app"}${report.app.version ? ` ${report.app.version}` : ""} — generated facts`, ""];
+	const packages = [...report.packages ?? []].sort((first, second) => compare(first.name, second.name));
+	if (packages.length > 0) lines.push(`Warlock packages: ${packages.map((entry) => `\`${entry.name}@${entry.version}\``).join(", ")}.`, "");
+	return lines;
+}
+function modulesSection(report, extra) {
+	const routeCounts = /* @__PURE__ */ new Map();
+	const modelCounts = /* @__PURE__ */ new Map();
+	for (const route of report.routes ?? []) {
+		const module = moduleOf(route.sourceFile);
+		if (module) routeCounts.set(module, (routeCounts.get(module) ?? 0) + 1);
+	}
+	for (const model of report.models ?? []) {
+		const module = moduleOf(model.sourceFile);
+		if (module) modelCounts.set(module, (modelCounts.get(module) ?? 0) + 1);
+	}
+	const modules = [...new Set([
+		...extra,
+		...routeCounts.keys(),
+		...modelCounts.keys()
+	])].sort();
+	if (modules.length === 0) return [];
+	return [
+		"### Modules",
+		"",
+		"Each lives in `src/app/<module>/`.",
+		"",
+		"| Module | Routes | Models |",
+		"| ------ | ------ | ------ |",
+		...modules.map((module) => `| \`${module}\` | ${routeCounts.get(module) ?? 0} | ${modelCounts.get(module) ?? 0} |`),
+		""
+	];
+}
+function routesSection(report, maxRoutes) {
+	const routes = sortRoutes(report.routes ?? []);
+	if (routes.length === 0) return [];
+	const counts = /* @__PURE__ */ new Map();
+	for (const route of routes) counts.set(route.method, (counts.get(route.method) ?? 0) + 1);
+	const methods = [...counts.keys()].sort((first, second) => (METHOD_ORDER.indexOf(first) + 1 || 99) - (METHOD_ORDER.indexOf(second) + 1 || 99) || compare(first, second));
+	const unguarded = routes.filter(isUnguardedWrite);
+	const lines = [
+		"### Routes",
+		"",
+		`${routes.length} route(s): ${methods.map((method) => `${counts.get(method) ?? 0} ${method}`).join(", ")}.`,
+		""
+	];
+	if (unguarded.length > 0) lines.push(`Mutating routes without an auth guard (confirm each is meant to be public): ${unguarded.map((route) => `\`${route.method} ${route.path}\``).join(", ")}.`, "");
+	lines.push(...routes.slice(0, maxRoutes).map(routeLine));
+	if (routes.length > maxRoutes) lines.push(`- +${routes.length - maxRoutes} more — run \`npx warlock inspect --json --section routes\``);
+	lines.push("");
+	return lines;
+}
+function modelsSection(report) {
+	const models = [...report.models ?? []].sort((first, second) => compare(first.name, second.name));
+	if (models.length === 0) return [];
+	return [
+		"### Models",
+		"",
+		...models.map((model) => {
+			const module = moduleOf(model.sourceFile);
+			const table = model.table ? ` → \`${model.table}\`` : "";
+			return `- \`${model.name}\`${table}${module ? ` (module \`${module}\`)` : ""}`;
+		}),
+		""
+	];
+}
+/** The rules `warlock check` enforces (WL9001–WL9012) and the layout every skill assumes. */
+const CONVENTIONS = [
+	"- Features live in `src/app/<module>/`; flow is one-way: `routes.ts` → controllers → services → repositories → models. Resources only map output.",
+	"- Never import auto-loaded files: `src/app/main.ts`, `src/app/<module>/routes.ts`, `main.ts`, `worker.ts`, `events/*.ts` (`WL9001`).",
+	"- No `.js` extensions in import paths (`WL9002`).",
+	"- Cross-module imports use the `app/<module>/...` alias, not `../../` (`WL9003`); relative paths stay inside a module.",
+	"- Cascade uses standard decorators: never set `\"experimentalDecorators\": true` (`WL9004`).",
+	"- Controllers are thin and read input with `request.validated()`, never `request.all()` (`WL9005`); schemas live in `schema/<action>.schema.ts` and export the value and its `Infer` type. One controller per file (`WL9011`).",
+	"- Every POST/PUT/PATCH/DELETE route is inside `guarded()` (or has auth middleware) or says `public: true` (`WL9006`).",
+	"- Redirect targets from request input go through `safeRedirect()` / `safeRedirectTarget()` (`WL9007`); logs never carry raw emails, credentials or request bodies (`WL9008`); regexes run on request input have bounded quantifiers (`WL9009`).",
+	"- Import each API from its home package: `v` from `@warlock.js/seal`, `Model` from `@warlock.js/cascade`, `router` from `@warlock.js/core`."
+];
+function skillsSection(skills) {
+	if (skills.length === 0) return [];
+	const byPackage = /* @__PURE__ */ new Map();
+	for (const skill of skills) byPackage.set(skill.package, [...byPackage.get(skill.package) ?? [], skill]);
+	const lines = [
+		"### Skills",
+		"",
+		"Installed with the packages, at `node_modules/<package>/skills/<slug>/SKILL.md`. Read the matching one before changing that area.",
+		""
+	];
+	for (const packageName of [...byPackage.keys()].sort()) {
+		lines.push(`**${packageName}**`, "");
+		const entries = [...byPackage.get(packageName) ?? []].sort((first, second) => compare(first.slug, second.slug));
+		for (const skill of entries) {
+			const line = shortSkillLine(skill.description);
+			lines.push(`- \`${skill.slug}\`${line ? ` — ${line}` : ""}`);
+		}
+		lines.push("");
+	}
+	return lines;
+}
+const VERIFY = [
+	"### Verify a change",
+	"",
+	"- `npx warlock check --changed --json` — typecheck, lint, affected tests and conventions; exit 1 = your code, 2 = this machine.",
+	"- `npx warlock inspect --json` — routes, models, config keys, events, pages, jobs from the booted app.",
+	"- `npx warlock explain <code>` — what a `WLxxxx` code means and how to fix it.",
+	"- `npx warlock trace <method> <url> --json` — send a request to the running `warlock dev` and print its devtools timeline.",
+	"- `npx warlock mcp` — the same facts and actions as an MCP server.",
+	""
+];
+/**
+* Render the app-specific AGENTS.md section from an inspect report: the app
+* and its Warlock packages, modules, a routes summary (unguarded writes
+* flagged), models, the conventions `warlock check` enforces, the installed
+* skills and the verify commands.
+*
+* Deterministic: no timestamps and stable ordering, so regenerating an
+* unchanged app yields the same bytes and `writeAgentsMd` writes nothing.
+* Returned without the markers.
+*
+* @param report An `inspectApp()` report (routes, models and packages are read when present).
+* @param options Skills and module folders to include.
+*/
+function renderAgentsMdSection(report, options = {}) {
+	return `${[
+		"<!-- Generated by `warlock agents-md` and refreshed by `warlock dev`. Write your own notes outside the warlock:generated markers; everything between them is replaced. -->",
+		"",
+		...appSection(report),
+		...modulesSection(report, options.modules ?? []),
+		...routesSection(report, options.maxRoutes ?? 60),
+		...modelsSection(report),
+		"### Conventions in force",
+		"",
+		...CONVENTIONS,
+		"",
+		...skillsSection(options.skills ?? []),
+		...VERIFY
+	].join("\n").replace(/\n+$/, "")}\n`;
+}
+
+//#endregion
+export { listAppModules, renderAgentsMdSection };
+//# sourceMappingURL=render-agents-md.mjs.map

package/esm/tooling/agents-md/render-agents-md.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-agents-md.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/render-agents-md.ts"],"sourcesContent":["import { readdirSync } from \"node:fs\";\nimport path from \"node:path\";\nimport type { InspectReport, InspectRoute } from \"../inspect/inspect-report.types\";\nimport { type InstalledSkill, shortSkillLine } from \"./installed-skills\";\n\n/** Options of {@link renderAgentsMdSection}. */\nexport type RenderAgentsMdOptions = {\n  /** Installed skills to list (see `listInstalledSkills`). Default: none listed. */\n  skills?: readonly InstalledSkill[];\n  /** Module folder names under `src/app` (see `listAppModules`); merged with the ones routes and models name. */\n  modules?: readonly string[];\n  /** How many routes the compact list shows before pointing at `warlock inspect`. Default: 60. */\n  maxRoutes?: number;\n};\n\n/** Methods that change state; one of these without an auth guard is flagged. */\nconst MUTATING_METHODS = new Set([\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\n/** Fixed method order for the per-method counts. */\nconst METHOD_ORDER = [\"GET\", \"POST\", \"PUT\", \"PATCH\", \"DELETE\", \"HEAD\", \"OPTIONS\"];\n\n/**\n * The module folders under `<cwd>/src/app`, sorted. Empty when there is none.\n *\n * @param cwd The project root.\n */\nexport function listAppModules(cwd: string): string[] {\n  try {\n    return readdirSync(path.join(cwd, \"src\", \"app\"), { withFileTypes: true })\n      .filter((entry) => entry.isDirectory())\n      .map((entry) => entry.name)\n      .sort();\n  } catch {\n    return [];\n  }\n}\n\n/** The module a project-relative source path belongs to (`src/app/<module>/…`). */\nfunction moduleOf(file: string | null): string | undefined {\n  return file ? /^src\\/app\\/([^/]+)\\//.exec(file.split(\"\\\\\").join(\"/\"))?.[1] : undefined;\n}\n\nfunction compare(first: string, second: string): number {\n  return first < second ? -1 : first > second ? 1 : 0;\n}\n\nfunction isUnguardedWrite(route: InspectRoute): boolean {\n  return MUTATING_METHODS.has(route.method.toUpperCase()) && !route.auth.required && !route.isPage;\n}\n\nfunction routeLine(route: InspectRoute): string {\n  const guard = route.auth.required ? \" [auth]\" : \"\";\n  const name = route.name ? ` ${route.name}` : \"\";\n\n  return `- \\`${route.method} ${route.path}\\`${guard}${name}`;\n}\n\nfunction sortRoutes(routes: readonly InspectRoute[]): InspectRoute[] {\n  return [...routes].sort(\n    (first, second) =>\n      compare(first.path, second.path) ||\n      METHOD_ORDER.indexOf(first.method) - METHOD_ORDER.indexOf(second.method) ||\n      compare(first.method, second.method),\n  );\n}\n\nfunction appSection(report: InspectReport): string[] {\n  const name = report.app.name ?? \"This app\";\n  const version = report.app.version ? ` ${report.app.version}` : \"\";\n  const lines = [`## ${name}${version} — generated facts`, \"\"];\n  const packages = [...(report.packages ?? [])].sort((first, second) =>\n    compare(first.name, second.name),\n  );\n\n  if (packages.length > 0) {\n    lines.push(\n      `Warlock packages: ${packages.map((entry) => `\\`${entry.name}@${entry.version}\\``).join(\", \")}.`,\n      \"\",\n    );\n  }\n\n  return lines;\n}\n\nfunction modulesSection(report: InspectReport, extra: readonly string[]): string[] {\n  const routeCounts = new Map<string, number>();\n  const modelCounts = new Map<string, number>();\n\n  for (const route of report.routes ?? []) {\n    const module = moduleOf(route.sourceFile);\n    if (module) routeCounts.set(module, (routeCounts.get(module) ?? 0) + 1);\n  }\n\n  for (const model of report.models ?? []) {\n    const module = moduleOf(model.sourceFile);\n    if (module) modelCounts.set(module, (modelCounts.get(module) ?? 0) + 1);\n  }\n\n  const modules = [...new Set([...extra, ...routeCounts.keys(), ...modelCounts.keys()])].sort();\n\n  if (modules.length === 0) return [];\n\n  return [\n    \"### Modules\",\n    \"\",\n    \"Each lives in `src/app/<module>/`.\",\n    \"\",\n    \"| Module | Routes | Models |\",\n    \"| ------ | ------ | ------ |\",\n    ...modules.map(\n      (module) =>\n        `| \\`${module}\\` | ${routeCounts.get(module) ?? 0} | ${modelCounts.get(module) ?? 0} |`,\n    ),\n    \"\",\n  ];\n}\n\nfunction routesSection(report: InspectReport, maxRoutes: number): string[] {\n  const routes = sortRoutes(report.routes ?? []);\n\n  if (routes.length === 0) return [];\n\n  const counts = new Map<string, number>();\n\n  for (const route of routes) {\n    counts.set(route.method, (counts.get(route.method) ?? 0) + 1);\n  }\n\n  const methods = [...counts.keys()].sort(\n    (first, second) =>\n      (METHOD_ORDER.indexOf(first) + 1 || 99) - (METHOD_ORDER.indexOf(second) + 1 || 99) ||\n      compare(first, second),\n  );\n  const unguarded = routes.filter(isUnguardedWrite);\n  const lines = [\n    \"### Routes\",\n    \"\",\n    `${routes.length} route(s): ${methods.map((method) => `${counts.get(method) ?? 0} ${method}`).join(\", \")}.`,\n    \"\",\n  ];\n\n  if (unguarded.length > 0) {\n    lines.push(\n      `Mutating routes without an auth guard (confirm each is meant to be public): ${unguarded\n        .map((route) => `\\`${route.method} ${route.path}\\``)\n        .join(\", \")}.`,\n      \"\",\n    );\n  }\n\n  lines.push(...routes.slice(0, maxRoutes).map(routeLine));\n\n  if (routes.length > maxRoutes) {\n    lines.push(\n      `- +${routes.length - maxRoutes} more — run \\`npx warlock inspect --json --section routes\\``,\n    );\n  }\n\n  lines.push(\"\");\n\n  return lines;\n}\n\nfunction modelsSection(report: InspectReport): string[] {\n  const models = [...(report.models ?? [])].sort((first, second) =>\n    compare(first.name, second.name),\n  );\n\n  if (models.length === 0) return [];\n\n  return [\n    \"### Models\",\n    \"\",\n    ...models.map((model) => {\n      const module = moduleOf(model.sourceFile);\n      const table = model.table ? ` → \\`${model.table}\\`` : \"\";\n\n      return `- \\`${model.name}\\`${table}${module ? ` (module \\`${module}\\`)` : \"\"}`;\n    }),\n    \"\",\n  ];\n}\n\n/** The rules `warlock check` enforces (WL9001–WL9012) and the layout every skill assumes. */\nconst CONVENTIONS = [\n  \"- Features live in `src/app/<module>/`; flow is one-way: `routes.ts` → controllers → services → repositories → models. Resources only map output.\",\n  \"- Never import auto-loaded files: `src/app/main.ts`, `src/app/<module>/routes.ts`, `main.ts`, `worker.ts`, `events/*.ts` (`WL9001`).\",\n  \"- No `.js` extensions in import paths (`WL9002`).\",\n  \"- Cross-module imports use the `app/<module>/...` alias, not `../../` (`WL9003`); relative paths stay inside a module.\",\n  '- Cascade uses standard decorators: never set `\"experimentalDecorators\": true` (`WL9004`).',\n  \"- Controllers are thin and read input with `request.validated()`, never `request.all()` (`WL9005`); schemas live in `schema/<action>.schema.ts` and export the value and its `Infer` type. One controller per file (`WL9011`).\",\n  \"- Every POST/PUT/PATCH/DELETE route is inside `guarded()` (or has auth middleware) or says `public: true` (`WL9006`).\",\n  \"- Redirect targets from request input go through `safeRedirect()` / `safeRedirectTarget()` (`WL9007`); logs never carry raw emails, credentials or request bodies (`WL9008`); regexes run on request input have bounded quantifiers (`WL9009`).\",\n  \"- Import each API from its home package: `v` from `@warlock.js/seal`, `Model` from `@warlock.js/cascade`, `router` from `@warlock.js/core`.\",\n];\n\nfunction skillsSection(skills: readonly InstalledSkill[]): string[] {\n  if (skills.length === 0) return [];\n\n  const byPackage = new Map<string, InstalledSkill[]>();\n\n  for (const skill of skills) {\n    byPackage.set(skill.package, [...(byPackage.get(skill.package) ?? []), skill]);\n  }\n\n  const lines = [\n    \"### Skills\",\n    \"\",\n    \"Installed with the packages, at `node_modules/<package>/skills/<slug>/SKILL.md`. Read the matching one before changing that area.\",\n    \"\",\n  ];\n\n  for (const packageName of [...byPackage.keys()].sort()) {\n    lines.push(`**${packageName}**`, \"\");\n\n    const entries = [...(byPackage.get(packageName) ?? [])].sort((first, second) =>\n      compare(first.slug, second.slug),\n    );\n\n    for (const skill of entries) {\n      const line = shortSkillLine(skill.description);\n\n      lines.push(`- \\`${skill.slug}\\`${line ? ` — ${line}` : \"\"}`);\n    }\n\n    lines.push(\"\");\n  }\n\n  return lines;\n}\n\nconst VERIFY = [\n  \"### Verify a change\",\n  \"\",\n  \"- `npx warlock check --changed --json` — typecheck, lint, affected tests and conventions; exit 1 = your code, 2 = this machine.\",\n  \"- `npx warlock inspect --json` — routes, models, config keys, events, pages, jobs from the booted app.\",\n  \"- `npx warlock explain <code>` — what a `WLxxxx` code means and how to fix it.\",\n  \"- `npx warlock trace <method> <url> --json` — send a request to the running `warlock dev` and print its devtools timeline.\",\n  \"- `npx warlock mcp` — the same facts and actions as an MCP server.\",\n  \"\",\n];\n\n/**\n * Render the app-specific AGENTS.md section from an inspect report: the app\n * and its Warlock packages, modules, a routes summary (unguarded writes\n * flagged), models, the conventions `warlock check` enforces, the installed\n * skills and the verify commands.\n *\n * Deterministic: no timestamps and stable ordering, so regenerating an\n * unchanged app yields the same bytes and `writeAgentsMd` writes nothing.\n * Returned without the markers.\n *\n * @param report An `inspectApp()` report (routes, models and packages are read when present).\n * @param options Skills and module folders to include.\n */\nexport function renderAgentsMdSection(\n  report: InspectReport,\n  options: RenderAgentsMdOptions = {},\n): string {\n  const lines = [\n    \"<!-- Generated by `warlock agents-md` and refreshed by `warlock dev`. Write your own notes outside the warlock:generated markers; everything between them is replaced. -->\",\n    \"\",\n    ...appSection(report),\n    ...modulesSection(report, options.modules ?? []),\n    ...routesSection(report, options.maxRoutes ?? 60),\n    ...modelsSection(report),\n    \"### Conventions in force\",\n    \"\",\n    ...CONVENTIONS,\n    \"\",\n    ...skillsSection(options.skills ?? []),\n    ...VERIFY,\n  ];\n\n  return `${lines.join(\"\\n\").replace(/\\n+$/, \"\")}\\n`;\n}\n"],"mappings":"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"}

package/esm/tooling/agents-md/write-agents-md.d.mts

@@ -0,0 +1,33 @@
+import { InspectReport } from "../inspect/inspect-report.types.mjs";
+import { InstalledSkill } from "./installed-skills.mjs";
+
+//#region ../../packages/core/src/tooling/agents-md/write-agents-md.d.ts
+/** What {@link writeAgentsMd} did. */
+type AgentsMdWriteStatus = "created" | "updated" | "unchanged" | "skipped";
+/** Options of {@link writeAgentsMd}. */
+type WriteAgentsMdOptions = {
+  /** Project root. Default: `process.cwd()`. */cwd?: string; /** The inspect report to render. */
+  report: InspectReport; /** Create AGENTS.md when it does not exist. Default: `true`; `false` reports `skipped`. */
+  create?: boolean; /** Skills to list. Default: `listInstalledSkills(cwd)`. */
+  skills?: readonly InstalledSkill[]; /** Module folders. Default: `listAppModules(cwd)`. */
+  modules?: readonly string[];
+};
+/** The result of {@link writeAgentsMd}. */
+type WriteAgentsMdResult = {
+  /** Absolute path of AGENTS.md. */file: string;
+  status: AgentsMdWriteStatus; /** The generated section, without markers. */
+  section: string;
+};
+/**
+ * Render the generated section and put it between the markers of
+ * `<cwd>/AGENTS.md`, preserving every byte outside them. Writes only when the
+ * content changed (atomically: temp file + rename). Throws `WL7501` on
+ * malformed markers, before writing anything.
+ *
+ * @example
+ * const { status } = writeAgentsMd({ report: await inspectApp() });
+ */
+declare function writeAgentsMd(options: WriteAgentsMdOptions): WriteAgentsMdResult;
+//#endregion
+export { AgentsMdWriteStatus, WriteAgentsMdOptions, WriteAgentsMdResult, writeAgentsMd };
+//# sourceMappingURL=write-agents-md.d.mts.map

package/esm/tooling/agents-md/write-agents-md.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-agents-md.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/write-agents-md.ts"],"mappings":";;;;;KAQY,mBAAA;AAAZ;AAAA,KAGY,oBAAA;gDAEV,GAAA,WAL6B;EAO7B,MAAA,EAAQ,aAAA,EAJsB;EAM9B,MAAA,YAEgC;EAAhC,MAAA,YAAkB,cAAc,IAJhC;EAMA,OAAA;AAAA;;KAIU,mBAAA;EAJV,kCAMA,IAAA;EACA,MAAA,EAAQ,mBAAmB,EAHjB;EAKV,OAAA;AAAA;;;;;;;AAAO;AAYT;;iBAAgB,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,mBAAmB"}

package/esm/tooling/agents-md/write-agents-md.mjs

@@ -0,0 +1,49 @@
+import { AGENTS_MD_FILE, upsertGeneratedSection } from "./agents-md-markers.mjs";
+import { listInstalledSkills } from "./installed-skills.mjs";
+import { listAppModules, renderAgentsMdSection } from "./render-agents-md.mjs";
+import path from "node:path";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+
+//#region ../../packages/core/src/tooling/agents-md/write-agents-md.ts
+/**
+* Render the generated section and put it between the markers of
+* `<cwd>/AGENTS.md`, preserving every byte outside them. Writes only when the
+* content changed (atomically: temp file + rename). Throws `WL7501` on
+* malformed markers, before writing anything.
+*
+* @example
+* const { status } = writeAgentsMd({ report: await inspectApp() });
+*/
+function writeAgentsMd(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const file = path.join(cwd, AGENTS_MD_FILE);
+	const section = renderAgentsMdSection(options.report, {
+		skills: options.skills ?? listInstalledSkills(cwd),
+		modules: options.modules ?? listAppModules(cwd)
+	});
+	const exists = existsSync(file);
+	if (!exists && options.create === false) return {
+		file,
+		status: "skipped",
+		section
+	};
+	const existing = exists ? readFileSync(file, "utf8") : void 0;
+	const next = upsertGeneratedSection(existing, section);
+	if (next === existing) return {
+		file,
+		status: "unchanged",
+		section
+	};
+	const temporary = `${file}.${process.pid}.tmp`;
+	writeFileSync(temporary, next, "utf8");
+	renameSync(temporary, file);
+	return {
+		file,
+		status: exists ? "updated" : "created",
+		section
+	};
+}
+
+//#endregion
+export { writeAgentsMd };
+//# sourceMappingURL=write-agents-md.mjs.map

package/esm/tooling/agents-md/write-agents-md.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-agents-md.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/agents-md/write-agents-md.ts"],"sourcesContent":["import { existsSync, readFileSync, renameSync, writeFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport type { InspectReport } from \"../inspect/inspect-report.types\";\nimport { AGENTS_MD_FILE, upsertGeneratedSection } from \"./agents-md-markers\";\nimport { type InstalledSkill, listInstalledSkills } from \"./installed-skills\";\nimport { listAppModules, renderAgentsMdSection } from \"./render-agents-md\";\n\n/** What {@link writeAgentsMd} did. */\nexport type AgentsMdWriteStatus = \"created\" | \"updated\" | \"unchanged\" | \"skipped\";\n\n/** Options of {@link writeAgentsMd}. */\nexport type WriteAgentsMdOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** The inspect report to render. */\n  report: InspectReport;\n  /** Create AGENTS.md when it does not exist. Default: `true`; `false` reports `skipped`. */\n  create?: boolean;\n  /** Skills to list. Default: `listInstalledSkills(cwd)`. */\n  skills?: readonly InstalledSkill[];\n  /** Module folders. Default: `listAppModules(cwd)`. */\n  modules?: readonly string[];\n};\n\n/** The result of {@link writeAgentsMd}. */\nexport type WriteAgentsMdResult = {\n  /** Absolute path of AGENTS.md. */\n  file: string;\n  status: AgentsMdWriteStatus;\n  /** The generated section, without markers. */\n  section: string;\n};\n\n/**\n * Render the generated section and put it between the markers of\n * `<cwd>/AGENTS.md`, preserving every byte outside them. Writes only when the\n * content changed (atomically: temp file + rename). Throws `WL7501` on\n * malformed markers, before writing anything.\n *\n * @example\n * const { status } = writeAgentsMd({ report: await inspectApp() });\n */\nexport function writeAgentsMd(options: WriteAgentsMdOptions): WriteAgentsMdResult {\n  const cwd = options.cwd ?? process.cwd();\n  const file = path.join(cwd, AGENTS_MD_FILE);\n  const section = renderAgentsMdSection(options.report, {\n    skills: options.skills ?? listInstalledSkills(cwd),\n    modules: options.modules ?? listAppModules(cwd),\n  });\n  const exists = existsSync(file);\n\n  if (!exists && options.create === false) {\n    return { file, status: \"skipped\", section };\n  }\n\n  const existing = exists ? readFileSync(file, \"utf8\") : undefined;\n  const next = upsertGeneratedSection(existing, section);\n\n  if (next === existing) {\n    return { file, status: \"unchanged\", section };\n  }\n\n  const temporary = `${file}.${process.pid}.tmp`;\n\n  writeFileSync(temporary, next, \"utf8\");\n  renameSync(temporary, file);\n\n  return { file, status: exists ? \"updated\" : \"created\", section };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0CA,SAAgB,cAAc,SAAoD;CAChF,MAAM,MAAM,QAAQ,OAAO,QAAQ,IAAI;CACvC,MAAM,OAAO,KAAK,KAAK,KAAK,cAAc;CAC1C,MAAM,UAAU,sBAAsB,QAAQ,QAAQ;EACpD,QAAQ,QAAQ,UAAU,oBAAoB,GAAG;EACjD,SAAS,QAAQ,WAAW,eAAe,GAAG;CAChD,CAAC;CACD,MAAM,SAAS,WAAW,IAAI;CAE9B,IAAI,CAAC,UAAU,QAAQ,WAAW,OAChC,OAAO;EAAE;EAAM,QAAQ;EAAW;CAAQ;CAG5C,MAAM,WAAW,SAAS,aAAa,MAAM,MAAM,IAAI;CACvD,MAAM,OAAO,uBAAuB,UAAU,OAAO;CAErD,IAAI,SAAS,UACX,OAAO;EAAE;EAAM,QAAQ;EAAa;CAAQ;CAG9C,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,IAAI;CAEzC,cAAc,WAAW,MAAM,MAAM;CACrC,WAAW,WAAW,IAAI;CAE1B,OAAO;EAAE;EAAM,QAAQ,SAAS,YAAY;EAAW;CAAQ;AACjE"}

package/esm/tooling/board/board-message.d.mts

@@ -0,0 +1,31 @@
+import { BoardVerdict } from "./board.types.mjs";
+
+//#region ../../packages/core/src/tooling/board/board-message.d.ts
+/** The fields a message file's front matter carries. */
+type BoardMessageFields = {
+  from: string;
+  to: string;
+  item: number | null;
+  subject: string;
+  at: string;
+};
+/** A message file's contents, parsed. */
+type ParsedBoardMessage = BoardMessageFields & {
+  body: string;
+  verdict: BoardVerdict | null;
+};
+/**
+ * Render a message file: front matter (`from`, `to`, `item`, `subject`, `at`),
+ * a blank line, the body, and — for a verdict — a final line that is exactly
+ * `VERDICT: APPROVED` or `VERDICT: CHANGES REQUESTED`.
+ */
+declare function formatBoardMessage(fields: BoardMessageFields, body: string, verdict?: BoardVerdict | null): string;
+/**
+ * Parse a message file. Tolerates a file without front matter (everything is
+ * the body). The verdict is read from the last non-empty line only, so a
+ * quoted verdict inside the body does not count.
+ */
+declare function parseBoardMessage(text: string): ParsedBoardMessage;
+//#endregion
+export { BoardMessageFields, ParsedBoardMessage, formatBoardMessage, parseBoardMessage };
+//# sourceMappingURL=board-message.d.mts.map

package/esm/tooling/board/board-message.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-message.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/board/board-message.ts"],"mappings":";;;;KAGY,kBAAA;EACV,IAAA;EACA,EAAA;EACA,IAAA;EACA,OAAA;EACA,EAAA;AAAA;;KAIU,kBAAA,GAAqB,kBAAA;EAC/B,IAAA;EACA,OAAA,EAAS,YAAY;AAAA;AAFvB;;;;;AAAA,iBAegB,kBAAA,CACd,MAAA,EAAQ,kBAAA,EACR,IAAA,UACA,OAAA,GAAS,YAAY;;;;AAhBA;AAavB;iBA0CgB,iBAAA,CAAkB,IAAA,WAAe,kBAAkB"}