@aiaiai-pt/martha-cli 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -2,12 +2,39 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [Unreleased]
+
+### Changed — 0.5.1 CLI onboarding feedback
+- `martha init` now defaults to the local preset; the hosted Martha cloud profile remains available through explicit `--preset cloud` and uses `keycloak.frank.nomadriver.co`.
+- CLI version output now reads `martha-cli/package.json` instead of a second hardcoded literal.
+- `martha agents create` exposes `--system-prompt` as the primary inline flag and keeps `--prompt` as a compatibility alias.
+- CLI docs and bundled agent skill now explain explicit customer profile setup, `system_prompt`, and the normal chat-client agent grant-as-tool path.
+
+### Added — #407 connections command (service-account Drive auth)
+- `martha connections create|list|update|test|delete` — manage Vault-backed integration connections from the CLI (previously admin-UI / raw-curl only). `create` mirrors `POST /api/admin/connections`; `update` mirrors `PUT`.
+- Service-account Google Drive: `martha connections create --integration google_drive --auth-type service_account --credential-value @sa-key.json --config '{"subject":"...","scopes":[...]}'` reads enterprise Shared Drives without CASA (#407). The SA key shape (`type`, `client_email`) is validated before submit; `--credential-value` accepts `@file` / `-` (stdin) / literal.
+- **SA key rotation** (#407 key-rotation story): `martha connections update <id> --credential-value @new-sa.json` rotates the key in Vault in place and drops the cached SA token so the new key takes effect immediately (no ~1h staleness window).
+- OAuth2 connections are rejected with a clear error (they need interactive browser consent — use the admin UI).
+
+### Added — #372 PR5 inbound Drive folder sync
+- `document-sync reconcile-tree --source <id> | --all [--dry-run]` — backfills the collection tree from a Google Drive source's folder hierarchy. Stamps `drive_folder_id` on existing collections matching `(parent, name)` and creates sub-collections for unmapped Drive folders. Runs server-side against the source's live OAuth token; idempotent on re-run. `--dry-run` previews link/create/skip counts without writing.
+
+## [0.5.0] — 2026-05-20
+
+### Added — #372 PR4 collection-hierarchy CLI parity
+- `documents collections --tree` renders the parent → child hierarchy as ASCII, mirroring the admin tree UX from #372 PR3.
+- `documents create-collection --parent <slug-or-id>` creates a sub-collection under the named parent. Same slug/name/UUID resolution the agent uses.
+- `documents move-collection <id> --parent <slug-or-id> | --root` moves a collection atomically. Cycle prevention is server-side; CLI rejects self-as-parent eagerly.
+- `clients grant <c> function <fn> --collection <slug-or-id>` and the matching `clients revoke ... --collection`. Scoped grants only apply to functions (#372 PR2 cascade); passing `--collection` to a workflow or agent grant is a clean Validation error.
+- `agents add-function <a> <fn> --collection <slug-or-id>` and `agents remove-function <a> <fn> --collection` likewise. Omit the flag to target the root grant (`collection_id IS NULL` per the allowlist semantics).
+- Shared `lib/collections.ts:resolveCollectionIdForGrant` resolves UUID, slug, or name with a single `GET /api/admin/collections` round-trip.
+
 ## [0.3.0] — 2026-05-10
 
 First-run UX for third-party developers and agent runtimes.
 
 ### Added
-- `martha init` — interactive wizard that writes a profile to `~/.martha/config.yaml`. Two presets: `cloud` (martha.nomadriver.co + auth.nomadriver.co) and `local` (localhost:8080 + 8180). Idempotent with `--force`; rejects overwrites without it.
+- `martha init` — interactive wizard that writes a profile to `~/.martha/config.yaml`. Two presets: `cloud` (martha.nomadriver.co + keycloak.frank.nomadriver.co) and `local` (localhost:8080 + 8180). Idempotent with `--force`; rejects overwrites without it.
 - `martha doctor` — five-check diagnostic: API health, API/CLI version skew (via the new `GET /api/version` endpoint), Keycloak OIDC discovery, stored token validity, authenticated request. Exits non-zero only on FAIL, not WARN.
 - `martha skill` — prints the bundled `SKILL.md` to stdout. Agent runtimes that don't read filesystems by convention can now seed prompt context with `npx -y @aiaiai-pt/martha-cli@0.3.0 skill | head -200`.
 

package/README.md

@@ -15,7 +15,7 @@ npx -y @aiaiai-pt/martha-cli@latest --help
 Pin a version when calling from CI or agent runtimes:
 
 ```bash
-npx -y @aiaiai-pt/martha-cli@0.2.0 agents list --json
+npx -y @aiaiai-pt/martha-cli@0.5.1 agents list --json
 ```
 
 ### Install globally
@@ -31,9 +31,12 @@ Requires Node.js >= 22.
 
 ```bash
 # 1. Configure a profile — writes ~/.martha/config.yaml
-martha init                       # interactive (defaults to cloud preset)
-martha init --preset local        # localhost dev stack
-martha init --no-interactive --name staging --api-url https://...   # scripted
+martha init                       # interactive, local preset by default
+martha init --preset cloud        # martha.nomadriver.co + keycloak.frank.nomadriver.co
+martha init --no-interactive --name acme \
+  --api-url https://martha.acme.example \
+  --keycloak-url https://auth.acme.example \
+  --keycloak-realm acme           # scripted customer profile
 
 # 2. Authenticate
 martha auth login                 # browser flow (PKCE)
@@ -56,15 +59,19 @@ Full command reference: `martha --help` (or any subcommand `--help`).
 Profiles live at `~/.martha/config.yaml`. Each profile defines:
 
 ```yaml
-current_profile: default
+current_profile: local
 profiles:
-  default:
-    api_url: https://martha.nomadriver.co
-    keycloak_url: https://auth.nomadriver.co
+  local:
+    api_url: http://localhost:8080
+    keycloak_url: http://localhost:8180
     keycloak_realm: frank
     auth_type: oidc
 ```
 
+Install does not create or mutate `~/.martha/config.yaml`. Run `martha init`
+or set `MARTHA_API_URL`, `MARTHA_KEYCLOAK_URL`, and
+`MARTHA_KEYCLOAK_REALM` explicitly for your deployment.
+
 Override per-command:
 
 ```bash
@@ -102,12 +109,32 @@ martha skill
 npx -y @aiaiai-pt/martha-cli@latest skill | head -200
 ```
 
+Agent YAML should use `system_prompt` for the durable agent instruction. To
+make an agent callable from a chat client, grant the agent to that client; the
+chat model will call it as a tool:
+
+```yaml
+kind: Agent
+name: support-bot
+system_prompt: You help customers resolve support tickets.
+llm_config:
+  provider: anthropic
+  model: claude-sonnet-4-6
+loop_config:
+  max_iterations: 10
+```
+
+```bash
+martha definitions apply -f support-bot.yaml --yes
+martha clients grant web-chat agent support-bot
+```
+
 ## Stability
 
 `0.x` releases may change CLI flags or JSON output between minor versions. Pin a version in CI/agent contexts:
 
 ```bash
-npx -y @aiaiai-pt/martha-cli@0.3.0 ...
+npx -y @aiaiai-pt/martha-cli@0.5.1 ...
 ```
 
 `1.0.0` will commit to a stable contract — see the [tracking issue](https://github.com/westeuropeco/martha/issues/292).