@warlock.js/core 5.30.0 → 5.31.0

package/esm/tooling/dev-state/dev-server-state.d.mts

@@ -0,0 +1,39 @@
+//#region ../../packages/core/src/tooling/dev-state/dev-server-state.d.ts
+/** Where `warlock dev` records the address of the running server, under the project root. */
+declare const DEV_SERVER_STATE_FILE = ".warlock/dev-server.json";
+/**
+ * What a running `warlock dev` worker records about itself, so `warlock trace`
+ * and `warlock mcp` can find it without guessing a port.
+ *
+ * Written once the server is ready, rewritten when `--mcp` starts, and removed
+ * when the worker shuts down. A crashed worker can leave a stale file behind,
+ * so readers confirm the server answers before trusting it.
+ */
+type DevServerState = {
+  schemaVersion: 1; /** The worker process id (informational: readers never signal it). */
+  pid: number; /** The address to send requests to, e.g. `http://localhost:2030`. */
+  url: string; /** ISO time the worker became ready. */
+  startedAt: string; /** The devtools mount, when `@warlock.js/devtools` was registered. */
+  devtools: {
+    path: string;
+  } | null; /** The MCP endpoint `warlock dev --mcp` serves, when it is on. */
+  mcp: {
+    url: string;
+  } | null;
+};
+/** Narrow parsed JSON to a {@link DevServerState}; `undefined` for anything else. */
+declare function parseDevServerState(value: unknown): DevServerState | undefined;
+/** The recorded state, or `undefined` when no dev server recorded one. */
+declare function readDevServerState(cwd?: string): DevServerState | undefined;
+/** Record the state atomically (temp file + rename), creating `.warlock/` when needed. */
+declare function writeDevServerState(state: DevServerState, cwd?: string): void;
+/** Merge fields into the recorded state; a no-op when there is none. */
+declare function updateDevServerState(patch: Partial<Omit<DevServerState, "schemaVersion">>, cwd?: string): void;
+/**
+ * Remove the state file — only when it still belongs to `pid`, so a worker
+ * that shuts down late never deletes the record of the worker that replaced it.
+ */
+declare function removeDevServerState(pid?: number, cwd?: string): void;
+//#endregion
+export { DEV_SERVER_STATE_FILE, DevServerState, parseDevServerState, readDevServerState, removeDevServerState, updateDevServerState, writeDevServerState };
+//# sourceMappingURL=dev-server-state.d.mts.map

package/esm/tooling/dev-state/dev-server-state.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server-state.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/dev-state/dev-server-state.ts"],"mappings":";;cAIa,qBAAA;;;;AAAqB;AAUlC;;;;KAAY,cAAA;EACV,aAAA,KAIA;EAFA,GAAA,UAMA;EAJA,GAAA,UAMA;EAJA,SAAA,UAIU;EAFV,QAAA;IAAY,IAAA;EAAA;EAEZ,GAAA;IAAO,GAAA;EAAA;AAAA;;iBAYO,mBAAA,CAAoB,KAAA,YAAiB,cAAc;AAsBI;AAAA,iBAAvD,kBAAA,CAAmB,GAAA,YAAsB,cAAc;;iBAavD,mBAAA,CAAoB,KAAA,EAAO,cAAc,EAAE,GAAA;;iBAU3C,oBAAA,CACd,KAAA,EAAO,OAAA,CAAQ,IAAA,CAAK,cAAA,qBACpB,GAAA;;;;AAZ4E;iBAyB9D,oBAAA,CAAqB,GAAA,WAAmB,GAAmB"}

package/esm/tooling/dev-state/dev-server-state.mjs

@@ -0,0 +1,67 @@
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+
+//#region ../../packages/core/src/tooling/dev-state/dev-server-state.ts
+/** Where `warlock dev` records the address of the running server, under the project root. */
+const DEV_SERVER_STATE_FILE = ".warlock/dev-server.json";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function statePath(cwd) {
+	return path.join(cwd, DEV_SERVER_STATE_FILE);
+}
+/** Narrow parsed JSON to a {@link DevServerState}; `undefined` for anything else. */
+function parseDevServerState(value) {
+	if (!isRecord(value) || value.schemaVersion !== 1) return void 0;
+	if (typeof value.url !== "string" || typeof value.pid !== "number") return void 0;
+	const devtools = isRecord(value.devtools) && typeof value.devtools.path === "string" ? { path: value.devtools.path } : null;
+	const mcp = isRecord(value.mcp) && typeof value.mcp.url === "string" ? { url: value.mcp.url } : null;
+	return {
+		schemaVersion: 1,
+		pid: value.pid,
+		url: value.url,
+		startedAt: typeof value.startedAt === "string" ? value.startedAt : "",
+		devtools,
+		mcp
+	};
+}
+/** The recorded state, or `undefined` when no dev server recorded one. */
+function readDevServerState(cwd = process.cwd()) {
+	const file = statePath(cwd);
+	if (!existsSync(file)) return void 0;
+	try {
+		return parseDevServerState(JSON.parse(readFileSync(file, "utf8")));
+	} catch {
+		return;
+	}
+}
+/** Record the state atomically (temp file + rename), creating `.warlock/` when needed. */
+function writeDevServerState(state, cwd = process.cwd()) {
+	const file = statePath(cwd);
+	const temporary = `${file}.${process.pid}.tmp`;
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+	renameSync(temporary, file);
+}
+/** Merge fields into the recorded state; a no-op when there is none. */
+function updateDevServerState(patch, cwd = process.cwd()) {
+	const current = readDevServerState(cwd);
+	if (!current) return;
+	writeDevServerState({
+		...current,
+		...patch
+	}, cwd);
+}
+/**
+* Remove the state file — only when it still belongs to `pid`, so a worker
+* that shuts down late never deletes the record of the worker that replaced it.
+*/
+function removeDevServerState(pid = process.pid, cwd = process.cwd()) {
+	const current = readDevServerState(cwd);
+	if (current && current.pid !== pid) return;
+	rmSync(statePath(cwd), { force: true });
+}
+
+//#endregion
+export { DEV_SERVER_STATE_FILE, parseDevServerState, readDevServerState, removeDevServerState, updateDevServerState, writeDevServerState };
+//# sourceMappingURL=dev-server-state.mjs.map

