@nocobase/ctl 0.1.5

package/README.md

@@ -0,0 +1,164 @@
+# NocoBase CLI
+
+NocoBase CLI combines:
+
+- built-in commands for environment management and generic resource access
+- runtime-generated commands loaded from your NocoBase application's Swagger schema
+
+This allows the CLI to stay aligned with the target application instead of relying on a fixed command list.
+
+## Install
+
+Install dependencies for local development:
+
+```bash
+pnpm install
+```
+
+Run in development mode:
+
+```bash
+node ./bin/dev.js --help
+```
+
+Build the CLI:
+
+```bash
+pnpm build
+```
+
+Run the built CLI:
+
+```bash
+node ./bin/run.js --help
+```
+
+After packaging or linking, the executable name is:
+
+```bash
+nocobase
+```
+
+## Quick Start
+
+Add an environment:
+
+```bash
+nocobase env add --name local --base-url http://localhost:13000/api --token <token>
+```
+
+Show the current environment:
+
+```bash
+nocobase env
+```
+
+List configured environments:
+
+```bash
+nocobase env list
+```
+
+Switch the current environment:
+
+```bash
+nocobase env use local
+```
+
+Update the runtime command cache from `swagger:get`:
+
+```bash
+nocobase env update
+nocobase env update -e local
+```
+
+Use the generic resource commands:
+
+```bash
+nocobase resource list --resource users
+nocobase resource get --resource users --filter-by-tk 1
+nocobase resource create --resource users --values '{"nickname":"Ada"}'
+```
+
+## Runtime Commands
+
+When you execute a runtime command, the CLI will:
+
+1. resolve the target environment
+2. read the application's Swagger schema from `swagger:get`
+3. generate or reuse a cached runtime command set for that application version
+4. execute the requested command
+
+If the `API documentation plugin` is disabled, the CLI will prompt to enable it.
+
+## Environment Selection
+
+Use `-e, --env` to temporarily select an environment:
+
+```bash
+nocobase env update -e prod
+nocobase resource list --resource users -e prod
+```
+
+This does not change the current environment unless you explicitly run:
+
+```bash
+nocobase env use <name>
+```
+
+## Config Scope
+
+The `env` command supports two config scopes:
+
+- `project`: use `./.nocobase-cli` in the current working directory
+- `global`: use the global `.nocobase-cli` directory
+
+Use `-s, --scope` to select one explicitly:
+
+```bash
+nocobase env list -s project
+nocobase env add -s global --name prod --base-url http://example.com/api --token <token>
+nocobase env use local -s project
+```
+
+If you do not pass `--scope`, the CLI uses automatic resolution:
+
+1. current working directory if `./.nocobase-cli` exists
+2. `NOCOBASE_HOME_CLI`
+3. your home directory
+
+## Built-in Commands
+
+Current built-in topics:
+
+- `env`
+- `resource`
+
+Check available commands at any time:
+
+```bash
+nocobase --help
+nocobase env --help
+nocobase resource --help
+```
+
+## Common Flags
+
+- `-e, --env`: temporary environment selection
+- `-s, --scope`: config scope for `env` commands
+- `-t, --token`: token override
+- `-j, --json-output`: print raw JSON response
+
+Example:
+
+```bash
+nocobase env update -e prod -s global
+nocobase resource list --resource users -e prod -j
+```
+
+## Local Data
+
+The CLI stores its local state in `.nocobase-cli`, including:
+
+- `config.json`: environment definitions and current selection
+- `versions/<version>/commands.json`: cached runtime commands for a generated version

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --import tsx --no-warnings=ExperimentalWarning "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env -S node --import tsx --disable-warning=ExperimentalWarning
+
+import { ensureRuntimeFromArgv } from '../src/lib/bootstrap.ts';
+import { execute } from '@oclif/core';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+await ensureRuntimeFromArgv(process.argv.slice(2), {
+  configFile: path.join(path.dirname(__dirname), 'nocobase-cli.config.json'),
+});
+
+await execute({ development: true, dir: import.meta.url });

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { ensureRuntimeFromArgv } from '../dist/lib/bootstrap.js';
+import { execute } from '@oclif/core';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+try {
+  await ensureRuntimeFromArgv(process.argv.slice(2), {
+    configFile: path.join(path.dirname(__dirname), 'nocobase-cli.config.json'),
+  });
+
+  await execute({ dir: import.meta.url });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+}

