@flytedesk/app-kit 0.3.0 → 0.4.0

package/dist/chat/mcp-protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The Model Context Protocol conversation a dispatched chat agent speaks, as pure
+ * functions — extracted and generalized from media-planner's
+ * `packages/chat-mcp/src/protocol.mjs`.
+ *
+ * MCP over stdio is JSON-RPC 2.0 in newline-delimited JSON. The surface a client
+ * actually needs from a tools-only server is small — `initialize`, `tools/list`,
+ * `tools/call`, and `ping` — implemented directly here rather than pulling in the
+ * MCP SDK, the same reasoning the original file gave: this protocol is meant to run
+ * dependency-free (see mcp-server.ts), so this module imports nothing beyond
+ * ./types.js.
+ *
+ * The ONE thing the original hard-coded that this version generalizes: which tools
+ * exist. There, `planner_reply` plus five media-planner-specific tools were all
+ * switched on by name inside `tools/call`. Here, `tools/call` dispatches to whichever
+ * `AppRegisteredTool` the caller registered — `createReplyTool` below builds the
+ * reply tool through that SAME mechanism, so "the reply tool" and "an app's own
+ * tool" are not two different code paths, just two entries in the same array. That
+ * array is the extension point AK-12 asks for: an app adds `audience_validate`,
+ * `audience_sample`, `audience_propose_change`, or whatever else it needs, by
+ * passing more `AppRegisteredTool` entries to `createChatMcpProtocol`.
+ */
+import type { AppRegisteredTool } from "./types.js";
+/** The protocol version this server implements and will fall back to. */
+export declare const FALLBACK_PROTOCOL_VERSION = "2024-11-05";
+/** JSON-RPC error codes used here (the subset from the spec that applies). */
+export declare const JSON_RPC: {
+    INVALID_PARAMS: number;
+    METHOD_NOT_FOUND: number;
+    INTERNAL_ERROR: number;
+};
+export interface ChatMcpProtocolOptions {
+    /** Advertised in `initialize`'s `serverInfo.name`. */
+    serverName: string;
+    /** Advertised in `initialize`'s `serverInfo.version`. Defaults to "0.1.0". */
+    serverVersion?: string;
+    /** Every tool this server exposes — the reply tool (via `createReplyTool`) plus
+     *  whatever the consuming app registers of its own. Order is preserved in
+     *  `tools/list`. */
+    tools: AppRegisteredTool[];
+}
+export interface ChatMcpProtocol {
+    /**
+     * Handle one incoming JSON-RPC message. Returns `null` for anything that must not
+     * be answered — notifications (which carry no id and by spec get no response).
+     * The caller writes whatever is returned and writes nothing otherwise.
+     */
+    handleMessage(message: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+}
+export declare function createChatMcpProtocol(options: ChatMcpProtocolOptions): ChatMcpProtocol;
+export interface ChatReplyPayload {
+    kind: "progress" | "final";
+    text: string;
+    packet?: {
+        type: string;
+        payload: Record<string, unknown>;
+    };
+    citations?: unknown[];
+}
+export type ReplyDeliverResult = {
+    ok: true;
+} | {
+    ok: false;
+    retryable: boolean;
+    message: string;
+};
+export interface ParseReplyArgumentsOptions {
+    /** Restrict `packet.type` to this list. Omit to allow any non-empty string —
+     *  useful when the app validates packet shape downstream of delivery instead
+     *  (the same choice media-planner's own `/chat/internal/reply` route makes). */
+    packetTypes?: string[];
+}
+/** Validate the arguments of a reply-tool call. Exported for direct unit testing,
+ *  matching the original protocol.mjs's own `parseReplyArguments`. */
+export declare function parseReplyArguments(args: unknown, options?: ParseReplyArgumentsOptions): {
+    ok: true;
+    value: ChatReplyPayload;
+} | {
+    ok: false;
+    message: string;
+};
+export interface ReplyToolOptions {
+    /** Tool name advertised to the agent. Default "chat_reply". */
+    name?: string;
+    /** Full description shown to the model — write this in your own product's voice;
+     *  it is the one thing that tells the agent this is its ONLY way to speak. */
+    description: string;
+    /** See ParseReplyArgumentsOptions.packetTypes. */
+    packetTypes?: string[];
+    /** POST (or otherwise deliver) one reply to the app's own callback route. */
+    deliver: (reply: ChatReplyPayload) => Promise<ReplyDeliverResult>;
+}
+/** Build the reply tool — the ONE tool every consumer of this module needs, and the
+ *  one built-in entry alongside whatever `AppRegisteredTool`s the app adds of its
+ *  own (the extension point). */
+export declare function createReplyTool(options: ReplyToolOptions): AppRegisteredTool;

package/dist/chat/mcp-protocol.js

@@ -0,0 +1,200 @@
+/** The protocol version this server implements and will fall back to. */
+export const FALLBACK_PROTOCOL_VERSION = "2024-11-05";
+/** JSON-RPC error codes used here (the subset from the spec that applies). */
+export const JSON_RPC = {
+    INVALID_PARAMS: -32602,
+    METHOD_NOT_FOUND: -32601,
+    INTERNAL_ERROR: -32603,
+};
+function ok(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function err(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
+/**
+ * A tool-call outcome that is the AGENT's mistake rather than a transport failure —
+ * a bad argument, or a reply sent after the turn already closed. MCP models these as
+ * a successful call whose result carries `isError`, which is what puts the message
+ * in front of the model so it can correct itself, instead of a JSON-RPC error that
+ * surfaces as a broken tool.
+ */
+function toolError(id, message) {
+    return ok(id, { content: [{ type: "text", text: message }], isError: true });
+}
+function toolSuccess(id, content) {
+    return ok(id, { content });
+}
+export function createChatMcpProtocol(options) {
+    const toolsByName = new Map(options.tools.map((tool) => [tool.name, tool]));
+    return {
+        async handleMessage(message) {
+            const method = typeof message.method === "string" ? message.method : "";
+            const hasId = message.id !== undefined && message.id !== null;
+            const id = hasId ? message.id : null;
+            // Notifications carry no id and get no response, per JSON-RPC.
+            if (!hasId)
+                return null;
+            switch (method) {
+                case "initialize": {
+                    const params = (message.params ?? {});
+                    const requested = params.protocolVersion;
+                    return ok(id, {
+                        protocolVersion: typeof requested === "string" ? requested : FALLBACK_PROTOCOL_VERSION,
+                        capabilities: { tools: {} },
+                        serverInfo: { name: options.serverName, version: options.serverVersion ?? "0.1.0" },
+                    });
+                }
+                case "tools/list":
+                    return ok(id, {
+                        tools: options.tools.map((tool) => ({
+                            name: tool.name,
+                            description: tool.description,
+                            inputSchema: tool.inputSchema,
+                        })),
+                    });
+                case "tools/call": {
+                    const params = (message.params ?? {});
+                    const name = params.name;
+                    if (typeof name !== "string" || name === "") {
+                        return err(id, JSON_RPC.INVALID_PARAMS, '`params.name` must be a non-empty string.');
+                    }
+                    const tool = toolsByName.get(name);
+                    if (!tool) {
+                        return err(id, JSON_RPC.METHOD_NOT_FOUND, `Unknown tool "${name}"`);
+                    }
+                    const result = await tool.handler(params.arguments);
+                    if (result.ok)
+                        return toolSuccess(id, result.content);
+                    // A retryable failure is the transport's fault and is reported as a
+                    // JSON-RPC error; a non-retryable one is the agent's own mistake and is
+                    // reported as a tool error so the model reads it and corrects itself
+                    // rather than retrying into the same failure.
+                    return result.retryable
+                        ? err(id, JSON_RPC.INTERNAL_ERROR, result.message)
+                        : toolError(id, result.message);
+                }
+                case "ping":
+                    return ok(id, {});
+                default:
+                    return err(id, JSON_RPC.METHOD_NOT_FOUND, `Unknown method "${method}"`);
+            }
+        },
+    };
+}
+/** Validate the arguments of a reply-tool call. Exported for direct unit testing,
+ *  matching the original protocol.mjs's own `parseReplyArguments`. */
+export function parseReplyArguments(args, options = {}) {
+    if (args === null || typeof args !== "object" || Array.isArray(args)) {
+        return { ok: false, message: "Arguments must be an object with `kind` and `text`." };
+    }
+    const record = args;
+    const { kind, text, packet, citations } = record;
+    if (kind !== "progress" && kind !== "final") {
+        return { ok: false, message: '`kind` must be either "progress" or "final".' };
+    }
+    if (typeof text !== "string" || text.trim() === "") {
+        return { ok: false, message: "`text` must be a non-empty string." };
+    }
+    if (packet !== undefined && packet !== null) {
+        if (typeof packet !== "object" || Array.isArray(packet)) {
+            return { ok: false, message: "`packet` must be an object with `type` and `payload`." };
+        }
+        const p = packet;
+        if (typeof p.type !== "string" || p.type === "") {
+            return { ok: false, message: "`packet.type` must be a non-empty string." };
+        }
+        if (options.packetTypes && !options.packetTypes.includes(p.type)) {
+            return {
+                ok: false,
+                message: `\`packet.type\` must be one of: ${options.packetTypes.join(", ")}.`,
+            };
+        }
+        if (p.payload === null || typeof p.payload !== "object" || Array.isArray(p.payload)) {
+            return { ok: false, message: "`packet.payload` must be an object." };
+        }
+        // A packet on a progress line would never be rendered — reject it rather than
+        // dropping it silently and leaving the agent believing it proposed something.
+        if (kind === "progress") {
+            return { ok: false, message: "A `packet` can only be attached to a `final` reply." };
+        }
+    }
+    if (citations !== undefined && citations !== null && !Array.isArray(citations)) {
+        return { ok: false, message: "`citations` must be an array." };
+    }
+    const value = { kind, text };
+    if (packet !== undefined && packet !== null)
+        value.packet = packet;
+    if (citations !== undefined && citations !== null)
+        value.citations = citations;
+    return { ok: true, value };
+}
+/** Build the reply tool — the ONE tool every consumer of this module needs, and the
+ *  one built-in entry alongside whatever `AppRegisteredTool`s the app adds of its
+ *  own (the extension point). */
+export function createReplyTool(options) {
+    const name = options.name ?? "chat_reply";
+    return {
+        name,
+        description: options.description,
+        inputSchema: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: ["progress", "final"],
+                    description: '"progress" for a short status line shown while you work (send this immediately, ' +
+                        'before doing anything else); "final" for your complete answer. Exactly one "final" per turn.',
+                },
+                text: {
+                    type: "string",
+                    description: 'The message. For "final", markdown formatted. For "progress", one short present-tense line.',
+                },
+                packet: {
+                    type: "object",
+                    description: "Optional, and only on a final reply: a structured proposal attached to the answer.",
+                    properties: {
+                        type: options.packetTypes ? { type: "string", enum: options.packetTypes } : { type: "string" },
+                        payload: { type: "object" },
+                    },
+                    required: ["type", "payload"],
+                },
+                citations: {
+                    type: "array",
+                    description: "Optional source references shown under a final answer.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            marker: { type: "number" },
+                            title: { type: "string" },
+                            detail: { type: "string" },
+                        },
+                        required: ["marker", "title"],
+                    },
+                },
+            },
+            required: ["kind", "text"],
+        },
+        async handler(args) {
+            const parsed = parseReplyArguments(args, { packetTypes: options.packetTypes });
+            if (!parsed.ok)
+                return { ok: false, retryable: false, message: parsed.message };
+            const result = await options.deliver(parsed.value);
+            if (result.ok) {
+                return {
+                    ok: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: parsed.value.kind === "final"
+                                ? "Delivered. This turn is now complete — do not send anything further."
+                                : "Delivered. Continue with the work, then send your final reply.",
+                        },
+                    ],
+                };
+            }
+            return { ok: false, retryable: result.retryable, message: result.message };
+        },
+    };
+}
+//# sourceMappingURL=mcp-protocol.js.map