package/esm/tooling/dev-state/dev-server-state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server-state.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/dev-state/dev-server-state.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from \"node:fs\";\nimport path from \"node:path\";\n\n/** Where `warlock dev` records the address of the running server, under the project root. */\nexport const DEV_SERVER_STATE_FILE = \".warlock/dev-server.json\";\n\n/**\n * What a running `warlock dev` worker records about itself, so `warlock trace`\n * and `warlock mcp` can find it without guessing a port.\n *\n * Written once the server is ready, rewritten when `--mcp` starts, and removed\n * when the worker shuts down. A crashed worker can leave a stale file behind,\n * so readers confirm the server answers before trusting it.\n */\nexport type DevServerState = {\n  schemaVersion: 1;\n  /** The worker process id (informational: readers never signal it). */\n  pid: number;\n  /** The address to send requests to, e.g. `http://localhost:2030`. */\n  url: string;\n  /** ISO time the worker became ready. */\n  startedAt: string;\n  /** The devtools mount, when `@warlock.js/devtools` was registered. */\n  devtools: { path: string } | null;\n  /** The MCP endpoint `warlock dev --mcp` serves, when it is on. */\n  mcp: { url: string } | null;\n};\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction statePath(cwd: string): string {\n  return path.join(cwd, DEV_SERVER_STATE_FILE);\n}\n\n/** Narrow parsed JSON to a {@link DevServerState}; `undefined` for anything else. */\nexport function parseDevServerState(value: unknown): DevServerState | undefined {\n  if (!isRecord(value) || value.schemaVersion !== 1) return undefined;\n  if (typeof value.url !== \"string\" || typeof value.pid !== \"number\") return undefined;\n\n  const devtools =\n    isRecord(value.devtools) && typeof value.devtools.path === \"string\"\n      ? { path: value.devtools.path }\n      : null;\n  const mcp =\n    isRecord(value.mcp) && typeof value.mcp.url === \"string\" ? { url: value.mcp.url } : null;\n\n  return {\n    schemaVersion: 1,\n    pid: value.pid,\n    url: value.url,\n    startedAt: typeof value.startedAt === \"string\" ? value.startedAt : \"\",\n    devtools,\n    mcp,\n  };\n}\n\n/** The recorded state, or `undefined` when no dev server recorded one. */\nexport function readDevServerState(cwd = process.cwd()): DevServerState | undefined {\n  const file = statePath(cwd);\n\n  if (!existsSync(file)) return undefined;\n\n  try {\n    return parseDevServerState(JSON.parse(readFileSync(file, \"utf8\")));\n  } catch {\n    return undefined;\n  }\n}\n\n/** Record the state atomically (temp file + rename), creating `.warlock/` when needed. */\nexport function writeDevServerState(state: DevServerState, cwd = process.cwd()): void {\n  const file = statePath(cwd);\n  const temporary = `${file}.${process.pid}.tmp`;\n\n  mkdirSync(path.dirname(file), { recursive: true });\n  writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\\n`, \"utf8\");\n  renameSync(temporary, file);\n}\n\n/** Merge fields into the recorded state; a no-op when there is none. */\nexport function updateDevServerState(\n  patch: Partial<Omit<DevServerState, \"schemaVersion\">>,\n  cwd = process.cwd(),\n): void {\n  const current = readDevServerState(cwd);\n\n  if (!current) return;\n\n  writeDevServerState({ ...current, ...patch }, cwd);\n}\n\n/**\n * Remove the state file — only when it still belongs to `pid`, so a worker\n * that shuts down late never deletes the record of the worker that replaced it.\n */\nexport function removeDevServerState(pid = process.pid, cwd = process.cwd()): void {\n  const current = readDevServerState(cwd);\n\n  if (current && current.pid !== pid) return;\n\n  rmSync(statePath(cwd), { force: true });\n}\n"],"mappings":";;;;;AAIA,MAAa,wBAAwB;AAwBrC,SAAS,SAAS,OAAkD;CAClE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,UAAU,KAAqB;CACtC,OAAO,KAAK,KAAK,KAAK,qBAAqB;AAC7C;;AAGA,SAAgB,oBAAoB,OAA4C;CAC9E,IAAI,CAAC,SAAS,KAAK,KAAK,MAAM,kBAAkB,GAAG,OAAO;CAC1D,IAAI,OAAO,MAAM,QAAQ,YAAY,OAAO,MAAM,QAAQ,UAAU,OAAO;CAE3E,MAAM,WACJ,SAAS,MAAM,QAAQ,KAAK,OAAO,MAAM,SAAS,SAAS,WACvD,EAAE,MAAM,MAAM,SAAS,KAAK,IAC5B;CACN,MAAM,MACJ,SAAS,MAAM,GAAG,KAAK,OAAO,MAAM,IAAI,QAAQ,WAAW,EAAE,KAAK,MAAM,IAAI,IAAI,IAAI;CAEtF,OAAO;EACL,eAAe;EACf,KAAK,MAAM;EACX,KAAK,MAAM;EACX,WAAW,OAAO,MAAM,cAAc,WAAW,MAAM,YAAY;EACnE;EACA;CACF;AACF;;AAGA,SAAgB,mBAAmB,MAAM,QAAQ,IAAI,GAA+B;CAClF,MAAM,OAAO,UAAU,GAAG;CAE1B,IAAI,CAAC,WAAW,IAAI,GAAG,OAAO;CAE9B,IAAI;EACF,OAAO,oBAAoB,KAAK,MAAM,aAAa,MAAM,MAAM,CAAC,CAAC;CACnE,QAAQ;EACN;CACF;AACF;;AAGA,SAAgB,oBAAoB,OAAuB,MAAM,QAAQ,IAAI,GAAS;CACpF,MAAM,OAAO,UAAU,GAAG;CAC1B,MAAM,YAAY,GAAG,KAAK,GAAG,QAAQ,IAAI;CAEzC,UAAU,KAAK,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;CACjD,cAAc,WAAW,GAAG,KAAK,UAAU,OAAO,MAAM,CAAC,EAAE,KAAK,MAAM;CACtE,WAAW,WAAW,IAAI;AAC5B;;AAGA,SAAgB,qBACd,OACA,MAAM,QAAQ,IAAI,GACZ;CACN,MAAM,UAAU,mBAAmB,GAAG;CAEtC,IAAI,CAAC,SAAS;CAEd,oBAAoB;EAAE,GAAG;EAAS,GAAG;CAAM,GAAG,GAAG;AACnD;;;;;AAMA,SAAgB,qBAAqB,MAAM,QAAQ,KAAK,MAAM,QAAQ,IAAI,GAAS;CACjF,MAAM,UAAU,mBAAmB,GAAG;CAEtC,IAAI,WAAW,QAAQ,QAAQ,KAAK;CAEpC,OAAO,UAAU,GAAG,GAAG,EAAE,OAAO,KAAK,CAAC;AACxC"}

package/esm/tooling/devtools/devtools-client.d.mts

