chore: initial open source release

Author: rhuanbarreto

.archgate/adrs/ARCH-001-command-structure.md

@@ -0,0 +1,167 @@
+---
+id: ARCH-001
+title: Command Structure
+domain: architecture
+rules: true
+files: ["src/commands/**/*.ts"]
+---
+
+## Context
+
+The CLI needs a consistent pattern for defining and registering commands. As the command surface grows (init, check, adr, mcp, upgrade, clean), the registration mechanism must scale without introducing hidden coupling or making the dependency graph opaque.
+
+**Alternatives considered:**
+
+- **Auto-discovery via `executableDir()`** — Commander.js supports automatic command discovery by scanning a directory for executable files. This eliminates manual imports but hides the dependency graph: adding or removing a command has no type-checked reference, making dead command detection impossible. It also requires each command to be a standalone executable, which prevents in-process testing and forces separate process spawning for every subcommand invocation.
+- **Plugin-based registration** — A plugin system where commands register themselves via a manifest or hook (similar to Oclif or Clipanion). This adds flexibility for third-party extensions but introduces significant complexity for an internal CLI with a known, finite set of commands. The indirection makes it harder to trace which code handles which command.
+- **Single-file command map** — Define all commands in a single file as a map of name-to-handler. Simple but creates a monolithic file that grows with every command, making merge conflicts frequent and readability poor.
+
+The explicit register pattern strikes the right balance: each command owns its registration logic, the entry point makes all commands visible at a glance, and in-process execution enables straightforward testing without process spawning.
+
+## Decision
+
+Commands live in `src/commands/` and export a `register*Command(program)` function. The main entry point (`src/cli.ts`) explicitly imports and calls each register function. Subcommands (e.g., `adr create`, `adr list`) use nested directories with an `index.ts` that composes the subcommand group.
+
+**Key constraints:**
+
+1. **One command per file** — Each `.ts` file in `src/commands/` defines exactly one command (or one command group via its `index.ts`)
+2. **Explicit registration** — Every command must be manually imported and registered in `src/cli.ts`. No auto-discovery.
+3. **Thin commands** — Command files handle I/O only: parse arguments, call engine/helpers, format output. No business logic.
+4. **In-process execution** — Commands run in the same Bun process as the CLI entry point. No child process spawning.
+
+## Do's and Don'ts
+
+### Do
+
+- Export a `register*Command` function from each command module
+- Keep commands thin: parse args, call helpers/engine, format output
+- Use `src/commands/<name>.ts` for top-level commands
+- Use `src/commands/<name>/index.ts` for command groups with subcommands
+- Import the register function explicitly in `src/cli.ts`
+
+### Don't
+
+- Don't put business logic in command files — move it to `src/engine/`, `src/helpers/`, or `src/formats/`
+- Don't use `executableDir()` for command discovery
+- Don't call `.parse()` in command files — the entry point handles parsing
+- Don't create commands that spawn child processes for subcommand execution
+
+## Implementation Pattern
+
+### Good Example
+
+```typescript
+// src/commands/check.ts — thin command that delegates to engine
+import type { Command } from "@commander-js/extra-typings";
+import { loadRuleAdrs } from "../engine/loader";
+import { runChecks } from "../engine/runner";
+import { reportConsole, reportJSON, getExitCode } from "../engine/reporter";
+import { logError } from "../helpers/log";
+
+export function registerCheckCommand(program: Command) {
+  program
+    .command("check")
+    .description("Run automated ADR compliance checks")
+    .option("--json", "Output results as JSON")
+    .option("--staged", "Only check staged files")
+    .action(async (opts) => {
+      const adrs = await loadRuleAdrs();
+      const results = await runChecks(adrs, { staged: opts.staged });
+      if (opts.json) {
+        reportJSON(results);
+      } else {
+        reportConsole(results);
+      }
+      process.exit(getExitCode(results));
+    });
+}
+```
+
+```typescript
+// src/cli.ts — explicit imports make all commands visible
+import { registerCheckCommand } from "./commands/check";
+import { registerInitCommand } from "./commands/init";
+import { registerAdrCommand } from "./commands/adr";
+
+registerInitCommand(program);
+registerCheckCommand(program);
+registerAdrCommand(program);
+```
+
+### Bad Example
+
+```typescript
+// BAD: business logic inside command file
+export function registerCheckCommand(program: Command) {
+  program.command("check").action(async () => {
+    // Business logic should NOT be here
+    const files = await glob("src/**/*.ts");
+    for (const file of files) {
+      const content = await Bun.file(file).text();
+      const violations = content.match(/console\.error/g);
+      // ... complex processing ...
+    }
+  });
+}
+```
+
+### Subcommand Group Pattern
+
+```typescript
+// src/commands/adr/index.ts — composes subcommand group (contains real logic)
+import type { Command } from "@commander-js/extra-typings";
+import { registerAdrCreateCommand } from "./create";
+import { registerAdrListCommand } from "./list";
+import { registerAdrShowCommand } from "./show";
+import { registerAdrUpdateCommand } from "./update";
+
+export function registerAdrCommand(program: Command) {
+  const adr = program
+    .command("adr")
+    .description("Manage Architecture Decision Records");
+
+  registerAdrCreateCommand(adr);
+  registerAdrListCommand(adr);
+  registerAdrShowCommand(adr);
+  registerAdrUpdateCommand(adr);
+}
+```
+
+## Consequences
+
+### Positive
+
+- **In-process execution enables testing** — Commands can be tested by calling `register*Command()` directly, without spawning subprocesses or mocking executables
+- **Explicit imports make dependencies clear** — Opening `src/cli.ts` shows every command the CLI supports. No hidden commands loaded at runtime.
+- **Subcommand nesting is straightforward** — Command groups use the same pattern as top-level commands, with an `index.ts` that composes children
+- **Type-safe registration** — Commander.js `@commander-js/extra-typings` provides full type inference for options and arguments within each register function
+
+### Negative
+
+- **Manual import bookkeeping** — Each new command requires adding an import and registration call in `src/cli.ts`. This is a minor overhead for a CLI with fewer than 15 commands.
+- **No hot-reload of commands** — Adding a new command requires restarting the CLI process. Acceptable for a development tool.
+
+### Risks
+
+- **Stale imports when commands are removed** — If a command file is deleted but its import in `src/cli.ts` is not removed, TypeScript will catch the error at compile time. The `bun run typecheck` step in the validation pipeline prevents this from reaching production.
+- **Command group index.ts confused with barrels** — The `index.ts` files in command group directories (e.g., `src/commands/adr/index.ts`) contain real composition logic, not re-exports. [ARCH-004 — No Barrel Files](./ARCH-004-no-barrel-files.md) explicitly permits `index.ts` files with logic.
+
+## Compliance and Enforcement
+
+### Automated Enforcement
+
+- **Archgate rule** `ARCH-001/register-function-export`: Scans all command files under `src/commands/` (excluding `index.ts` group files) and verifies each exports a `register*Command` function. Severity: `error`.
+- **Archgate rule** `ARCH-001/no-business-logic`: Detects complex data transformation patterns in command files that should be in helpers. Severity: `error`.
+
+### Manual Enforcement
+
+Code reviewers MUST verify:
+
+1. New commands are imported and registered in `src/cli.ts`
+2. Command files delegate to engine/helpers for business logic
+3. Command group `index.ts` files contain composition logic, not just re-exports
+
+## References
+
+- [Commander.js documentation](https://github.com/tj/commander.js)
+- [ARCH-004 — No Barrel Files](./ARCH-004-no-barrel-files.md) — Permits `index.ts` with logic, forbids re-export-only barrels

.archgate/adrs/ARCH-001-command-structure.rules.ts

@@ -0,0 +1,46 @@
+import { defineRules } from "../../src/formats/rules";
+
+export default defineRules({
+  "register-function-export": {
+    description: "Command files must export a register*Command function",
+    async check(ctx) {
+      const files = ctx.scopedFiles.filter((f) => !f.endsWith("index.ts"));
+      const checks = files.map(async (file) => {
+        const content = await ctx.readFile(file);
+        if (!/export\s+function\s+register\w+Command/.test(content)) {
+          ctx.report.violation({
+            message: "Command file must export a register*Command function",
+            file,
+          });
+        }
+      });
+      await Promise.all(checks);
+    },
+  },
+  "no-business-logic": {
+    description: "Command files should not contain business logic patterns",
+    severity: "error",
+    async check(ctx) {
+      const files = ctx.scopedFiles.filter((f) => !f.endsWith("index.ts"));
+      const matches = await Promise.all(
+        files.map((file) =>
+          ctx.grep(
+            file,
+            /\.(parse|match|replace|split)\(.*\).*\.(parse|match|replace|split)\(/
+          )
+        )
+      );
+      for (const fileMatches of matches) {
+        for (const m of fileMatches) {
+          ctx.report.violation({
+            message:
+              "Complex data transformations should be in helpers, not command files",
+            file: m.file,
+            line: m.line,
+            fix: "Move transformation logic to a helper in src/helpers/ or src/formats/",
+          });
+        }
+      }
+    },
+  },
+});

.archgate/adrs/ARCH-002-error-handling.md

@@ -0,0 +1,146 @@
+---
+id: ARCH-002
+title: Error Handling
+domain: architecture
+rules: true
+files: ["src/**/*.ts"]
+---
+
+# Error Handling
+
+## Context
+
+CLI tools must provide clear, actionable error messages without exposing internal details to users. Inconsistent error handling leads to confusing experiences: some errors show stack traces, others silently swallow failures, and exit codes are unpredictable for scripts and CI integrations.
+
+**Alternatives considered:**
+
+- **Try-catch everywhere** — Wrapping every function in try-catch blocks provides fine-grained error control but leads to deeply nested code and often results in errors being caught and swallowed unintentionally. Developers forget to re-throw or log, and errors disappear silently.
+- **Error middleware / centralized handler** — A single `process.on("uncaughtException")` handler catches all unhandled errors. This works for unexpected crashes but cannot distinguish between user errors (invalid input) and bugs (null pointer). All errors get the same treatment, losing the semantic distinction between "you made a mistake" and "we have a bug."
+- **Result types (Either/Result monad)** — Encoding success/failure in return types (e.g., `Result<T, E>`) makes error handling explicit. This is the most type-safe approach but adds significant ceremony for a CLI where most errors are terminal (print message, exit). The overhead is not justified when the error handling strategy is "tell the user and exit."
+
+The three-tier exit code model provides a simple contract that covers all CLI use cases: success, expected failure, and unexpected crash. Combined with `logError()` for consistent formatting, this gives users and CI systems predictable behavior without overengineering.
+
+## Decision
+
+Use three exit codes with clear semantics:
+
+| Exit Code | Meaning          | When to Use                                                                   |
+| --------- | ---------------- | ----------------------------------------------------------------------------- |
+| `0`       | Success          | Operation completed successfully                                              |
+| `1`       | Expected failure | Invalid input, missing config, ADR violations found, operation cannot proceed |
+| `2`       | Internal error   | Bugs, unhandled exceptions, unexpected crashes                                |
+
+**Error output conventions:**
+
+- User-facing errors use `logError()` from `src/helpers/log.ts`, which formats with `styleText("red", ...)` and writes to stderr
+- Actionable suggestions accompany error messages when possible (e.g., "Run `archgate init` to create a governance directory")
+- No stack traces for user-triggered errors (exit code 1)
+- Unexpected errors (exit code 2) may include stack traces when `DEBUG` or `TRACE` environment variables are set
+- All error output goes to stderr, never stdout (stdout is reserved for command output and `--json` results)
+
+## Do's and Don'ts
+
+### Do
+
+- Use `logError()` from `src/helpers/log.ts` for user-facing errors
+- Exit with code 1 for expected failures (missing config, invalid input, violations found)
+- Let unexpected errors crash naturally (exit code 2)
+- Provide actionable suggestions in error messages
+- Write errors to stderr (via `logError()`), not stdout
+
+### Don't
+
+- Don't catch and swallow unexpected errors — let them propagate
+- Don't show stack traces for user errors
+- Don't use `console.error()` directly — use `logError()` for consistent formatting
+- Don't exit with code 0 when an operation fails
+- Don't use exit codes other than 0, 1, or 2
+
+## Implementation Pattern
+
+### Good Example
+
+```typescript
+// Expected failure — user error with actionable suggestion
+import { logError } from "../helpers/log";
+
+const adrsPath = resolve(projectRoot, ".archgate/adrs");
+if (!existsSync(adrsPath)) {
+  logError(
+    "No .archgate/ directory found. Run `archgate init` to initialize governance."
+  );
+  process.exit(1);
+}
+```
+
+```typescript
+// Validation failure — report and exit with code 1
+const results = await runChecks(adrs);
+const exitCode = getExitCode(results); // 0 if clean, 1 if violations
+process.exit(exitCode);
+```
+
+### Bad Example
+
+```typescript
+// BAD: swallowing errors silently
+try {
+  const config = await loadConfig();
+} catch {
+  // Error is lost — caller has no idea something failed
+}
+
+// BAD: using console.error directly
+console.error("Something went wrong"); // No consistent formatting
+
+// BAD: non-standard exit code
+process.exit(42); // Scripts cannot interpret this
+
+// BAD: showing stack trace for user error
+try {
+  validateInput(args);
+} catch (e) {
+  console.error(e); // Prints stack trace for simple validation failure
+  process.exit(1);
+}
+```
+
+## Consequences
+
+### Positive
+
+- **Consistent error experience** — Users always see the same error format regardless of which command fails
+- **Exit codes enable scripting** — CI systems and shell scripts can branch on 0/1/2 with clear semantics
+- **Clear separation between user errors and bugs** — Exit code 1 means "you need to fix something," exit code 2 means "we have a bug"
+- **Actionable messages reduce support burden** — Telling users what to do next prevents repeated "how do I fix this?" questions
+
+### Negative
+
+- **Debugging requires environment variables** — Detailed error context (stack traces, internal state) is only available with `DEBUG` or `TRACE` env vars. This is intentional but can slow down debugging for contributors unfamiliar with the convention.
+
+### Risks
+
+- **Swallowed errors in async code** — Async functions that catch errors without re-throwing can silently fail. Unhandled promise rejections in Bun terminate the process with a non-zero exit code, which provides a safety net, but the error message may be unclear.
+  - **Mitigation:** The `logError()` convention makes explicit error handling visible in code review. The `use-log-error` automated rule flags direct `console.error()` usage, nudging developers toward the standard pattern.
+- **Exit code 2 masking real issues** — If an unexpected error occurs in a rule file, the CLI exits with code 2 ("internal error") rather than code 1 ("violations"). This could confuse CI systems that only check for non-zero exit.
+  - **Mitigation:** The check engine wraps rule execution with timeout and error boundaries, reporting rule errors separately from violations. The `--verbose` flag shows which rules errored.
+
+## Compliance and Enforcement
+
+### Automated Enforcement
+
+- **Archgate rule** `ARCH-002/use-log-error`: Scans all source files (excluding `helpers/log.ts` and test files) for `console.error()` usage and flags violations. Severity: `error`.
+- **Archgate rule** `ARCH-002/exit-code-convention`: Scans all source files for `process.exit()` calls and verifies the exit code is 0, 1, or 2. Severity: `error`.
+
+### Manual Enforcement
+
+Code reviewers MUST verify:
+
+1. Error messages include actionable suggestions where possible
+2. Expected failures exit with code 1, not code 2
+3. No try-catch blocks that swallow errors without logging or re-throwing
+
+## References
+
+- [POSIX exit code conventions](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_08_02)
+- [ARCH-003 — Output Formatting](./ARCH-003-output-formatting.md) — Complements this ADR with output conventions (stderr for errors, stdout for results)