package/dist/chat/mcp-protocol.js.map

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

package/dist/chat/mcp-server.d.ts

@@ -0,0 +1,17 @@
+import type { ChatMcpProtocol } from "./mcp-protocol.js";
+export interface ChatMcpStdioServerOptions {
+    protocol: ChatMcpProtocol;
+    /** Defaults to `process.stdin`. Overridable for tests. */
+    input?: NodeJS.ReadableStream;
+    /** Defaults to `process.stdout`. Overridable for tests. */
+    output?: NodeJS.WritableStream;
+    /** Defaults to writing to `process.stderr`. Overridable for tests. */
+    onError?: (message: string) => void;
+}
+export interface ChatMcpStdioServer {
+    /** Start reading lines from `input`. Registers listeners and returns immediately —
+     *  it does not block until the stream closes; the process stays alive on its own
+     *  (stdin being read is enough to keep Node running) until `input` closes. */
+    start(): void;
+}
+export declare function createChatMcpStdioServer(options: ChatMcpStdioServerOptions): ChatMcpStdioServer;

package/dist/chat/mcp-server.js

@@ -0,0 +1,71 @@
+/**
+ * The stdio transport for a chat MCP server — extracted and generalized from
+ * media-planner's `packages/chat-mcp/src/server.mjs`'s I/O loop (that file's own
+ * `deliver`/`read`/`write` HTTP helpers stay app-specific; only the newline-delimited
+ * JSON-RPC plumbing moves here).
+ *
+ * Deliberately built on Node builtins ONLY (`node:readline`) — no runtime dependency
+ * on anything else in this package or elsewhere. The reason: danxbot runs a
+ * dispatched agent's MCP server straight out of a plain git clone with no install
+ * step, so whatever script actually executes there must be runnable with nothing
+ * more than `node <file>`. This module (and mcp-protocol.ts, which it composes with)
+ * satisfy that constraint structurally; wiring a specific app's checkout so the
+ * *published* `@flytedesk/app-kit` package is actually resolvable from that
+ * unbuilt clone is that app's own integration concern, not this module's.
+ */
+import { createInterface } from "node:readline";
+export function createChatMcpStdioServer(options) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const onError = options.onError ?? ((message) => process.stderr.write(`${message}\n`));
+    function writeLine(payload) {
+        output.write(`${JSON.stringify(payload)}\n`);
+    }
+    return {
+        start() {
+            const rl = createInterface({ input });
+            rl.on("line", (line) => {
+                const trimmed = line.trim();
+                if (trimmed === "")
+                    return;
+                let message;
+                try {
+                    message = JSON.parse(trimmed);
+                }
+                catch {
+                    // Unparseable input has no id to answer against, so there is nothing to
+                    // reply to — report it and keep the stream alive rather than tearing down
+                    // the session.
+                    onError(`ignoring unparseable line: ${trimmed}`);
+                    return;
+                }
+                // Handled without awaiting so a slow delivery cannot block the next
+                // request; JSON-RPC responses carry their own id, so out-of-order
+                // completion is fine.
+                void options.protocol
+                    .handleMessage(message)
+                    .then((response) => {
+                    if (response)
+                        writeLine(response);
+                })
+                    .catch((cause) => {
+                    const err = cause;
+                    onError(`handler failed: ${err?.stack ?? String(cause)}`);
+                    const id = message.id;
+                    if (id !== undefined && id !== null) {
+                        writeLine({
+                            jsonrpc: "2.0",
+                            id,
+                            error: { code: -32603, message: `Internal error: ${err?.message ?? String(cause)}` },
+                        });
+                    }
+                });
+            });
+            // stdin closing is the client going away — nothing further to do; the
+            // process's own exit is the caller's concern (see this module's usage in a
+            // package `bin`/entrypoint script), not this function's.
+            rl.on("close", () => { });
+        },
+    };
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/chat/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../../src/chat/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAoBhD,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAChD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC;IAE/F,SAAS,SAAS,CAAC,OAAgC;QACjD,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO;QACL,KAAK;YACH,MAAM,EAAE,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YAEtC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBACrB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,IAAI,OAAO,KAAK,EAAE;oBAAE,OAAO;gBAE3B,IAAI,OAAgC,CAAC;gBACrC,IAAI,CAAC;oBACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;gBAC3D,CAAC;gBAAC,MAAM,CAAC;oBACP,wEAAwE;oBACxE,0EAA0E;oBAC1E,eAAe;oBACf,OAAO,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;oBACjD,OAAO;gBACT,CAAC;gBAED,oEAAoE;gBACpE,kEAAkE;gBAClE,sBAAsB;gBACtB,KAAK,OAAO,CAAC,QAAQ;qBAClB,aAAa,CAAC,OAAO,CAAC;qBACtB,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE;oBACjB,IAAI,QAAQ;wBAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;gBACpC,CAAC,CAAC;qBACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;oBACxB,MAAM,GAAG,GAAG,KAAyD,CAAC;oBACtE,OAAO,CAAC,mBAAmB,GAAG,EAAE,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBAC1D,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;oBACtB,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;wBACpC,SAAS,CAAC;4BACR,OAAO,EAAE,KAAK;4BACd,EAAE;4BACF,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,mBAAmB,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;yBACrF,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC,CAAC,CAAC;YACP,CAAC,CAAC,CAAC;YAEH,sEAAsE;YACtE,2EAA2E;YAC3E,yDAAyD;YACzD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/chat/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types for @flytedesk/app-kit/chat — see index.ts for the module overview.
+ */
+/** danxbot's own launch/resume response shape (`POST /api/launch` / `/api/resume`). */
+export interface DanxbotDispatchResult {
+    jobId: string;
+    parentJobId?: string;
+}
+export interface DanxbotJobStatus {
+    jobId: string;
+    /** danxbot's own vocabulary — "running", "completed", "failed", "critical_failure", … */
+    status: string;
+    summary: string;
+    elapsedSeconds: number;
+    /** Real usage off danxbot's own wire, never estimated. Defaulted to 0 only for a
+     *  field genuinely ABSENT from an otherwise-successful response (defensive parsing
+     *  of someone else's JSON) — a failed `getJobStatus` call throws, it never returns
+     *  zeros to paper over a failure. */
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+}
+export interface DanxbotLauncherOptions {
+    /** Base URL of the danxbot worker's HTTP API, e.g. "http://localhost:5555". */
+    apiUrl: string;
+    /** Bearer token danxbot's `/api/launch`/`/api/resume`/`/api/status` expect. */
+    apiToken: string;
+    /** The danxbot board this app's chat turns dispatch onto, e.g. "sms-app:sms-app-main". */
+    board: string;
+    /** The danxbot agent profile to dispatch — the board-level chat profile the
+     *  consuming app registered (see this module's README section on wiring a
+     *  `.danxbot/config` profile override), NOT danxbot's own per-card `board-chat`. */
+    profile: string;
+}
+export interface DanxbotLauncher {
+    /** Dispatch one chat turn — see dispatchChatTurn's own doc comment for the
+     *  launch-vs-resume branching. */
+    dispatchChatTurn(input: {
+        task: string;
+        overlay: Record<string, string>;
+        parentJobId?: string | null;
+    }): Promise<DanxbotDispatchResult>;
+    getJobStatus(jobId: string): Promise<DanxbotJobStatus>;
+}
+/** One MCP tool-result content block — the two kinds this module's tools ever return. */
+export type ChatToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/**
+ * The outcome of one tool call, common to the built-in reply tool and every
+ * app-registered tool. Mirrors the retryable/non-retryable split the underlying HTTP
+ * call already makes: a transport failure (network error, 5xx) is worth the agent
+ * retrying, while a 4xx/validation failure is the agent's own mistake to correct, so
+ * it is reported as a tool error the model reads rather than a broken tool.
+ */
+export type ChatToolCallResult = {
+    ok: true;
+    content: ChatToolContent[];
+} | {
+    ok: false;
+    retryable: boolean;
+    message: string;
+};
+/**
+ * One tool an app registers on top of the shared chat MCP server — the extension
+ * point AK-12 exists to provide. `handler` receives the raw `tools/call` arguments
+ * (validating them, including reporting a bad argument as a non-retryable
+ * `ChatToolCallResult`, is the tool's own job — the same contract MCP itself uses:
+ * arguments are untyped until a specific tool decides what shape it needs).
+ */
+export interface AppRegisteredTool {
+    name: string;
+    description: string;
+    /** JSON Schema, exactly as advertised in `tools/list`. */
+    inputSchema: Record<string, unknown>;
+    handler: (args: unknown) => Promise<ChatToolCallResult>;
+}
+/** The env contract every app wiring this module in shares — see env.ts. */
+export interface ChatEnv {
+    danxbotApiUrl: string;
+    danxbotBoardId: string;
+    danxbotApiToken: string;
+    danxbotCallbackApiUrl: string;
+    danxbotCallbackSecret: string;
+}