@@ -0,0 +1,91 @@
+//#region ../../packages/core/src/tooling/devtools/devtools-client.d.ts
+/**
+ * A client for the JSON API `@warlock.js/devtools` mounts on the running dev
+ * server (`GET <path>/api/requests`, `GET <path>/api/requests/:id`).
+ *
+ * Shapes are mirrored structurally rather than imported: devtools is an
+ * optional dev dependency, and this module must load without it.
+ */
+/** The devtools mount every app uses unless it wired devtools by hand. */
+declare const DEFAULT_DEVTOOLS_PATH = "/__warlock";
+/** The `fetch` this client calls; injectable for tests. */
+type DevtoolsFetch = (input: string, init?: RequestInit) => Promise<Response>;
+/** One timed phase: `route.match`, `middleware` (with `attrs.name`), `validation`, `handler`. */
+type DevtoolsPhaseRecord = {
+  name: string;
+  startedAt: number;
+  durationMs: number;
+  attrs?: Record<string, unknown>;
+};
+/** The row `GET <path>/api/requests` returns. */
+type DevtoolsRequestSummaryRecord = {
+  id: string;
+  method: string;
+  path: string;
+  route?: string;
+  status?: number;
+  startedAt: number;
+  durationMs?: number;
+  queryCount: number;
+  warningCount: number;
+};
+/** Everything devtools recorded for one request (`GET <path>/api/requests/:id`). */
+type DevtoolsRequestRecord = {
+  id: string;
+  method: string;
+  path: string;
+  route?: string;
+  status?: number;
+  startedAt: number; /** Absent while the request is still in flight. */
+  durationMs?: number;
+  error?: string;
+  phases: DevtoolsPhaseRecord[]; /** Queries: `sql`/`collection`, `durationMs`, `shape`, `caller`, `error`. */
+  queries: Record<string, unknown>[];
+  cache: Record<string, unknown>[];
+  logs: Record<string, unknown>[];
+  mails: string[]; /** `{ type: "n+1", message, shape, count, caller }` entries. */
+  warnings: Record<string, unknown>[];
+};
+/** Where the dev server and its devtools API live. */
+type DevtoolsEndpoint = {
+  /** The dev server origin, e.g. `http://localhost:2030`. */url: string; /** The devtools mount, e.g. `/__warlock`. */
+  devtoolsPath: string;
+};
+/** Options of {@link connectDevtools}. */
+type ConnectDevtoolsOptions = {
+  /** Project root, where `.warlock/dev-server.json` is read. Default: `process.cwd()`. */cwd?: string; /** The dev server address; overrides the recorded one. */
+  url?: string; /** The devtools mount; overrides the recorded one. */
+  devtoolsPath?: string;
+  fetch?: DevtoolsFetch;
+};
+/** A connected devtools API. */
+type DevtoolsClient = DevtoolsEndpoint & {
+  /** The summaries devtools holds, newest last (the order the collector keeps). */listRequests(): Promise<DevtoolsRequestSummaryRecord[]>; /** One request's full record, or `undefined` when devtools does not hold it. */
+  getRequest(id: string): Promise<DevtoolsRequestRecord | undefined>;
+  /**
+   * Poll until the request is recorded AND settled (`durationMs` set), or the
+   * timeout passes. On timeout, resolves the last record seen (still without
+   * `durationMs`), or `undefined` when devtools never recorded the request.
+   */
+  waitForRequest(id: string, options?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+  }): Promise<DevtoolsRequestRecord | undefined>;
+};
+/** Narrow one summary row; `undefined` when it is not one. */
+declare function parseRequestSummary(value: unknown): DevtoolsRequestSummaryRecord | undefined;
+/** Narrow a full request record; `undefined` when it is not one. */
+declare function parseRequestRecord(value: unknown): DevtoolsRequestRecord | undefined;
+/** Where the dev server is: the explicit option, else `.warlock/dev-server.json`. Throws `WL8008`. */
+declare function resolveDevServerEndpoint(options?: ConnectDevtoolsOptions): DevtoolsEndpoint;
+/**
+ * Connect to the devtools API of the running dev server.
+ *
+ * Throws `WL8008` when no dev server is recorded or it does not answer, and
+ * `WL8009` when it answers but devtools is not mounted (404, or anything that
+ * is not the devtools JSON).
+ */
+declare function connectDevtools(options?: ConnectDevtoolsOptions): Promise<DevtoolsClient>;
+//#endregion
+export { ConnectDevtoolsOptions, DEFAULT_DEVTOOLS_PATH, DevtoolsClient, DevtoolsEndpoint, DevtoolsFetch, DevtoolsPhaseRecord, DevtoolsRequestRecord, DevtoolsRequestSummaryRecord, connectDevtools, parseRequestRecord, parseRequestSummary, resolveDevServerEndpoint };
+//# sourceMappingURL=devtools-client.d.mts.map

package/esm/tooling/devtools/devtools-client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-client.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/devtools/devtools-client.ts"],"mappings":";;AAYA;;;;AAAkC;AAGlC;;cAHa,qBAAA;;KAGD,aAAA,IAAiB,KAAA,UAAe,IAAA,GAAO,WAAA,KAAgB,OAAA,CAAQ,QAAA;;KAG/D,mBAAA;EACV,IAAA;EACA,SAAA;EACA,UAAA;EACA,KAAA,GAAQ,MAAM;AAAA;;KAIJ,4BAAA;EACV,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,SAAA;EACA,UAAA;EACA,UAAA;EACA,YAAA;AAAA;;KAIU,qBAAA;EACV,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,SAAA,UAhBA;EAkBA,UAAA;EACA,KAAA;EACA,MAAA,EAAQ,mBAAA,IAhBR;EAkBA,OAAA,EAAS,MAAA;EACT,KAAA,EAAO,MAAA;EACP,IAAA,EAAM,MAAA;EACN,KAAA,YAfU;EAiBV,QAAA,EAAU,MAAA;AAAA;;KAIA,gBAAA;EARH,2DAUP,GAAA,UANU;EAQV,YAAY;AAAA;;KAIF,sBAAA;EA1BV,wFA4BA,GAAA,WA1BA;EA4BA,GAAA,WAzBA;EA2BA,YAAA;EACA,KAAA,GAAQ,aAAa;AAAA;;KAIX,cAAA,GAAiB,gBAAA;EA3B3B,iFA6BA,YAAA,IAAgB,OAAA,CAAQ,4BAAA,KA5BxB;EA8BA,UAAA,CAAW,EAAA,WAAa,OAAA,CAAQ,qBAAA;EA7BhC;;;;AAEgB;EAiChB,cAAA,CACE,EAAA,UACA,OAAA;IAAY,SAAA;IAAoB,UAAA;EAAA,IAC/B,OAAA,CAAQ,qBAAA;AAAA;AAxBb;AAAA,iBA4CgB,mBAAA,CAAoB,KAAA,YAAiB,4BAA4B;;iBAmBjE,kBAAA,CAAmB,KAAA,YAAiB,qBAAqB;;iBAsDzD,wBAAA,CAAyB,OAAA,GAAS,sBAAA,GAA8B,gBAAgB;;;;;AA9GzE;AAIvB;;iBAmIsB,eAAA,CACpB,OAAA,GAAS,sBAAA,GACR,OAAA,CAAQ,cAAA"}

package/esm/tooling/devtools/devtools-client.mjs

