@theokit/cli 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- `theokit db` subcommand wrapping drizzle-kit (Plan `usetheo-orm-v1` Phase 6.5). Subcommands: `generate`, `migrate`, `studio`, `push`, `export-schema`, `check-schema-drift`. Schema commands consume `orm.config.ts` (default-exports `{ schema }`) and invoke `@theokit/orm/schema-export` to emit JSON Schema 7 per entity to `.theokit/schema/{entity}.schema.json`. `check-schema-drift` diffs fresh vs committed schemas and exits 1 on drift — wires into CI as a polyglot-safety gate.
+
+## 2.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @theokit/sdk@1.3.0
+  - @theokit/acp@2.0.0
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @theokit/sdk@1.2.0
+  - @theokit/acp@1.0.0
+
+## [Unreleased]
+
+### Added (`theokit tasks` — observable async work registry, ADRs D361-D374)
+
+- New top-level subcommand `theokit tasks {list|inspect|cancel}` reads the
+  `JsonFileTaskStore` at `$THEOKIT_HOME/tasks/` (fallback: `cwd/.theokit/tasks`).
+  Reports CLI exit codes: 0 success, 2 permission/IO, 3 invalid id grammar,
+  4 task not found.
+- `theokit tasks list [--state S] [--kind K] [--json]` — table or JSON view.
+- `theokit tasks inspect <id> [--json]` — full handle dump.
+- `theokit tasks cancel <id> [--reason R]` — cross-process best-effort cancel via
+  the `cancelRequested` flag on the JSON-backed handle. The owning Node process
+  (the one that submitted the task) honors the flag at the next checkpoint
+  (EC-7). Queued tasks transition directly to `cancelled`. Terminal tasks
+  print `task already terminal` and exit 0.
+- 12 unit tests under `tests/commands/tasks.test.ts` covering fresh-install
+  ENOENT (EC-6), invalid id grammar, not-found, and the 3 cancel paths.
+
+### Added (`theokit acp` — ACP server adapter, ADRs D349-D360)
+
+- New top-level subcommand `theokit acp` launches a stdio ACP server pointing at
+  the entry file's default-exported `SDKAgent` or factory. Used by Zed,
+  Cursor, Claude Desktop, and any [Agent Client Protocol](https://agentclientprotocol.com)
+  host.
+- `--entry <path>` reuses the same resolver as `theokit dev` (D357). Default:
+  `src/index.ts` or `package.main`.
+- `--permission ask|auto|deny` controls tool gate (default `ask`). `--trusted-tools`
+  bypass list. `--permission-timeout-ms` overrides the 60 s default (EC-2 absorbed).
+- CJS/ESM interop fallback (`mod.default ?? mod`) so consumers using
+  `module.exports = factory` work without contortions (EC-4).
+- `@theokit/acp` listed as an OPTIONAL peer dependency — install only when you
+  need the subcommand: `npm i @theokit/acp`.
+- 4 new tests in `tests/commands/acp.test.ts` covering entry resolution, default
+  export fallback, permission flag validation.
+
+### Added (Roadmap v1.4 #5 — `theokit setup gworkspace`, ADRs D340-D348)
+
+- New top-level subcommand `theokit setup <domain>` (ADR D346) with `gworkspace`
+  as the first concrete domain. Future domains follow the same pattern.
+- `packages/cli/src/commands/setup.ts` + `packages/cli/src/setup/gworkspace.ts` —
+  walkthrough that validates `~/.google-mcp/credentials.json` BEFORE delegating
+  to upstream `npx google-workspace-mcp setup` + `accounts add`.
+- EC-1 (MUST FIX): rejects Web-type OAuth client up-front with actionable error.
+- EC-2: rejects malformed JSON with parse-error message.
+- EC-3: `--probe` mode caps each upstream call at 10s.
+- Path-traversal guard on `--credentials-path` (D80 pattern).
+- 8 new tests in `tests/setup/` (credentials-check + dispatch).
+
+### Added (T0.1 — workspace scaffolding, Adoption Roadmap #1)
+
+- New workspace package `@theokit/cli` — developer CLI for `@theokit/sdk`.
+- `bin: theokit` registered; executable shim at `src/bin/theokit.ts`.
+- Programmatic API: `main(argv): Promise<number>` returns exit code.
+- Build-time constants `SDK_VERSION` / `CLI_VERSION` injected via tsup
+  `define` (EC-L fix — never `workspace:*` in scaffolded projects).
+- `"files": ["dist", "templates", "README.md", ...]` in package.json
+  (EC-C MUST FIX — ensures templates ship in the published tarball).
+- Smoke tests + tarball-contents guard.
+
+Subcommand surface (`init`, `dev`, `inspect`, `eval`) ships in T1.1-T5.1.

package/README.md

@@ -0,0 +1,126 @@
+# @theokit/cli — `theokit`
+
+Developer CLI for `@theokit/sdk`. Four subcommands at v1: `init`, `dev`,
+`inspect`, `eval`. Adoption Roadmap #1.
+
+## Install
+
+```bash
+# One-shot scaffold via npx (recommended for first use):
+npx @theokit/cli init my-bot
+
+# Or install globally:
+pnpm add -g @theokit/cli
+theokit --help
+```
+
+## `theokit init <project-name>`
+
+Scaffold a new agent project from a bundled template.
+
+```bash
+theokit init my-bot --template minimal
+theokit init local-rag --template ollama-local
+theokit init my-bot-tg --template telegram-bot
+```
+
+**Templates:**
+
+- `minimal` — smallest possible Agent.create + send + stream.
+- `ollama-local` — 100% local via Ollama (no remote API key).
+- `telegram-bot` — Telegram bot via `@theokit/gateway` + grammy.
+
+**Flags:**
+
+- `-t, --template <name>` — template to use (prompts if omitted).
+- `-f, --force` — overwrite non-empty destination.
+- `-y, --yes` — skip prompts (CI mode).
+
+## `theokit dev`
+
+Run your agent's entry point under `tsx --watch`.
+
+```bash
+theokit dev                      # auto-detects src/index.ts or package.main
+theokit dev --entry src/bot.ts   # explicit entry
+theokit dev --env .env.local     # custom env file (default: .env)
+```
+
+## `theokit inspect`
+
+List what the SDK sees: builtin providers, embedding adapters, gateway
+adapters, discovered plugins.
+
+```bash
+theokit inspect
+theokit inspect --json                 # machine-readable
+theokit inspect --filter providers     # narrow to one kind
+```
+
+## `theokit eval`
+
+Run a `eval.config.{ts,mjs}` against a real LLM and emit a markdown
+report.
+
+```bash
+theokit eval                              # ./eval.config.ts → ./eval-report.md
+theokit eval --config my-eval.ts --output reports/run1.md
+```
+
+**Example `eval.config.ts`:**
+
+```ts
+import type { EvalConfig } from "@theokit/cli";
+
+export default {
+  dataset: [
+    { input: "Say hello in one word.", expected: "hello" },
+    { input: "What is 2+2?", expected: "4" },
+  ],
+  scorers: [
+    {
+      name: "contains-expected",
+      score: (output, expected) =>
+        typeof expected === "string" && output.toLowerCase().includes(expected.toLowerCase())
+          ? { score: 1 }
+          : { score: 0, reason: `expected "${expected}"` },
+    },
+  ],
+  agent: {
+    apiKey: process.env.THEOKIT_API_KEY ?? "local",
+    model: { id: "ollama/llama3.2:3b" },
+    local: { cwd: process.cwd() },
+  },
+} satisfies EvalConfig;
+```
+
+The eval runner v1 wraps `Agent.batch` (ADR D134); when Roadmap #2
+ships, internals swap to `Eval.run` — your config keeps working.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Unknown error |
+| 2 | User error (bad flags, validation failure, etc.) |
+
+## Architecture
+
+See ADRs D193-D201 in `.claude/knowledge-base/adrs/`:
+
+- D193: separate workspace package
+- D194: commander routing
+- D195: bin name `theokit`
+- D196: bundled templates (offline-friendly)
+- D197: `dev` via `tsx --watch`
+- D198: `inspect` is read-only
+- D199: `eval` v1 wraps `Agent.batch`
+- D200: 3 initial templates
+- D201: `Theokit.inspect.*` public API
+
+## Requirements
+
+- Node 22.12+.
+- pnpm (recommended) or npm. Templates use pnpm scripts; npm/yarn
+  users can manually translate.