@warlock.js/core 5.30.0 → 5.32.0

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 = /* @__PURE__ */ 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 = [.../* @__PURE__ */ 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,38 @@
+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. */
+export type AgentsMdWriteStatus = "created" | "updated" | "unchanged" | "skipped";
+/** Options of {@link writeAgentsMd}. */
+export 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}. */
+export 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() });
+ */
+export declare function writeAgentsMd(options: WriteAgentsMdOptions): WriteAgentsMdResult;
+//#endregion
+//# 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":";;;;YAQY;;YAGA;;EAEV;;EAEA,QAAQ;;EAER;;EAEA,kBAAkB;;EAElB;;;YAIU;;EAEV;EACA,QAAQ;;EAER;;;;;;;;;;;wBAYc,cAAc,SAAS,uBAAuB"}

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,29 @@
+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. */
+export type BoardMessageFields = {
+  from: string;
+  to: string;
+  item: number | null;
+  subject: string;
+  at: string;
+};
+/** A message file's contents, parsed. */
+export 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`.
+ */
+export 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.
+ */
+export declare function parseBoardMessage(text: string): ParsedBoardMessage;
+//#endregion
+//# 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":";;;YAGY;EACV;EACA;EACA;EACA;EACA;;;YAIU,qBAAqB;EAC/B;EACA,SAAS;;;;;;;wBAaK,mBACd,QAAQ,oBACR,cACA,UAAS;;;;;;wBAuCK,kBAAkB,eAAe"}

package/esm/tooling/board/board-message.mjs

@@ -0,0 +1,86 @@
+import { BOARD_VERDICT_LINES } from "./board.types.mjs";
+
+//#region ../../packages/core/src/tooling/board/board-message.ts
+/** Subjects are one line: newlines would break the front matter. */
+function oneLine(value) {
+	return value.replace(/[\r\n]+/g, " ").trim();
+}
+/**
+* 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`.
+*/
+function formatBoardMessage(fields, body, verdict = null) {
+	const lines = [
+		"---",
+		`from: ${oneLine(fields.from)}`,
+		`to: ${oneLine(fields.to)}`,
+		`item: ${fields.item ?? ""}`,
+		`subject: ${oneLine(fields.subject)}`,
+		`at: ${fields.at}`,
+		"---",
+		""
+	];
+	const text = body.replace(/\s+$/, "");
+	if (text.length > 0) lines.push(text);
+	if (verdict) {
+		if (text.length > 0) lines.push("");
+		lines.push(BOARD_VERDICT_LINES[verdict]);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/** The verdict a line spells, or `null`. */
+function verdictOf(line) {
+	const trimmed = line.trim();
+	if (trimmed === BOARD_VERDICT_LINES.approved) return "approved";
+	if (trimmed === BOARD_VERDICT_LINES["changes-requested"]) return "changes-requested";
+	return null;
+}
+/**
+* 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.
+*/
+function parseBoardMessage(text) {
+	const fields = {
+		from: "",
+		to: "",
+		item: null,
+		subject: "",
+		at: ""
+	};
+	let rest = text.replace(/\r\n/g, "\n");
+	if (rest.startsWith("---\n")) {
+		const end = rest.indexOf("\n---", 4);
+		if (end !== -1) {
+			const header = rest.slice(4, end);
+			for (const line of header.split("\n")) {
+				const separator = line.indexOf(":");
+				if (separator === -1) continue;
+				const key = line.slice(0, separator).trim();
+				const value = line.slice(separator + 1).trim();
+				if (key === "from") fields.from = value;
+				else if (key === "to") fields.to = value;
+				else if (key === "subject") fields.subject = value;
+				else if (key === "at") fields.at = value;
+				else if (key === "item") {
+					const id = Number.parseInt(value, 10);
+					fields.item = Number.isInteger(id) && id > 0 ? id : null;
+				}
+			}
+			rest = rest.slice(end + 4).replace(/^\n+/, "");
+		}
+	}
+	const lines = rest.replace(/\s+$/, "").split("\n");
+	const verdict = verdictOf(lines[lines.length - 1] ?? "");
+	if (verdict) lines.pop();
+	return {
+		...fields,
+		body: lines.join("\n").replace(/\s+$/, ""),
+		verdict
+	};
+}
+
+//#endregion
+export { formatBoardMessage, parseBoardMessage };
+//# sourceMappingURL=board-message.mjs.map

package/esm/tooling/board/board-message.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-message.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/board/board-message.ts"],"sourcesContent":["import { BOARD_VERDICT_LINES, type BoardVerdict } from \"./board.types\";\n\n/** The fields a message file's front matter carries. */\nexport type BoardMessageFields = {\n  from: string;\n  to: string;\n  item: number | null;\n  subject: string;\n  at: string;\n};\n\n/** A message file's contents, parsed. */\nexport type ParsedBoardMessage = BoardMessageFields & {\n  body: string;\n  verdict: BoardVerdict | null;\n};\n\n/** Subjects are one line: newlines would break the front matter. */\nfunction oneLine(value: string): string {\n  return value.replace(/[\\r\\n]+/g, \" \").trim();\n}\n\n/**\n * Render a message file: front matter (`from`, `to`, `item`, `subject`, `at`),\n * a blank line, the body, and — for a verdict — a final line that is exactly\n * `VERDICT: APPROVED` or `VERDICT: CHANGES REQUESTED`.\n */\nexport function formatBoardMessage(\n  fields: BoardMessageFields,\n  body: string,\n  verdict: BoardVerdict | null = null,\n): string {\n  const lines = [\n    \"---\",\n    `from: ${oneLine(fields.from)}`,\n    `to: ${oneLine(fields.to)}`,\n    `item: ${fields.item ?? \"\"}`,\n    `subject: ${oneLine(fields.subject)}`,\n    `at: ${fields.at}`,\n    \"---\",\n    \"\",\n  ];\n  const text = body.replace(/\\s+$/, \"\");\n\n  if (text.length > 0) lines.push(text);\n\n  if (verdict) {\n    if (text.length > 0) lines.push(\"\");\n    lines.push(BOARD_VERDICT_LINES[verdict]);\n  }\n\n  return `${lines.join(\"\\n\")}\\n`;\n}\n\n/** The verdict a line spells, or `null`. */\nfunction verdictOf(line: string): BoardVerdict | null {\n  const trimmed = line.trim();\n\n  if (trimmed === BOARD_VERDICT_LINES.approved) return \"approved\";\n  if (trimmed === BOARD_VERDICT_LINES[\"changes-requested\"]) return \"changes-requested\";\n\n  return null;\n}\n\n/**\n * Parse a message file. Tolerates a file without front matter (everything is\n * the body). The verdict is read from the last non-empty line only, so a\n * quoted verdict inside the body does not count.\n */\nexport function parseBoardMessage(text: string): ParsedBoardMessage {\n  const fields: BoardMessageFields = { from: \"\", to: \"\", item: null, subject: \"\", at: \"\" };\n  let rest = text.replace(/\\r\\n/g, \"\\n\");\n\n  if (rest.startsWith(\"---\\n\")) {\n    const end = rest.indexOf(\"\\n---\", 4);\n\n    if (end !== -1) {\n      const header = rest.slice(4, end);\n\n      for (const line of header.split(\"\\n\")) {\n        const separator = line.indexOf(\":\");\n\n        if (separator === -1) continue;\n\n        const key = line.slice(0, separator).trim();\n        const value = line.slice(separator + 1).trim();\n\n        if (key === \"from\") fields.from = value;\n        else if (key === \"to\") fields.to = value;\n        else if (key === \"subject\") fields.subject = value;\n        else if (key === \"at\") fields.at = value;\n        else if (key === \"item\") {\n          const id = Number.parseInt(value, 10);\n          fields.item = Number.isInteger(id) && id > 0 ? id : null;\n        }\n      }\n\n      rest = rest.slice(end + 4).replace(/^\\n+/, \"\");\n    }\n  }\n\n  const lines = rest.replace(/\\s+$/, \"\").split(\"\\n\");\n  const last = lines[lines.length - 1] ?? \"\";\n  const verdict = verdictOf(last);\n\n  if (verdict) lines.pop();\n\n  return { ...fields, body: lines.join(\"\\n\").replace(/\\s+$/, \"\"), verdict };\n}\n"],"mappings":";;;;AAkBA,SAAS,QAAQ,OAAuB;CACtC,OAAO,MAAM,QAAQ,YAAY,GAAG,CAAC,CAAC,KAAK;AAC7C;;;;;;AAOA,SAAgB,mBACd,QACA,MACA,UAA+B,MACvB;CACR,MAAM,QAAQ;EACZ;EACA,SAAS,QAAQ,OAAO,IAAI;EAC5B,OAAO,QAAQ,OAAO,EAAE;EACxB,SAAS,OAAO,QAAQ;EACxB,YAAY,QAAQ,OAAO,OAAO;EAClC,OAAO,OAAO;EACd;EACA;CACF;CACA,MAAM,OAAO,KAAK,QAAQ,QAAQ,EAAE;CAEpC,IAAI,KAAK,SAAS,GAAG,MAAM,KAAK,IAAI;CAEpC,IAAI,SAAS;EACX,IAAI,KAAK,SAAS,GAAG,MAAM,KAAK,EAAE;EAClC,MAAM,KAAK,oBAAoB,QAAQ;CACzC;CAEA,OAAO,GAAG,MAAM,KAAK,IAAI,EAAE;AAC7B;;AAGA,SAAS,UAAU,MAAmC;CACpD,MAAM,UAAU,KAAK,KAAK;CAE1B,IAAI,YAAY,oBAAoB,UAAU,OAAO;CACrD,IAAI,YAAY,oBAAoB,sBAAsB,OAAO;CAEjE,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAkB,MAAkC;CAClE,MAAM,SAA6B;EAAE,MAAM;EAAI,IAAI;EAAI,MAAM;EAAM,SAAS;EAAI,IAAI;CAAG;CACvF,IAAI,OAAO,KAAK,QAAQ,SAAS,IAAI;CAErC,IAAI,KAAK,WAAW,OAAO,GAAG;EAC5B,MAAM,MAAM,KAAK,QAAQ,SAAS,CAAC;EAEnC,IAAI,QAAQ,IAAI;GACd,MAAM,SAAS,KAAK,MAAM,GAAG,GAAG;GAEhC,KAAK,MAAM,QAAQ,OAAO,MAAM,IAAI,GAAG;IACrC,MAAM,YAAY,KAAK,QAAQ,GAAG;IAElC,IAAI,cAAc,IAAI;IAEtB,MAAM,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC,KAAK;IAC1C,MAAM,QAAQ,KAAK,MAAM,YAAY,CAAC,CAAC,CAAC,KAAK;IAE7C,IAAI,QAAQ,QAAQ,OAAO,OAAO;SAC7B,IAAI,QAAQ,MAAM,OAAO,KAAK;SAC9B,IAAI,QAAQ,WAAW,OAAO,UAAU;SACxC,IAAI,QAAQ,MAAM,OAAO,KAAK;SAC9B,IAAI,QAAQ,QAAQ;KACvB,MAAM,KAAK,OAAO,SAAS,OAAO,EAAE;KACpC,OAAO,OAAO,OAAO,UAAU,EAAE,KAAK,KAAK,IAAI,KAAK;IACtD;GACF;GAEA,OAAO,KAAK,MAAM,MAAM,CAAC,CAAC,CAAC,QAAQ,QAAQ,EAAE;EAC/C;CACF;CAEA,MAAM,QAAQ,KAAK,QAAQ,QAAQ,EAAE,CAAC,CAAC,MAAM,IAAI;CAEjD,MAAM,UAAU,UADH,MAAM,MAAM,SAAS,MAAM,EACV;CAE9B,IAAI,SAAS,MAAM,IAAI;CAEvB,OAAO;EAAE,GAAG;EAAQ,MAAM,MAAM,KAAK,IAAI,CAAC,CAAC,QAAQ,QAAQ,EAAE;EAAG;CAAQ;AAC1E"}

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

