@flytedesk/app-kit 5.0.0 → 6.0.0

package/dist/bigquery/types.d.ts

@@ -32,6 +32,20 @@ export interface BigQueryTableReference {
     datasetId?: string;
     tableId?: string;
 }
+/** A result-schema field exactly as BigQuery's job statistics report it: the
+ *  real SDK's `ITableFieldSchema`, where every property is optional. Only the
+ *  raw boundary speaks this shape; callers get `BigQueryResultSchemaField`
+ *  (name and type guaranteed) from `estimateQueryBytes`. */
+export interface BigQueryRawSchemaField {
+    name?: string;
+    type?: string;
+    mode?: string;
+    fields?: BigQueryRawSchemaField[];
+}
+/** `IJobStatistics2.schema`, an `ITableSchema`. */
+export interface BigQueryRawSchema {
+    fields?: BigQueryRawSchemaField[];
+}
 export interface BigQueryJobStatistics {
     query?: {
         totalBytesProcessed?: string | number;
@@ -42,6 +56,9 @@ export interface BigQueryJobStatistics {
         statementType?: string;
         /** Every table the query touches — `IJobStatistics2.referencedTables`. */
         referencedTables?: BigQueryTableReference[];
+        /** The result schema BigQuery computed for the (dry-run) query —
+         *  `IJobStatistics2.schema`, an `ITableSchema` (`{ fields }`). */
+        schema?: BigQueryRawSchema;
     };
 }
 export interface BigQueryJobMetadata {
@@ -92,6 +109,10 @@ export interface BigQueryCreateQueryJobOptions {
      *  than run. Distinct from `EstimateQueryBytesOptions.maxBytesBilled`
      *  (a pre-flight dry-run check this module enforces client-side). */
     maximumBytesBilled?: string;
+    /** BigQuery's own `configuration.jobTimeoutMs` — the job fails with
+     *  `stopped` state once it runs longer than this, wall-clock, from job
+     *  creation. The SDK converts this number to the wire's decimal string. */
+    jobTimeoutMs?: number;
 }
 export interface BigQueryExtractOptions {
     /** `@google-cloud/bigquery`'s own extract-job vocabulary — note this is
@@ -111,14 +132,25 @@ export interface GcsFileLike {
     };
 }
 /** One BigQuery table-schema field, as `createWriteStream`'s `schema` option
- *  (and the REST API's `tables.insert`) accepts it. `fields` recurses for
- *  RECORD/STRUCT columns. */
+ *  (and the REST API's `tables.insert`) accepts it: load-job INPUT, where the
+ *  caller must state `name` and `type`. `fields` recurses for RECORD/STRUCT
+ *  columns. The schema BigQuery reports back is `BigQueryResultSchemaField`. */
 export interface BigQuerySchemaField {
     name: string;
     type: string;
     mode?: "NULLABLE" | "REQUIRED" | "REPEATED";
     fields?: BigQuerySchemaField[];
 }
+/** One column of a query's result schema, normalised from BigQuery's own
+ *  dry-run statistics: `name` and `type` are guaranteed (a field missing
+ *  either is rejected with `MalformedResultSchemaError`); `mode` is BigQuery's
+ *  string as reported. `fields` recurses for RECORD/STRUCT columns. */
+export interface BigQueryResultSchemaField {
+    name: string;
+    type: string;
+    mode?: string;
+    fields?: BigQueryResultSchemaField[];
+}
 export interface BigQueryLoadOptions {
     sourceFormat?: "NEWLINE_DELIMITED_JSON" | "CSV" | "AVRO" | "PARQUET";
     /** Full destination-table schema. Required when the table doesn't already
@@ -182,6 +214,11 @@ export interface RunQueryOptions {
      *  belt to that check's suspenders, since data can grow between a dry
      *  run and the real job, or a caller can skip the dry run entirely. */
     maximumBytesBilled?: number;
+    /** Fails the job with a typed `JobTimeoutError` once it runs longer than
+     *  this many milliseconds, wall-clock from job creation — set on the job's
+     *  own `configuration.jobTimeoutMs` (BigQuery enforces it server-side),
+     *  not a client-side `Promise.race`. */
+    jobTimeoutMs?: number;
 }
 export interface QueryPage<T = Record<string, unknown>> {
     rows: T[];
@@ -197,6 +234,10 @@ export interface EstimateQueryBytesOptions {
     /** When given, `estimateQueryBytes` throws `DryRunBudgetExceededError`
      *  instead of returning once the estimate exceeds this many bytes. */
     maxBytesBilled?: number;
+    /** Same `configuration.jobTimeoutMs` enforcement as `RunQueryOptions` —
+     *  applies to the dry-run job itself, not the (never-run) query it
+     *  estimates. */
+    jobTimeoutMs?: number;
 }
 export interface DryRunEstimate {
     totalBytesProcessed: number;
@@ -211,6 +252,10 @@ export interface DryRunEstimate {
      *  checks every entry against its own read-only table allowlist before
      *  ever submitting the real job. */
     referencedTables?: BigQueryTableReference[];
+    /** BigQuery's own result schema for the query, typed directly from the
+     *  dry-run job's `statistics.query.schema` — never inferred client-side.
+     *  `undefined` only when BigQuery's dry-run statistics omitted it. */
+    schema?: BigQueryResultSchemaField[];
 }
 export interface ExtractTableToGCSInput {
     datasetId: string;

package/dist/chat/index.d.ts

@@ -41,32 +41,63 @@
  *     async (request) => recordReply(request.body),
  *   );
  *
- * Usage — the MCP server script the dispatched agent's clean room actually runs
- * (typically `dist/chat/mcp/entry.js`, wired through a `.danxbot/config/mcp-servers/
- * *.yml`):
+ * Usage — the MCP server the dispatched agent's clean room actually runs (AK-34): a
+ * `.danxbot/config/mcp-servers/*.yml` launches the PUBLISHED `app-kit-chat-mcp` bin
+ * directly, no vendored copy and no local install in the app's own repo. This
+ * package publishes FIVE bins and none is named `app-kit`, so `npx` needs
+ * `--package=` to say which package to fetch, separately from which bin to run —
+ * `npx -y @flytedesk/app-kit@<v> app-kit-chat-mcp` fails ("could not determine
+ * executable to run"); this is the form that actually works (verified against a real
+ * `npm pack` tarball run via `npx --package=<tgz>` from a clean directory with no
+ * `node_modules` — see `mcp/entry.test.ts`):
  *
- *   import {
- *     createChatMcpProtocol,
- *     createChatMcpStdioServer,
- *     createReplyTool,
- *   } from "@flytedesk/app-kit/chat";
+ *   server:
+ *     command: npx
+ *     args:
+ *       - "-y"
+ *       - "--package=@flytedesk/app-kit@6.0.0"
+ *       - "app-kit-chat-mcp"
+ *       - "--tools"
+ *       - "${DANX_REPO_ROOT}/packages/audience-chat-mcp/src/chatTools.mjs"
  *
- *   const protocol = createChatMcpProtocol({
- *     serverName: "sms-app-chat",
- *     tools: [
- *       createReplyTool({ description: "...", deliver: postReplyToApi }),
- *       // The extension point: register whatever app-specific tools the agent
- *       // needs — each is just { name, description, inputSchema, handler }.
- *       { name: "audience_validate", description: "...", inputSchema: {...}, handler: validateAudience },
- *     ],
- *   });
- *   createChatMcpStdioServer({ protocol }).start();
+ * `--tools <path>` MUST be absolute — danxbot's cwd for this process is its own
+ * clean room, never assumed to equal the app's repo root, hence the
+ * `${DANX_REPO_ROOT}`-prefixed path above rather than a bare relative one.
+ *
+ * The path names the ONE thing this package cannot supply itself: the app's own
+ * tools module. That module must NOT `import` anything from `@flytedesk/app-kit` —
+ * a bare package import cannot resolve from danxbot's unbuilt dispatch clone (no
+ * `node_modules`). Instead, `app-kit-chat-mcp` INJECTS the pieces the module needs as
+ * a `ChatMcpKit` argument, and the module returns a (optionally wrapped)
+ * `ChatMcpProtocol` rather than a plain options bag:
+ *
+ *   // chatTools.mjs — the app's own file, never vendored, never copied, never
+ *   // imports @flytedesk/app-kit as a VALUE (a type-only `// @ts-check` JSDoc
+ *   // reference to BuildChatServer/ChatMcpKit is fine — see mcp/entry.ts's header)
+ *   export default function buildChatServer(kit) {
+ *     return kit.createChatMcpProtocol({
+ *       serverName: "sms-app-chat",
+ *       tools: [
+ *         kit.createReplyTool({ description: "...", deliver: postReplyToApi }),
+ *         // The extension point: register whatever app-specific tools the agent
+ *         // needs — each is just { name, description, inputSchema, handler }.
+ *         { name: "audience_validate", description: "...", inputSchema: {...}, handler: validateAudience },
+ *       ],
+ *     });
+ *   }
+ *
+ * `app-kit-chat-mcp` (`src/chat/mcp/entry.ts`, published as `dist/chat/mcp/entry.js`)
+ * loads that module, calls its default export with the kit, and starts the stdio
+ * loop on whatever `ChatMcpProtocol` it returns — see `entry.ts`'s own doc comment
+ * for the full contract, why it stays dependency-free, and how a consumer (e.g.
+ * media-planner's MP-169 `loggedProtocol`) wraps `handleMessage` before returning.
  */
-export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus } from "./launcher.js";
-export { callbackSecretMatches, requireCallbackSecret } from "./callback-secret.js";
+export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus, } from "./launcher.js";
+export { callbackSecretMatches, requireCallbackSecret, } from "./callback-secret.js";
 export { createChatMcpProtocol, createReplyTool, parseReplyArguments, FALLBACK_PROTOCOL_VERSION, JSON_RPC, } from "./mcp-protocol.js";
 export { createChatMcpStdioServer } from "./mcp-server.js";
 export { parseChatEnv, ChatEnvError } from "./env.js";
 export type { AppRegisteredTool, ChatEnv, ChatToolCallResult, ChatToolContent, DanxbotDispatchResult, DanxbotJobStatus, DanxbotLauncher, DanxbotLauncherOptions, } from "./types.js";
 export type { ChatMcpProtocol, ChatMcpProtocolOptions, ChatReplyPayload, ParseReplyArgumentsOptions, ReplyDeliverResult, ReplyToolOptions, } from "./mcp-protocol.js";
-export type { ChatMcpStdioServer, ChatMcpStdioServerOptions } from "./mcp-server.js";
+export type { ChatMcpStdioServer, ChatMcpStdioServerOptions, } from "./mcp-server.js";
+export type { BuildChatServer, ChatMcpKit } from "./mcp/entry.js";

package/dist/chat/index.js

@@ -41,29 +41,59 @@
  *     async (request) => recordReply(request.body),
  *   );
  *
- * Usage — the MCP server script the dispatched agent's clean room actually runs
- * (typically `dist/chat/mcp/entry.js`, wired through a `.danxbot/config/mcp-servers/
- * *.yml`):
+ * Usage — the MCP server the dispatched agent's clean room actually runs (AK-34): a
+ * `.danxbot/config/mcp-servers/*.yml` launches the PUBLISHED `app-kit-chat-mcp` bin
+ * directly, no vendored copy and no local install in the app's own repo. This
+ * package publishes FIVE bins and none is named `app-kit`, so `npx` needs
+ * `--package=` to say which package to fetch, separately from which bin to run —
+ * `npx -y @flytedesk/app-kit@<v> app-kit-chat-mcp` fails ("could not determine
+ * executable to run"); this is the form that actually works (verified against a real
+ * `npm pack` tarball run via `npx --package=<tgz>` from a clean directory with no
+ * `node_modules` — see `mcp/entry.test.ts`):
  *
- *   import {
- *     createChatMcpProtocol,
- *     createChatMcpStdioServer,
- *     createReplyTool,
- *   } from "@flytedesk/app-kit/chat";
+ *   server:
+ *     command: npx
+ *     args:
+ *       - "-y"
+ *       - "--package=@flytedesk/app-kit@6.0.0"
+ *       - "app-kit-chat-mcp"
+ *       - "--tools"
+ *       - "${DANX_REPO_ROOT}/packages/audience-chat-mcp/src/chatTools.mjs"
  *
- *   const protocol = createChatMcpProtocol({
- *     serverName: "sms-app-chat",
- *     tools: [
- *       createReplyTool({ description: "...", deliver: postReplyToApi }),
- *       // The extension point: register whatever app-specific tools the agent
- *       // needs — each is just { name, description, inputSchema, handler }.
- *       { name: "audience_validate", description: "...", inputSchema: {...}, handler: validateAudience },
- *     ],
- *   });
- *   createChatMcpStdioServer({ protocol }).start();
+ * `--tools <path>` MUST be absolute — danxbot's cwd for this process is its own
+ * clean room, never assumed to equal the app's repo root, hence the
+ * `${DANX_REPO_ROOT}`-prefixed path above rather than a bare relative one.
+ *
+ * The path names the ONE thing this package cannot supply itself: the app's own
+ * tools module. That module must NOT `import` anything from `@flytedesk/app-kit` —
+ * a bare package import cannot resolve from danxbot's unbuilt dispatch clone (no
+ * `node_modules`). Instead, `app-kit-chat-mcp` INJECTS the pieces the module needs as
+ * a `ChatMcpKit` argument, and the module returns a (optionally wrapped)
+ * `ChatMcpProtocol` rather than a plain options bag:
+ *
+ *   // chatTools.mjs — the app's own file, never vendored, never copied, never
+ *   // imports @flytedesk/app-kit as a VALUE (a type-only `// @ts-check` JSDoc
+ *   // reference to BuildChatServer/ChatMcpKit is fine — see mcp/entry.ts's header)
+ *   export default function buildChatServer(kit) {
+ *     return kit.createChatMcpProtocol({
+ *       serverName: "sms-app-chat",
+ *       tools: [
+ *         kit.createReplyTool({ description: "...", deliver: postReplyToApi }),
+ *         // The extension point: register whatever app-specific tools the agent
+ *         // needs — each is just { name, description, inputSchema, handler }.
+ *         { name: "audience_validate", description: "...", inputSchema: {...}, handler: validateAudience },
+ *       ],
+ *     });
+ *   }
+ *
+ * `app-kit-chat-mcp` (`src/chat/mcp/entry.ts`, published as `dist/chat/mcp/entry.js`)
+ * loads that module, calls its default export with the kit, and starts the stdio
+ * loop on whatever `ChatMcpProtocol` it returns — see `entry.ts`'s own doc comment
+ * for the full contract, why it stays dependency-free, and how a consumer (e.g.
+ * media-planner's MP-169 `loggedProtocol`) wraps `handleMessage` before returning.
  */
-export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus } from "./launcher.js";
-export { callbackSecretMatches, requireCallbackSecret } from "./callback-secret.js";
+export { createDanxbotLauncher, DanxbotError, isFailedJobStatus, isTerminalJobStatus, } from "./launcher.js";
+export { callbackSecretMatches, requireCallbackSecret, } from "./callback-secret.js";
 export { createChatMcpProtocol, createReplyTool, parseReplyArguments, FALLBACK_PROTOCOL_VERSION, JSON_RPC, } from "./mcp-protocol.js";
 export { createChatMcpStdioServer } from "./mcp-server.js";
 export { parseChatEnv, ChatEnvError } from "./env.js";

package/dist/chat/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5G,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/chat/mcp/entry.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { createChatMcpProtocol, createReplyTool, parseReplyArguments, type ChatMcpProtocol } from "../mcp-protocol.js";
+/**
+ * Everything a `--tools` module needs, injected rather than imported — see this
+ * file's own doc comment for why a runtime `import "@flytedesk/app-kit/chat"` from
+ * the module itself cannot work in danxbot's unbuilt dispatch clone.
+ */
+export interface ChatMcpKit {
+    createReplyTool: typeof createReplyTool;
+    parseReplyArguments: typeof parseReplyArguments;
+    createChatMcpProtocol: typeof createChatMcpProtocol;
+}
+/** The contract a `--tools` module's default export must satisfy: given the kit,
+ *  return a (possibly wrapped) `ChatMcpProtocol`. */
+export type BuildChatServer = (kit: ChatMcpKit) => ChatMcpProtocol | Promise<ChatMcpProtocol>;
+export declare class ChatMcpEntryError extends Error {
+}
+export interface ChatMcpEntryArgs {
+    /** Path to the app's tools module. MUST be absolute in real dispatch use (see this
+     *  file's own doc comment) — resolved against `process.cwd()` only as a fallback
+     *  for a genuinely relative path, which `path.resolve` leaves untouched when the
+     *  input is already absolute. */
+    toolsPath: string;
+}
+/** Parse argv into `{toolsPath}`. Exported for direct unit testing. */
+export declare function parseArgs(argv: string[]): ChatMcpEntryArgs;
+/**
+ * Dynamically `import()` the app's tools module and validate its default export.
+ * Exported for direct unit testing (no process spawn needed to exercise the loading
+ * and validation logic — see entry.test.ts's own split between a fast in-process
+ * suite for this function and real stdio/npx spawn suites for the whole process).
+ */
+export declare function loadBuildChatServer(toolsPath: string): Promise<BuildChatServer>;
+/** Run the server: load the tools module, build the protocol (via the injected
+ *  kit), and start stdio. Exported for direct unit testing of argument/validation
+ *  failures without a process spawn. */
+export declare function main(argv: string[]): Promise<void>;

package/dist/chat/mcp/entry.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * app-kit-chat-mcp (AK-34) — a runnable stdio entry point for
+ * `@flytedesk/app-kit/chat`'s MCP server, so a consuming app's
+ * `.danxbot/config/mcp-servers/*.yml` can launch a real chat MCP server without
+ * vendoring a copy of `mcp-protocol.js`/`mcp-server.js` into its own repo.
+ *
+ * ## Launch form
+ *
+ * This package publishes FIVE bins and none is named `app-kit`, so npx needs
+ * `--package=` to say which package to fetch (separate from which bin to run):
+ *
+ *   npx -y --package=@flytedesk/app-kit@<v> app-kit-chat-mcp --tools <abs path>
+ *
+ * `npx -y @flytedesk/app-kit@<v> app-kit-chat-mcp` (no `--package=`) fails —
+ * verified against a real `npm pack` tarball run via `npx --package=<tgz>` from a
+ * clean directory with no `node_modules` (see entry.test.ts's "packed via npm pack,
+ * run via npx --package" suite).
+ *
+ * `--tools <path>` is resolved against `process.cwd()`, which danxbot sets to its
+ * OWN clean-room working directory — an app's yml MUST pass a
+ * `${DANX_REPO_ROOT}`-absolute path, never a bare relative one.
+ *
+ * ## The `--tools` module — kit injection, not a package import
+ *
+ * The module must NOT `import` `@flytedesk/app-kit` itself — that cannot resolve
+ * from danxbot's unbuilt dispatch clone (no `node_modules`), and would just move the
+ * vendoring problem this card closes into "the app re-implements createReplyTool".
+ * Instead this file injects a `ChatMcpKit` (`createReplyTool`, `parseReplyArguments`,
+ * `createChatMcpProtocol` — the same values `@flytedesk/app-kit/chat` exports) as
+ * the module's one argument:
+ *
+ *   export default function build(kit) {
+ *     return kit.createChatMcpProtocol({
+ *       serverName: "my-app-chat",
+ *       tools: [kit.createReplyTool({ description: "...", deliver: postReply }), ...],
+ *     });
+ *   }
+ *
+ * The default export returns a `ChatMcpProtocol` (`{handleMessage}`), not a plain
+ * options bag, so it can wrap the built protocol before returning (e.g.
+ * media-planner's MP-169 `loggedProtocol`). A module wanting type-checking can
+ * reference the exported `BuildChatServer`/`ChatMcpKit` TYPES via a `// @ts-check`
+ * JSDoc `@type` comment — type-only, erased, resolves fine from the app's own dev
+ * environment; it must never become a value import.
+ *
+ * ## Dependency-free at runtime
+ *
+ * Node builtins + this package's own `mcp-protocol.js`/`mcp-server.js` (themselves
+ * dependency-free) + `../../cli/is-running-as-main.js` (also Node-builtins-only —
+ * deliberately not imported from `../../cli/sync-engine.js`, which pulls in
+ * `cross-spawn` for its own Prisma-shelling subcommands).
+ */
+import { pathToFileURL } from "node:url";
+import { resolve as resolvePath } from "node:path";
+import { createChatMcpProtocol, createReplyTool, parseReplyArguments, } from "../mcp-protocol.js";
+import { createChatMcpStdioServer } from "../mcp-server.js";
+import { isRunningAsMain } from "../../cli/is-running-as-main.js";
+const KIT = {
+    createReplyTool,
+    parseReplyArguments,
+    createChatMcpProtocol,
+};
+export class ChatMcpEntryError extends Error {
+}
+/** Parse argv into `{toolsPath}`. Exported for direct unit testing. */
+export function parseArgs(argv) {
+    let toolsPath;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--tools") {
+            toolsPath = argv[i + 1];
+            i += 1;
+        }
+        else {
+            throw new ChatMcpEntryError(`app-kit-chat-mcp: unrecognized argument "${arg}"`);
+        }
+    }
+    if (toolsPath === undefined || toolsPath === "") {
+        throw new ChatMcpEntryError("app-kit-chat-mcp: missing required --tools <absolute path to the app's tools module>");
+    }
+    return { toolsPath };
+}
+/**
+ * Dynamically `import()` the app's tools module and validate its default export.
+ * Exported for direct unit testing (no process spawn needed to exercise the loading
+ * and validation logic — see entry.test.ts's own split between a fast in-process
+ * suite for this function and real stdio/npx spawn suites for the whole process).
+ */
+export async function loadBuildChatServer(toolsPath) {
+    const absolutePath = resolvePath(process.cwd(), toolsPath);
+    let mod;
+    try {
+        mod = await import(pathToFileURL(absolutePath).href);
+    }
+    catch (cause) {
+        throw new ChatMcpEntryError(`app-kit-chat-mcp: could not load tools module "${toolsPath}" (resolved to ` +
+            `${absolutePath}): ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const candidate = mod.default;
+    if (typeof candidate !== "function") {
+        throw new ChatMcpEntryError(`app-kit-chat-mcp: tools module "${toolsPath}" must have a default export that is a ` +
+            `function returning a ChatMcpProtocol; got ${typeof candidate}.`);
+    }
+    return candidate;
+}
+/** Run the server: load the tools module, build the protocol (via the injected
+ *  kit), and start stdio. Exported for direct unit testing of argument/validation
+ *  failures without a process spawn. */
+export async function main(argv) {
+    const { toolsPath } = parseArgs(argv);
+    const buildChatServer = await loadBuildChatServer(toolsPath);
+    let protocol;
+    try {
+        protocol = await buildChatServer(KIT);
+    }
+    catch (cause) {
+        throw new ChatMcpEntryError(`app-kit-chat-mcp: tools module "${toolsPath}" threw while building its chat server: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    if (protocol === null ||
+        typeof protocol !== "object" ||
+        typeof protocol.handleMessage !== "function") {
+        throw new ChatMcpEntryError(`app-kit-chat-mcp: tools module "${toolsPath}"'s default export must return a ` +
+            `ChatMcpProtocol ({handleMessage(message)}); got ${typeof protocol}.`);
+    }
+    createChatMcpStdioServer({ protocol }).start();
+}
+if (isRunningAsMain(import.meta.url)) {
+    main(process.argv.slice(2)).catch((err) => {
+        console.error(err instanceof ChatMcpEntryError ? err.message : err);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=entry.js.map

package/dist/chat/mcp/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../src/chat/mcp/entry.ts"],"names":[],"mappings":"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"}

package/dist/cli/is-running-as-main.d.ts

@@ -0,0 +1 @@
+export declare function isRunningAsMain(moduleUrl: string): boolean;

package/dist/cli/is-running-as-main.js

@@ -0,0 +1,54 @@
+/**
+ * Whether the module at `moduleUrl` (pass `import.meta.url`) is the one Node was
+ * invoked to run directly — the ESM successor to `require.main === module`, shared
+ * by every bin wrapper (trace-sync.ts/profile-sync.ts/flags-sync.ts/spa-server/cli.ts
+ * and src/chat/mcp/entry.ts) so there's one fix point instead of N copies of the
+ * same check. Node builtins ONLY (`node:fs`, `node:url`) — importing this file never
+ * drags in anything else, which is why src/chat/mcp/entry.ts imports it directly
+ * instead of importing `isRunningAsMain` from ./sync-engine.js: that file also pulls
+ * in `cross-spawn` (for its Prisma-shelling subcommands) at module scope, which would
+ * break entry.ts's own "Node builtins + this package's own chat modules only"
+ * dependency-free bar. sync-engine.ts re-exports this same function so its existing
+ * importers (trace-sync.ts et al.) are unaffected.
+ *
+ * A raw `import.meta.url === pathToFileURL(process.argv[1]).href` string comparison
+ * (the previous check) is NOT reliable: a package manager's bin shim can leave
+ * `argv[1]` pointing at a *symlink* while Node resolves the ESM module id through
+ * that symlink to the real target path for `import.meta.url` — so the two name the
+ * same file but compare unequal. This is not hypothetical: pnpm's
+ * `node_modules/<pkg>` is exactly such a symlink into its content-addressable
+ * store, and it reproduces on Windows for every real invocation path (`pnpm exec
+ * flags-sync init`, an npm-script `"flags-sync init"` run via `pnpm run`, etc.) —
+ * confirmed by instrumenting a real 0.3.0 install: `argv[1]` resolved to
+ * `...\node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js` (the symlinked
+ * path) while `import.meta.url` resolved to
+ * `...\node_modules\.pnpm\@flytedesk+app-kit@0.3.0_.../node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js`
+ * (the real store path). The mismatch meant `main()` was never called at all —
+ * every CLI entrypoint silently no-op'd: exit code 0, no output, nothing written.
+ *
+ * `realpathSync.native` (the real OS `realpath` syscall, not Node's pure-JS
+ * fallback — verified directly: the JS fallback leaves an on-disk casing mismatch
+ * unresolved, e.g. `RealFile.js` vs `realfile.js` compare unequal even though NTFS
+ * treats them as the same file, while `.native` correctly normalizes both to the
+ * same canonical path) resolves both sides to the same canonical filesystem path
+ * first — following symlinks AND normalizing casing — so the comparison is correct
+ * regardless of symlinks, path-separator style, or casing differences between how
+ * a shell/bin-shim sets `argv[1]` and how Node constructs `import.meta.url` for
+ * the same file.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+export function isRunningAsMain(moduleUrl) {
+    if (process.argv[1] === undefined)
+        return false;
+    try {
+        return (realpathSync.native(fileURLToPath(moduleUrl)) ===
+            realpathSync.native(process.argv[1]));
+    }
+    catch {
+        // Either path doesn't exist / isn't resolvable (e.g. a REPL or a bundler that
+        // gives import.meta.url a non-file URL) — definitely not "run directly" then.
+        return false;
+    }
+}
+//# sourceMappingURL=is-running-as-main.js.map

package/dist/cli/is-running-as-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-running-as-main.js","sourceRoot":"","sources":["../../src/cli/is-running-as-main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC;QACH,OAAO,CACL,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;YAC7C,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CACrC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;QAC9E,8EAA8E;QAC9E,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/cli/sync-engine.d.ts

@@ -1,35 +1,4 @@
-/**
- * Whether the module at `moduleUrl` (pass `import.meta.url`) is the one Node was
- * invoked to run directly — the ESM successor to `require.main === module`, shared
- * by every bin wrapper (trace-sync.ts/profile-sync.ts/flags-sync.ts) so there's one
- * fix point instead of three copies of the same check.
- *
- * A raw `import.meta.url === pathToFileURL(process.argv[1]).href` string comparison
- * (the previous check) is NOT reliable: a package manager's bin shim can leave
- * `argv[1]` pointing at a *symlink* while Node resolves the ESM module id through
- * that symlink to the real target path for `import.meta.url` — so the two name the
- * same file but compare unequal. This is not hypothetical: pnpm's
- * `node_modules/<pkg>` is exactly such a symlink into its content-addressable
- * store, and it reproduces on Windows for every real invocation path (`pnpm exec
- * flags-sync init`, an npm-script `"flags-sync init"` run via `pnpm run`, etc.) —
- * confirmed by instrumenting a real 0.3.0 install: `argv[1]` resolved to
- * `...\node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js` (the symlinked
- * path) while `import.meta.url` resolved to
- * `...\node_modules\.pnpm\@flytedesk+app-kit@0.3.0_.../node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js`
- * (the real store path). The mismatch meant `main()` was never called at all —
- * every CLI entrypoint silently no-op'd: exit code 0, no output, nothing written.
- *
- * `realpathSync.native` (the real OS `realpath` syscall, not Node's pure-JS
- * fallback — verified directly: the JS fallback leaves an on-disk casing mismatch
- * unresolved, e.g. `RealFile.js` vs `realfile.js` compare unequal even though NTFS
- * treats them as the same file, while `.native` correctly normalizes both to the
- * same canonical path) resolves both sides to the same canonical filesystem path
- * first — following symlinks AND normalizing casing — so the comparison is correct
- * regardless of symlinks, path-separator style, or casing differences between how
- * a shell/bin-shim sets `argv[1]` and how Node constructs `import.meta.url` for
- * the same file.
- */
-export declare function isRunningAsMain(moduleUrl: string): boolean;
+export { isRunningAsMain } from "./is-running-as-main.js";
 /**
  * Everything that differs between `trace-sync` and `profile-sync`. `name` picks out
  * prisma/fragments/<name>.prisma, prisma/fragments/<name>.meta.json, and every

package/dist/cli/sync-engine.js

@@ -53,53 +53,15 @@
  */
 import { createHash } from "node:crypto";
 import spawn from "cross-spawn";
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-/**
- * Whether the module at `moduleUrl` (pass `import.meta.url`) is the one Node was
- * invoked to run directly — the ESM successor to `require.main === module`, shared
- * by every bin wrapper (trace-sync.ts/profile-sync.ts/flags-sync.ts) so there's one
- * fix point instead of three copies of the same check.
- *
- * A raw `import.meta.url === pathToFileURL(process.argv[1]).href` string comparison
- * (the previous check) is NOT reliable: a package manager's bin shim can leave
- * `argv[1]` pointing at a *symlink* while Node resolves the ESM module id through
- * that symlink to the real target path for `import.meta.url` — so the two name the
- * same file but compare unequal. This is not hypothetical: pnpm's
- * `node_modules/<pkg>` is exactly such a symlink into its content-addressable
- * store, and it reproduces on Windows for every real invocation path (`pnpm exec
- * flags-sync init`, an npm-script `"flags-sync init"` run via `pnpm run`, etc.) —
- * confirmed by instrumenting a real 0.3.0 install: `argv[1]` resolved to
- * `...\node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js` (the symlinked
- * path) while `import.meta.url` resolved to
- * `...\node_modules\.pnpm\@flytedesk+app-kit@0.3.0_.../node_modules\@flytedesk\app-kit\dist\cli\flags-sync.js`
- * (the real store path). The mismatch meant `main()` was never called at all —
- * every CLI entrypoint silently no-op'd: exit code 0, no output, nothing written.
- *
- * `realpathSync.native` (the real OS `realpath` syscall, not Node's pure-JS
- * fallback — verified directly: the JS fallback leaves an on-disk casing mismatch
- * unresolved, e.g. `RealFile.js` vs `realfile.js` compare unequal even though NTFS
- * treats them as the same file, while `.native` correctly normalizes both to the
- * same canonical path) resolves both sides to the same canonical filesystem path
- * first — following symlinks AND normalizing casing — so the comparison is correct
- * regardless of symlinks, path-separator style, or casing differences between how
- * a shell/bin-shim sets `argv[1]` and how Node constructs `import.meta.url` for
- * the same file.
- */
-export function isRunningAsMain(moduleUrl) {
-    if (process.argv[1] === undefined)
-        return false;
-    try {
-        return (realpathSync.native(fileURLToPath(moduleUrl)) ===
-            realpathSync.native(process.argv[1]));
-    }
-    catch {
-        // Either path doesn't exist / isn't resolvable (e.g. a REPL or a bundler that
-        // gives import.meta.url a non-file URL) — definitely not "run directly" then.
-        return false;
-    }
-}
+// Re-exported so trace-sync.ts/profile-sync.ts/flags-sync.ts keep importing it from
+// here unchanged — the implementation (and its symlink/casing bug history) now lives
+// in its own Node-builtins-only module because src/chat/mcp/entry.ts needs the exact
+// same check WITHOUT this file's `cross-spawn` import coming along for the ride. See
+// is-running-as-main.ts's own doc comment for the full contract.
+export { isRunningAsMain } from "./is-running-as-main.js";
 export class SyncCliError extends Error {
 }
 function readJson(filePath) {