baller-maester 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.1] - 2026-05-21
+
+### Fixed
+- **Docs and CLI strings now use the correct npm package name.** Every `npx maester ...` invocation has been replaced with `npx baller-maester ...` (or `npx -y baller-maester ...` for automation contexts). `npx` resolves by npm package name and this project publishes as `baller-maester`, so the old form would have failed at the registry. Touches the README, CHANGELOG, every `gspec/` document that named the command, both skill-template content files (freshness-awareness and connector-policy-fallback), the `maester init` outro, the missing-config error messages in the config loader, and the auto-generated `citadel.yaml` / `maester.yaml` header comments.
+- **Grand Maester `PreToolUse` hook command is now actually invokable.** The `.claude/settings.json` block installed by `maester skill install` previously embedded `npx maester skill runtime preread`, which would fail npm-side resolution. Updated to `npx -y baller-maester skill runtime preread` (matching the existing MCP-registration convention). The `-y` flag skips npx's first-run confirmation so the hook does not stall Claude Code's tool-call flow.
+- **Stale docstrings on the MCP registration writers** for Claude Code and Codex CLI claimed the entry embedded `process.argv[1]` rather than `npx maester`; the code has actually emitted `npx -y baller-maester mcp` since 0.4.0. Rewrote both docstrings to match reality.
+
+## [0.4.0] - 2026-05-21
+
+### Added
+- **Traveling Maesters (connectors framework)** — a new `connectors:` array in `citadel.yaml`, sibling to `sources:`, that registers external services as live MCP tools. Maester ships a stdio MCP server (`maester mcp`) built on `@modelcontextprotocol/sdk` that reads the citadel, instantiates every configured connector via the compile-time type registry, and exposes each operation as an MCP tool with a deterministic name (`<connector>__<operation>`, kebab → snake). Per-connector entries declare a `type`, a unique `name`, optional `description`, env-var token auth, and a per-type `config` block; unknown types and per-type config errors are caught at config-load time.
+- **GitLab Issues connector** (`type: gitlab-issues`) — first concrete connector type. Two operations exposed as MCP tools: `list-issues` (filters: state, labels, assignee, milestone, search, page, per_page; clamped to GitLab's documented max of 100) and `get-issue` (by project-scoped iid). Per-type config: `host` (HTTPS only, defaults to `https://gitlab.com`), `project` (path or numeric ID — purely numeric values are treated as IDs; paths are URL-encoded). Self-hosted GitLab instances work identically to gitlab.com. Native `fetch` client over `/api/v4`, no SDK dependency. GitLab HTTP outcomes map onto the framework's bounded error-code set (401/403 → `auth-failed` naming the env var, 404 → `remote-error/not-found`, 429 → `remote-error/rate-limited` with `Retry-After`, 5xx → `remote-error/transport`).
+- **`maester mcp` CLI verb** — runs the stdio MCP server in the current citadel-bearing repo. Validates `citadel.yaml` at startup (all-or-nothing — no partial tool surface); reroutes the project logger to stderr so stdout stays reserved for JSON-RPC frames; exits cleanly when stdio closes.
+- **`maester connector` CLI verb group** — `add` (interactive + non-interactive `--type --name --env-var --config --description` flag form), `remove [name] --yes`, `list`, `refresh` (re-validates `citadel.yaml` and re-runs the per-host MCP registration writer — use after editing `citadel.yaml` by hand), and `exec <name> <operation> [--key value]...` (the framework's P1 fallback dispatch surface for non-MCP agents). All mutating verbs refresh per-host MCP registrations after writing.
+- **Per-host MCP registration writers** — `<repo>/.mcp.json` (Claude Code), `<repo>/.cursor/mcp.json` (Cursor), and `<repo>/.codex/config.toml` (Codex CLI) with a managed `maester` entry that other entries are round-tripped around byte-for-byte. Writes are idempotent; running twice produces byte-identical files. Hooked into Grand Maester skill `install`/`upgrade` and `connector add`/`remove`/`refresh` so the tool surface stays in sync with `citadel.yaml`. All three writers emit the standard MCP-ecosystem convention: `command = "npx"`, `args = ["-y", "baller-maester", "mcp"]` — portable across machines and self-updating on the next `npm publish`. The Codex block additionally carries `cwd = "<absolute-citadel-path>"` because Codex spawns MCP subprocesses with `cwd = /` regardless of which config supplied the entry. Codex picks up `<repo>/.codex/config.toml` on projects marked `trust_level = "trusted"` in the user-global config (verified on Codex CLI v0.132).
+- **Grand Maester connector policy** — installed Grand Maester artifacts (Claude Code, Codex CLI, Cursor) gain a short fixed policy paragraph about reasoning over connector tool output (live data, cite identifiers, treat as point-in-time, watch the freshness verdict). The Generic `AGENTS.md` target gets a parallel paragraph documenting the fallback CLI. Neither artifact enumerates configured connectors — MCP discovery handles that.
+- **Init walkthrough connector step** — `maester init` adds an optional connector-registration loop between source registration and the Grand Maester offer; declining completes init normally with no `connectors` block written.
+
+### Changed
+- `ResolvedAuth` (returned by `src/core/auth/resolver.ts`) now carries the env-var name in its `token` variant: `{ type: "token"; value: string; envVar: string }`. Lets downstream consumers — including the GitLab connector's 401/403 path — surface the env-var name in error messages without re-walking the original `AuthRef`. The `delegated` variant is unchanged. Backwards-compatible for anything that only reads `type` or `value`.
+
+### Dependencies
+- Added `@modelcontextprotocol/sdk`, `zod-to-json-schema`, `@iarna/toml` as direct runtime dependencies (per architecture Gaps 34, 38, 39).
+
 ## [0.3.0] - 2026-05-14
 
 ### Added
@@ -37,5 +63,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Sync orchestration consolidated into a single `src/core/sources/fetcher.ts` (replacing the previously planned per-kind modules). The fetcher branches internally on whether the source declares an `includes` list.
-- **Repo-root detection is now always the current working directory.** `npx maester` (and every subcommand) treats `process.cwd()` as the root unconditionally — the old walk-upward-for-`.git`/`package.json` behavior is removed. `citadel.yaml` and `maester.yaml` always land in the directory where you typed the command, never in an ancestor. An existing config file in an ancestor directory is invisible to the cwd model.
+- **Repo-root detection is now always the current working directory.** `npx baller-maester` (and every subcommand) treats `process.cwd()` as the root unconditionally — the old walk-upward-for-`.git`/`package.json` behavior is removed. `citadel.yaml` and `maester.yaml` always land in the directory where you typed the command, never in an ancestor. An existing config file in an ancestor directory is invisible to the cwd model.
 - Top-level `baseDir` field on `citadel.yaml` (optional). When set, every source whose `destination` is unset is surfaced at `<baseDir>/<source-name>/` instead of `citadel/<source-name>/`. Per-source `destination` overrides always win. Omitting `baseDir` is identical to today's behavior — fully backward compatible. The citadel-init walkthrough prompts for it with `citadel` pre-filled and omits the field from the generated YAML when the default is accepted.

package/README.md

@@ -21,7 +21,7 @@ A directory can hold one role, the other, or both. There is at most one of each
 
 ### Where do the files land?
 
-**Every maester command uses the current working directory as the root.** When you run `npx maester init` from a directory, `citadel.yaml` is created in that exact directory — never in an ancestor. The same goes for `npx maester publish` (writes `maester.yaml` here), `npx maester sync` (reads `citadel.yaml` from here), and the interactive menu (`npx maester`).
+**Every maester command uses the current working directory as the root.** When you run `npx baller-maester init` from a directory, `citadel.yaml` is created in that exact directory — never in an ancestor. The same goes for `npx baller-maester publish` (writes `maester.yaml` here), `npx baller-maester sync` (reads `citadel.yaml` from here), and the interactive menu (`npx baller-maester`).
 
 If you run a maester command from the wrong directory, `cd` to the intended directory and re-run. The CLI does not walk upward to find a project root, so a stray `.git/` or `package.json` in a parent directory will not pull configuration files away from where you typed the command.
 
@@ -30,15 +30,15 @@ If you run a maester command from the wrong directory, `cd` to the intended dire
 In the directory you want to populate with aggregated knowledge:
 
 ```sh
-npx maester              # interactive menu (uses cwd as root)
-npx maester init         # citadel walkthrough — creates ./citadel.yaml
-npx maester sync         # fetch all configured sources — reads ./citadel.yaml
+npx baller-maester              # interactive menu (uses cwd as root)
+npx baller-maester init         # citadel walkthrough — creates ./citadel.yaml
+npx baller-maester sync         # fetch all configured sources — reads ./citadel.yaml
 ```
 
 In a directory that *publishes* docs to other citadels:
 
 ```sh
-npx maester publish      # maester manifest walkthrough — creates ./maester.yaml
+npx baller-maester publish      # maester manifest walkthrough — creates ./maester.yaml
 ```
 
 ## Pulling from sources you don't own
@@ -67,7 +67,7 @@ sources:
     description: Upstream React documentation snapshot.
 ```
 
-`npx maester sync` processes every source in one pass. The trade-off for the includes-driven mode: when the remote repo restructures, the citadel's `includes` may need to be updated. Sync prints a warning when an includes-driven source resolves to zero files so drift is visible.
+`npx baller-maester sync` processes every source in one pass. The trade-off for the includes-driven mode: when the remote repo restructures, the citadel's `includes` may need to be updated. Sync prints a warning when an includes-driven source resolves to zero files so drift is visible.
 
 ## Prerequisites