@notis_ai/cli 0.2.0-beta.102.1

package/src/command-specs/helpers.js

@@ -0,0 +1,186 @@
+import { randomUUID } from 'node:crypto';
+import { CliError, EXIT_CODES, usageError } from '../runtime/errors.js';
+import { callTool, httpRequest } from '../runtime/transport.js';
+
+export const COMPOSIO_SEARCH_TOOLS = 'COMPOSIO_SEARCH_TOOLS';
+export const COMPOSIO_GET_TOOL_SCHEMAS = 'COMPOSIO_GET_TOOL_SCHEMAS';
+export const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';
+
+const NOTIS_DATABASE_CORE_NAMES = new Set([
+  'query',
+  'get_database',
+  'get_document',
+  'list_databases',
+  'upsert_database',
+]);
+
+function isNotisDatabaseCoreName(coreName) {
+  // Mirrors server is_database_tool_name: canonical database ops plus generated
+  // upsert_<db> tools. Database tools live in the NOTIS_DATABASE toolkit so their
+  // public slug carries the DATABASE segment.
+  return NOTIS_DATABASE_CORE_NAMES.has(coreName) || coreName.startsWith('upsert_');
+}
+
+export function localNotisToolSlug(toolName) {
+  if (typeof toolName !== 'string' || !toolName.startsWith('notis-')) {
+    return toolName;
+  }
+  const coreName = toolName.slice('notis-'.length);
+  const prefix = isNotisDatabaseCoreName(coreName) ? 'LOCAL_NOTIS_DATABASE_' : 'LOCAL_NOTIS_';
+  return `${prefix}${coreName.replace(/-/g, '_').toUpperCase()}`;
+}
+
+export function parseJson(value, label) {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw usageError(`${label} must be valid JSON`, { value });
+  }
+}
+
+export function parseMaybeJson(value, label) {
+  if (!value) {
+    return undefined;
+  }
+  return parseJson(value, label);
+}
+
+export function nextIdempotencyKey(globalOptions) {
+  return globalOptions.idempotencyKey || randomUUID();
+}
+
+export async function runToolCommand({
+  runtime,
+  toolName,
+  arguments_ = {},
+  mutating = false,
+  idempotencyKey,
+  fileBindings = [],
+}) {
+  const result = await callTool({
+    runtime: { ...runtime, mutating },
+    toolName,
+    arguments_,
+    idempotencyKey: mutating ? idempotencyKey : null,
+    fileBindings,
+  });
+  return result;
+}
+
+export async function fetchToolkits(runtime) {
+  const payload = await fetchToolDiscovery(runtime, 'List available toolkit namespaces and connection statuses');
+  return (payload.toolkit_connection_statuses || []).map((entry) => ({
+    id: entry.toolkit,
+    provider: typeof entry.toolkit === 'string' ? entry.toolkit.split('-', 1)[0] : undefined,
+    description: entry.description || entry.status_message || entry.toolkit,
+    has_active_connection: Boolean(entry.has_active_connection),
+    status_message: entry.status_message || '',
+    connection_details: entry.connection_details || {},
+  }));
+}
+
+export async function probeAuth(runtime) {
+  return fetchToolDiscovery(runtime, 'List available toolkit namespaces and connection statuses');
+}
+
+export async function healthCheck(runtime) {
+  return httpRequest({
+    runtime,
+    method: 'GET',
+    path: '/health',
+    requireAuth: false,
+  });
+}
+
+export async function fetchToolSchema(runtime, toolName) {
+  const result = await runToolCommand({
+    runtime,
+    toolName: COMPOSIO_GET_TOOL_SCHEMAS,
+    arguments_: {
+      tool_slugs: [toolName],
+    },
+  });
+  const payload = result.payload || {};
+  const schema = (
+    payload.tool_schemas?.[toolName] ||
+    payload.schemas?.[toolName] ||
+    payload.tools?.find?.((tool) => tool?.tool_slug === toolName || tool?.name === toolName)
+  );
+  if (!schema) {
+    throw usageError(`Tool "${toolName}" not found.`);
+  }
+  return {
+    name: toolName,
+    toolkit_id: schema.toolkit,
+    description: schema.description || '',
+    parameters: schema.input_schema || { type: 'object', properties: {} },
+    output_schema: schema.output_schema || {},
+    schema_available: Boolean(schema.hasFullSchema),
+  };
+}
+
+export async function fetchToolDiscovery(runtime, useCase, knownFields = '') {
+  const query = { use_case: useCase };
+  if (knownFields) {
+    query.known_fields = knownFields;
+  }
+  const result = await runToolCommand({
+    runtime,
+    toolName: COMPOSIO_SEARCH_TOOLS,
+    arguments_: {
+      queries: [query],
+    },
+  });
+  return result.payload || {};
+}
+
+export function validateArguments(schema, args) {
+  const errors = [];
+  if (!schema || schema.type !== 'object') return errors;
+
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+
+  for (const field of required) {
+    if (!(field in args)) {
+      errors.push(`Missing required field: "${field}"`);
+    }
+  }
+
+  if (schema.additionalProperties === false) {
+    for (const key of Object.keys(args)) {
+      if (!(key in properties)) {
+        errors.push(`Unknown field: "${key}"`);
+      }
+    }
+  }
+
+  for (const [key, value] of Object.entries(args)) {
+    const prop = properties[key];
+    if (!prop) continue;
+    if (prop.type === 'string' && typeof value !== 'string') {
+      errors.push(`Field "${key}" should be a string, got ${typeof value}`);
+    }
+    if (prop.type === 'integer' && !Number.isInteger(value)) {
+      errors.push(`Field "${key}" should be an integer, got ${typeof value}`);
+    }
+    if (prop.type === 'array' && !Array.isArray(value)) {
+      errors.push(`Field "${key}" should be an array, got ${typeof value}`);
+    }
+    if (prop.type === 'object' && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+      errors.push(`Field "${key}" should be an object, got ${typeof value}`);
+    }
+  }
+
+  return errors;
+}
+
+export function toolConflictToError(payload, defaultMessage) {
+  return new CliError({
+    code: 'conflict',
+    message: payload?.error?.message || payload?.message || defaultMessage,
+    exitCode: EXIT_CODES.conflict,
+    details: payload || {},
+    hints: payload?.hints || [],
+  });
+}

