baller-maester 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+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).
+
+## [0.1.0] - 2026-05-13
+
+### Added
+- **Pretty CLI** styling layer — themed colors (truecolor → 256 → 16 → no-color downgrade ladder), Unicode glyph catalog with ASCII fallbacks, leveled logger with `--verbose`, `--quiet`, `--json` modes, panel/box rendering (light, heavy, rounded), table rendering, and width-aware breakpoints (tiny / compact / default).
+- **Citadel initialization** flow (`maester init`) — interactive walkthrough for registering remote git repositories as sources, with an optional `includes` step per source, secret-guarded env-var-name validation, optional destination overrides, idempotent `.gitignore` updates, and an idempotent `maester:sync` script entry in `package.json` when present.
+- **Maester configuration** flow (`maester publish`) — interactive walkthrough that writes a `maester.yaml` publish manifest at the repo root, including optional descriptions, categories, and tags per entry, plus a README.md suggestion when one exists.
+- **Maester sync** (`maester sync [names...]`) — single-shot sync of every (or scoped) configured source using partial-clone + sparse-checkout, with per-source progress, atomic destination promotion, `.maester-source.json` provenance markers, destination-clobber guard, and `--json` NDJSON output. Continues past individual source failures; non-zero exit if any failed. Each source is either **manifest-driven** (the remote publishes its own `maester.yaml`) or **includes-driven** (the citadel declares an `includes` list on the source); both modes are processed by the same command. Includes-driven sources emit a `no-matches` warning when their includes resolve to zero files at the resolved ref.
+- **CLI banner** — pre-rendered figlet specimen with full + compact variants. Shown only on `--help`, `--version`, and the first-run welcome screen; suppressed below 40 cells and on non-TTY output. Opt-out via `--no-welcome` or `MAESTER_NO_WELCOME=1`.
+- **Citadel status** (`maester status [names...]`) — read-only freshness check that reports each configured source as `up-to-date`, `behind`, or `failed` using a three-signal probe (never-synced, remote-ref-advanced, manifest-changed). Behind-aware exit codes (`0` / `1` / `2`), `--json` NDJSON output, and per-source scoping. Reuses sync's auth and provenance machinery without mutating the working tree.
+- **Document state tagging** — every materialized citadel file carries an inline `state: draft | canon` declared at the source. Markdown frontmatter, HTML comments, top-level YAML/JSON keys, and first-line `state:` for plain text are all supported. Resolution is inline > matching rule (maester-config or citadel-includes) > default (`draft`). Per-source state breakdown appears in sync output (human + `--json`); a `--verbose` listing names the source-of-truth for each file; an informational warning surfaces when inline state disagrees with a rule.
+- **Grand Maester agent skill** — opt-in installer that drops citadel-aware, state-aware, freshness-aware instructions into agent-specific locations: `.claude/skills/grand-maester/SKILL.md` plus a managed `maester` key in `.claude/settings.json` (Claude Code), `AGENTS.md` at the repo root (Codex CLI and a generic-fallback target dedup to the same file), and `.cursor/rules/grand-maester.mdc` (Cursor). Standalone CLI: `maester skill install [--target id]`, `maester skill upgrade [--check]`, `maester skill add-target <id>`, `maester skill status`. Claude Code receives a `PreToolUse` hook that calls `maester skill runtime preread`, which path-scopes to citadel reads and runs `maester status` only when needed, with a debounced cache at `.maester/.skill-cache.json` (TTL configurable via `MAESTER_SKILL_STATUS_TTL`, default 300s). Offered as a recommended opt-in step at the end of citadel-init. Every installed artifact carries an idempotent managed-region marker; upgrades preserve user content outside it.
+- **Citadel YAML schema v1** — top-level `sources:` array. Each entry is a `Source`; the optional `includes` field decides the mode.
+- **CI/CD** — GitHub Actions `ci.yml` matrix (Node 24 + 22) and `release.yml` tag-triggered `npm publish --provenance` via OIDC.
+- Public library exports (`src/index.ts`): `loadCitadelConfig`, `loadMaesterConfig`, `runSync`, schema types (`CitadelConfig`, `Source`, `AuthRef`, `MaesterConfig`, `PublishedDocument`), and typed error classes.
+
+### 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.
+- 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baller Software
+
+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,142 @@
+# Maester
+
+> Aggregate documentation from many sources into one central knowledge home for developers and AI agents.
+
+[![CI](https://github.com/baller-software/maester/actions/workflows/ci.yml/badge.svg)](https://github.com/baller-software/maester/actions/workflows/ci.yml)
+
+Maester is a Node CLI and helper library for teams whose knowledge is spread across multiple sources — Git repositories today, with hosted document tools and web sources planned next. A **citadel** gathers content from many remote git repositories into a structured knowledge base that is easier to read, update, and reason over.
+
+A repo you own can publish a `maester.yaml` manifest declaring what it offers — the citadel consumes whatever the manifest publishes. For sources you do not own (public third-party repos, vendor docs you have read access to), the citadel can take ownership of the filter set by declaring an `includes` list directly on the source — see below.
+
+## Two roles, two files
+
+Maester defines two repository roles, each declared by a single committed YAML file at the directory where the CLI was invoked:
+
+| Role     | File           | Created by         |
+|----------|----------------|--------------------|
+| citadel  | `citadel.yaml` | `maester init`     |
+| maester  | `maester.yaml` | `maester publish`  |
+
+A directory can hold one role, the other, or both. There is at most one of each per directory.
+
+### 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`).
+
+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.
+
+## Quickstart
+
+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
+```
+
+In a directory that *publishes* docs to other citadels:
+
+```sh
+npx maester publish      # maester manifest walkthrough — creates ./maester.yaml
+```
+
+## Pulling from sources you don't own
+
+Every entry in `citadel.yaml` is a **source** — a remote git repo. Each source is one of two modes, decided implicitly by whether you declare an `includes` list on it:
+
+- **Manifest-driven** (no `includes`): the remote repo publishes its own `maester.yaml` declaring what it offers. The remote owns the publish surface; the citadel just consumes it. Use this for repos you own.
+- **Includes-driven** (`includes` set): the citadel declares the filter set directly. The remote `maester.yaml` (if any) is ignored. Use this for public third-party repos, vendor docs you have read access to but cannot modify, and any other source that does not publish a manifest.
+
+```yaml
+# citadel.yaml (excerpt)
+schemaVersion: 1
+
+sources:
+  # Manifest-driven — the remote publishes its own maester.yaml.
+  - name: design-system
+    url: https://github.com/example-org/design-system.git
+
+  # Includes-driven — the citadel owns the filter set.
+  - name: react-docs
+    url: https://github.com/facebook/react.git
+    ref: main
+    includes:
+      - docs/**/*.md
+      - README.md
+    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.
+
+## Prerequisites
+
+- **Node.js** ≥ 24 LTS
+- **git** ≥ 2.27 (older versions fall back automatically to `--depth=1` clones)
+- **pnpm** 9.x for development (consumers can use any package manager)
+
+## Local Development Setup
+
+```sh
+git clone https://github.com/<org>/maester.git
+cd maester
+pnpm install
+pnpm run build
+pnpm run test
+```
+
+## Available Scripts
+
+| Script | Purpose |
+|---|---|
+| `pnpm run build` | Bundle CLI + library with `tsup` |
+| `pnpm run dev` | Watch mode build |
+| `pnpm run test` | Run Vitest unit + e2e tests once |
+| `pnpm run test:watch` | Watch mode tests |
+| `pnpm run lint` | Lint with Biome |
+| `pnpm run lint:fix` | Lint and auto-fix |
+| `pnpm run typecheck` | `tsc --noEmit` |
+| `pnpm run format` | Format with Biome |
+| `pnpm run prepublishOnly` | Full quality gate (lint + typecheck + test + build) |
+
+## Try the CLI Locally
+
+```sh
+pnpm link --global
+cd /tmp/my-scratch-repo
+git init
+maester
+```
+
+## Environment Variables
+
+Maester reads tokens only at runtime; nothing secret is ever written to disk. Per-source token env-var **names** are stored in `citadel.yaml`; the values live in your shell, `.env` loader, or CI secret manager.
+
+| Variable | Purpose |
+|---|---|
+| `<user-defined>` | Each source with `auth.type: "token"` reads from the env-var name in its config (e.g. `MAESTER_DOCS_TOKEN`). |
+| `NO_COLOR` | Disable ANSI color. Standard. |
+| `FORCE_COLOR` | Force color (`0`–`3`). Standard. |
+| `MAESTER_THEME` | `light` or `dark` to override automatic detection. |
+| `MAESTER_NO_MOTION` | Replace spinners with static elapsed counters. |
+| `MAESTER_NO_WELCOME` | Suppress the first-run welcome banner. |
+
+## Project Structure
+
+```
+src/
+├── cli/        Commander dispatch + interactive walkthroughs
+├── core/       Domain (config, git, sync, auth)
+├── schemas/    Zod schemas for the two YAML configs
+└── ui/         Theme + logger + terminal components
+test/           Vitest unit + e2e tests
+gspec/          Living specifications
+```
+
+## Specifications
+
+This project is built from a living specification under `gspec/`. The product profile, technology stack, visual style guide, development practices, technical architecture, and per-feature PRDs all live there. Changes to behavior should update the relevant spec; see `CLAUDE.md` for the contract.
+
+## License
+
+MIT.

package/bin/maester.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import("../dist/cli/main.js")
+  .then((mod) => mod.run())
+  .catch((err) => {
+    console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    process.exit(1);
+  });

package/dist/cli/main.d.ts

@@ -0,0 +1,4 @@
+declare function run(argv?: readonly string[]): Promise<void>;
+declare function runMain(argv?: readonly string[]): Promise<number>;
+
+export { run, runMain };