@notis_ai/cli 0.2.0-beta.16.1

package/src/command-specs/tools.js

@@ -0,0 +1,391 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { usageError } from '../runtime/errors.js';
+import {
+  fetchToolkits,
+  fetchToolSchema,
+  nextIdempotencyKey,
+  parseJson,
+  parseMaybeJson,
+  resolveSearchToolkits,
+  runToolCommand,
+  validateArguments,
+} from './helpers.js';
+
+async function resolveJsonInput(value, label) {
+  if (!value) return undefined;
+
+  if (value === '-') {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    return parseJson(Buffer.concat(chunks).toString('utf-8'), label);
+  }
+
+  if (value.startsWith('@')) {
+    const filePath = value.slice(1);
+    if (!existsSync(filePath)) {
+      throw usageError(`File not found: ${filePath}`);
+    }
+    return parseJson(readFileSync(filePath, 'utf-8'), label);
+  }
+
+  return parseJson(value, label);
+}
+
+async function toolsToolkitsHandler(ctx) {
+  const toolkits = await fetchToolkits(ctx.runtime);
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { toolkits },
+    humanSummary: `Found ${toolkits.length} toolkits`,
+    hints: [
+      { command: 'notis tools search <query>', reason: 'Search for tools in these toolkits' },
+    ],
+    renderHuman: () => toolkits.map((entry) => `${entry.id}  ${entry.description}`).join('\n'),
+  });
+}
+
+async function toolsSearchHandler(ctx) {
+  const toolkits = await resolveSearchToolkits(ctx.runtime, ctx.options.toolkits);
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'notis_find_tools',
+    arguments_: {
+      query: ctx.args.query || undefined,
+      toolkits,
+    },
+  });
+  const tools = result.payload.tools || [];
+  const firstTool = tools[0];
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { toolkits, tools },
+    humanSummary: `Found ${tools.length} tools`,
+    hints: firstTool
+      ? [
+          { command: `notis tools exec ${firstTool.name} --get-schema`, reason: 'Inspect the parameter schema' },
+          { command: `notis tools exec ${firstTool.name} --arguments '{}'`, reason: 'Execute the tool' },
+        ]
+      : [],
+    renderHuman: () =>
+      tools
+        .map((tool) => `${tool.name}\n  ${tool.toolkit_id || 'unknown toolkit'}\n  ${tool.description || 'No description'}\n`)
+        .join('\n')
+        .trim(),
+  });
+}
+
+async function toolsDescribeHandler(ctx) {
+  const toolkits = await resolveSearchToolkits(ctx.runtime, ctx.options.toolkits);
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'notis_find_tools',
+    arguments_: {
+      query: ctx.args.toolName,
+      toolkits,
+    },
+  });
+  const tools = result.payload.tools || [];
+  const match = tools.find((tool) => tool.name === ctx.args.toolName);
+  if (!match) {
+    throw usageError(`Tool ${ctx.args.toolName} was not found in the selected toolkits.`);
+  }
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { tool: match, toolkits },
+    humanSummary: `Described tool ${ctx.args.toolName}`,
+    hints: [
+      { command: `notis tools exec ${ctx.args.toolName} --dry-run --arguments '{}'`, reason: 'Validate arguments first' },
+      { command: `notis tools exec ${ctx.args.toolName} --arguments '{}'`, reason: 'Execute this tool' },
+    ],
+    renderHuman: () => JSON.stringify(match, null, 2),
+  });
+}
+
+async function toolsExecHandler(ctx) {
+  if (ctx.options.getSchema) {
+    const tool = await fetchToolSchema(ctx.runtime, ctx.args.toolName);
+    return ctx.output.emitSuccess({
+      command: ctx.spec.command_path.join(' '),
+      data: { tool },
+      humanSummary: `Schema for ${ctx.args.toolName}`,
+      hints: [
+        { command: `notis tools exec ${ctx.args.toolName} --dry-run --arguments '{}'`, reason: 'Validate arguments before executing' },
+      ],
+      renderHuman: () => JSON.stringify(tool, null, 2),
+    });
+  }
+
+  const rawArguments = ctx.options.arguments || '{}';
+  const args = rawArguments === '-' || rawArguments.startsWith('@')
+    ? await resolveJsonInput(rawArguments, 'arguments') || {}
+    : parseMaybeJson(rawArguments, 'arguments') || {};
+
+  if (ctx.options.dryRun) {
+    const tool = await fetchToolSchema(ctx.runtime, ctx.args.toolName);
+    const errors = validateArguments(tool.parameters, args);
+
+    if (errors.length) {
+      return ctx.output.emitSuccess({
+        command: ctx.spec.command_path.join(' '),
+        data: { valid: false, errors, tool: ctx.args.toolName },
+        humanSummary: `Dry run failed: ${errors.length} validation error(s)`,
+        hints: [
+          { command: `notis tools exec ${ctx.args.toolName} --get-schema`, reason: 'Review the full parameter schema' },
+        ],
+        renderHuman: () => errors.map((e) => `  - ${e}`).join('\n'),
+      });
+    }
+
+    return ctx.output.emitSuccess({
+      command: ctx.spec.command_path.join(' '),
+      data: { valid: true, tool: ctx.args.toolName, arguments: args },
+      humanSummary: `Dry run passed for ${ctx.args.toolName}`,
+      hints: [
+        { command: `notis tools exec ${ctx.args.toolName} --arguments '${JSON.stringify(args)}'`, reason: 'Execute with these arguments' },
+      ],
+    });
+  }
+
+  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+
+  if (ctx.options.watch) {
+    const intervalSec = Math.max(1, parseInt(ctx.options.watch, 10));
+    const intervalMs = intervalSec * 1000;
+    process.on('SIGINT', () => process.exit(0));
+
+    while (true) {
+      try {
+        const result = await runToolCommand({
+          runtime: ctx.runtime,
+          toolName: 'notis_execute_tool',
+          arguments_: { tool_name: ctx.args.toolName, arguments: args },
+          mutating: true,
+          idempotencyKey: nextIdempotencyKey(ctx.globalOptions),
+        });
+        ctx.output.emitSuccess({
+          command: ctx.spec.command_path.join(' '),
+          data: result.payload,
+          humanSummary: `[${new Date().toISOString()}] ${ctx.args.toolName}`,
+          renderHuman: () => JSON.stringify(result.payload, null, 2),
+        });
+      } catch (error) {
+        process.stderr.write(`[${new Date().toISOString()}] Error: ${error.message}\n`);
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  }
+
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'notis_execute_tool',
+    arguments_: {
+      tool_name: ctx.args.toolName,
+      arguments: args,
+    },
+    mutating: true,
+    idempotencyKey,
+  });
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: result.payload,
+    humanSummary: `Executed tool ${ctx.args.toolName}`,
+    meta: { mutating: true, idempotency_key: idempotencyKey },
+    renderHuman: () => JSON.stringify(result.payload, null, 2),
+  });
+}
+
+async function toolsExecParallelHandler(ctx) {
+  const calls = parseMaybeJson(ctx.args.calls, 'calls');
+  if (!Array.isArray(calls) || !calls.length) {
+    throw usageError('calls must be a non-empty JSON array of {tool_name, arguments} objects');
+  }
+
+  for (const [i, call] of calls.entries()) {
+    if (!call.tool_name || typeof call.tool_name !== 'string') {
+      throw usageError(`calls[${i}] missing required "tool_name" string`);
+    }
+  }
+
+  const data = await Promise.all(
+    calls.map((call) =>
+      runToolCommand({
+        runtime: ctx.runtime,
+        toolName: 'notis_execute_tool',
+        arguments_: {
+          tool_name: call.tool_name,
+          arguments: call.arguments || {},
+        },
+        mutating: true,
+        idempotencyKey: nextIdempotencyKey(ctx.globalOptions),
+      })
+        .then((r) => ({ tool_name: call.tool_name, status: 'ok', payload: r.payload }))
+        .catch((e) => ({ tool_name: call.tool_name, status: 'error', error: e.message }))
+    )
+  );
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { results: data },
+    humanSummary: `Executed ${calls.length} tools in parallel`,
+    meta: { mutating: true },
+    renderHuman: () => data.map((r) => `${r.tool_name}: ${r.status}`).join('\n'),
+  });
+}
+
+async function toolsLinkHandler(ctx) {
+  const apiBase = ctx.runtime.apiBase.replace(/\/+$/, '');
+  let portalBase;
+  try {
+    const parsed = new URL(apiBase);
+    if (parsed.hostname.startsWith('api.')) {
+      parsed.hostname = parsed.hostname.replace(/^api\./, 'app.');
+      portalBase = parsed.origin;
+    } else if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
+      const apiPort = parseInt(parsed.port, 10) || 80;
+      parsed.port = String(apiPort === 3001 ? 3000 : apiPort);
+      portalBase = parsed.origin;
+    } else {
+      portalBase = apiBase;
+    }
+  } catch {
+    portalBase = apiBase.replace('api.', 'app.');
+  }
+  const portalUrl = `${portalBase}/integrations?connect=${encodeURIComponent(ctx.args.toolkit)}`;
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: {
+      toolkit: ctx.args.toolkit,
+      auth_url: portalUrl,
+    },
+    humanSummary: `Open this URL to connect ${ctx.args.toolkit}`,
+    hints: [
+      { command: 'notis tools toolkits', reason: 'Verify the toolkit is connected after setup' },
+    ],
+    renderHuman: () =>
+      [
+        `Connect ${ctx.args.toolkit}:`,
+        `  ${portalUrl}`,
+        '',
+        'After connecting, verify with:',
+        '  notis tools toolkits',
+      ].join('\n'),
+  });
+}
+
+export const toolsCommandSpecs = [
+  {
+    command_path: ['tools', 'toolkits'],
+    summary: 'List toolkit namespaces available to the active user.',
+    when_to_use: 'Use this before searching or executing generic tools.',
+    args_schema: { arguments: [], options: [] },
+    examples: ['notis tools toolkits', 'notis tools toolkits --json'],
+    output_schema: 'Returns available toolkit namespaces.',
+    mutates: false,
+    idempotent: true,
+    related_commands: ['notis tools search <query>', 'notis tools describe <tool-name>'],
+    backend_call: { type: 'tool', name: 'notis_find_toolkits' },
+    handler: toolsToolkitsHandler,
+  },
+  {
+    command_path: ['tools', 'search'],
+    summary: 'Search across toolkit namespaces using natural language.',
+    when_to_use: 'Use this when you need a generic capability that does not have a first-class CLI command.',
+    args_schema: {
+      arguments: [{ token: '<query>', description: 'Natural language description of the tool you need.' }],
+      options: [{ flags: '--toolkits <csv-or-json>', description: 'Optional subset of toolkit ids to search.' }],
+    },
+    examples: ['notis tools search "send an email"', 'notis tools search "update framer page" --toolkits mcp-framer'],
+    output_schema: 'Returns tool matches with descriptions and parameter schemas.',
+    mutates: false,
+    idempotent: true,
+    related_commands: ['notis tools toolkits', 'notis tools exec <tool-name>'],
+    backend_call: { type: 'tool', name: 'notis_find_tools' },
+    handler: toolsSearchHandler,
+  },
+  {
+    command_path: ['tools', 'describe'],
+    summary: 'Describe a generic tool by name.',
+    when_to_use: 'Use this when you know the tool name and want its parameter schema before execution.',
+    args_schema: {
+      arguments: [{ token: '<tool-name>', description: 'Exact tool name to locate and describe.' }],
+      options: [{ flags: '--toolkits <csv-or-json>', description: 'Optional subset of toolkit ids to search.' }],
+    },
+    examples: ['notis tools describe composio-gmail-default-send_email', 'notis tools describe notis-default-query --toolkits notis-default'],
+    output_schema: 'Returns one tool descriptor with name, description, and parameters.',
+    mutates: false,
+    idempotent: true,
+    related_commands: ['notis tools search <query>', 'notis tools exec <tool-name>'],
+    backend_call: { type: 'tool', name: 'notis_find_tools' },
+    handler: toolsDescribeHandler,
+  },
+  {
+    command_path: ['tools', 'exec'],
+    summary: 'Execute a generic tool by canonical tool name.',
+    when_to_use: 'Use this as the escape hatch for integrations or Notis tools without a first-class CLI wrapper.',
+    args_schema: {
+      arguments: [{ token: '<tool-name>', description: 'Tool name returned by `notis tools search`.' }],
+      options: [
+        { flags: '--arguments <json>', description: 'JSON object, @file path, or - for stdin.' },
+        { flags: '--get-schema', description: 'Display the tool parameter schema without executing.' },
+        { flags: '--dry-run', description: 'Validate arguments against the tool schema without executing.' },
+        { flags: '--watch <seconds>', description: 'Re-execute on an interval and stream results.' },
+      ],
+    },
+    examples: [
+      'notis tools exec notis-default-query --arguments \'{"database_slug":"tasks","query":{}}\'',
+      'notis tools exec notis-default-query --get-schema',
+      'notis tools exec notis-default-query --dry-run --arguments \'{"database_slug":"tasks","query":{}}\'',
+      'notis tools exec notis-default-query --arguments @query.json',
+      'notis tools exec notis-default-query --arguments - < query.json',
+      'notis tools exec notis-default-query --watch 10 --arguments \'{"database_slug":"tasks","query":{}}\'',
+    ],
+    output_schema: 'Returns the raw tool execution payload.',
+    mutates: true,
+    idempotent: true,
+    related_commands: ['notis tools search <query>', 'notis tools describe <tool-name>', 'notis tools exec-parallel <calls>'],
+    backend_call: { type: 'tool', name: 'notis_execute_tool' },
+    handler: toolsExecHandler,
+  },
+  {
+    command_path: ['tools', 'exec-parallel'],
+    summary: 'Execute multiple tools concurrently.',
+    when_to_use: 'Use this when you need to run independent tool calls simultaneously for speed.',
+    args_schema: {
+      arguments: [
+        { token: '<calls>', description: 'JSON array of {tool_name, arguments} objects.' },
+      ],
+      options: [],
+    },
+    examples: [
+      'notis tools exec-parallel \'[{"tool_name":"notis-default-query","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"notis-default-list_databases","arguments":{}}]\'',
+    ],
+    output_schema: 'Returns an array of results, one per tool call.',
+    mutates: true,
+    idempotent: true,
+    related_commands: ['notis tools exec <tool-name>', 'notis tools search <query>'],
+    backend_call: { type: 'tool', name: 'notis_execute_tool' },
+    handler: toolsExecParallelHandler,
+  },
+  {
+    command_path: ['tools', 'link'],
+    summary: 'Get the URL to connect an integration toolkit.',
+    when_to_use: 'Use this when a tool requires authentication with an external service.',
+    args_schema: {
+      arguments: [{ token: '<toolkit>', description: 'Toolkit name to connect (e.g. github, gmail, slack).' }],
+      options: [],
+    },
+    examples: ['notis tools link github', 'notis tools link gmail --json'],
+    output_schema: 'Returns the authentication URL for the specified toolkit.',
+    mutates: false,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis tools toolkits', 'notis tools search <query>'],
+    backend_call: { type: 'local' },
+    handler: toolsLinkHandler,
+  },
+];