@notis_ai/cli 0.2.0-beta.16.1

package/src/command-specs/db.js

@@ -0,0 +1,163 @@
+import { formatTable } from '../runtime/output.js';
+import { nextIdempotencyKey, parseMaybeJson, runToolCommand } from './helpers.js';
+
+async function dbListHandler(ctx) {
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'notis_list_databases',
+  });
+  const databases = result.payload.databases || [];
+  const firstSlug = databases[0]?.slug;
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: { databases },
+    humanSummary: databases.length ? `Found ${databases.length} databases` : 'No databases found.',
+    hints: firstSlug
+      ? [{ command: `notis db query ${firstSlug}`, reason: 'Query this database' }]
+      : [{ command: 'notis db upsert --operation create --title "My DB"', reason: 'Create a new database' }],
+    renderHuman: () =>
+      databases.length
+        ? formatTable(databases, [
+            { label: 'ID', value: (database) => database.id || '' },
+            { label: 'Name', value: (database) => database.name || 'Untitled' },
+            { label: 'Slug', value: (database) => database.slug || '-' },
+          ])
+        : 'No databases found.',
+  });
+}
+
+async function dbUpsertHandler(ctx) {
+  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  const payload = {
+    operation: ctx.options.operation,
+  };
+  if (ctx.options.databaseId) {
+    payload.database_id = ctx.options.databaseId;
+  }
+  if (ctx.options.title) {
+    payload.title = ctx.options.title;
+  }
+  if (ctx.options.description) {
+    payload.description = ctx.options.description;
+  }
+  if (ctx.options.icon) {
+    const v = ctx.options.icon;
+    payload.icon = v.startsWith('lucide:') ? v : `lucide:${v}`;
+  }
+  if (ctx.options.properties) {
+    payload.properties = parseMaybeJson(ctx.options.properties, 'properties');
+  }
+
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'notis_upsert_database',
+    arguments_: payload,
+    mutating: true,
+    idempotencyKey,
+  });
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: result.payload,
+    humanSummary: `Database ${ctx.options.operation} completed`,
+    meta: { mutating: true, idempotency_key: idempotencyKey || null },
+  });
+}
+
+async function dbQueryHandler(ctx) {
+  const query = {};
+  if (ctx.options.filter) {
+    query.filter = parseMaybeJson(ctx.options.filter, 'filter');
+  }
+  if (ctx.options.sort) {
+    const parsedSorts = parseMaybeJson(ctx.options.sort, 'sort');
+    query.sorts = Array.isArray(parsedSorts) ? parsedSorts : [parsedSorts];
+  }
+  if (ctx.options.pageSize) {
+    query.page_size = Number.parseInt(ctx.options.pageSize, 10);
+  }
+
+  const payload = {
+    database_slug: ctx.args.databaseSlug,
+    query,
+  };
+  if (ctx.options.offset) {
+    payload.offset = Number.parseInt(ctx.options.offset, 10);
+  }
+  if (ctx.options.cursor) {
+    payload.start_cursor = ctx.options.cursor;
+  }
+
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'notis_query',
+    arguments_: payload,
+  });
+
+  return ctx.output.emitSuccess({
+    command: ctx.spec.command_path.join(' '),
+    data: result.payload,
+    humanSummary: `Queried database ${ctx.args.databaseSlug}`,
+    renderHuman: () => JSON.stringify(result.payload, null, 2),
+  });
+}
+
+export const dbCommandSpecs = [
+  {
+    command_path: ['db', 'list'],
+    summary: 'List native Notis databases.',
+    when_to_use: 'Use this to find database ids and slugs before querying or updating schemas.',
+    args_schema: { arguments: [], options: [] },
+    examples: ['notis db list', 'notis db list --json'],
+    output_schema: 'Returns an array of native database records.',
+    mutates: false,
+    idempotent: true,
+    related_commands: ['notis db query <database-slug>', 'notis db upsert'],
+    backend_call: { type: 'tool', name: 'notis_list_databases' },
+    handler: dbListHandler,
+  },
+  {
+    command_path: ['db', 'upsert'],
+    summary: 'Create or update a native database schema.',
+    when_to_use: 'Use this when you need to provision a new database or adjust an existing schema.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--operation <create|update>', description: 'Create a new database or update an existing one.' },
+        { flags: '--database-id <id>', description: 'Database id for update operations.' },
+        { flags: '--title <text>', description: 'Database title.' },
+        { flags: '--description <text>', description: 'Database description.' },
+        { flags: '--icon <lucide-icon-name>', description: 'Database icon (Lucide icon name, e.g. database).' },
+        { flags: '--properties <json>', description: 'JSON array of property definitions.' },
+      ],
+    },
+    examples: ['notis db upsert --operation create --title "Tasks"', 'notis db upsert --operation update --database-id db_123 --title "Tasks V2"'],
+    output_schema: 'Returns the backend database upsert payload.',
+    mutates: true,
+    idempotent: true,
+    related_commands: ['notis db list', 'notis db query <database-slug>'],
+    backend_call: { type: 'tool', name: 'notis_upsert_database' },
+    handler: dbUpsertHandler,
+  },
+  {
+    command_path: ['db', 'query'],
+    summary: 'Run a structured query against a native Notis database.',
+    when_to_use: 'Use this when the database slug is known and you need direct filters, sorts, or pagination.',
+    args_schema: {
+      arguments: [{ token: '<database-slug>', description: 'Slug of the native database to query.' }],
+      options: [
+        { flags: '--filter <json>', description: 'Structured query filter JSON.' },
+        { flags: '--sort <json>', description: 'Sort JSON object or array.' },
+        { flags: '--page-size <n>', description: 'Page size between 1 and 100.' },
+        { flags: '--offset <n>', description: 'Zero-based offset.' },
+        { flags: '--cursor <value>', description: 'Pagination cursor alias for next_offset.' },
+      ],
+    },
+    examples: ['notis db query tasks --page-size 50', 'notis db query tasks --filter \'{"property":"Status"}\''],
+    output_schema: 'Returns the native database query payload from `notis_query`.',
+    mutates: false,
+    idempotent: true,
+    related_commands: ['notis db list', 'notis db upsert'],
+    backend_call: { type: 'tool', name: 'notis_query' },
+    handler: dbQueryHandler,
+  },
+];