@@ -0,0 +1,155 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import { DEV_SERVER_STATE_FILE, readDevServerState } from "../dev-state/dev-server-state.mjs";
+
+//#region ../../packages/core/src/tooling/devtools/devtools-client.ts
+/**
+* A client for the JSON API `@warlock.js/devtools` mounts on the running dev
+* server (`GET <path>/api/requests`, `GET <path>/api/requests/:id`).
+*
+* Shapes are mirrored structurally rather than imported: devtools is an
+* optional dev dependency, and this module must load without it.
+*/
+/** The devtools mount every app uses unless it wired devtools by hand. */
+const DEFAULT_DEVTOOLS_PATH = "/__warlock";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function records(value) {
+	return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function optionalNumber(value) {
+	return typeof value === "number" ? value : void 0;
+}
+function optionalString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+/** Narrow one summary row; `undefined` when it is not one. */
+function parseRequestSummary(value) {
+	if (!isRecord(value)) return void 0;
+	if (typeof value.id !== "string" || typeof value.method !== "string") return void 0;
+	if (typeof value.path !== "string") return void 0;
+	return {
+		id: value.id,
+		method: value.method,
+		path: value.path,
+		route: optionalString(value.route),
+		status: optionalNumber(value.status),
+		startedAt: optionalNumber(value.startedAt) ?? 0,
+		durationMs: optionalNumber(value.durationMs),
+		queryCount: optionalNumber(value.queryCount) ?? 0,
+		warningCount: optionalNumber(value.warningCount) ?? 0
+	};
+}
+/** Narrow a full request record; `undefined` when it is not one. */
+function parseRequestRecord(value) {
+	if (!isRecord(value)) return void 0;
+	if (typeof value.id !== "string" || typeof value.method !== "string") return void 0;
+	if (typeof value.path !== "string") return void 0;
+	const phases = records(value.phases).flatMap((phase) => typeof phase.name === "string" ? [{
+		name: phase.name,
+		startedAt: optionalNumber(phase.startedAt) ?? 0,
+		durationMs: optionalNumber(phase.durationMs) ?? 0,
+		...isRecord(phase.attrs) ? { attrs: phase.attrs } : {}
+	}] : []);
+	return {
+		id: value.id,
+		method: value.method,
+		path: value.path,
+		route: optionalString(value.route),
+		status: optionalNumber(value.status),
+		startedAt: optionalNumber(value.startedAt) ?? 0,
+		durationMs: optionalNumber(value.durationMs),
+		error: optionalString(value.error),
+		phases,
+		queries: records(value.queries),
+		cache: records(value.cache),
+		logs: records(value.logs),
+		mails: Array.isArray(value.mails) ? value.mails.filter((mail) => typeof mail === "string") : [],
+		warnings: records(value.warnings)
+	};
+}
+function errorMessage(error) {
+	if (error instanceof Error) {
+		const cause = error.cause;
+		const code = isRecord(cause) && typeof cause.code === "string" ? ` (${cause.code})` : "";
+		return `${error.message}${code}`;
+	}
+	return String(error);
+}
+function trimSlash(value) {
+	return value.replace(/\/+$/, "");
+}
+/** Where the dev server is: the explicit option, else `.warlock/dev-server.json`. Throws `WL8008`. */
+function resolveDevServerEndpoint(options = {}) {
+	const state = options.url === void 0 ? readDevServerState(options.cwd) : void 0;
+	const url = options.url ?? state?.url;
+	if (!url) throw new WarlockError("WL8008", `No running dev server is recorded in ${DEV_SERVER_STATE_FILE}. Start \`warlock dev\` in this project, or pass --url.`);
+	const devtoolsPath = trimSlash(options.devtoolsPath ?? state?.devtools?.path ?? "/__warlock");
+	return {
+		url: trimSlash(url),
+		devtoolsPath
+	};
+}
+/**
+* Connect to the devtools API of the running dev server.
+*
+* Throws `WL8008` when no dev server is recorded or it does not answer, and
+* `WL8009` when it answers but devtools is not mounted (404, or anything that
+* is not the devtools JSON).
+*/
+async function connectDevtools(options = {}) {
+	const endpoint = resolveDevServerEndpoint(options);
+	const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+	const api = `${endpoint.url}${endpoint.devtoolsPath}/api`;
+	const getJson = async (url) => {
+		let response;
+		try {
+			response = await fetcher(url, { headers: { accept: "application/json" } });
+		} catch (error) {
+			throw new WarlockError("WL8008", `The dev server at ${endpoint.url} is not reachable: ${errorMessage(error)}. Start \`warlock dev\`, or pass --url.`, { cause: error });
+		}
+		const text = await response.text();
+		let body;
+		try {
+			body = text.length > 0 ? JSON.parse(text) : void 0;
+		} catch {
+			body = void 0;
+		}
+		return {
+			status: response.status,
+			body
+		};
+	};
+	const probe = await getJson(`${api}/requests`);
+	if (probe.status !== 200 || !Array.isArray(probe.body)) throw new WarlockError("WL8009", `The dev server at ${endpoint.url} answered ${probe.status} on ${endpoint.devtoolsPath}/api/requests: devtools is not running there. Install it with \`warlock add devtools\` and restart \`warlock dev\`.`);
+	const client = {
+		...endpoint,
+		async listRequests() {
+			const { body } = await getJson(`${api}/requests`);
+			return Array.isArray(body) ? body.flatMap((row) => {
+				const summary = parseRequestSummary(row);
+				return summary ? [summary] : [];
+			}) : [];
+		},
+		async getRequest(id) {
+			const { status, body } = await getJson(`${api}/requests/${encodeURIComponent(id)}`);
+			return status === 200 ? parseRequestRecord(body) : void 0;
+		},
+		async waitForRequest(id, waitOptions = {}) {
+			const timeoutMs = waitOptions.timeoutMs ?? 5e3;
+			const intervalMs = waitOptions.intervalMs ?? 50;
+			const deadline = Date.now() + timeoutMs;
+			for (;;) {
+				const record = await client.getRequest(id);
+				if (record && record.durationMs !== void 0) return record;
+				if (Date.now() >= deadline) return record;
+				await new Promise((resolve) => setTimeout(resolve, intervalMs));
+			}
+		}
+	};
+	return client;
+}
+
+//#endregion
+export { DEFAULT_DEVTOOLS_PATH, connectDevtools, parseRequestRecord, parseRequestSummary, resolveDevServerEndpoint };
+//# sourceMappingURL=devtools-client.mjs.map

package/esm/tooling/devtools/devtools-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-client.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/devtools/devtools-client.ts"],"sourcesContent":["import { WarlockError } from \"../../errors/warlock-error\";\nimport { DEV_SERVER_STATE_FILE, readDevServerState } from \"../dev-state/dev-server-state\";\n\n/**\n * A client for the JSON API `@warlock.js/devtools` mounts on the running dev\n * server (`GET <path>/api/requests`, `GET <path>/api/requests/:id`).\n *\n * Shapes are mirrored structurally rather than imported: devtools is an\n * optional dev dependency, and this module must load without it.\n */\n\n/** The devtools mount every app uses unless it wired devtools by hand. */\nexport const DEFAULT_DEVTOOLS_PATH = \"/__warlock\";\n\n/** The `fetch` this client calls; injectable for tests. */\nexport type DevtoolsFetch = (input: string, init?: RequestInit) => Promise<Response>;\n\n/** One timed phase: `route.match`, `middleware` (with `attrs.name`), `validation`, `handler`. */\nexport type DevtoolsPhaseRecord = {\n  name: string;\n  startedAt: number;\n  durationMs: number;\n  attrs?: Record<string, unknown>;\n};\n\n/** The row `GET <path>/api/requests` returns. */\nexport type DevtoolsRequestSummaryRecord = {\n  id: string;\n  method: string;\n  path: string;\n  route?: string;\n  status?: number;\n  startedAt: number;\n  durationMs?: number;\n  queryCount: number;\n  warningCount: number;\n};\n\n/** Everything devtools recorded for one request (`GET <path>/api/requests/:id`). */\nexport type DevtoolsRequestRecord = {\n  id: string;\n  method: string;\n  path: string;\n  route?: string;\n  status?: number;\n  startedAt: number;\n  /** Absent while the request is still in flight. */\n  durationMs?: number;\n  error?: string;\n  phases: DevtoolsPhaseRecord[];\n  /** Queries: `sql`/`collection`, `durationMs`, `shape`, `caller`, `error`. */\n  queries: Record<string, unknown>[];\n  cache: Record<string, unknown>[];\n  logs: Record<string, unknown>[];\n  mails: string[];\n  /** `{ type: \"n+1\", message, shape, count, caller }` entries. */\n  warnings: Record<string, unknown>[];\n};\n\n/** Where the dev server and its devtools API live. */\nexport type DevtoolsEndpoint = {\n  /** The dev server origin, e.g. `http://localhost:2030`. */\n  url: string;\n  /** The devtools mount, e.g. `/__warlock`. */\n  devtoolsPath: string;\n};\n\n/** Options of {@link connectDevtools}. */\nexport type ConnectDevtoolsOptions = {\n  /** Project root, where `.warlock/dev-server.json` is read. Default: `process.cwd()`. */\n  cwd?: string;\n  /** The dev server address; overrides the recorded one. */\n  url?: string;\n  /** The devtools mount; overrides the recorded one. */\n  devtoolsPath?: string;\n  fetch?: DevtoolsFetch;\n};\n\n/** A connected devtools API. */\nexport type DevtoolsClient = DevtoolsEndpoint & {\n  /** The summaries devtools holds, newest last (the order the collector keeps). */\n  listRequests(): Promise<DevtoolsRequestSummaryRecord[]>;\n  /** One request's full record, or `undefined` when devtools does not hold it. */\n  getRequest(id: string): Promise<DevtoolsRequestRecord | undefined>;\n  /**\n   * Poll until the request is recorded AND settled (`durationMs` set), or the\n   * timeout passes. On timeout, resolves the last record seen (still without\n   * `durationMs`), or `undefined` when devtools never recorded the request.\n   */\n  waitForRequest(\n    id: string,\n    options?: { timeoutMs?: number; intervalMs?: number },\n  ): Promise<DevtoolsRequestRecord | undefined>;\n};\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction records(value: unknown): Record<string, unknown>[] {\n  return Array.isArray(value) ? value.filter(isRecord) : [];\n}\n\nfunction optionalNumber(value: unknown): number | undefined {\n  return typeof value === \"number\" ? value : undefined;\n}\n\nfunction optionalString(value: unknown): string | undefined {\n  return typeof value === \"string\" ? value : undefined;\n}\n\n/** Narrow one summary row; `undefined` when it is not one. */\nexport function parseRequestSummary(value: unknown): DevtoolsRequestSummaryRecord | undefined {\n  if (!isRecord(value)) return undefined;\n  if (typeof value.id !== \"string\" || typeof value.method !== \"string\") return undefined;\n  if (typeof value.path !== \"string\") return undefined;\n\n  return {\n    id: value.id,\n    method: value.method,\n    path: value.path,\n    route: optionalString(value.route),\n    status: optionalNumber(value.status),\n    startedAt: optionalNumber(value.startedAt) ?? 0,\n    durationMs: optionalNumber(value.durationMs),\n    queryCount: optionalNumber(value.queryCount) ?? 0,\n    warningCount: optionalNumber(value.warningCount) ?? 0,\n  };\n}\n\n/** Narrow a full request record; `undefined` when it is not one. */\nexport function parseRequestRecord(value: unknown): DevtoolsRequestRecord | undefined {\n  if (!isRecord(value)) return undefined;\n  if (typeof value.id !== \"string\" || typeof value.method !== \"string\") return undefined;\n  if (typeof value.path !== \"string\") return undefined;\n\n  const phases: DevtoolsPhaseRecord[] = records(value.phases).flatMap((phase) =>\n    typeof phase.name === \"string\"\n      ? [\n          {\n            name: phase.name,\n            startedAt: optionalNumber(phase.startedAt) ?? 0,\n            durationMs: optionalNumber(phase.durationMs) ?? 0,\n            ...(isRecord(phase.attrs) ? { attrs: phase.attrs } : {}),\n          },\n        ]\n      : [],\n  );\n\n  return {\n    id: value.id,\n    method: value.method,\n    path: value.path,\n    route: optionalString(value.route),\n    status: optionalNumber(value.status),\n    startedAt: optionalNumber(value.startedAt) ?? 0,\n    durationMs: optionalNumber(value.durationMs),\n    error: optionalString(value.error),\n    phases,\n    queries: records(value.queries),\n    cache: records(value.cache),\n    logs: records(value.logs),\n    mails: Array.isArray(value.mails)\n      ? value.mails.filter((mail): mail is string => typeof mail === \"string\")\n      : [],\n    warnings: records(value.warnings),\n  };\n}\n\nfunction errorMessage(error: unknown): string {\n  if (error instanceof Error) {\n    const cause = error.cause;\n    const code = isRecord(cause) && typeof cause.code === \"string\" ? ` (${cause.code})` : \"\";\n\n    return `${error.message}${code}`;\n  }\n\n  return String(error);\n}\n\nfunction trimSlash(value: string): string {\n  return value.replace(/\\/+$/, \"\");\n}\n\n/** Where the dev server is: the explicit option, else `.warlock/dev-server.json`. Throws `WL8008`. */\nexport function resolveDevServerEndpoint(options: ConnectDevtoolsOptions = {}): DevtoolsEndpoint {\n  const state = options.url === undefined ? readDevServerState(options.cwd) : undefined;\n  const url = options.url ?? state?.url;\n\n  if (!url) {\n    throw new WarlockError(\n      \"WL8008\",\n      `No running dev server is recorded in ${DEV_SERVER_STATE_FILE}. Start \\`warlock dev\\` in this project, or pass --url.`,\n    );\n  }\n\n  const devtoolsPath = trimSlash(\n    options.devtoolsPath ?? state?.devtools?.path ?? DEFAULT_DEVTOOLS_PATH,\n  );\n\n  return { url: trimSlash(url), devtoolsPath };\n}\n\n/**\n * Connect to the devtools API of the running dev server.\n *\n * Throws `WL8008` when no dev server is recorded or it does not answer, and\n * `WL8009` when it answers but devtools is not mounted (404, or anything that\n * is not the devtools JSON).\n */\nexport async function connectDevtools(\n  options: ConnectDevtoolsOptions = {},\n): Promise<DevtoolsClient> {\n  const endpoint = resolveDevServerEndpoint(options);\n  const fetcher: DevtoolsFetch = options.fetch ?? ((input, init) => fetch(input, init));\n  const api = `${endpoint.url}${endpoint.devtoolsPath}/api`;\n\n  const getJson = async (url: string): Promise<{ status: number; body: unknown }> => {\n    let response: Response;\n\n    try {\n      response = await fetcher(url, { headers: { accept: \"application/json\" } });\n    } catch (error) {\n      throw new WarlockError(\n        \"WL8008\",\n        `The dev server at ${endpoint.url} is not reachable: ${errorMessage(error)}. Start \\`warlock dev\\`, or pass --url.`,\n        { cause: error },\n      );\n    }\n\n    const text = await response.text();\n    let body: unknown;\n\n    try {\n      body = text.length > 0 ? JSON.parse(text) : undefined;\n    } catch {\n      body = undefined;\n    }\n\n    return { status: response.status, body };\n  };\n\n  const probe = await getJson(`${api}/requests`);\n\n  if (probe.status !== 200 || !Array.isArray(probe.body)) {\n    throw new WarlockError(\n      \"WL8009\",\n      `The dev server at ${endpoint.url} answered ${probe.status} on ${endpoint.devtoolsPath}/api/requests: devtools is not running there. Install it with \\`warlock add devtools\\` and restart \\`warlock dev\\`.`,\n    );\n  }\n\n  const client: DevtoolsClient = {\n    ...endpoint,\n    async listRequests() {\n      const { body } = await getJson(`${api}/requests`);\n\n      return Array.isArray(body)\n        ? body.flatMap((row) => {\n            const summary = parseRequestSummary(row);\n            return summary ? [summary] : [];\n          })\n        : [];\n    },\n    async getRequest(id) {\n      const { status, body } = await getJson(`${api}/requests/${encodeURIComponent(id)}`);\n\n      return status === 200 ? parseRequestRecord(body) : undefined;\n    },\n    async waitForRequest(id, waitOptions = {}) {\n      const timeoutMs = waitOptions.timeoutMs ?? 5_000;\n      const intervalMs = waitOptions.intervalMs ?? 50;\n      const deadline = Date.now() + timeoutMs;\n\n      for (;;) {\n        const record = await client.getRequest(id);\n\n        if (record && record.durationMs !== undefined) return record;\n        if (Date.now() >= deadline) return record;\n\n        await new Promise((resolve) => setTimeout(resolve, intervalMs));\n      }\n    },\n  };\n\n  return client;\n}\n"],"mappings":"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"}

