@dikolab/kbdb 0.1.6 → 0.2.1

package/docs/modules/typescript/shared/cli/functions.md

@@ -0,0 +1,630 @@
+# cli/functions -- Command Functions
+
+*CLI orchestrator, command dispatcher, argument parser,
+utility helpers, and one function per CLI sub-command.*
+
+## Source
+
+`src/shared/cli/functions/`
+
+## Functions
+
+### `runCli`
+
+**File:** `run-cli.function.ts`
+
+Full CLI orchestrator. Parses arguments, routes to the
+appropriate sub-flow, and returns a `CommandResult`
+without touching process globals.
+
+```ts
+async function runCli(
+   argv: string[],
+   deps: CliDeps,
+): Promise<CommandResult>;
+```
+
+`CliDeps` is an injectable dependency record:
+
+```ts
+interface CliDeps {
+   isStdinTty: () => boolean;
+   promptUser: (question: string) => Promise<string>;
+   createWorkerClient: (opts: {
+      contextPath: string;
+   }) => Promise<DisconnectableClient>;
+   findDb: (basePath?: string) => string | null;
+   runInit: (options: CliOptions) => InitResult;
+   startMcpServer?: (contextPath: string) => Promise<void>;
+}
+```
+
+Routes:
+
+| Command     | Handler                          |
+|-------------|----------------------------------|
+| `help`      | returns `HELP_TEXT`              |
+| `version`   | returns `VERSION`                |
+| `init`      | calls `deps.runInit`             |
+| `mcp`       | calls `deps.startMcpServer`      |
+| `migrate`   | version check + migrate daemon   |
+| *(other)*   | `dispatchCommand(client, opts)`  |
+
+### `dispatchCommand`
+
+**File:** `dispatch-command.function.ts`
+
+Routes a parsed CLI command to the appropriate handler
+and returns a `CommandResult` without touching process
+globals.
+
+```ts
+async function dispatchCommand(
+   client: DispatchClient,
+   options: CliOptions,
+   io?: LearnIO,
+): Promise<CommandResult>;
+```
+
+`DispatchClient` is the intersection of all per-command
+client interfaces (`SearchClient & LearnClient &
+UnlearnClient & ContentClient & CheckClient &
+GcClient & RebuildClient & SkillClient & AgentClient`).
+
+| Command        | Handler                          |
+|----------------|----------------------------------|
+| `learn`        | `runLearn(client, options, io)`  |
+| `unlearn`      | `runUnlearn(client, options)`    |
+| `search`       | `runSearch(client, options)`     |
+| `content`      | `runContent(client, options)`    |
+| `check`        | `runCheck(client, options)`      |
+| `gc`           | `runGc(client, options)`         |
+| `rebuild`      | `runRebuild(client, options)`    |
+| `skill-learn`  | `runSkillLearn(client, options)` |
+| `skill-list`   | `runSkillList(client, options)`  |
+| `skill-get`    | `runSkillGet(client, options)`   |
+| `skill-delete` | `runSkillDelete(client, options)`|
+| `agent-create` | `runAgentCreate(client, options)`|
+| `agent-list`   | `runAgentList(client, options)`  |
+| `agent-get`    | `runAgentGet(client, options)`   |
+| `agent-delete` | `runAgentDelete(client, options)`|
+
+### `parseArgs`
+
+**File:** `parse-args.function.ts`
+
+Parses command-line arguments into a typed `CliOptions`
+object. Supports both Deno (`Deno.args`) and Node.js
+(`process.argv.slice(2)`) argument sources.
+
+```ts
+function parseArgs(
+   argv: string[],
+): CliOptions;
+```
+
+Throws on invalid or missing required arguments.
+Prints help text and exits for `--help` / `--version`.
+
+**Compound command handling**: when the first positional
+argument is `db`, `skill`, or `agent`, the parser
+consumes the next positional as the subcommand and sets
+`command` to the hyphenated form:
+
+| First positional | Second positional | `command` value  |
+|------------------|-------------------|------------------|
+| `db`             | `init`            | `db-init`        |
+| `db`             | `migrate`         | `db-migrate`     |
+| `skill`          | `learn`           | `skill-learn`    |
+| `skill`          | `list`            | `skill-list`     |
+| `skill`          | `get`             | `skill-get`      |
+| `skill`          | `delete`          | `skill-delete`   |
+| `agent`          | `create`          | `agent-create`   |
+| `agent`          | `list`            | `agent-list`     |
+| `agent`          | `get`             | `agent-get`      |
+| `agent`          | `delete`          | `agent-delete`   |
+
+**New options parsed:**
+
+| Flag            | `CliOptions` field | Description           |
+|-----------------|--------------------|-----------------------|
+| `--name <n>`    | `name`             | Skill or agent name   |
+| `--persona <p>` | `persona`          | Agent persona file    |
+| `--body <b>`    | `body`             | Skill body file       |
+| `--skills <s>`  | `skills`           | Comma-separated kbids |
+
+### `findDb`
+
+**File:** `find-db.function.ts`
+
+Resolves the absolute path to the `.kbdb` directory
+under the given base path. Returns `null` when the
+directory does not exist. Pure read-only -- never
+creates the directory.
+
+```ts
+function findDb(
+   dbPath?: string,
+): string | null;
+```
+
+### `runInit`
+
+**File:** `run-init.function.ts`
+
+Creates the `.kbdb` directory scaffold directly on disk
+without requiring a running worker daemon.
+
+```ts
+function runInit(
+   options: CliOptions,
+): InitResult;
+```
+
+```ts
+interface InitResult {
+   readonly ok: boolean;
+   readonly targetPath: string;
+   readonly errorMessage?: string;
+}
+```
+
+### `runMigrate`
+
+**File:** `run-migrate.function.ts`
+
+Checks the database version and runs pending migrations
+when needed.
+
+```ts
+async function runMigrate(
+   client: MigrateClient,
+   options: CliOptions,
+): Promise<MigrateCommandResult>;
+```
+
+```ts
+interface MigrateCommandResult {
+   readonly status: VersionCompatibility;
+   readonly versionStatus: VersionStatus;
+   readonly migrateResult?: MigrateResult;
+}
+```
+
+Resolution order:
+
+| Version status    | Action                              |
+|-------------------|-------------------------------------|
+| `compatible`      | returns without running migrations  |
+| `needs_migration` | calls `client.migrateDatabase`      |
+| `too_new`         | returns without running migrations  |
+
+### `runLearn`
+
+**File:** `run-learn.function.ts`
+
+Imports and indexes documents into the knowledge base.
+
+```ts
+async function runLearn(
+   client: LearnClient,
+   options: CliOptions,
+   io?: LearnIO,
+): Promise<LearnResult[]>;
+```
+
+- If input is a **directory**: recursively scans for
+  supported text files (`.md`, `.txt`, `.rst`,
+  `.adoc`). Image files are silently skipped during
+  directory scans. Computes content hash for each,
+  skips duplicates, calls `client.addSection()` per
+  file.
+- If input is a **text file**: adds that single file.
+  `--title` and `--description` are optional.
+- If input is **stdin** (`-`): reads `text/markdown`.
+- Returns a `LearnResult[]` with one record per file
+  processed.
+
+### `runUnlearn`
+
+**File:** `run-unlearn.function.ts`
+
+Removes knowledge base contents by KB ID.
+
+```ts
+async function runUnlearn(
+   client: UnlearnClient,
+   options: CliOptions,
+): Promise<unknown>;
+```
+
+Accepts a list of KB IDs from `options.args`. Calls
+`client.removeSection()` for each.
+
+### `runSearch`
+
+**File:** `run-search.function.ts`
+
+Searches the knowledge base by query string.
+
+```ts
+async function runSearch(
+   client: SearchClient,
+   options: CliOptions,
+): Promise<SearchDisplay[]>;
+```
+
+Calls `client.search()` with the query, mode, and
+limit from options. Returns `SearchDisplay[]` for
+use by `dispatchCommand`.
+
+### `runContent`
+
+**File:** `run-content.function.ts`
+
+Composes and outputs a rendered Markdown document from
+one or more kbid or docid identifiers.
+
+```ts
+async function runContent(
+   client: ContentClient,
+   options: CliOptions,
+): Promise<unknown>;
+```
+
+Takes identifiers from `options.args`. Calls
+`client.content(ids)`.
+
+### `runCheck`
+
+**File:** `run-check.function.ts`
+
+Runs an integrity check on the database.
+
+```ts
+async function runCheck(
+   client: CheckClient,
+   options: CliOptions,
+): Promise<{ ok: boolean }>;
+```
+
+Calls `client.integrityCheck()`.
+
+### `runGc`
+
+**File:** `run-gc.function.ts`
+
+Runs garbage collection on the database.
+
+```ts
+async function runGc(
+   client: GcClient,
+   options: CliOptions,
+): Promise<unknown>;
+```
+
+Calls `client.gc()`.
+
+### `runRebuild`
+
+**File:** `run-rebuild.function.ts`
+
+Rebuilds all indexes from sections and documents.
+
+```ts
+async function runRebuild(
+   client: RebuildClient,
+   options: CliOptions,
+): Promise<unknown>;
+```
+
+Calls `client.rebuildIndexes()`.
+
+### `ensureDb`
+
+**File:** `ensure-db.function.ts`
+
+Ensures the database directory exists, prompting the
+user if stdin is a TTY or failing if stdin is piped.
+
+```ts
+async function ensureDb(
+   dbPath: string,
+): Promise<void>;
+```
+
+### `formatOutput`
+
+**File:** `format-output.function.ts`
+
+Formats a result object for the selected output format.
+
+```ts
+function formatOutput(
+   result: unknown,
+   format: OutputFormat,
+): string;
+```
+
+| Format | Output                      |
+|--------|-----------------------------|
+| `json` | JSON string (default)       |
+| `text` | Human-readable list         |
+| `mcp`  | MCP tool result format      |
+
+### `errorToMessage`
+
+**File:** `error-to-message.function.ts`
+
+Converts an unknown thrown value to a human-readable
+message.
+
+```ts
+function errorToMessage(
+   err: unknown,
+): string;
+```
+
+Returns `err.message` for `Error` instances, or
+`String(err)` for all other values.
+
+### `isStdinTty`
+
+**File:** `is-stdin-tty.function.ts`
+
+Returns `true` when stdin is an interactive terminal.
+
+```ts
+function isStdinTty(
+   stdin?: NodeJS.ReadStream,
+): boolean;
+```
+
+`stdin` defaults to `process.stdin`.
+
+### `promptUser`
+
+**File:** `prompt-user.function.ts`
+
+Prompts the user on stdin (TTY only) and returns the
+trimmed reply.
+
+```ts
+async function promptUser(
+   question: string,
+   io?: PromptIO,
+): Promise<string>;
+```
+
+`io` is an injectable interface for testing:
+
+```ts
+interface PromptIO {
+   ask: (question: string) => Promise<string>;
+}
+```
+
+Defaults to readline on `process.stdin`/`process.stdout`.
+
+### `runDbInit`
+
+**File:** `run-db-init.function.ts`
+
+Creates the `.kbdb` directory scaffold directly on disk
+without requiring a running worker daemon. Replaces
+the deprecated `runInit` for the `kbdb db init`
+subcommand.
+
+```ts
+async function runDbInit(
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+Output on success: JSON `{ "path": "...", "created": true }`.
+
+### `runDbMigrate`
+
+**File:** `run-db-migrate.function.ts`
+
+Checks the database version and runs pending migrations
+when needed. Successor to the deprecated `runMigrate`
+for the `kbdb db migrate` subcommand.
+
+```ts
+async function runDbMigrate(
+   client: MigrateClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+Calls `client.migrateDatabase(dbDir)` after resolving
+the database directory from options.
+
+### `runSkillLearn`
+
+**File:** `run-skill-learn.function.ts`
+
+Creates a new skill definition in the knowledge base.
+Reads the skill body from the file path in
+`options.body` (or stdin when `options.body` is `-`),
+constructs the skill JSON, and adds it as a section
+with `sectionType: 'skill'`.
+
+```ts
+async function runSkillLearn(
+   client: SkillLearnClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+| Parameter         | Source          | Required |
+|-------------------|-----------------|----------|
+| `options.name`    | `--name`        | yes      |
+| `options.body`    | `--body`        | yes      |
+| `options.description` | `--description` | no  |
+
+Output: JSON `{ "kbid": "...", "name": "...",
+"arguments": ["argName", ...] }`.
+
+### `runSkillList`
+
+**File:** `run-skill-list.function.ts`
+
+Lists all skill sections stored in the knowledge base.
+
+```ts
+async function runSkillList(
+   client: SkillListClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+Calls `client.listByType('skill')`. Output: JSON array
+of `{ kbid, name, description, argumentCount }`.
+
+### `runSkillGet`
+
+**File:** `run-skill-get.function.ts`
+
+Retrieves a single skill by name or kbid.
+
+```ts
+async function runSkillGet(
+   client: SkillGetClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+The name-or-kbid argument is taken from `options.args[0]`.
+Output: JSON `SkillDefinition` with `kbid` field.
+
+### `runSkillDelete`
+
+**File:** `run-skill-delete.function.ts`
+
+Removes a skill section from the knowledge base.
+
+```ts
+async function runSkillDelete(
+   client: SkillDeleteClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+The kbid argument is taken from `options.args[0]`.
+Calls `client.removeSection(kbid)`. Output: JSON
+`{ "kbid": "...", "removed": true }`.
+
+### `runAgentCreate`
+
+**File:** `run-agent-create.function.ts`
+
+Creates a new agent document with a persona and
+ordered skill references. Reads the persona from the
+file path in `options.persona` (or stdin when `-`),
+validates the skill kbids from `options.skills`, and
+creates the agent document manifest.
+
+```ts
+async function runAgentCreate(
+   client: AgentCreateClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+| Parameter           | Source      | Required |
+|---------------------|-------------|----------|
+| `options.name`      | `--name`    | yes      |
+| `options.persona`   | `--persona` | yes      |
+| `options.skills`    | `--skills`  | yes      |
+| `options.description` | `--description` | no |
+
+Output: JSON `{ "docid": "agent-...", "name": "...",
+"skills": [...] }`.
+
+### `runAgentList`
+
+**File:** `run-agent-list.function.ts`
+
+Lists all agent documents stored in the knowledge base.
+
+```ts
+async function runAgentList(
+   client: AgentListClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+Calls `client.listDocumentsByType('agent')`. Output:
+JSON array of `{ docid, name, description, skillCount }`.
+
+### `runAgentGet`
+
+**File:** `run-agent-get.function.ts`
+
+Retrieves a single agent by document ID, with resolved
+skill definitions.
+
+```ts
+async function runAgentGet(
+   client: AgentGetClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+The docid argument is taken from `options.args[0]`.
+Output: JSON `AgentDefinition` with resolved skills.
+
+### `runAgentDelete`
+
+**File:** `run-agent-delete.function.ts`
+
+Removes an agent document manifest. The skill sections
+referenced by the agent are not deleted.
+
+```ts
+async function runAgentDelete(
+   client: AgentDeleteClient,
+   options: CliOptions,
+): Promise<CommandResult>;
+```
+
+The docid argument is taken from `options.args[0]`.
+Output: JSON `{ "docid": "...", "removed": true }`.
+
+## Testing
+
+Each function has a `.spec.ts` at the module root:
+
+```
+src/shared/cli/
+├── run-cli.spec.ts
+├── dispatch-command.spec.ts
+├── parse-args.spec.ts
+├── find-db.spec.ts
+├── run-init.spec.ts
+├── run-migrate.spec.ts
+├── run-db-init.spec.ts
+├── run-db-migrate.spec.ts
+├── run-learn.spec.ts
+├── run-unlearn.spec.ts
+├── run-search.spec.ts
+├── run-content.spec.ts
+├── run-check.spec.ts
+├── run-gc.spec.ts
+├── run-rebuild.spec.ts
+├── run-skill-learn.spec.ts
+├── run-skill-list.spec.ts
+├── run-skill-get.spec.ts
+├── run-skill-delete.spec.ts
+├── run-agent-create.spec.ts
+├── run-agent-list.spec.ts
+├── run-agent-get.spec.ts
+├── run-agent-delete.spec.ts
+├── ensure-db.spec.ts
+├── format-output.spec.ts
+├── error-to-message.spec.ts
+├── is-stdin-tty.spec.ts
+└── prompt-user.spec.ts
+```