package/dist/commands/env/add.js

@@ -0,0 +1,51 @@
+import { Command, Flags } from '@oclif/core';
+import { upsertEnv } from "../../lib/auth-store.js";
+import { formatCliHomeScope } from "../../lib/cli-home.js";
+import { isInteractiveTerminal, printVerbose, setVerboseMode, promptText } from "../../lib/ui.js";
+export default class EnvAdd extends Command {
+    static summary = 'Add or update a NocoBase environment';
+    static id = 'env add';
+    static flags = {
+        verbose: Flags.boolean({
+            description: 'Show detailed progress output',
+            default: false,
+        }),
+        name: Flags.string({
+            description: 'Environment name',
+            default: 'default',
+        }),
+        scope: Flags.string({
+            char: 's',
+            description: 'Config scope',
+            options: ['project', 'global'],
+        }),
+        'base-url': Flags.string({
+            description: 'NocoBase API base URL, for example http://localhost:13000/api',
+        }),
+        token: Flags.string({
+            char: 't',
+            description: 'Bearer token',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EnvAdd);
+        setVerboseMode(flags.verbose);
+        const name = flags.name || 'default';
+        const scope = flags.scope;
+        const baseUrl = flags['base-url'] ||
+            (isInteractiveTerminal()
+                ? await promptText('Base URL', { defaultValue: 'http://localhost:13000/api' })
+                : '');
+        const token = flags.token ||
+            (isInteractiveTerminal() ? await promptText('Bearer token', { secret: true }) : '');
+        if (!baseUrl) {
+            this.error('Missing base URL. Pass `--base-url <url>` or run in a TTY to enter it interactively.');
+        }
+        if (!token) {
+            this.error('Missing token. Pass `--token <token>` or run in a TTY to enter it interactively.');
+        }
+        printVerbose(`Saving env "${name}" with base URL ${baseUrl}`);
+        await upsertEnv(name, baseUrl, token, { scope });
+        this.log(`Saved env "${name}" and set it as current${scope ? ` in ${formatCliHomeScope(scope)} scope` : ''}.`);
+    }
+}

package/dist/commands/env/index.js

@@ -0,0 +1,27 @@
+import { Command, Flags } from '@oclif/core';
+import { getCurrentEnvName, getEnv } from "../../lib/auth-store.js";
+import { formatCliHomeScope } from "../../lib/cli-home.js";
+import { renderTable } from "../../lib/ui.js";
+export default class Env extends Command {
+    static summary = 'Show the current environment';
+    static id = 'env';
+    static flags = {
+        scope: Flags.string({
+            char: 's',
+            description: 'Config scope',
+            options: ['project', 'global'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Env);
+        const scope = flags.scope;
+        const envName = await getCurrentEnvName({ scope });
+        const env = await getEnv(envName, { scope });
+        if (!env?.baseUrl) {
+            this.log(`No current env is configured${scope ? ` in ${formatCliHomeScope(scope)} scope` : ''}.`);
+            this.log('Run `nocobase env add --name <name> --base-url <url> --token <token>` to add one.');
+            return;
+        }
+        this.log(renderTable(['Name', 'Base URL', 'Runtime'], [[envName, env?.baseUrl ?? '', env?.runtime?.version ?? '']]));
+    }
+}

package/dist/commands/env/list.js

@@ -0,0 +1,31 @@
+import { Command, Flags } from '@oclif/core';
+import { listEnvs } from "../../lib/auth-store.js";
+import { formatCliHomeScope } from "../../lib/cli-home.js";
+import { renderTable } from "../../lib/ui.js";
+export default class EnvList extends Command {
+    static summary = 'List configured environments';
+    static id = 'env list';
+    static flags = {
+        scope: Flags.string({
+            char: 's',
+            description: 'Config scope',
+            options: ['project', 'global'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EnvList);
+        const scope = flags.scope;
+        const { currentEnv, envs } = await listEnvs({ scope });
+        const names = Object.keys(envs).sort();
+        if (!names.length) {
+            this.log(`No envs configured${scope ? ` in ${formatCliHomeScope(scope)} scope` : ''}.`);
+            this.log('Run `nocobase env add --name <name> --base-url <url> --token <token>` to add one.');
+            return;
+        }
+        const rows = names.map((name) => {
+            const env = envs[name];
+            return [name === currentEnv ? '*' : '', name, env.baseUrl ?? '', env.runtime?.version ?? ''];
+        });
+        this.log(renderTable(['Current', 'Name', 'Base URL', 'Runtime'], rows));
+    }
+}

package/dist/commands/env/remove.js

@@ -0,0 +1,54 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { getCurrentEnvName, removeEnv } from "../../lib/auth-store.js";
+import { formatCliHomeScope } from "../../lib/cli-home.js";
+import { confirmAction, isInteractiveTerminal, printVerbose, setVerboseMode } from "../../lib/ui.js";
+export default class EnvRemove extends Command {
+    static id = 'env remove';
+    static summary = 'Remove a configured environment';
+    static flags = {
+        force: Flags.boolean({
+            char: 'f',
+            description: 'Remove without confirmation',
+            default: false,
+        }),
+        verbose: Flags.boolean({
+            description: 'Show detailed progress output',
+            default: false,
+        }),
+        scope: Flags.string({
+            char: 's',
+            description: 'Config scope',
+            options: ['project', 'global'],
+        }),
+    };
+    static args = {
+        name: Args.string({
+            description: 'Configured environment name',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(EnvRemove);
+        setVerboseMode(flags.verbose);
+        const scope = flags.scope;
+        const currentEnv = await getCurrentEnvName({ scope });
+        if (args.name === currentEnv && !flags.force) {
+            if (!isInteractiveTerminal()) {
+                this.error('Refusing to remove the current env without confirmation. Re-run with `--force`.');
+            }
+            const confirmed = await confirmAction(`Remove current env "${args.name}"?`, { defaultValue: false });
+            if (!confirmed) {
+                this.log('Canceled.');
+                return;
+            }
+        }
+        printVerbose(`Removing env "${args.name}"`);
+        const result = await removeEnv(args.name, { scope });
+        this.log(`Removed env "${result.removed}"${scope ? ` from ${formatCliHomeScope(scope)} scope` : ''}.`);
+        if (result.hasEnvs) {
+            this.log(`Current env: ${result.currentEnv}`);
+            return;
+        }
+        this.log('No envs configured.');
+    }
+}

package/dist/commands/env/update.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command, Flags } from '@oclif/core';
+import { updateEnvRuntime } from "../../lib/bootstrap.js";
+import { formatCliHomeScope } from "../../lib/cli-home.js";
+import { failTask, startTask, succeedTask } from "../../lib/ui.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export default class EnvUpdate extends Command {
+    static summary = 'Update commands for an environment from swagger:get';
+    static id = 'env update';
+    static flags = {
+        verbose: Flags.boolean({
+            description: 'Show detailed progress output',
+            default: false,
+        }),
+        env: Flags.string({
+            char: 'e',
+            description: 'Environment name',
+        }),
+        scope: Flags.string({
+            char: 's',
+            description: 'Config scope',
+            options: ['project', 'global'],
+        }),
+        'base-url': Flags.string({
+            description: 'NocoBase API base URL override',
+        }),
+        token: Flags.string({
+            char: 't',
+            description: 'Bearer token override',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EnvUpdate);
+        const scope = flags.scope;
+        const envLabel = flags.env ?? 'current';
+        startTask(`Updating env runtime: ${envLabel}${scope ? ` (${formatCliHomeScope(scope)})` : ''}`);
+        try {
+            const runtime = await updateEnvRuntime({
+                envName: flags.env,
+                scope,
+                baseUrl: flags['base-url'],
+                token: flags.token,
+                configFile: path.join(path.dirname(path.dirname(path.dirname(__dirname))), 'nocobase-ctl.config.json'),
+                verbose: flags.verbose,
+            });
+            succeedTask(`Updated env "${envLabel}" to runtime "${runtime.version}"${scope ? ` in ${formatCliHomeScope(scope)} scope` : ''}.`);
+        }
+        catch (error) {
+            failTask(`Failed to update env "${envLabel}".`);
+            throw error;
+        }
+    }
+}

package/dist/commands/env/use.js

@@ -0,0 +1,26 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { setCurrentEnv } from "../../lib/auth-store.js";
+import { formatCliHomeScope } from "../../lib/cli-home.js";
+export default class EnvUse extends Command {
+    static summary = 'Switch the current environment';
+    static id = 'env use';
+    static flags = {
+        scope: Flags.string({
+            char: 's',
+            description: 'Config scope',
+            options: ['project', 'global'],
+        }),
+    };
+    static args = {
+        name: Args.string({
+            description: 'Configured environment name',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(EnvUse);
+        const scope = flags.scope;
+        await setCurrentEnv(args.name, { scope });
+        this.log(`Current env: ${args.name}${scope ? ` (${formatCliHomeScope(scope)} scope)` : ''}`);
+    }
+}

package/dist/commands/resource/create.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildCreateArgs, createFlags, runResourceCommand } from "../../lib/resource-command.js";
+export default class ResourceCreate extends Command {
+    static summary = 'Create a record in a resource';
+    static description = 'Create a record in a generic resource. Pass record content through --values as a JSON object.';
+    static examples = [
+        `<%= config.bin %> <%= command.id %> --resource users --values '{"nickname":"Ada"}'`,
+        `<%= config.bin %> <%= command.id %> --resource posts.comments --source-id 1 --values '{"content":"Hello"}'`,
+    ];
+    static flags = createFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceCreate);
+        await runResourceCommand(this, 'create', flags, buildCreateArgs(flags));
+    }
+}

package/dist/commands/resource/destroy.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildDestroyArgs, destroyFlags, runResourceCommand } from "../../lib/resource-command.js";
+export default class ResourceDestroy extends Command {
+    static summary = 'Delete records from a resource';
+    static description = 'Delete records from a generic resource. Target records with --filter-by-tk or --filter.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --resource users --filter-by-tk 1',
+        `<%= config.bin %> <%= command.id %> --resource posts --filter '{"status":"archived"}'`,
+    ];
+    static flags = destroyFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceDestroy);
+        await runResourceCommand(this, 'destroy', flags, buildDestroyArgs(flags));
+    }
+}

package/dist/commands/resource/get.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildGetArgs, getFlags, runResourceCommand } from "../../lib/resource-command.js";
+export default class ResourceGet extends Command {
+    static summary = 'Get a record from a resource';
+    static description = 'Get a record from a generic resource. Use --filter-by-tk for the primary key and association resource names with --source-id when needed.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --resource users --filter-by-tk 1',
+        '<%= config.bin %> <%= command.id %> --resource posts.comments --source-id 1 --filter-by-tk 2',
+    ];
+    static flags = getFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceGet);
+        await runResourceCommand(this, 'get', flags, buildGetArgs(flags));
+    }
+}