package/esm/tooling/generate/generation.d.mts

@@ -0,0 +1,78 @@
+import { GeneratorSpec } from "./generator-spec.mjs";
+import { CliRunner } from "./run-cli.mjs";
+
+//#region ../../packages/core/src/tooling/generate/generation.d.ts
+/** The largest diff kept per file; a longer one is cut with a note. */
+declare const MAX_FILE_DIFF_BYTES: number;
+/** One file a generation creates, changes or removes. */
+type GeneratedFile = {
+  /** Project-relative POSIX path. */path: string;
+  status: "created" | "modified" | "deleted"; /** Unified diff against the project's current content (`""` for a binary file). */
+  diff: string; /** Set when the file is binary; `diff` is then empty. */
+  binary?: boolean;
+};
+/** What a generation would do (or did). */
+type GenerationPlan = {
+  spec: GeneratorSpec; /** The argv that ran, starting with `warlock`. */
+  command: string[]; /** Whether the command exited 0. A failed run usually lists no files. */
+  ok: boolean;
+  exitCode: number | null;
+  files: GeneratedFile[]; /** The command's stdout and stderr, ANSI stripped and capped. */
+  output: string;
+};
+/** Options every backend accepts. */
+type GenerationPlanOptions = {
+  /** Project root. Default: `process.cwd()`. */cwd?: string; /** Default {@link DEFAULT_GENERATION_TIMEOUT_MS}. */
+  timeoutMs?: number;
+};
+/**
+ * Computes what a generation would change without touching the project.
+ *
+ * The seam a native `warlock generate.* --dry-run --json` can implement later;
+ * {@link sandboxBackend} implements it by generating into a throwaway copy.
+ */
+type GenerationBackend = {
+  plan(spec: GeneratorSpec, options?: GenerationPlanOptions): Promise<GenerationPlan>;
+};
+/** Options of {@link sandboxBackend}. */
+type SandboxBackendOptions = {
+  /** The `warlock` bin to run. Default: {@link resolveCliEntry}. */cliEntry?: string; /** How the CLI runs. Default: {@link spawnCli}. */
+  runner?: CliRunner; /** Where sandboxes are created. Default: `os.tmpdir()`. */
+  tempDirectory?: string;
+};
+/**
+ * The sandbox {@link GenerationBackend}: copies the project's root files and
+ * `src/` tree (never `.env` files) into a temporary directory, links the
+ * project's `node_modules` into it, runs the real `warlock` command there,
+ * and reports every file that changed as a unified diff against the project.
+ * The project is never written; the sandbox is always removed.
+ *
+ * `add` runs with `--no-install`: package.json shows the dependencies it
+ * would record, and nothing is downloaded.
+ *
+ * @example
+ * const plan = await sandboxBackend().plan(
+ *   { type: "make", generator: "service", name: "users/send-welcome" },
+ *   { cwd: projectRoot },
+ * );
+ * plan.files.map((file) => `${file.status} ${file.path}`);
+ */
+declare function sandboxBackend(options?: SandboxBackendOptions): GenerationBackend;
+/** Options of {@link applyGeneration}. */
+type ApplyGenerationOptions = GenerationPlanOptions & {
+  /** The `warlock` bin to run. Default: {@link resolveCliEntry}. */cliEntry?: string; /** How the CLI runs. Default: {@link spawnCli}. */
+  runner?: CliRunner; /** For `add`: install the packages it records. Default `true`. */
+  install?: boolean;
+};
+/**
+ * Run a generation in the real project and report what it changed, as a
+ * {@link GenerationPlan} whose diffs compare the files before and after.
+ *
+ * Only the generation scope (root files and `src/`, never `.env` files) is
+ * compared. This WRITES the project: `warlock mcp` exposes it only with
+ * `--allow-writes`.
+ */
+declare function applyGeneration(spec: GeneratorSpec, options?: ApplyGenerationOptions): Promise<GenerationPlan>;
+//#endregion
+export { ApplyGenerationOptions, GeneratedFile, GenerationBackend, GenerationPlan, GenerationPlanOptions, MAX_FILE_DIFF_BYTES, SandboxBackendOptions, applyGeneration, sandboxBackend };
+//# sourceMappingURL=generation.d.mts.map