package/src/command-specs/index.js

@@ -0,0 +1,14 @@
+import { appsCommandSpecs } from './apps.js';
+import { toolsCommandSpecs } from './tools.js';
+import { metaCommandSpecs } from './meta.js';
+
+export const GROUP_SUMMARIES = {
+  apps: 'Develop, deploy, and submit Notis Apps.',
+  tools: 'Discover and execute generic tools exposed through Notis.',
+};
+
+export const COMMAND_SPECS = [
+  ...appsCommandSpecs,
+  ...toolsCommandSpecs,
+  ...metaCommandSpecs,
+];

package/src/command-specs/meta.js

@@ -0,0 +1,161 @@
+import { COMPOSIO_SEARCH_TOOLS, healthCheck, probeAuth } from './helpers.js';
+import { findCommandSpec, formatDescribe } from '../runtime/help.js';
+import { createExpiredAuthError } from '../runtime/desktop-auth.js';
+import { isJwtExpired } from '../runtime/profiles.js';
+
+async function doctorHandler(ctx) {
+  const checks = {
+    config: 'ok',
+    auth: 'missing',
+    health: 'unknown',
+    tool_roundtrip: 'unknown',
+  };
+
+  checks.auth = ctx.runtime.jwt
+    ? (isJwtExpired(ctx.runtime.jwt) ? 'expired' : 'configured')
+    : 'missing';
+
+  try {
+    await healthCheck(ctx.runtime);
+    checks.health = 'ok';
+  } catch (error) {
+    checks.health = 'error';
+  }
+
+  if (ctx.runtime.jwt) {
+    try {
+      const payload = await probeAuth(ctx.runtime);
+      checks.tool_roundtrip = Array.isArray(payload.toolkit_connection_statuses) ? 'ok' : 'error';
+    } catch {
+      checks.tool_roundtrip = 'error';
+    }
+  }
+
+  const hints = [];
+  if (checks.auth === 'missing') {
+    hints.push({ command: 'Open the Notis desktop app and sign in', reason: 'Configure CLI credentials' });
+  } else if (checks.auth === 'expired') {
+    hints.push(...createExpiredAuthError(ctx.runtime).hints);
+  }
+  if (checks.health === 'error' && checks.auth !== 'expired') {
+    hints.push({ command: 'Open the Notis desktop app and sign in again', reason: 'Refresh local CLI configuration' });
+  }
+  if (checks.tool_roundtrip === 'error') {
+    hints.push({ command: 'notis whoami', reason: 'Verify your account and permissions' });
+  }
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: {
+      profile: ctx.runtime.profileName,
+      api_base: ctx.runtime.apiBase,
+      checks,
+    },
+    humanSummary: `Doctor checks completed for profile ${ctx.runtime.profileName}`,
+    hints,
+    renderHuman: () =>
+      Object.entries(checks)
+        .map(([name, status]) => `${name.padEnd(14)} ${status}`)
+        .join('\n'),
+  });
+}
+
+function decodeJwtUserId(jwt) {
+  if (!jwt) return null;
+  try {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) return null;
+    const decoded = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return decoded.sub || decoded.user_id || null;
+  } catch {
+    return null;
+  }
+}
+
+async function whoamiHandler(ctx) {
+  const payload = await probeAuth(ctx.runtime);
+  const toolkits = payload.toolkit_connection_statuses || [];
+  const userId = decodeJwtUserId(ctx.runtime.jwt);
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: {
+      profile: ctx.runtime.profileName,
+      api_base: ctx.runtime.apiBase,
+      user_id: userId,
+      toolkit_count: toolkits.length,
+      toolkits: toolkits.map((t) => t.toolkit),
+      cli_version: ctx.runtime.cliVersion,
+    },
+    humanSummary: `Logged in as ${userId || 'unknown'} via profile "${ctx.runtime.profileName}"`,
+    renderHuman: () =>
+      [
+        `Profile:   ${ctx.runtime.profileName}`,
+        `API:       ${ctx.runtime.apiBase}`,
+        `User:      ${userId || 'unknown'}`,
+        `Toolkits:  ${toolkits.length}`,
+        `Version:   ${ctx.runtime.cliVersion}`,
+      ].join('\n'),
+    hints: [
+      { command: 'notis tools toolkits', reason: 'List available toolkit namespaces and connection statuses' },
+      { command: 'notis doctor', reason: 'Run a full health check' },
+    ],
+  });
+}
+
+async function describeHandler(ctx) {
+  const spec = findCommandSpec(ctx.registrySpecs, ctx.args.commandPath);
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { spec },
+    humanSummary: `Described ${spec.command_path.join(' ')}`,
+    renderHuman: () => formatDescribe(spec),
+  });
+}
+
+export const metaCommandSpecs = [
+  {
+    command_path: ['whoami'],
+    summary: 'Display the active profile, user, and available toolkit connection statuses.',
+    when_to_use: 'Use this to quickly confirm which account and environment a command will target.',
+    args_schema: { arguments: [], options: [] },
+    examples: ['notis whoami', 'notis whoami --json'],
+    output_schema: 'Returns profile, api_base, user_id, toolkit count, and CLI version.',
+    mutates: false,
+    idempotent: true,
+    related_commands: ['notis doctor'],
+    backend_call: { type: 'tool', name: COMPOSIO_SEARCH_TOOLS },
+    handler: whoamiHandler,
+  },
+  {
+    command_path: ['doctor'],
+    summary: 'Run a quick CLI health check for config, auth, and API reachability.',
+    when_to_use: 'Use this before relying on the CLI in automation or after changing environments.',
+    args_schema: { arguments: [], options: [] },
+    examples: ['notis doctor', 'notis doctor --json'],
+    output_schema: 'Returns config, auth, health, and roundtrip check statuses.',
+    mutates: false,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis tools toolkits'],
+    backend_call: { type: 'health+tool_roundtrip' },
+    handler: doctorHandler,
+  },
+  {
+    command_path: ['describe'],
+    summary: 'Describe a first-class CLI command in detail.',
+    when_to_use: 'Use this when an agent or human needs the exact shape, examples, and semantics of a command.',
+    args_schema: {
+      arguments: [{ token: '<command...>', key: 'commandPath', description: 'Command path to describe, such as "apps deploy".' }],
+      options: [],
+    },
+    examples: ['notis describe apps deploy', 'notis describe tools exec'],
+    output_schema: 'Returns the command spec metadata for the requested command.',
+    mutates: false,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis --help', 'notis tools describe <tool-name>'],
+    backend_call: { type: 'local_registry' },
+    handler: describeHandler,
+  },
+];