package/dist/commands/resource/index.js

@@ -0,0 +1,7 @@
+import { Command } from '@oclif/core';
+export default class Resource extends Command {
+    static summary = 'Work with generic collection resources';
+    async run() {
+        this.log('Use `nocobase resource --help` to view available subcommands.');
+    }
+}

package/dist/commands/resource/list.js

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+import { buildListArgs, listFlags, runResourceCommand } from "../../lib/resource-command.js";
+export default class ResourceList extends Command {
+    static summary = 'List records from a resource';
+    static description = 'List records from a generic resource. Use association resource names like posts.comments with --source-id when needed.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --resource users',
+        '<%= config.bin %> <%= command.id %> --resource posts.comments --source-id 1 --fields id --fields content',
+        `<%= config.bin %> <%= command.id %> --resource users --filter '{"status":"active"}' --sort=-createdAt`,
+    ];
+    static flags = listFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceList);
+        await runResourceCommand(this, 'list', flags, buildListArgs(flags));
+    }
+}

package/dist/commands/resource/query.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildQueryArgs, queryFlags, runResourceCommand } from "../../lib/resource-command.js";
+export default class ResourceQuery extends Command {
+    static summary = 'Run an aggregate query on a resource';
+    static description = 'Run an aggregate query on a generic resource. Pass measures, dimensions, and orders as JSON arrays.';
+    static examples = [
+        `<%= config.bin %> <%= command.id %> --resource orders --measures '[{"field":["id"],"aggregation":"count","alias":"count"}]'`,
+        `<%= config.bin %> <%= command.id %> --resource orders --dimensions '[{"field":["status"],"alias":"status"}]' --orders '[{"field":["createdAt"],"order":"desc"}]'`,
+    ];
+    static flags = queryFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceQuery);
+        await runResourceCommand(this, 'query', flags, buildQueryArgs(flags));
+    }
+}