package/esm/tooling/generate/generation.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/generate/generation.ts"],"mappings":";;;;;cAwBa,mBAAA;AAAb;AAAA,KAGY,aAAA;qCAEV,IAAA;EACA,MAAA,sCAHU;EAKV,IAAA;EAEA,MAAA;AAAA;;KAIU,cAAA;EACV,IAAA,EAAM,aAAA,EALA;EAON,OAAA,YAHU;EAKV,EAAA;EACA,QAAA;EACA,KAAA,EAAO,aAAa,IANpB;EAQA,MAAA;AAAA;;KAIU,qBAAA;EANV,8CAQA,GAAA,WANA;EAQA,SAAS;AAAA;AAJX;;;;AAIW;AASX;AAbA,KAaY,iBAAA;EACV,IAAA,CAAK,IAAA,EAAM,aAAA,EAAe,OAAA,GAAU,qBAAA,GAAwB,OAAA,CAAQ,cAAA;AAAA;;KAI1D,qBAAA;EAJkD,kEAM5D,QAAA,WANmE;EAQnE,MAAA,GAAS,SAAS,EARP;EAUX,aAAA;AAAA;;;;;AAVkF;AAIpF;;;;;;;;;AAMe;AA6Ef;;iBAAgB,cAAA,CAAe,OAAA,GAAS,qBAAA,GAA6B,iBAAiB;;KA2C1E,sBAAA,GAAyB,qBAAA;EA3CN,kEA6C7B,QAAA,WA7CoF;EA+CpF,MAAA,GAAS,SAAS,EAJR;EAMV,OAAA;AAAA;;;;;;;;AAAO;iBAWa,eAAA,CACpB,IAAA,EAAM,aAAA,EACN,OAAA,GAAS,sBAAA,GACR,OAAA,CAAQ,cAAA"}

