@notis_ai/cli 0.2.0-beta.16.1

package/README.md

@@ -0,0 +1,335 @@
+# @notis_ai/cli
+
+Agent-first Notis CLI for apps, databases, and generic tool execution.
+
+## Install
+
+The Notis CLI is bundled automatically with the Notis desktop app.
+
+## Quick Start
+
+```bash
+notis --help
+notis auth status
+notis apps list
+notis db list
+```
+
+If you're using the desktop app, login and logout keep the CLI profile in sync automatically.
+
+The CLI defaults to `json` output in agent or non-TTY contexts and `table` output in interactive terminals.
+
+## Global Flags
+
+- `--json` — Shortcut for `--output json`
+- `--output <table|json|yaml|ndjson>` — Output mode override
+- `--non-interactive` — Disable prompts
+- `--profile <name>` — Select a stored profile
+- `--api-base <url>` — Override the API base for one invocation
+- `--timeout-ms <n>` — HTTP timeout in milliseconds
+- `--idempotency-key <key>` — Override the generated idempotency key for mutating commands
+
+## Auth
+
+### `notis auth login`
+
+Store credentials for a named CLI profile.
+
+When to use: Use this before authenticated commands, especially in fresh environments or CI profiles.
+
+Options:
+- `--jwt <token>` — JWT token to store for the profile.
+
+Examples:
+- `notis auth login --jwt <token>`
+- `notis auth login --profile staging --api-base http://localhost:3001`
+
+### `notis auth logout`
+
+Remove the stored JWT for the active profile.
+
+When to use: Use this to clear local credentials without touching other profiles.
+
+Examples:
+- `notis auth logout`
+- `notis auth logout --profile staging`
+
+### `notis auth status`
+
+Inspect local auth configuration and optionally verify it against the API.
+
+When to use: Use this before automating commands to confirm the active profile and token health.
+
+Options:
+- `--verify` — Perform a live authenticated roundtrip to the API.
+
+Examples:
+- `notis auth status`
+- `notis auth status --verify --json`
+
+
+## Apps
+
+### `notis apps list`
+
+List apps the current profile can access.
+
+When to use: Discover existing apps before linking or deploying.
+
+Examples:
+- `notis apps list`
+- `notis apps list --json`
+
+### `notis apps init <name> [dir]`
+
+Scaffold a new Notis app project.
+
+When to use: Start a new Notis app. Creates a Vite + React project with @notis/sdk pre-configured.
+
+Examples:
+- `notis apps init "Mind the Flo"`
+- `notis apps init "My App" ./my-app`
+
+### `notis apps create <name> [dir]`
+
+Create a new remote Notis app and optionally link a local project to it.
+
+When to use: Provision a fresh remote app before the first deploy. Pass a project directory to link it immediately.
+
+Options:
+- `--description <text>` — Optional app description.
+- `--icon <lucide:icon>` — Optional Lucide icon, for example lucide:dices.
+
+Examples:
+- `notis apps create "My App"`
+- `notis apps create "My App" . --description "Internal tool" --icon lucide:layout-dashboard`
+
+### `notis apps dev [dir]`
+
+Run the Vite dev server for local development.
+
+When to use: Iterate on app UI with hot reload. SDK hooks return mock data.
+
+Examples:
+- `notis apps dev`
+- `notis apps dev ./my-app`
+
+### `notis apps build [dir]`
+
+Build and package the app into .notis/output/.
+
+When to use: Prepare the app for preview or deployment.
+
+Examples:
+- `notis apps build`
+- `notis apps build ./my-app`
+
+### `notis apps preview [dir]`
+
+Serve the built bundle locally for testing.
+
+When to use: Smoke-test the exact bundle that will be deployed. Databases use seed data.
+
+Options:
+- `--port <number>` — Server port (default: 8787).
+
+Examples:
+- `notis apps preview`
+- `notis apps preview --port 3000`
+
+### `notis apps link <app-id> [dir]`
+
+Link a local project to a remote Notis app.
+
+When to use: Connect a local project to an existing app for deployment.
+
+Examples:
+- `notis apps link abc123`
+- `notis apps link abc123 ./my-app`
+
+### `notis apps deploy [dir]`
+
+Build and upload the app to the linked Notis app.
+
+When to use: Ship the installed app to production for the linked user/team app. Requires a linked app (notis apps link). This command does not publish to the app store.
+
+Options:
+- `--app-id <id>` — Override linked app ID.
+- `--skip-build` — Skip the build step (use existing .notis/output/).
+- `--direct` — Upload directly to Supabase storage, bypassing the backend server. Auto-fallback on network errors.
+
+Examples:
+- `notis apps deploy`
+- `notis apps deploy --skip-build`
+- `notis apps deploy --app-id abc123`
+- `notis apps deploy --direct`
+
+### `notis apps doctor [dir]`
+
+Check project health and readiness.
+
+When to use: Diagnose issues with a Notis app project.
+
+Examples:
+- `notis apps doctor`
+- `notis apps doctor ./my-app`
+
+
+## Databases
+
+### `notis db list`
+
+List native Notis databases.
+
+When to use: Use this to find database ids and slugs before querying or updating schemas.
+
+Examples:
+- `notis db list`
+- `notis db list --json`
+
+### `notis db upsert`
+
+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.
+
+Options:
+- `--operation <create|update>` — Create a new database or update an existing one.
+- `--database-id <id>` — Database id for update operations.
+- `--title <text>` — Database title.
+- `--description <text>` — Database description.
+- `--icon <lucide-icon-name>` — Database icon (Lucide icon name, e.g. database).
+- `--properties <json>` — 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"`
+
+### `notis db query <database-slug>`
+
+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.
+
+Options:
+- `--filter <json>` — Structured query filter JSON.
+- `--sort <json>` — Sort JSON object or array.
+- `--page-size <n>` — Page size between 1 and 100.
+- `--offset <n>` — Zero-based offset.
+- `--cursor <value>` — Pagination cursor alias for next_offset.
+
+Examples:
+- `notis db query tasks --page-size 50`
+- `notis db query tasks --filter '{"property":"Status"}'`
+
+
+## Generic Tools
+
+### `notis tools toolkits`
+
+List toolkit namespaces available to the active user.
+
+When to use: Use this before searching or executing generic tools.
+
+Examples:
+- `notis tools toolkits`
+- `notis tools toolkits --json`
+
+### `notis tools search <query>`
+
+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.
+
+Options:
+- `--toolkits <csv-or-json>` — Optional subset of toolkit ids to search.
+
+Examples:
+- `notis tools search "send an email"`
+- `notis tools search "update framer page" --toolkits mcp-framer`
+
+### `notis tools describe <tool-name>`
+
+Describe a generic tool by name.
+
+When to use: Use this when you know the tool name and want its parameter schema before execution.
+
+Options:
+- `--toolkits <csv-or-json>` — 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`
+
+### `notis tools exec <tool-name>`
+
+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.
+
+Options:
+- `--arguments <json>` — JSON object, @file path, or - for stdin.
+- `--get-schema` — Display the tool parameter schema without executing.
+- `--dry-run` — Validate arguments against the tool schema without executing.
+- `--watch <seconds>` — 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":{}}'`
+
+### `notis tools exec-parallel <calls>`
+
+Execute multiple tools concurrently.
+
+When to use: Use this when you need to run independent tool calls simultaneously for speed.
+
+Examples:
+- `notis tools exec-parallel '[{"tool_name":"notis-default-query","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"notis-default-list_databases","arguments":{}}]'`
+
+### `notis tools link <toolkit>`
+
+Get the URL to connect an integration toolkit.
+
+When to use: Use this when a tool requires authentication with an external service.
+
+Examples:
+- `notis tools link github`
+- `notis tools link gmail --json`
+
+
+## Meta Commands
+
+### `notis doctor`
+
+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.
+
+Examples:
+- `notis doctor`
+- `notis doctor --json`
+
+### `notis describe <command...>`
+
+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.
+
+Examples:
+- `notis describe apps push`
+- `notis describe db query`
+
+
+## Local Development
+
+```bash
+cd cli/npm
+npm install
+node ./bin/notis.js --help
+npm run docs:generate
+npm test
+```