@@ -0,0 +1,121 @@
+import { BoardItem, BoardMessage, BoardState, BoardStatus, BoardVerdict } from "./board.types.mjs";
+//#region ../../packages/core/src/tooling/board/board.d.ts
+/** What `initBoard` did. */
+export type InitBoardResult = {
+  /** The board directory, relative to the project root. */
+  directory: string;
+  /** `false` when the board already existed. */
+  created: boolean;
+  /** Whether `.warlock/board/` was added to `.gitignore` by this call. */
+  gitignoreUpdated: boolean;
+};
+/** Inputs of {@link addBoardItem}. */
+export type AddBoardItemInput = {
+  title: string;
+  assignee?: string | null;
+  reviewer?: string | null;
+  /** The agent creating it, recorded in the history. */
+  by?: string | null;
+  /** Clock, for tests. */
+  now?: () => Date;
+};
+/** Inputs of {@link moveBoardItem}. */
+export type MoveBoardItemOptions = {
+  by?: string | null;
+  note?: string | null;
+  now?: () => Date;
+};
+/** Inputs of {@link sendBoardMessage}. */
+export type SendBoardMessageInput = {
+  to: string;
+  from: string;
+  subject: string;
+  body?: string;
+  /** The item the message is about. */
+  item?: number | null;
+  /** A review verdict; with `item`, also moves the item to that state. */
+  verdict?: BoardVerdict | null;
+  now?: () => Date;
+};
+/** What {@link sendBoardMessage} wrote. */
+export type SendBoardMessageResult = {
+  message: BoardMessage;
+  /** The item after the verdict moved it, when the message carried one. */
+  item: BoardItem | null;
+};
+/** Inputs of {@link watchBoard}. */
+export type WatchBoardOptions = {
+  agent: string;
+  /** Return messages numbered above this. Default: the agent's cursor. */
+  since?: number;
+  /** Give up after this long; throws `WL7404`. Default: 10 minutes. */
+  timeoutMs?: number;
+  /** Poll interval. Default: 250 ms. */
+  intervalMs?: number;
+  /** Stop early (resolves with no messages). */
+  signal?: AbortSignal;
+};
+/** What {@link watchBoard} returned. */
+export type WatchBoardResult = {
+  agent: string;
+  /** The new messages, oldest first. */
+  messages: BoardMessage[];
+  /** The agent's cursor after the call. */
+  cursor: number;
+};
+/** A file-name slug: lower-case, dashes, at most 48 characters. */
+export declare function boardSlug(value: string, fallback: string): string;
+/** Throw unless `name` is a valid agent name. */
+export declare function assertAgentName(name: string, label?: string): void;
+/** Whether a `.gitignore` already ignores the board folder (or `.warlock` as a whole). */
+export declare function gitignoreCoversBoard(content: string): boolean;
+/**
+ * Create the board (idempotent): `.warlock/board/` with its `board.json`
+ * marker, `items/`, and `.warlock/board/` in `.gitignore` unless the project
+ * already ignores it. A `.gitignore` is created when there is none.
+ */
+export declare function initBoard(cwd?: string, now?: () => Date): InitBoardResult;
+/** Every item, by id. Throws `WL7401` when the board does not exist. */
+export declare function listBoardItems(cwd?: string): BoardItem[];
+/** One item. Throws `WL7402` for an unknown id. */
+export declare function readBoardItem(id: number, cwd?: string): BoardItem;
+/** Add an item in state `todo`, with a fresh id no other writer can take. */
+export declare function addBoardItem(input: AddBoardItemInput, cwd?: string): BoardItem;
+/** The states an item in `state` may move to. */
+export declare function nextBoardStates(state: BoardState): readonly BoardState[];
+/** Throw `WL7403` unless `from → to` is in {@link BOARD_TRANSITIONS}. */
+export declare function assertBoardTransition(id: number, from: BoardState, to: BoardState): void;
+/**
+ * Move an item to another state, recording who moved it and why. Throws
+ * `WL7402` for an unknown id and `WL7403` for a move the state machine does
+ * not allow.
+ */
+export declare function moveBoardItem(id: number, to: BoardState, options?: MoveBoardItemOptions, cwd?: string): BoardItem;
+/**
+ * Write a message to `to-<agent>/NNNN-<slug>.md`. Messages are append-only:
+ * the number is reserved exclusively and the file is created with `wx`, so it
+ * is never rewritten. A verdict with an `item` also moves the item to
+ * `approved` / `changes-requested` — before the message is written, so a
+ * refused move (`WL7403`) leaves no message behind.
+ */
+export declare function sendBoardMessage(input: SendBoardMessageInput, cwd?: string): SendBoardMessageResult;
+/** The messages in an agent's inbox numbered above `since`, oldest first. */
+export declare function listBoardMessages(agent: string, options?: {
+  since?: number;
+}, cwd?: string): BoardMessage[];
+/** The highest message number `watch` has returned to `agent` (0 when none). */
+export declare function readBoardCursor(agent: string, cwd?: string): number;
+/** Record that `agent` has seen messages up to `number`. Never moves the cursor back. */
+export declare function writeBoardCursor(agent: string, number: number, cwd?: string): number;
+/** Every item and every inbox with its message count, cursor and unread count. */
+export declare function readBoardStatus(cwd?: string): BoardStatus;
+/**
+ * Block until `agent` has a message numbered above `since` (default: its
+ * cursor), then return every such message and advance the cursor past them.
+ *
+ * Polls the inbox every `intervalMs`; throws `WL7404` when `timeoutMs` passes
+ * first. An aborted `signal` resolves with no messages.
+ */
+export declare function watchBoard(options: WatchBoardOptions, cwd?: string): Promise<WatchBoardResult>;
+//#endregion
+//# sourceMappingURL=board.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"board.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/board/board.ts"],"mappings":";;;YAiCY;;EAEV;;EAEA;;EAEA;;;YAIU;EACV;EACA;EACA;;EAEA;;EAEA,YAAY;;;YAIF;EACV;EACA;EACA,YAAY;;;YAIF;EACV;EACA;EACA;EACA;;EAEA;;EAEA,UAAU;EACV,YAAY;;;YAIF;EACV,SAAS;;EAET,MAAM;;;YAII;EACV;;EAEA;;EAEA;;EAEA;;EAEA,SAAS;;;YAIC;EACV;;EAEA,UAAU;;EAEV;;;wBAgBc,UAAU,eAAe;;wBAYzB,gBAAgB,cAAc;;wBA8E9B,qBAAqB;;;;;;wBAsBrB,UACd,cACA,YAAW,OACV;;wBA4Fa,eAAe,eAAsB;;wBAerC,cAAc,YAAY,eAAsB;;wBAgBhD,aAAa,OAAO,mBAAmB,eAAsB;;wBAqC7D,gBAAgB,OAAO,sBAAsB;;wBAK7C,sBAAsB,YAAY,MAAM,YAAY,IAAI;;;;;;wBAcxD,cACd,YACA,IAAI,YACJ,UAAS,sBACT,eACC;;;;;;;;wBAoCa,iBACd,OAAO,uBACP,eACC;;wBAyDa,kBACd,eACA;EAAW;GACX,eACC;;wBA6Ba,gBAAgB,eAAe;;wBAe/B,iBAAiB,eAAe,gBAAgB;;wBAchD,gBAAgB,eAAsB;;;;;;;;wBA+BhC,WACpB,SAAS,mBACT,eACC,QAAQ"}