package/esm/tooling/generate/generation.mjs

@@ -0,0 +1,123 @@
+import { buildGeneratorArgs } from "./generator-spec.mjs";
+import { compareSnapshots, copyProjectScope, forEachSandboxFile, forEachScopedFile, isBinary, snapshotFiles } from "./project-files.mjs";
+import { DEFAULT_GENERATION_TIMEOUT_MS, describeRun, resolveCliEntry, spawnCli } from "./run-cli.mjs";
+import { unifiedDiff } from "./unified-diff.mjs";
+import path from "node:path";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+
+//#region ../../packages/core/src/tooling/generate/generation.ts
+/** The largest diff kept per file; a longer one is cut with a note. */
+const MAX_FILE_DIFF_BYTES = 200 * 1024;
+function readOrNull(file) {
+	return existsSync(file) ? readFileSync(file) : null;
+}
+function capDiff(diff) {
+	return diff.length > 204800 ? `${diff.slice(0, MAX_FILE_DIFF_BYTES)}\n… (diff truncated)\n` : diff;
+}
+/**
+* Build the {@link GeneratedFile} for one change from the two contents, or
+* `undefined` when they are byte-identical (a file rewritten unchanged).
+*/
+function describeChange(change, before, after) {
+	if (before !== null && after !== null && before.equals(after)) return void 0;
+	const status = before === null ? "created" : after === null ? "deleted" : "modified";
+	if (before && isBinary(before) || after && isBinary(after)) return {
+		path: change.path,
+		status,
+		diff: "",
+		binary: true
+	};
+	return {
+		path: change.path,
+		status,
+		diff: capDiff(unifiedDiff({
+			path: change.path,
+			before: before === null ? null : before.toString("utf8"),
+			after: after === null ? null : after.toString("utf8")
+		}))
+	};
+}
+function planFrom(spec, args, run, files) {
+	return {
+		spec,
+		command: ["warlock", ...args],
+		ok: run.exitCode === 0 && !run.timedOut,
+		exitCode: run.exitCode,
+		files,
+		output: describeRun(run)
+	};
+}
+/**
+* The sandbox {@link GenerationBackend}: copies the project's root files and
+* `src/` tree (never `.env` files) into a temporary directory, links the
+* project's `node_modules` into it, runs the real `warlock` command there,
+* and reports every file that changed as a unified diff against the project.
+* The project is never written; the sandbox is always removed.
+*
+* `add` runs with `--no-install`: package.json shows the dependencies it
+* would record, and nothing is downloaded.
+*
+* @example
+* const plan = await sandboxBackend().plan(
+*   { type: "make", generator: "service", name: "users/send-welcome" },
+*   { cwd: projectRoot },
+* );
+* plan.files.map((file) => `${file.status} ${file.path}`);
+*/
+function sandboxBackend(options = {}) {
+	const runner = options.runner ?? spawnCli;
+	return { async plan(spec, planOptions = {}) {
+		const cwd = path.resolve(planOptions.cwd ?? process.cwd());
+		const args = buildGeneratorArgs(spec, { install: false });
+		const sandbox = mkdtempSync(path.join(options.tempDirectory ?? os.tmpdir(), "warlock-generate-"));
+		try {
+			copyProjectScope(cwd, sandbox);
+			const before = snapshotFiles(sandbox, forEachSandboxFile);
+			return planFrom(spec, args, await runner({
+				entry: options.cliEntry ?? resolveCliEntry(),
+				args,
+				cwd: sandbox,
+				timeoutMs: planOptions.timeoutMs ?? 12e4
+			}), compareSnapshots(before, snapshotFiles(sandbox, forEachSandboxFile)).flatMap((change) => {
+				const file = describeChange(change, readOrNull(path.join(cwd, change.path)), change.status === "deleted" ? null : readOrNull(path.join(sandbox, change.path)));
+				return file ? [file] : [];
+			}));
+		} finally {
+			rmSync(sandbox, {
+				recursive: true,
+				force: true
+			});
+		}
+	} };
+}
+/**
+* Run a generation in the real project and report what it changed, as a
+* {@link GenerationPlan} whose diffs compare the files before and after.
+*
+* Only the generation scope (root files and `src/`, never `.env` files) is
+* compared. This WRITES the project: `warlock mcp` exposes it only with
+* `--allow-writes`.
+*/
+async function applyGeneration(spec, options = {}) {
+	const cwd = path.resolve(options.cwd ?? process.cwd());
+	const args = buildGeneratorArgs(spec, { install: options.install ?? true });
+	const contents = /* @__PURE__ */ new Map();
+	forEachScopedFile(cwd, (absolute, relative) => {
+		contents.set(relative, readFileSync(absolute));
+	});
+	const before = snapshotFiles(cwd, forEachScopedFile);
+	return planFrom(spec, args, await (options.runner ?? spawnCli)({
+		entry: options.cliEntry ?? resolveCliEntry(),
+		args,
+		cwd,
+		timeoutMs: options.timeoutMs ?? 12e4
+	}), compareSnapshots(before, snapshotFiles(cwd, forEachScopedFile)).flatMap((change) => {
+		const file = describeChange(change, contents.get(change.path) ?? null, change.status === "deleted" ? null : readOrNull(path.join(cwd, change.path)));
+		return file ? [file] : [];
+	}));
+}
+
+//#endregion
+export { MAX_FILE_DIFF_BYTES, applyGeneration, sandboxBackend };
+//# sourceMappingURL=generation.mjs.map