package/bin/notis.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/cli.js').then(({ run }) => run());

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@notis_ai/cli",
+  "version": "0.2.0-beta.16.1",
+  "description": "Agent-first Notis CLI for apps, databases, and generic tool execution",
+  "type": "module",
+  "bin": {
+    "notis": "bin/notis.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "README.md"
+  ],
+  "scripts": {
+    "docs:generate": "node ./scripts/generate-docs.js",
+    "docs:check": "node ./scripts/generate-docs.js --check",
+    "release:prepare": "node ./scripts/prepare-publish.js --apply",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {},
+  "keywords": [
+    "notis",
+    "cli",
+    "ai",
+    "agent-skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,147 @@
+import { Command } from 'commander';
+import { COMMAND_SPECS, GROUP_SUMMARIES } from './command-specs/index.js';
+import { OutputManager } from './runtime/output.js';
+import { asCliError } from './runtime/errors.js';
+import { resolveRuntimeProfile, workspacePath } from './runtime/profiles.js';
+
+const CLI_VERSION = '0.2.0';
+
+function buildHelpFooter(spec) {
+  const lines = [
+    '',
+    `When to use: ${spec.when_to_use}`,
+    '',
+    'Examples:',
+    ...(spec.examples || []).map((example) => `  ${example}`),
+  ];
+  if (spec.related_commands?.length) {
+    lines.push('', 'Related commands:', ...spec.related_commands.map((command) => `  ${command}`));
+  }
+  return lines.join('\n');
+}
+function mapArgs(spec, rawArgs) {
+  const mapped = {};
+  const argumentDefs = spec.args_schema?.arguments || [];
+  for (const [index, argument] of argumentDefs.entries()) {
+    const normalizedToken = (argument.key || argument.token.replace(/[<>\[\]]/g, '').replace('...', ''))
+      .replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+    mapped[normalizedToken] = rawArgs[index];
+  }
+  return mapped;
+}
+
+function ensureParentCommand(program, parentMap, parentPath) {
+  const key = parentPath.join(' ');
+  if (parentMap.has(key)) {
+    return parentMap.get(key);
+  }
+
+  const parentCommand = ensureParentCommand(program, parentMap, parentPath.slice(0, -1));
+  const segment = parentPath[parentPath.length - 1];
+  const command = parentCommand.command(segment).description(GROUP_SUMMARIES[segment] || '');
+  parentMap.set(key, command);
+  return command;
+}
+
+function buildRuntime(globalOptions, spec) {
+  const runtime = resolveRuntimeProfile(globalOptions, { requireAuth: spec.require_auth !== false });
+  return {
+    ...runtime,
+    cliVersion: CLI_VERSION,
+    color: globalOptions.color !== false,
+    workspacePath,
+  };
+}
+
+function attachSpec(program, parentMap, spec, specs) {
+  const parent = ensureParentCommand(program, parentMap, spec.command_path.slice(0, -1));
+  const leaf = spec.command_path[spec.command_path.length - 1];
+  const command = parent.command(leaf).description(spec.summary);
+  command.addHelpText('after', buildHelpFooter(spec));
+
+  for (const argument of spec.args_schema?.arguments || []) {
+    command.argument(argument.token, argument.description);
+  }
+
+  for (const option of spec.args_schema?.options || []) {
+    command.option(option.flags, option.description);
+  }
+
+  command.action(async (...raw) => {
+    const commanderCommand = raw[raw.length - 1];
+    const argumentValues = raw.slice(0, -1);
+    const globalOptions = commanderCommand.optsWithGlobals();
+    try {
+      const runtime = buildRuntime(globalOptions, spec);
+      const output = new OutputManager(runtime);
+      const args = mapArgs(spec, argumentValues);
+
+      if (spec.deprecated_alias_for && runtime.outputMode === 'table') {
+        output.writeWarning(`Warning: Command "${spec.command_path.join(' ')}" is deprecated. Use "${spec.deprecated_alias_for}" instead.`);
+      }
+
+      const exitCode = await spec.handler({
+        spec,
+        registrySpecs: specs,
+        args,
+        options: commanderCommand.opts(),
+        globalOptions,
+        runtime,
+        output,
+      });
+      process.exitCode = typeof exitCode === 'number' ? exitCode : 0;
+    } catch (error) {
+      const runtime = {
+        ...resolveRuntimeProfile(globalOptions, { requireAuth: false }),
+        cliVersion: CLI_VERSION,
+        color: globalOptions.color !== false,
+        workspacePath,
+      };
+      const output = new OutputManager(runtime);
+      const cliError = asCliError(error);
+      process.exitCode = output.emitError({
+        command: spec.command_path.join(' '),
+        error: cliError,
+      });
+    }
+  });
+}
+
+export function createProgram() {
+  const program = new Command();
+
+  program
+    .name('notis')
+    .description('Agent-first Notis CLI for apps, databases, and generic tool execution')
+    .version(CLI_VERSION)
+    .showHelpAfterError()
+    .option('--json', 'Shortcut for --output json')
+    .option('--output <table|json|yaml|ndjson>', 'Output mode override')
+    .option('--non-interactive', 'Disable all interactive prompts')
+    .option('--quiet', 'Suppress non-essential human output')
+    .option('--verbose', 'Show extra human-readable diagnostics')
+    .option('--no-color', 'Disable ANSI color output')
+    .option('--profile <name>', 'CLI profile name', 'default')
+    .option('--api-base <url>', 'Override the API base URL for this invocation')
+    .option('--timeout-ms <n>', 'HTTP timeout in milliseconds')
+    .option('--idempotency-key <key>', 'Override the generated idempotency key for mutating commands');
+
+  const parentMap = new Map([['', program]]);
+  for (const spec of COMMAND_SPECS) {
+    attachSpec(program, parentMap, spec, COMMAND_SPECS);
+  }
+
+  return program;
+}
+
+export async function run(argv = process.argv) {
+  const program = createProgram();
+  await program.parseAsync(argv);
+}
+
+const isDirectInvocation =
+  process.argv[1] && import.meta.url === new URL(process.argv[1], 'file://').href;
+
+if (isDirectInvocation) {
+  run();
+}