package/src/command-specs/helpers.js

@@ -0,0 +1,193 @@
+import { createInterface } from 'node:readline/promises';
+import { randomUUID } from 'node:crypto';
+import { CliError, EXIT_CODES, usageError } from '../runtime/errors.js';
+import { callTool, httpRequest } from '../runtime/transport.js';
+import {
+  DEFAULT_PROFILE,
+  ensureProfile,
+  loadConfig,
+  saveConfig,
+} from '../runtime/profiles.js';
+
+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 normalizeToolkits(value) {
+  if (!value) {
+    return [];
+  }
+  if (value.startsWith('[')) {
+    const parsed = parseJson(value, 'toolkits');
+    if (!Array.isArray(parsed)) {
+      throw usageError('toolkits JSON must be an array of toolkit strings');
+    }
+    return parsed;
+  }
+  return value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export async function promptForJwt() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const jwt = await rl.question('Paste your Notis JWT: ');
+    return jwt.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export function nextIdempotencyKey(globalOptions) {
+  return globalOptions.idempotencyKey || randomUUID();
+}
+
+export async function runToolCommand({
+  runtime,
+  toolName,
+  arguments_ = {},
+  mutating = false,
+  idempotencyKey,
+}) {
+  const result = await callTool({
+    runtime: { ...runtime, mutating },
+    toolName,
+    arguments_,
+    idempotencyKey: mutating ? idempotencyKey : null,
+  });
+  return result;
+}
+
+export async function fetchToolkits(runtime) {
+  const result = await runToolCommand({
+    runtime,
+    toolName: 'notis_find_toolkits',
+  });
+  return result.payload.toolkits || [];
+}
+
+export async function resolveSearchToolkits(runtime, rawToolkits) {
+  const toolkits = normalizeToolkits(rawToolkits);
+  if (toolkits.length) {
+    return toolkits;
+  }
+  const availableToolkits = await fetchToolkits(runtime);
+  return availableToolkits.map((entry) => entry.id);
+}
+
+export async function probeAuth(runtime) {
+  const result = await runToolCommand({
+    runtime,
+    toolName: 'notis_find_toolkits',
+  });
+  return result.payload;
+}
+
+export async function healthCheck(runtime) {
+  return httpRequest({
+    runtime,
+    method: 'GET',
+    path: '/health',
+    requireAuth: false,
+  });
+}
+
+export function updateStoredProfile({ profileName, jwt, apiBase, setCurrent = true }) {
+  let config = ensureProfile(loadConfig(), profileName || DEFAULT_PROFILE);
+  const resolvedName = profileName || DEFAULT_PROFILE;
+  config.profiles[resolvedName] = {
+    ...config.profiles[resolvedName],
+    ...(jwt ? { jwt } : {}),
+    ...(apiBase ? { api_base: apiBase } : {}),
+  };
+  if (setCurrent) {
+    config.current_profile = resolvedName;
+  }
+  saveConfig(config);
+  return config;
+}
+
+export function clearStoredJwt(profileName) {
+  const config = ensureProfile(loadConfig(), profileName || DEFAULT_PROFILE);
+  delete config.profiles[profileName || DEFAULT_PROFILE].jwt;
+  saveConfig(config);
+  return config;
+}
+
+export async function fetchToolSchema(runtime, toolName) {
+  const result = await runToolCommand({
+    runtime,
+    toolName: 'notis_find_tools',
+    arguments_: { query: toolName },
+  });
+  const tools = result.payload.tools || [];
+  const match = tools.find((t) => t.name === toolName);
+  if (!match) {
+    throw usageError(`Tool "${toolName}" not found.`);
+  }
+  return match;
+}
+
+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,20 @@
+import { authCommandSpecs } from './auth.js';
+import { appsCommandSpecs } from './apps.js';
+import { dbCommandSpecs } from './db.js';
+import { toolsCommandSpecs } from './tools.js';
+import { metaCommandSpecs } from './meta.js';
+
+export const GROUP_SUMMARIES = {
+  auth: 'Authentication and profile management.',
+  apps: 'Build, preview, and deploy Notis Apps.',
+  db: 'List, query, and update native Notis Databases.',
+  tools: 'Discover and execute generic tools exposed through Notis.',
+};
+
+export const COMMAND_SPECS = [
+  ...authCommandSpecs,
+  ...appsCommandSpecs,
+  ...dbCommandSpecs,
+  ...toolsCommandSpecs,
+  ...metaCommandSpecs,
+];

package/src/command-specs/meta.js

@@ -0,0 +1,154 @@
+import { healthCheck, probeAuth } from './helpers.js';
+import { findCommandSpec, formatDescribe } from '../runtime/help.js';
+
+async function doctorHandler(ctx) {
+  const checks = {
+    config: 'ok',
+    auth: 'missing',
+    health: 'unknown',
+    tool_roundtrip: 'unknown',
+  };
+
+  checks.auth = ctx.runtime.jwt ? '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.toolkits) ? 'ok' : 'error';
+    } catch {
+      checks.tool_roundtrip = 'error';
+    }
+  }
+
+  const hints = [];
+  if (checks.auth === 'missing') {
+    hints.push({ command: 'notis auth login --jwt <token>', reason: 'Configure credentials' });
+  }
+  if (checks.health === 'error') {
+    hints.push({ command: 'notis auth status', reason: 'Check API base URL 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.toolkits || [];
+  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.id),
+      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' },
+      { 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 toolkits.',
+    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 auth status --verify', 'notis doctor'],
+    backend_call: { type: 'tool', name: 'notis_find_toolkits' },
+    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,
+    related_commands: ['notis auth status --verify', '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 push".' }],
+      options: [],
+    },
+    examples: ['notis describe apps push', 'notis describe db query'],
+    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,
+  },
+];