@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/cli/mcp/protocol.js

@@ -0,0 +1,151 @@
+// @ts-check
+'use strict';
+
+const readline = require('node:readline');
+
+/**
+ * A tool of the server: what the client lists, and what runs when it calls it. `run` returns the structured result;
+ * a result with `isError` tells the model the command failed, in a way it can act on.
+ * @typedef {{
+ *   name: string;
+ *   title: string;
+ *   description: string;
+ *   inputSchema: Record<string, unknown>;
+ *   annotations: { readOnlyHint: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint: boolean };
+ *   run: (args: Record<string, unknown>) => Promise<{ result: unknown; isError?: boolean }>;
+ * }} Tool
+ */
+
+// The revision without a handshake, where every request names its version; and the ones with `initialize`, which
+// clients still speak (Claude Code takes either, by its runtime).
+const MODERN = '2026-07-28';
+const LEGACY = ['2025-11-25', '2025-06-18', '2025-03-26'];
+const SUPPORTED = [MODERN, ...LEGACY];
+const VERSION = 'io.modelcontextprotocol/protocolVersion';
+const SERVER_INFO = 'io.modelcontextprotocol/serverInfo';
+
+/**
+ * Serves tools over stdio as an MCP server: one JSON-RPC message per line in and out, nothing else on the output.
+ * Requests run one after another, so that a command's output, which the tools catch, never mixes with another's. It
+ * ends when the input does.
+ * @param {{
+ *   info: { name: string; version: string };
+ *   instructions: string;
+ *   tools: Tool[];
+ *   input?: NodeJS.ReadableStream;
+ *   send?: (line: string) => void;
+ * }} server `send` writes a line to the client: the real stdout, taken before any tool runs
+ * @returns {Promise<void>} when the input ends
+ */
+function serve({ info, instructions, tools, input = process.stdin, send }) {
+  const write = send ?? process.stdout.write.bind(process.stdout);
+  const reply = (/** @type {Record<string, unknown>} */ message) =>
+    write(JSON.stringify({ jsonrpc: '2.0', ...message }) + '\n');
+  let queue = Promise.resolve();
+  return new Promise((resolve) => {
+    const lines = readline.createInterface({ input });
+    lines.on('line', (line) => {
+      if (!line.trim()) return;
+      /** @type {any} */
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        reply({ id: null, error: { code: -32700, message: 'Parse error' } });
+        return;
+      }
+      if (message?.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+        if (message?.id !== undefined) {
+          reply({ id: message.id, error: { code: -32600, message: 'Invalid request' } });
+        }
+        return;
+      }
+      // A notification (initialized, cancelled) asks for no answer.
+      if (message.id === undefined) return;
+      queue = queue.then(() => handle(message));
+    });
+    lines.on('close', () => queue.then(() => resolve()));
+  });
+
+  /**
+   * @param {{ id: string | number; method: string; params?: any }} message
+   */
+  async function handle({ id, method, params }) {
+    try {
+      const requested = params?._meta?.[VERSION];
+      if (requested !== undefined && !SUPPORTED.includes(requested)) {
+        throw rpcError(-32022, 'Unsupported protocol version', { supported: SUPPORTED, requested });
+      }
+      /** @type {Record<string, unknown>} */
+      let result;
+      if (method === 'initialize') {
+        const asked = params?.protocolVersion;
+        result = {
+          protocolVersion: LEGACY.includes(asked) ? asked : LEGACY[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: info,
+          instructions,
+        };
+      } else if (method === 'ping') {
+        result = {};
+      } else if (method === 'server/discover') {
+        result = {
+          supportedVersions: SUPPORTED,
+          capabilities: { tools: { listChanged: false } },
+          instructions,
+          ttlMs: 0,
+          cacheScope: 'private',
+        };
+      } else if (method === 'tools/list') {
+        result = {
+          tools: tools.map(({ name, title, description, inputSchema, annotations }) => ({
+            name,
+            title,
+            description,
+            inputSchema,
+            annotations,
+          })),
+          ttlMs: 0,
+          cacheScope: 'private',
+        };
+      } else if (method === 'tools/call') {
+        const tool = tools.find(({ name }) => name === params?.name);
+        if (!tool) throw rpcError(-32602, `Unknown tool: ${params?.name}`);
+        const arguments_ = params?.arguments ?? {};
+        if (typeof arguments_ !== 'object' || Array.isArray(arguments_)) {
+          throw rpcError(-32602, 'arguments is an object');
+        }
+        const { result: structured, isError = false } = await tool.run(arguments_);
+        const text =
+          typeof structured === 'string' ? structured : JSON.stringify(structured, null, 2);
+        // Claude Code shows the structured result in place of the text: both carry the same.
+        result = {
+          content: [{ type: 'text', text }],
+          ...(typeof structured === 'object' &&
+            structured !== null && { structuredContent: structured }),
+          isError,
+        };
+      } else {
+        throw rpcError(-32601, `Method not found: ${method}`);
+      }
+      if (requested === MODERN) {
+        result = { resultType: 'complete', ...result, _meta: { [SERVER_INFO]: info } };
+      }
+      reply({ id, result });
+    } catch (error) {
+      const { code = -32603, message = String(error), data } = /** @type {any} */ (error);
+      reply({ id, error: { code, message, ...(data !== undefined && { data }) } });
+    }
+  }
+}
+
+/**
+ * @param {number} code
+ * @param {string} message
+ * @param {unknown} [data]
+ */
+function rpcError(code, message, data) {
+  return Object.assign(new Error(message), { code, data });
+}
+
+module.exports = { serve, SUPPORTED };