package/dist/chat/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for @flytedesk/app-kit/chat — see index.ts for the module overview.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/chat/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/chat/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/cli/flags-sync.js

@@ -8,14 +8,11 @@
  * fragment name and the "flags-sync" bin name; trace-sync.ts/profile-sync.ts are the
  * same wrapper for the trace/profile fragments.
  */
-import { pathToFileURL } from "node:url";
-import { runSyncCli, SyncCliError } from "./sync-engine.js";
+import { isRunningAsMain, runSyncCli, SyncCliError } from "./sync-engine.js";
 export async function main(argv) {
     return runSyncCli(argv, { name: "flags", binName: "flags-sync" });
 }
-const isMainModule = process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMainModule) {
+if (isRunningAsMain(import.meta.url)) {
     main(process.argv.slice(2)).catch((err) => {
         if (!(err instanceof SyncCliError)) {
             console.error(err);

package/dist/cli/flags-sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"flags-sync.js","sourceRoot":"","sources":["../../src/cli/flags-sync.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,YAAY,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS;IAC7B,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAE1D,IAAI,YAAY,EAAE,CAAC;IACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"flags-sync.js","sourceRoot":"","sources":["../../src/cli/flags-sync.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE7E,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/profile-sync.js

@@ -8,14 +8,11 @@
  * fragment name and the "profile-sync" bin name; trace-sync.ts is the same wrapper
  * for the trace fragment.
  */
-import { pathToFileURL } from "node:url";
-import { runSyncCli, SyncCliError } from "./sync-engine.js";
+import { isRunningAsMain, runSyncCli, SyncCliError } from "./sync-engine.js";
 export async function main(argv) {
     return runSyncCli(argv, { name: "profile", binName: "profile-sync" });
 }
-const isMainModule = process.argv[1] !== undefined &&
-    import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isMainModule) {
+if (isRunningAsMain(import.meta.url)) {
     main(process.argv.slice(2)).catch((err) => {
         if (!(err instanceof SyncCliError)) {
             console.error(err);

package/dist/cli/profile-sync.js.map

@@ -1 +1 @@
-{"version":3,"file":"profile-sync.js","sourceRoot":"","sources":["../../src/cli/profile-sync.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,YAAY,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS;IAC7B,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAE1D,IAAI,YAAY,EAAE,CAAC;IACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"profile-sync.js","sourceRoot":"","sources":["../../src/cli/profile-sync.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AACH,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE7E,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAc;IACvC,OAAO,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC"}

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

@@ -1,3 +1,35 @@
+/**
+ * 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;
 /**
  * Everything that differs between `trace-sync` and `profile-sync`. `name` picks out
  * prisma/fragments/<name>.prisma, prisma/fragments/<name>.meta.json, and every