kubun 0.9.0 → 0.11.0

package/README.md

@@ -1,247 +1,35 @@
-kubun
-=================
+# kubun
 
-Kubun CLI
+Kubun CLI.
 
-
-[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
 [![Version](https://img.shields.io/npm/v/kubun.svg)](https://npmjs.org/package/kubun)
 [![Downloads/week](https://img.shields.io/npm/dw/kubun.svg)](https://npmjs.org/package/kubun)
 
+## Usage
 
-<!-- toc -->
-* [Usage](#usage)
-* [Commands](#commands)
-<!-- tocstop -->
-# Usage
-<!-- usage -->
 ```sh-session
-$ npm install -g kubun
-$ kubun COMMAND
-running command...
-$ kubun (--version)
-kubun/0.9.0 darwin-arm64 node-v24.15.0
-$ kubun --help [COMMAND]
-USAGE
-  $ kubun COMMAND
-...
-```
-<!-- usagestop -->
-# Commands
-<!-- commands -->
-* [`kubun account generate`](#kubun-account-generate)
-* [`kubun account id`](#kubun-account-id)
-* [`kubun graph deploy`](#kubun-graph-deploy)
-* [`kubun graph mutate ID TEXT`](#kubun-graph-mutate-id-text)
-* [`kubun graph query ID TEXT`](#kubun-graph-query-id-text)
-* [`kubun graphql schema`](#kubun-graphql-schema)
-* [`kubun help [COMMAND]`](#kubun-help-command)
-* [`kubun mcp`](#kubun-mcp)
-* [`kubun model cluster`](#kubun-model-cluster)
-* [`kubun model create NAME SCHEMA`](#kubun-model-create-name-schema)
-* [`kubun serve`](#kubun-serve)
-
-## `kubun account generate`
-
-Generate a random private key to use as account signer
-
-```
-USAGE
-  $ kubun account generate
-
-DESCRIPTION
-  Generate a random private key to use as account signer
-```
-
-## `kubun account id`
-
-Display the DID of an account given its private key
-
-```
-USAGE
-  $ kubun account id -k <value>
-
-FLAGS
-  -k, --privateKey=<value>  (required) [env: KUBUN_PRIVATE_KEY] base64-encoded private key
-
-DESCRIPTION
-  Display the DID of an account given its private key
-```
-
-## `kubun graph deploy`
-
-Deploy a documents model graph
-
+$ pnpm add -g kubun
+$ kubun --help
+$ kubun <command> --help
 ```
-USAGE
-  $ kubun graph deploy -c <value>... -k <value> [--id <value>] [-n <value>] [--url <value>]
 
-FLAGS
-  -c, --cluster=<value>...  (required) path of the JSON file of the cluster
-  -k, --privateKey=<value>  (required) [env: KUBUN_PRIVATE_KEY] base64-encoded private key
-  -n, --name=<value>        graph name
-      --id=<value>          graph ID
-      --url=<value>         Kubun server URL
+The CLI is built on [commander](https://github.com/tj/commander.js) with [`@tejika/cli`](https://www.npmjs.com/package/@tejika/cli); status output renders to stderr (via ink) and data payloads to stdout, so command output stays pipeable.
 
-DESCRIPTION
-  Deploy a documents model graph
-```
+## Commands
 
-## `kubun graph mutate ID TEXT`
+Run `kubun <command> --help` for the full, authoritative flag list — the descriptions below are a summary.
 
-Execute a GraphQL mutation on a graph
+| Command | Description |
+| --- | --- |
+| `kubun account generate` | Generate a random private key to use as account signer |
+| `kubun account id` | Display the DID of an account given its private key |
+| `kubun graph mutate <id> <text>` | Execute a GraphQL mutation on a graph |
+| `kubun graph query <id> <text>` | Execute a GraphQL query on a graph |
+| `kubun graph deploy` | Deploy a documents model graph |
+| `kubun graphql schema` | Create a GraphQL schema from clusters of document models |
+| `kubun model cluster` | Create a documents cluster model |
+| `kubun model create <name> <schema>` | Create a document model |
+| `kubun mcp` | Start an MCP server for Kubun |
+| `kubun serve` | Start a local Kubun server |
 
-```
-USAGE
-  $ kubun graph mutate ID TEXT -k <value> [--url <value>] [--variables <value>]
-
-ARGUMENTS
-  ID    graph ID
-  TEXT  mutation text
-
-FLAGS
-  -k, --privateKey=<value>  (required) [env: KUBUN_PRIVATE_KEY] base64-encoded private key
-      --url=<value>         Kubun server URL
-      --variables=<value>   query variables as JSON string
-
-DESCRIPTION
-  Execute a GraphQL mutation on a graph
-```
-
-## `kubun graph query ID TEXT`
-
-Execute a GraphQL query on a graph
-
-```
-USAGE
-  $ kubun graph query ID TEXT -k <value> [--url <value>] [--variables <value>]
-
-ARGUMENTS
-  ID    graph ID
-  TEXT  query text
-
-FLAGS
-  -k, --privateKey=<value>  (required) [env: KUBUN_PRIVATE_KEY] base64-encoded private key
-      --url=<value>         Kubun server URL
-      --variables=<value>   query variables as JSON string
-
-DESCRIPTION
-  Execute a GraphQL query on a graph
-```
-
-## `kubun graphql schema`
-
-Create a GraphQL schema from clusters of document models
-
-```
-USAGE
-  $ kubun graphql schema -c <value>... [-o <value>]
-
-FLAGS
-  -c, --cluster=<value>...  (required) path of the JSON file of the cluster
-  -o, --output=<value>      output file for the GraphQL schema
-
-DESCRIPTION
-  Create a GraphQL schema from clusters of document models
-```
-
-## `kubun help [COMMAND]`
-
-Display help for kubun.
-
-```
-USAGE
-  $ kubun help [COMMAND...] [-n]
-
-ARGUMENTS
-  [COMMAND...]  Command to show help for.
-
-FLAGS
-  -n, --nested-commands  Include all nested commands in the output.
-
-DESCRIPTION
-  Display help for kubun.
-```
-
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.2.46/src/commands/help.ts)_
-
-## `kubun mcp`
-
-Start an MCP server for Kubun
-
-```
-USAGE
-  $ kubun mcp [-c <value> | -d <value>] [-k <value>]
-
-FLAGS
-  -c, --connect=<value>     URL of an existing Kubun HTTP server to connect to
-  -d, --db=<value>          SQLite database path or PostgreSQL URL
-  -k, --privateKey=<value>  [env: KUBUN_PRIVATE_KEY] base64-encoded private key
-
-DESCRIPTION
-  Start an MCP server for Kubun
-```
-
-## `kubun model cluster`
-
-Create a documents cluster model
-
-```
-USAGE
-  $ kubun model cluster -m <value>... [-o <value>]
-
-FLAGS
-  -m, --model=<value>...  (required) document model as JSON string
-  -o, --output=<value>    output file for the cluster
-
-DESCRIPTION
-  Create a documents cluster model
-```
-
-## `kubun model create NAME SCHEMA`
-
-Create a document model
-
-```
-USAGE
-  $ kubun model create NAME SCHEMA [-b default|interface|unique] [-c] [-o <value>] [-u <value>...]
-
-ARGUMENTS
-  NAME    document model name
-  SCHEMA  document schema as JSON string
-
-FLAGS
-  -b, --behavior=<option>       [default: default] behavior of the document
-                                <options: default|interface|unique>
-  -c, --cluster                 create a cluster model instead of a document model
-  -o, --output=<value>          output file
-  -u, --uniqueField=<value>...  unique field of the document when behavior is set to "unique"
-
-DESCRIPTION
-  Create a document model
-```
-
-## `kubun serve`
-
-Start a local Kubun server
-
-```
-USAGE
-  $ kubun serve [-a <value>] [--autoAcceptPeers <value> --p2p] [--db <value>] [-l
-    trace|debug|info|warning|error|fatal] [-p <value>] [-k <value> | --id <value>]
-
-FLAGS
-  -a, --allowedOrigin=<value>    [default: *, env: KUBUN_ALLOWED_ORIGIN] allowed HTTP origin
-  -k, --privateKey=<value>       [env: KUBUN_PRIVATE_KEY] base64-encoded private key
-  -l, --logLevel=<option>        [default: warning] log level
-                                 <options: trace|debug|info|warning|error|fatal>
-  -p, --port=<value>             port to listen on
-      --autoAcceptPeers=<value>  comma-separated DIDs to auto-accept for peer join flows
-      --db=<value>               path to the local SQLite database
-      --id=<value>               server ID
-      --p2p                      enable P2P mode with sync and graph protocols over HTTP
-
-DESCRIPTION
-  Start a local Kubun server
-```
-<!-- commandsstop -->
+Common flags: `-k, --private-key <value>` (also read from `KUBUN_PRIVATE_KEY`), `--url <value>`, `-l, --log-level <level>`, `-p, --port <port>`, `-a, --allowed-origin <origin>` (also `KUBUN_ALLOWED_ORIGIN`).

package/bin/dev.js

@@ -1,6 +1,14 @@
-#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+#!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
-// eslint-disable-next-line n/shebang
-import { execute } from '@oclif/core'
+import { run } from '../lib/index.js'
 
-await execute({ development: true, dir: import.meta.url })
+process.on('unhandledRejection', (reason) => {
+  const message = reason instanceof Error ? reason.message : String(reason)
+  process.stderr.write(`✘ ${message}\n`)
+  if (process.env.KUBUN_DEBUG === '1' && reason instanceof Error && reason.stack != null) {
+    process.stderr.write(`${reason.stack}\n`)
+  }
+  process.exitCode = 1
+})
+
+await run(process.argv)

package/bin/run.js

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
-import { execute } from '@oclif/core'
+import { run } from '../lib/index.js'
 
-await execute({ dir: import.meta.url })
+process.on('unhandledRejection', (reason) => {
+  const message = reason instanceof Error ? reason.message : String(reason)
+  process.stderr.write(`✘ ${message}\n`)
+  if (process.env.KUBUN_DEBUG === '1' && reason instanceof Error && reason.stack != null) {
+    process.stderr.write(`${reason.stack}\n`)
+  }
+  process.exitCode = 1
+})
+
+await run(process.argv)

package/lib/account.d.ts

@@ -0,0 +1,2 @@
+import { type SigningIdentity } from '@kokuin/token';
+export declare function getSigner(key: string): SigningIdentity;

package/lib/account.js

@@ -0,0 +1,5 @@
+import { createSigningIdentity } from '@kokuin/token';
+import { fromB64 } from '@sozai/codec';
+export function getSigner(key) {
+    return createSigningIdentity(fromB64(key));
+}

package/lib/client.d.ts

@@ -0,0 +1,2 @@
+import { HTTPClient } from '@kubun/http-client';
+export declare function createClient(signerKey: string, url?: string): HTTPClient;

package/{dist → lib}/client.js

@@ -1,5 +1,8 @@
 import { HTTPClient } from '@kubun/http-client';
 import { getSigner } from './account.js';
 export function createClient(signerKey, url = 'http://localhost:4321') {
-    return new HTTPClient({ identity: getSigner(signerKey), url });
+    return new HTTPClient({
+        identity: getSigner(signerKey),
+        url
+    });
 }

package/lib/commands/account.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createAccountCommand(): Command;

package/lib/commands/account.js

@@ -0,0 +1,24 @@
+import { randomPrivateKey } from '@kokuin/token';
+import { toB64 } from '@sozai/codec';
+import { Command } from 'commander';
+import { getSigner } from '../account.js';
+import { withPrivateKey } from '../options.js';
+function createGenerateCommand() {
+    return new Command('generate').description('Generate a random private key to use as account signer').action(async ()=>{
+        const key = await randomPrivateKey();
+        console.log(toB64(key));
+    });
+}
+function createIDCommand() {
+    const cmd = new Command('id').description('Display the DID of an account given its private key');
+    withPrivateKey(cmd, {
+        required: true
+    });
+    cmd.action((opts)=>{
+        console.log(getSigner(opts.privateKey).id);
+    });
+    return cmd;
+}
+export function createAccountCommand() {
+    return new Command('account').description('Account commands').addCommand(createGenerateCommand()).addCommand(createIDCommand());
+}

package/lib/commands/graph.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createGraphCommand(): Command;

package/lib/commands/graph.js

@@ -0,0 +1,74 @@
+import { Command } from 'commander';
+import { createClient } from '../client.js';
+import { readJSON } from '../fs.js';
+import { withPrivateKey, withURL } from '../options.js';
+import { renderNotice, withSpinner } from '../ui.js';
+function parseVariables(value) {
+    if (!value) {
+        return {};
+    }
+    try {
+        return JSON.parse(value);
+    } catch  {
+        throw new Error(`--variables is not valid JSON: ${value}`);
+    }
+}
+function createMutateCommand() {
+    const cmd = new Command('mutate').description('Execute a GraphQL mutation on a graph').argument('<id>', 'graph ID').argument('<text>', 'mutation text').option('--variables <json>', 'query variables as JSON string');
+    withPrivateKey(cmd, {
+        required: true
+    });
+    withURL(cmd);
+    cmd.action(async (id, text, opts)=>{
+        const client = createClient(opts.privateKey, opts.url);
+        const result = await withSpinner('Executing graph mutation...', ()=>client.mutateGraph({
+                id,
+                text,
+                variables: parseVariables(opts.variables)
+            }));
+        renderNotice('success', 'Graph mutation executed');
+        console.log(JSON.stringify(result, null, 2));
+    });
+    return cmd;
+}
+function createQueryCommand() {
+    const cmd = new Command('query').description('Execute a GraphQL query on a graph').argument('<id>', 'graph ID').argument('<text>', 'query text').option('--variables <json>', 'query variables as JSON string');
+    withPrivateKey(cmd, {
+        required: true
+    });
+    withURL(cmd);
+    cmd.action(async (id, text, opts)=>{
+        const client = createClient(opts.privateKey, opts.url);
+        const result = await withSpinner('Querying graph...', ()=>client.queryGraph({
+                id,
+                text,
+                variables: parseVariables(opts.variables)
+            }));
+        renderNotice('success', 'Graph query executed');
+        console.log(JSON.stringify(result, null, 2));
+    });
+    return cmd;
+}
+function createDeployCommand() {
+    const cmd = new Command('deploy').description('Deploy a documents model graph').requiredOption('-c, --cluster <path...>', 'path of the JSON file of the cluster (repeatable)').option('--id <id>', 'graph ID').option('-n, --name <name>', 'graph name');
+    withPrivateKey(cmd, {
+        required: true
+    });
+    withURL(cmd);
+    cmd.action(async (opts)=>{
+        const client = createClient(opts.privateKey, opts.url);
+        const graph = await withSpinner('Deploying graph clusters...', async ()=>{
+            const clusters = await Promise.all(opts.cluster.map((path)=>readJSON(path)));
+            return client.deployGraph({
+                clusters,
+                id: opts.id,
+                name: opts.name
+            });
+        });
+        renderNotice('success', `Deployed graph with ID: ${graph.id}`);
+    });
+    return cmd;
+}
+export function createGraphCommand() {
+    return new Command('graph').description('Graph commands').addCommand(createMutateCommand()).addCommand(createQueryCommand()).addCommand(createDeployCommand());
+}

package/lib/commands/graphql.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createGraphQLCommand(): Command;

package/lib/commands/graphql.js

@@ -0,0 +1,33 @@
+import { createSchema } from '@kubun/graphql';
+import { clusterToRecord, GraphModel } from '@kubun/protocol';
+import { Command } from 'commander';
+import { printSchema } from 'graphql';
+import { readJSON, writeFile } from '../fs.js';
+import { renderNotice, withSpinner } from '../ui.js';
+function createSchemaCommand() {
+    const cmd = new Command('schema').description('Create a GraphQL schema from clusters of document models').requiredOption('-c, --cluster <path...>', 'path of the JSON file of the cluster (repeatable)').option('-o, --output <file>', 'output file for the GraphQL schema');
+    cmd.action(async (opts)=>{
+        const schema = await withSpinner('Loading clusters...', async ()=>{
+            const clusterModels = await Promise.all(opts.cluster.map((path)=>readJSON(path)));
+            const clusters = {};
+            for (const cluster of clusterModels){
+                Object.assign(clusters, clusterToRecord(cluster));
+            }
+            const model = GraphModel.fromClusters({
+                clusters
+            });
+            return printSchema(createSchema(model));
+        });
+        if (opts.output == null) {
+            renderNotice('success', 'GraphQL schema generated');
+            console.log(schema);
+        } else {
+            await writeFile(opts.output, schema);
+            renderNotice('success', `GraphQL schema written to ${opts.output}`);
+        }
+    });
+    return cmd;
+}
+export function createGraphQLCommand() {
+    return new Command('graphql').description('GraphQL commands').addCommand(createSchemaCommand());
+}

package/lib/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createMCPCommand(): Command;

package/lib/commands/mcp.js

@@ -0,0 +1,21 @@
+import { createConfig } from '@kubun/mcp';
+import { serveProcess } from '@mokei/context-server';
+import { Command } from 'commander';
+import { getSigner } from '../account.js';
+import { withPrivateKey } from '../options.js';
+export function createMCPCommand() {
+    const cmd = new Command('mcp').description('Start an MCP server for Kubun').option('-c, --connect <url>', 'URL of an existing Kubun HTTP server to connect to').option('-d, --db <path>', 'SQLite database path or PostgreSQL URL');
+    withPrivateKey(cmd);
+    cmd.action(async (opts)=>{
+        if (opts.connect != null && opts.db != null) {
+            throw new Error('--connect and --db are mutually exclusive');
+        }
+        const config = await createConfig({
+            connect: opts.connect,
+            database: opts.db,
+            identity: opts.privateKey ? getSigner(opts.privateKey) : undefined
+        });
+        serveProcess(config);
+    });
+    return cmd;
+}

package/lib/commands/model.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createModelCommand(): Command;

package/lib/commands/model.js

@@ -0,0 +1,69 @@
+import { ClusterBuilder } from '@kubun/protocol';
+import { Command, Option } from 'commander';
+import { writeJSON } from '../fs.js';
+import { renderNotice } from '../ui.js';
+function parseJSON(label, value) {
+    try {
+        return JSON.parse(value);
+    } catch  {
+        throw new Error(`${label} is not valid JSON: ${value}`);
+    }
+}
+function createClusterCommand() {
+    const cmd = new Command('cluster').description('Create a documents cluster model').requiredOption('-m, --model <json...>', 'document model as JSON string (repeatable)').option('-o, --output <file>', 'output file for the cluster');
+    cmd.action(async (opts)=>{
+        const builder = new ClusterBuilder();
+        builder.addAll(opts.model.map((model)=>parseJSON('--model', model)));
+        const cluster = builder.build();
+        if (opts.output == null) {
+            renderNotice('success', 'Cluster model created');
+            console.log(JSON.stringify(cluster));
+        } else {
+            await writeJSON(opts.output, cluster);
+            renderNotice('success', `Cluster model written to ${opts.output}`);
+        }
+    });
+    return cmd;
+}
+function createCreateCommand() {
+    const cmd = new Command('create').description('Create a document model').argument('<name>', 'document model name').argument('<schema>', 'document schema as JSON string').addOption(new Option('-b, --behavior <behavior>', 'behavior of the document').choices([
+        'default',
+        'interface',
+        'unique'
+    ]).default('default')).option('-c, --cluster', 'create a cluster model instead of a document model').option('-o, --output <file>', 'output file').option('-u, --unique-field <field...>', 'unique field of the document when behavior is "unique" (repeatable)');
+    cmd.action(async (name, schema, opts)=>{
+        const model = {
+            name,
+            behavior: opts.behavior,
+            schema: parseJSON('<schema>', schema)
+        };
+        if (opts.behavior === 'unique') {
+            model.uniqueFields = opts.uniqueField;
+        }
+        const builder = new ClusterBuilder();
+        builder.add(model);
+        if (opts.cluster) {
+            const cluster = builder.build();
+            if (opts.output == null) {
+                renderNotice('success', 'Cluster model created');
+                console.log(JSON.stringify(cluster));
+            } else {
+                await writeJSON(opts.output, cluster);
+                renderNotice('success', `Cluster model written to ${opts.output}`);
+            }
+            return;
+        }
+        const document = builder.cluster[0];
+        if (opts.output == null) {
+            renderNotice('success', 'Document model created');
+            console.log(JSON.stringify(document));
+        } else {
+            await writeJSON(opts.output, document);
+            renderNotice('success', `Document model written to ${opts.output}`);
+        }
+    });
+    return cmd;
+}
+export function createModelCommand() {
+    return new Command('model').description('Model commands').addCommand(createClusterCommand()).addCommand(createCreateCommand());
+}

package/lib/commands/serve.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createServeCommand(): Command;