@dikolab/kbdb 0.5.0 → 0.6.1

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

@@ -1,809 +0,0 @@
-# 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, configures the
-log level from `-v`/`-vv`/`-vvv` or `KBDB_LOG_LEVEL`,
-resolves non-interactive mode from `--non-interactive`
-or `KBDB_NON_INTERACTIVE` before dispatching commands,
-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   |
-| `worker-stop`    | `runWorkerStop(dbDir)`           |
-| `worker-restart` | `runWorkerRestart(dbDir)`        |
-| *(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 & RecallClient & ContentClient &
-CheckClient & GcClient & RebuildClient & StatusClient &
-ExportClient & SkillClient & AgentClient`).
-
-| Command        | Handler                          |
-|----------------|----------------------------------|
-| `learn`        | `runLearn(client, options, io)`  |
-| `export`       | `runExport(client, options)`     |
-| `unlearn`      | `runUnlearn(client, options)`    |
-| `search`       | `runSearch(client, options)`     |
-| `recall`       | `runRecall(client, options)`     |
-| `content`      | `runContent(client, options)`    |
-| `check`        | `runCheck(client, options)`      |
-| `gc`           | `runGc(client, options)`         |
-| `status`       | `runStatus(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`. Prints the
-version string and exits for `--version`.
-
-`-v` maps to `--verbose` (log level WARNING), not to
-`--version`. Use `--version` (long form only) to print
-the version. `-vv` sets log level INFO; `-vvv` sets
-DEBUG. The resolved level is stored in
-`CliOptions.logLevel`.
-
-**Compound command handling**: when the first positional
-argument is `db`, `skill`, `agent`, or `worker`, 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`   |
-| `worker`         | `stop`            | `worker-stop`    |
-| `worker`         | `restart`         | `worker-restart` |
-
-**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 |
-| `--non-interactive` | `nonInteractive` | Suppress prompts  |
-
-### `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`.
-- `--tags <t,...>` attaches comma-separated tags for
-  scoping and filtering.
-- `--replace` enables supersession by source key:
-  if a section with the same source key exists, the
-  old section is replaced.
-- Returns a `LearnResult[]` with one record per file
-  processed. Each result includes `superseded` (kbid
-  of replaced section or `null`), `warnings` (e.g.
-  `"heading_missing"`), and `near_duplicates`.
-
-### `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)`.
-
-### `runRecall`
-
-**File:** `run-recall.function.ts`
-
-Retrieves full content and progressive context for one
-or more sections by kbid.
-
-```ts
-async function runRecall(
-   client: RecallClient,
-   options: CliOptions,
-): Promise<CommandResult>;
-```
-
-`RecallClient` interface:
-
-```ts
-interface RecallClient {
-   recall(
-      params: RecallParams,
-   ): Promise<RecallResult | RecallResult[]>;
-}
-```
-
-Takes kbid(s) from `options.args` and depth from
-`options.depth` (default 0, clamped 0-3). When a
-single kbid is provided, returns a `RecallResult`
-JSON object. When multiple kbids are provided, returns
-a `RecallResult[]` JSON array.
-
-### `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()`.
-
-### `runExport`
-
-**File:** `run-export.function.ts`
-
-Exports the knowledge base as a self-contained
-directory snapshot for backup or versioning.
-
-```ts
-async function runExport(
-   client: ExportClient,
-   options: CliOptions,
-): Promise<CommandResult>;
-```
-
-Copies sections, documents, and catalog (no indexes
--- they are rebuildable via `rebuild`). The export
-destination defaults to `./kbdb-export/` and can be
-overridden via `options.args[0]`.
-
-Output: JSON `{ "path": "...",
-"sections_exported": number,
-"documents_exported": number,
-"elapsed_ms": number }`.
-
-### `runStatus`
-
-**File:** `run-status.function.ts`
-
-Retrieves the database status summary report from the
-worker daemon.
-
-```ts
-async function runStatus(
-   client: StatusClient,
-   options: CliOptions,
-): Promise<unknown>;
-```
-
-`StatusClient` interface:
-
-```ts
-interface StatusClient {
-   dbStatus(): Promise<unknown>;
-}
-```
-
-Delegates to `client.dbStatus()`. The caller is
-responsible for serialising the result and setting
-the process exit code.
-
-### `runWorkerStop`
-
-**File:** `run-worker-stop.function.ts`
-
-Stops the background worker daemon for the current
-database. Discovers the daemon via its PID file and
-sends `SIGTERM`. Returns success when the daemon was
-stopped or was not running.
-
-```ts
-async function runWorkerStop(
-   dbDir: string,
-): Promise<CommandResult>;
-```
-
-Routed directly by `runCli` (not via
-`dispatchCommand`) because the worker-stop command
-does not require a live worker client connection.
-
-### `runWorkerRestart`
-
-**File:** `run-worker-restart.function.ts`
-
-Stops and restarts the background worker daemon.
-Calls `runWorkerStop` internally; the daemon
-auto-spawns on the next CLI command, so restart only
-needs to stop the current instance.
-
-```ts
-async function runWorkerRestart(
-   dbDir: string,
-): Promise<CommandResult>;
-```
-
-Routed directly by `runCli` (not via
-`dispatchCommand`) for the same reason as
-`runWorkerStop`.
-
-### `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`.
-
-### `resolveKbidPrefix`
-
-**File:** `resolve-kbid-prefix.function.ts`
-
-Resolves a short kbid prefix to a full 26-character
-kbid. Scans all section types (`text`, `code`, `image`)
-for kbids matching the prefix and returns the full
-identifier when exactly one match exists. Full-length
-identifiers (>= 26 chars) are returned as-is. Throws
-when the prefix is ambiguous (multiple matches) or
-unrecognized (no matches).
-
-```ts
-async function resolveKbidPrefix(
-   prefix: string,
-   client: PrefixResolver,
-): Promise<string>;
-```
-
-`PrefixResolver` interface:
-
-```ts
-interface PrefixResolver {
-   listByType(
-      sectionType: string,
-   ): Promise<readonly { kbid: string }[]>;
-}
-```
-
-### `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-export.spec.ts
-├── run-unlearn.spec.ts
-├── run-search.spec.ts
-├── run-recall.spec.ts
-├── run-content.spec.ts
-├── run-status.spec.ts
-├── run-check.spec.ts
-├── run-gc.spec.ts
-├── run-rebuild.spec.ts
-├── run-worker-stop.spec.ts
-├── run-worker-restart.spec.ts
-├── resolve-kbid-prefix.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
-```