package/dist/commands/resource/update.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildUpdateArgs, runResourceCommand, updateFlags } from "../../lib/resource-command.js";
+export default class ResourceUpdate extends Command {
+    static summary = 'Update records in a resource';
+    static description = 'Update records in a generic resource. Target records with --filter-by-tk or --filter, and pass updated values through --values.';
+    static examples = [
+        `<%= config.bin %> <%= command.id %> --resource users --filter-by-tk 1 --values '{"nickname":"Grace"}'`,
+        `<%= config.bin %> <%= command.id %> --resource posts --filter '{"status":"draft"}' --values '{"status":"published"}'`,
+    ];
+    static flags = updateFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceUpdate);
+        await runResourceCommand(this, 'update', flags, buildUpdateArgs(flags));
+    }
+}

package/dist/generated/command-registry.js

@@ -0,0 +1,81 @@
+import { Command } from '@oclif/core';
+import EnvAdd from "../commands/env/add.js";
+import Env from "../commands/env/index.js";
+import EnvList from "../commands/env/list.js";
+import EnvRemove from "../commands/env/remove.js";
+import EnvUpdate from "../commands/env/update.js";
+import EnvUse from "../commands/env/use.js";
+import ResourceCreate from "../commands/resource/create.js";
+import ResourceDestroy from "../commands/resource/destroy.js";
+import ResourceGet from "../commands/resource/get.js";
+import Resource from "../commands/resource/index.js";
+import ResourceList from "../commands/resource/list.js";
+import ResourceQuery from "../commands/resource/query.js";
+import ResourceUpdate from "../commands/resource/update.js";
+import { getCurrentEnvName, getEnv } from "../lib/auth-store.js";
+import { createGeneratedFlags, GeneratedApiCommand } from "../lib/generated-command.js";
+import { toKebabCase } from "../lib/naming.js";
+import { loadRuntimeSync } from "../lib/runtime-store.js";
+function readEnvName(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--env') {
+            return argv[index + 1];
+        }
+        if (token === '-e') {
+            return argv[index + 1];
+        }
+        if (token.startsWith('--env=')) {
+            return token.slice('--env='.length);
+        }
+    }
+    return undefined;
+}
+function createRuntimeCommand(operation) {
+    return class RuntimeCommand extends GeneratedApiCommand {
+        static summary = operation.summary;
+        static description = operation.description;
+        static examples = operation.examples;
+        static flags = createGeneratedFlags(operation);
+        static operation = operation;
+    };
+}
+function createRuntimeIndexCommand(commandId, operation) {
+    return class RuntimeIndexCommand extends Command {
+        static summary = operation.resourceDescription || operation.resourceDisplayName || `Work with ${commandId}`;
+        static description = operation.resourceDescription;
+        async run() {
+            this.log(`Use \`nocobase ${commandId} --help\` to view available subcommands.`);
+        }
+    };
+}
+const registry = {
+    env: Env,
+    'env:add': EnvAdd,
+    'env:list': EnvList,
+    'env:remove': EnvRemove,
+    'env:update': EnvUpdate,
+    'env:use': EnvUse,
+    resource: Resource,
+    'resource:create': ResourceCreate,
+    'resource:destroy': ResourceDestroy,
+    'resource:get': ResourceGet,
+    'resource:list': ResourceList,
+    'resource:query': ResourceQuery,
+    'resource:update': ResourceUpdate,
+};
+const envName = readEnvName(process.argv.slice(2)) ?? (await getCurrentEnvName());
+const env = await getEnv(envName);
+const runtime = loadRuntimeSync(env?.runtime?.version);
+for (const operation of runtime?.commands ?? []) {
+    const commandSegments = operation.commandId.split(' ');
+    const commandKey = commandSegments.join(':');
+    registry[commandKey] = createRuntimeCommand(operation);
+    const topLevelCommandId = commandSegments[0];
+    const modulePrefix = toKebabCase(operation.moduleDisplayName || operation.moduleName || '');
+    const isTopLevelResource = Boolean(topLevelCommandId && modulePrefix && topLevelCommandId !== modulePrefix);
+    if (isTopLevelResource && !registry[topLevelCommandId]) {
+        registry[topLevelCommandId] = createRuntimeIndexCommand(topLevelCommandId, operation);
+    }
+}
+export default registry;