package/cli/mcp/tools.js

@@ -0,0 +1,389 @@
+// @ts-check
+'use strict';
+
+const { codegen } = require('../codegen');
+const { doctor } = require('../doctor');
+const { exec } = require('../exec');
+const { icons } = require('../icons');
+const { info } = require('../info');
+const { links } = require('../links');
+const { migrate } = require('../migrate');
+const { screen } = require('../screen');
+const { setup } = require('../setup');
+const { splash } = require('../splash');
+const { createUI } = require('../ui');
+const { appMap } = require('./appMap');
+const { loadDocs, readDoc, searchDocs } = require('./docs');
+
+/** @typedef {import('./protocol').Tool} Tool */
+
+// An install that sharp, a dependency or the pods may need takes minutes; nothing may print to stdout meanwhile.
+const LONG = 20 * 60_000;
+
+const APPLY = {
+  apply: {
+    type: 'boolean',
+    description:
+      'Write the changes. Without it the tool returns the plan: every file with its diff.',
+  },
+};
+
+/**
+ * The tools of the server, on the app in `root`: the commands of the CLI as JSON, the map of the app, the docs.
+ * @param {string} root
+ * @param {import('../exec').Exec} [run]
+ * @returns {Tool[]}
+ */
+function createTools(root, run = exec) {
+  const install = (/** @type {string} */ manager, /** @type {string[]} */ args) =>
+    run(manager, args, { cwd: root, timeout: LONG }).ok;
+  /**
+   * A command that changes files: a plan, or written with `apply`.
+   * @param {Record<string, unknown>} args
+   */
+  const changes = (args) => ({
+    root,
+    yes: args.apply === true,
+    dryRun: args.apply !== true,
+    json: true,
+    ui: silentUI(),
+    run,
+  });
+  return [
+    {
+      name: 'app_map',
+      title: 'The map of the app',
+      description:
+        "The app's navigation from its code: each screen of screens with its props as TypeScript types them and whether it is React or native, the root or roots, the links of linking, and whether all screens render in one React tree. Read it before changing the navigation.",
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      run: async () => {
+        const map = appMap(root, run);
+        return { result: map, isError: 'error' in map };
+      },
+    },
+    {
+      name: 'docs_search',
+      title: 'Search the docs',
+      description:
+        'Searches the docs of the installed navigation: guides, the API, the options. Gives sections with a line each; read one with docs_read.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Words to look for, such as "modal sheet detents".',
+          },
+          limit: { type: 'integer', minimum: 1, maximum: 20, description: '8 by default.' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      run: async (args) => ({
+        result: {
+          results: searchDocs(loadDocs(), String(args.query ?? ''), Number(args.limit) || 8),
+        },
+      }),
+    },
+    {
+      name: 'docs_read',
+      title: 'Read the docs',
+      description:
+        'A page of the docs of the installed navigation as Markdown, or one of its sections: the page as docs_search gives it (such as "fundamentals/screens-and-props"), and the anchor of a section.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          page: { type: 'string', description: 'The page, such as "guides/deep-links".' },
+          section: { type: 'string', description: 'The anchor of a section, such as "routes".' },
+        },
+        required: ['page'],
+        additionalProperties: false,
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      run: async (args) => {
+        const page = readDoc(
+          loadDocs(),
+          String(args.page ?? ''),
+          args.section === undefined ? undefined : String(args.section)
+        );
+        return page
+          ? { result: page }
+          : {
+              result: { error: `No page or section ${args.page} ${args.section ?? ''}`.trim() },
+              isError: true,
+            };
+      },
+    },
+    {
+      name: 'doctor',
+      title: 'Check the app',
+      description:
+        'Checks what the navigation needs in the app and on this machine: React Native, the native files, the typed commands, the screens, the links, the icons, Xcode, CocoaPods, the JDK, the Android SDK, the devices. Each problem comes with its fix.',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      run: () =>
+        output((write) => doctor({ root, fix: false, json: true, ui: silentUI(), run, write })),
+    },
+    {
+      name: 'info',
+      title: 'What the app is made with',
+      description:
+        'The versions the app is made and built with, for an issue: the system, Node, React Native, the navigation and how it renders, Xcode, CocoaPods, the JDK, the Android SDK.',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      run: () => output((write) => info({ root, json: true, run, write })),
+    },
+    {
+      name: 'setup',
+      title: 'Set up the app',
+      description:
+        'Sets the app up for the navigation: its native entry points, index.js and Navigation.ts, the typed commands, then the pods on a Mac.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          ...APPLY,
+          skipPods: { type: 'boolean', description: 'Leave the pods for later.' },
+        },
+        additionalProperties: false,
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      run: (args) => output(() => setup({ ...changes(args), skipPods: args.skipPods === true })),
+    },
+    {
+      name: 'screen',
+      title: 'Add a screen',
+      description:
+        'Adds a screen: its file and its entry in screens. A native screen (native, or ios / android) also gets its Swift and Kotlin files and its generated code.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'PascalCase, such as Profile.' },
+          dir: {
+            type: 'string',
+            description: 'The folder of the screens, from the root of the app.',
+          },
+          native: {
+            type: 'boolean',
+            description: 'A native screen on both platforms, SwiftUI and Compose.',
+          },
+          ios: { type: 'string', enum: ['swiftui', 'uikit'] },
+          android: { type: 'string', enum: ['compose', 'views'] },
+          ...APPLY,
+        },
+        required: ['name'],
+        additionalProperties: false,
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      run: (args) =>
+        output(() =>
+          screen({
+            ...changes(args),
+            name: String(args.name ?? ''),
+            dir: optionalString(args.dir),
+            native: args.native === true,
+            ios: optionalString(args.ios),
+            android: optionalString(args.android),
+          })
+        ),
+    },
+    {
+      name: 'codegen',
+      title: 'Generate the native code',
+      description:
+        'Generates the Swift and Kotlin of the native screens from their props in TypeScript, with the typed commands of native code.',
+      inputSchema: { type: 'object', properties: { ...APPLY }, additionalProperties: false },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      run: (args) => output(() => codegen({ ...changes(args) })),
+    },
+    {
+      name: 'links',
+      title: 'Declare the links',
+      description:
+        'Declares the prefixes of linking on the native side: the schemes in Info.plist and the manifest, the web sites in the entitlements and a verified filter of the manifest.',
+      inputSchema: { type: 'object', properties: { ...APPLY }, additionalProperties: false },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      run: (args) => output(() => links({ ...changes(args) })),
+    },
+    {
+      name: 'icons',
+      title: 'Make the app icon',
+      description:
+        'Makes the app icon of both platforms from a logo and a color, or from a ready square icon; without options, again from the settings in package.json. Replaces the icon files.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          logo: {
+            type: 'string',
+            description: 'A PNG, JPEG, WebP or SVG on a transparent background.',
+          },
+          image: {
+            type: 'string',
+            description: 'A ready square icon, at least 1024 px, instead of logo.',
+          },
+          background: { type: 'string', description: 'A color such as #FFFFFF.' },
+          darkLogo: { type: 'string' },
+          logoSize: {
+            type: 'number',
+            description: 'The logo in percent of the icon, 60 by default.',
+          },
+          ...APPLY,
+        },
+        additionalProperties: false,
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      run: (args) =>
+        output(() =>
+          icons({
+            ...changes(args),
+            install,
+            options: {
+              logo: optionalString(args.logo),
+              image: optionalString(args.image),
+              background: optionalString(args.background),
+              darkLogo: optionalString(args.darkLogo),
+              logoSize: args.logoSize === undefined ? undefined : String(args.logoSize),
+            },
+          })
+        ),
+    },
+    {
+      name: 'splash',
+      title: 'Make the splash screen',
+      description:
+        'Makes the native splash screen of both platforms from a logo and colors; without options, again from the settings in package.json. Replaces the splash files.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          logo: { type: 'string' },
+          background: { type: 'string' },
+          darkLogo: { type: 'string' },
+          darkBackground: { type: 'string' },
+          logoWidth: { type: 'number', description: 'In points and dp, 100 by default.' },
+          ...APPLY,
+        },
+        additionalProperties: false,
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      run: (args) =>
+        output(() =>
+          splash({
+            ...changes(args),
+            install,
+            options: {
+              logo: optionalString(args.logo),
+              background: optionalString(args.background),
+              darkLogo: optionalString(args.darkLogo),
+              darkBackground: optionalString(args.darkBackground),
+              logoWidth: args.logoWidth === undefined ? undefined : String(args.logoWidth),
+            },
+          })
+        ),
+    },
+    {
+      name: 'migrate',
+      title: 'Move from another navigation',
+      description:
+        'Moves the app from react-native-navigation or React Navigation: the package, the native files and what the CLI can move of the code; the rest is a report, place by place, with the step of the migration guide.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          from: { type: 'string', enum: ['react-native-navigation', 'react-navigation'] },
+          ...APPLY,
+        },
+        additionalProperties: false,
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+      run: (args) => output(() => migrate({ ...changes(args), from: optionalString(args.from) })),
+    },
+  ];
+}
+
+/**
+ * What a command printed as its JSON, as the result of a tool. The commands print their one document to stdout, which
+ * is the channel of the protocol here: it is caught while they run (the server runs one request at a time, and writes
+ * its own messages through the stdout it took before). A command that failed is an error the agent can act on.
+ * @param {(write: (text: string) => void) => Promise<number>} command
+ * @returns {Promise<{ result: unknown; isError: boolean }>}
+ */
+async function output(command) {
+  let text = '';
+  const write = (/** @type {string} */ chunk) => {
+    text += chunk;
+  };
+  const original = process.stdout.write;
+  process.stdout.write = /** @type {typeof process.stdout.write} */ (
+    /** @type {unknown} */ (
+      (/** @type {string | Uint8Array} */ chunk) => {
+        write(String(chunk));
+        return true;
+      }
+    )
+  );
+  try {
+    await command(write);
+  } finally {
+    process.stdout.write = original;
+  }
+  /** @type {any} */
+  let result;
+  try {
+    result = JSON.parse(text);
+  } catch {
+    return { result: { error: text.trim() || 'The command printed nothing.' }, isError: true };
+  }
+  return { result, isError: Array.isArray(result?.errors) && result.errors.length > 0 };
+}
+
+/** A terminal that says nothing: under a tool the commands print JSON only, and never ask. */
+function silentUI() {
+  return createUI({
+    level: 'none',
+    out: { isTTY: false, columns: 100, write: () => true },
+  });
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function optionalString(value) {
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+module.exports = { createTools, output };