@knowledge-medium/agent-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Vladyslav Sitalo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @knowledge-medium/agent-cli
+
+`kmagent` — CLI + local HTTP bridge for driving the [Knowledge Medium](https://github.com/stvad/knowledge-medium) app from an agent (Claude, your own scripts, anything that can spawn a child process).
+
+Pairs once with a browser tab over a localhost relay, then forwards JSON commands to a long-poll loop inside the app. The CLI is the agent-facing surface; the bridge is the loopback HTTP server that brokers the connection.
+
+## Install
+
+```bash
+# Global — `kmagent` ends up on your PATH:
+npm install -g @knowledge-medium/agent-cli
+
+# Or per-project, then invoke via npx:
+npm install --save-dev @knowledge-medium/agent-cli
+npx kmagent ping
+```
+
+Requires Node ≥ 24.
+
+## Quick start
+
+```bash
+# 1. Open the app (https://stvad.github.io/knowledge-medium/ by default;
+#    set AGENT_RUNTIME_APP_URL to point at your own deploy).
+# 2. Pair the CLI with the app. The first command prints a URL; open it,
+#    generate a token in the in-app dialog, paste the token back.
+kmagent connect
+
+# 3. Test the connection.
+kmagent ping
+```
+
+After step 2, the token is saved at `~/.config/knowledge-medium/agent-token.json` and reused for every subsequent invocation.
+
+## What you can do
+
+The CLI exposes both *local* commands (pairing, profile management) and *bridge* commands (forwarded to the running app):
+
+| Command | Purpose |
+| --- | --- |
+| `kmagent connect [token]` | Pair the CLI with the app (or save a token directly). |
+| `kmagent disconnect` | Remove the current profile's token. |
+| `kmagent profiles` | List saved CLI token profiles. |
+| `kmagent ping` | Ping the bridge + runtime; print a status summary. |
+| `kmagent status` | Show bridge status (clients, commands). |
+| `kmagent runtime-summary` | Compact agent-oriented runtime context. |
+| `kmagent describe-runtime` | Full or targeted runtime diagnostics (`--guide <id>`, `--storage`, …). |
+| `kmagent sql <mode> <sql> [paramsJson]` | Run SQL (mode: `all\|get\|optional\|execute`). |
+| `kmagent get-block <id>` | Fetch a block. |
+| `kmagent subtree <rootId> [--include-root]` | Fetch a subtree. |
+| `kmagent create-block <json>` | Create a block from a JSON body. |
+| `kmagent update-block <json>` | Update a block from a JSON body. |
+| `kmagent install-extension <file> [label]` | Install a JS extension; `--verify` reports what it contributed. |
+| `kmagent enable-extension <handle>` | Enable / `disable-extension`, `uninstall-extension`. |
+| `kmagent run-action <id> [depsJson]` | Run a registered action by id. |
+| `kmagent eval [--raw] [--file <path>] [--data <path> \| --data-json <json>] <code>` | Run JS in the app (use `return …` to print a value). See [Eval execution scope](#eval-execution-scope) for the bindings available inside the code. |
+| `kmagent reload` | Hard-reload the app tab and wait for it to reconnect. |
+| `kmagent navigate <hash>` | Set `window.location.hash`. |
+| `kmagent types [outDir]` | Write compiled declarations for Knowledge Medium `@/` modules; `--module <spec>` prints one declaration. |
+| `kmagent raw <json>` | Send an arbitrary JSON command envelope to the bridge. |
+
+Run `kmagent <command> --help` for per-command details or `kmagent --help` for the full menu.
+
+## Eval execution scope
+
+`kmagent eval` runs your code inside the app tab, with the runtime context already destructured into the local scope. You do **not** need to dig values out of `window.__omniliner` — the following names are bound for you:
+
+| Name | What it is |
+| --- | --- |
+| `repo` | The live `Repo` (workspace, user, mutate, query, tx, …). |
+| `db` | `repo.db` — the underlying database handle. |
+| `runtime` | The `FacetRuntime`. Prefer `describe-runtime` over reading internal caches. |
+| `safeMode` | `true` when the runtime is paused for safe-mode boot. |
+| `sql(sql, params?, mode?)` | Thin SQL helper, matches `kmagent sql`. |
+| `block(id)` / `getBlock(id)` / `getSubtree(rootId)` | Block accessors. |
+| `createBlock(input)` / `updateBlock(input)` | Block mutators (same shape as the wire commands). |
+| `installExtension(input)` / `setExtensionEnabled(input)` / `uninstallExtension(input)` | Extension lifecycle. |
+| `actions`, `renderers` | Registered actions and block renderers. |
+| `refreshAppRuntime` | Re-run runtime registration (rarely needed). |
+| `React`, `ReactDOM`, `window`, `document` | The app's React + DOM. |
+| `data` | Parsed value from `--data <path>` / `--data-json <json>`, or `undefined` when neither flag was passed. |
+
+Use `return …` to print a value back to the CLI (anything else is silently discarded).
+
+### Passing structured input
+
+For one-off scripts that need a chunk of structured input, the `--data` flag is cleaner than template-embedding JSON in the code string:
+
+```bash
+# Apply logic in one file, input in a sibling JSON file:
+kmagent eval --file apply.js --data plans.json
+
+# Or inline for small payloads:
+kmagent eval --data-json '{"x":1}' 'return data.x'
+```
+
+`--data` reads JSON from a file and parses it; `--data-json` parses the inline argument directly. The parsed value is bound as `data` in the eval scope. The two flags are mutually exclusive.
+
+## Profiles
+
+If you connect to multiple browser profiles or workspaces, name each pairing:
+
+```bash
+kmagent --profile chrome-dev connect
+kmagent --profile firefox-main connect
+
+# Use one explicitly:
+kmagent --profile chrome-dev ping
+
+# Or set the default profile for a shell:
+export AGENT_RUNTIME_PROFILE=chrome-dev
+```
+
+## Type-vending for extension authors
+
+When you're authoring an extension that imports from Knowledge Medium modules (`@/extensions/api.js`, `@/data/api`, `@/components/ui/button.js`, etc.), `kmagent types` writes the app's compiled TypeScript declaration tree so type-aware editors resolve those imports with real signatures:
+
+```bash
+kmagent types agent-extensions/kernel-types
+```
+
+This directory form is the setup path for editors and typecheckers. It copies the published CLI's `dist/kernel-types` snapshot, so it reflects the app source at the time that CLI package was built.
+
+The command prints the `compilerOptions.paths` mapping to add to your extension-authoring `tsconfig.json`, usually:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["agent-extensions/kernel-types/src/*"]
+    }
+  }
+}
+```
+
+Re-run with `--force` after updating the app or CLI.
+
+For quick inspection, print one compiled module declaration to stdout:
+
+```bash
+kmagent types --module '@/extensions/api.js'
+kmagent types --module '@/data/api'
+```
+
+Single-module output is not bundled with its transitive dependencies; use the directory form above for editor/typechecker setup.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `AGENT_RUNTIME_APP_URL` | App URL to pair with. Defaults to the canonical deploy. |
+| `AGENT_RUNTIME_URL` | Bridge URL the CLI talks to. Defaults to `http://127.0.0.1:8787`. |
+| `AGENT_RUNTIME_TOKEN` | One-shot token, skips the persisted profile lookup. |
+| `AGENT_RUNTIME_PROFILE` | Default profile selection for `kmagent <command>`. |
+| `AGENT_RUNTIME_CONFIG_DIR` | Override the config directory (default: `$XDG_CONFIG_HOME/knowledge-medium`). |
+| `AGENT_RUNTIME_BRIDGE_SECRET` | Override the bridge secret (otherwise auto-generated per machine). |
+| `AGENT_RUNTIME_ALLOWED_ORIGINS` | Comma-separated extra origins the bridge will accept connections from. |
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}