package/esm/tooling/generate/generation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/generate/generation.ts"],"sourcesContent":["import { existsSync, mkdtempSync, readFileSync, rmSync } from \"node:fs\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport { buildGeneratorArgs, type GeneratorSpec } from \"./generator-spec\";\nimport {\n  compareSnapshots,\n  copyProjectScope,\n  forEachSandboxFile,\n  forEachScopedFile,\n  isBinary,\n  type SnapshotChange,\n  snapshotFiles,\n} from \"./project-files\";\nimport {\n  type CliRun,\n  type CliRunner,\n  DEFAULT_GENERATION_TIMEOUT_MS,\n  describeRun,\n  resolveCliEntry,\n  spawnCli,\n} from \"./run-cli\";\nimport { unifiedDiff } from \"./unified-diff\";\n\n/** The largest diff kept per file; a longer one is cut with a note. */\nexport const MAX_FILE_DIFF_BYTES = 200 * 1024;\n\n/** One file a generation creates, changes or removes. */\nexport type GeneratedFile = {\n  /** Project-relative POSIX path. */\n  path: string;\n  status: \"created\" | \"modified\" | \"deleted\";\n  /** Unified diff against the project's current content (`\"\"` for a binary file). */\n  diff: string;\n  /** Set when the file is binary; `diff` is then empty. */\n  binary?: boolean;\n};\n\n/** What a generation would do (or did). */\nexport type GenerationPlan = {\n  spec: GeneratorSpec;\n  /** The argv that ran, starting with `warlock`. */\n  command: string[];\n  /** Whether the command exited 0. A failed run usually lists no files. */\n  ok: boolean;\n  exitCode: number | null;\n  files: GeneratedFile[];\n  /** The command's stdout and stderr, ANSI stripped and capped. */\n  output: string;\n};\n\n/** Options every backend accepts. */\nexport type GenerationPlanOptions = {\n  /** Project root. Default: `process.cwd()`. */\n  cwd?: string;\n  /** Default {@link DEFAULT_GENERATION_TIMEOUT_MS}. */\n  timeoutMs?: number;\n};\n\n/**\n * Computes what a generation would change without touching the project.\n *\n * The seam a native `warlock generate.* --dry-run --json` can implement later;\n * {@link sandboxBackend} implements it by generating into a throwaway copy.\n */\nexport type GenerationBackend = {\n  plan(spec: GeneratorSpec, options?: GenerationPlanOptions): Promise<GenerationPlan>;\n};\n\n/** Options of {@link sandboxBackend}. */\nexport type SandboxBackendOptions = {\n  /** The `warlock` bin to run. Default: {@link resolveCliEntry}. */\n  cliEntry?: string;\n  /** How the CLI runs. Default: {@link spawnCli}. */\n  runner?: CliRunner;\n  /** Where sandboxes are created. Default: `os.tmpdir()`. */\n  tempDirectory?: string;\n};\n\nfunction readOrNull(file: string): Buffer | null {\n  return existsSync(file) ? readFileSync(file) : null;\n}\n\nfunction capDiff(diff: string): string {\n  return diff.length > MAX_FILE_DIFF_BYTES\n    ? `${diff.slice(0, MAX_FILE_DIFF_BYTES)}\\n… (diff truncated)\\n`\n    : diff;\n}\n\n/**\n * Build the {@link GeneratedFile} for one change from the two contents, or\n * `undefined` when they are byte-identical (a file rewritten unchanged).\n */\nfunction describeChange(\n  change: SnapshotChange,\n  before: Buffer | null,\n  after: Buffer | null,\n): GeneratedFile | undefined {\n  if (before !== null && after !== null && before.equals(after)) return undefined;\n\n  const status: GeneratedFile[\"status\"] =\n    before === null ? \"created\" : after === null ? \"deleted\" : \"modified\";\n\n  if ((before && isBinary(before)) || (after && isBinary(after))) {\n    return { path: change.path, status, diff: \"\", binary: true };\n  }\n\n  return {\n    path: change.path,\n    status,\n    diff: capDiff(\n      unifiedDiff({\n        path: change.path,\n        before: before === null ? null : before.toString(\"utf8\"),\n        after: after === null ? null : after.toString(\"utf8\"),\n      }),\n    ),\n  };\n}\n\nfunction planFrom(\n  spec: GeneratorSpec,\n  args: string[],\n  run: CliRun,\n  files: GeneratedFile[],\n): GenerationPlan {\n  return {\n    spec,\n    command: [\"warlock\", ...args],\n    ok: run.exitCode === 0 && !run.timedOut,\n    exitCode: run.exitCode,\n    files,\n    output: describeRun(run),\n  };\n}\n\n/**\n * The sandbox {@link GenerationBackend}: copies the project's root files and\n * `src/` tree (never `.env` files) into a temporary directory, links the\n * project's `node_modules` into it, runs the real `warlock` command there,\n * and reports every file that changed as a unified diff against the project.\n * The project is never written; the sandbox is always removed.\n *\n * `add` runs with `--no-install`: package.json shows the dependencies it\n * would record, and nothing is downloaded.\n *\n * @example\n * const plan = await sandboxBackend().plan(\n *   { type: \"make\", generator: \"service\", name: \"users/send-welcome\" },\n *   { cwd: projectRoot },\n * );\n * plan.files.map((file) => `${file.status} ${file.path}`);\n */\nexport function sandboxBackend(options: SandboxBackendOptions = {}): GenerationBackend {\n  const runner = options.runner ?? spawnCli;\n\n  return {\n    async plan(spec, planOptions = {}) {\n      const cwd = path.resolve(planOptions.cwd ?? process.cwd());\n      const args = buildGeneratorArgs(spec, { install: false });\n      const sandbox = mkdtempSync(\n        path.join(options.tempDirectory ?? os.tmpdir(), \"warlock-generate-\"),\n      );\n\n      try {\n        copyProjectScope(cwd, sandbox);\n\n        const before = snapshotFiles(sandbox, forEachSandboxFile);\n        const run = await runner({\n          entry: options.cliEntry ?? resolveCliEntry(),\n          args,\n          cwd: sandbox,\n          timeoutMs: planOptions.timeoutMs ?? DEFAULT_GENERATION_TIMEOUT_MS,\n        });\n        const after = snapshotFiles(sandbox, forEachSandboxFile);\n        const files = compareSnapshots(before, after).flatMap((change) => {\n          // Compared with the PROJECT, not the sandbox copy: a file outside the\n          // copied scope that the project already has is a change, not a creation.\n          const file = describeChange(\n            change,\n            readOrNull(path.join(cwd, change.path)),\n            change.status === \"deleted\" ? null : readOrNull(path.join(sandbox, change.path)),\n          );\n\n          return file ? [file] : [];\n        });\n\n        return planFrom(spec, args, run, files);\n      } finally {\n        rmSync(sandbox, { recursive: true, force: true });\n      }\n    },\n  };\n}\n\n/** Options of {@link applyGeneration}. */\nexport type ApplyGenerationOptions = GenerationPlanOptions & {\n  /** The `warlock` bin to run. Default: {@link resolveCliEntry}. */\n  cliEntry?: string;\n  /** How the CLI runs. Default: {@link spawnCli}. */\n  runner?: CliRunner;\n  /** For `add`: install the packages it records. Default `true`. */\n  install?: boolean;\n};\n\n/**\n * Run a generation in the real project and report what it changed, as a\n * {@link GenerationPlan} whose diffs compare the files before and after.\n *\n * Only the generation scope (root files and `src/`, never `.env` files) is\n * compared. This WRITES the project: `warlock mcp` exposes it only with\n * `--allow-writes`.\n */\nexport async function applyGeneration(\n  spec: GeneratorSpec,\n  options: ApplyGenerationOptions = {},\n): Promise<GenerationPlan> {\n  const cwd = path.resolve(options.cwd ?? process.cwd());\n  const args = buildGeneratorArgs(spec, { install: options.install ?? true });\n  const contents = new Map<string, Buffer>();\n\n  forEachScopedFile(cwd, (absolute, relative) => {\n    contents.set(relative, readFileSync(absolute));\n  });\n\n  const before = snapshotFiles(cwd, forEachScopedFile);\n  const run = await (options.runner ?? spawnCli)({\n    entry: options.cliEntry ?? resolveCliEntry(),\n    args,\n    cwd,\n    timeoutMs: options.timeoutMs ?? DEFAULT_GENERATION_TIMEOUT_MS,\n  });\n  const after = snapshotFiles(cwd, forEachScopedFile);\n  const files = compareSnapshots(before, after).flatMap((change) => {\n    const file = describeChange(\n      change,\n      contents.get(change.path) ?? null,\n      change.status === \"deleted\" ? null : readOrNull(path.join(cwd, change.path)),\n    );\n\n    return file ? [file] : [];\n  });\n\n  return planFrom(spec, args, run, files);\n}\n"],"mappings":"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"}