archgate 0.1.0

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2025 Archgate
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,237 @@
+# Archgate
+
+<div align="center">
+
+**Enforce Architecture Decision Records as executable rules — for both humans and AI agents.**
+
+[![License: FSL-1.1-ALv2](https://img.shields.io/badge/License-FSL--1.1--ALv2-blue.svg)](LICENSE.md)
+[![Release](https://github.com/archgate/cli/actions/workflows/release.yml/badge.svg)](https://github.com/archgate/cli/actions/workflows/release.yml)
+
+</div>
+
+---
+
+Archgate turns your Architecture Decision Records into a governance layer that runs in CI, enforces rules in pre-commit hooks, and feeds live context to AI coding agents — so architectural decisions don't stay in documents, they stay in the code.
+
+**Write an ADR once. Enforce it everywhere.**
+
+## How it works
+
+Archgate has two layers:
+
+1. **ADRs as documents** — markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do.
+2. **ADRs as rules** — each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations.
+
+```
+.archgate/
+└── adrs/
+    ├── ARCH-001-command-structure.md          # human-readable decision
+    ├── ARCH-001-command-structure.rules.ts    # machine-executable checks
+    ├── ARCH-002-error-handling.md
+    └── ARCH-002-error-handling.rules.ts
+```
+
+When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically.
+
+**The AI integration layer** is a Claude Code plugin that gives AI agents live access to your ADRs through the MCP server (`archgate mcp`). Agents read the decisions before writing code, validate changes after, and capture new patterns into the governance base. Archgate ships as its own governance subject — its own development is governed by the ADRs in `.archgate/adrs/`.
+
+## Installation
+
+```bash
+curl -fsSL https://archgate.dev/install.sh | sh
+```
+
+Installs the standalone binary to `~/.archgate/bin/` and adds it to your PATH.
+
+**Requirements:** macOS (arm64) or Linux (x86_64).
+
+## Quick start
+
+```bash
+# 1. Install
+curl -fsSL https://archgate.dev/install.sh | sh
+
+# 2. Initialize governance in your project
+cd my-project
+archgate init
+
+# 3. Edit the generated ADR to document a real decision
+# .archgate/adrs/ARCH-001-*.md
+
+# 4. Add a companion .rules.ts to enforce it automatically
+# .archgate/adrs/ARCH-001-*.rules.ts
+
+# 5. Run checks
+archgate check
+```
+
+`archgate init` creates the `.archgate/adrs/` directory, an example ADR with a companion rules file to show the pattern, and configures the Claude Code plugin if you use it.
+
+## Writing rules
+
+A companion `.rules.ts` file exports checks using `defineRules()` from the `archgate` package:
+
+```typescript
+// .archgate/adrs/ARCH-002-error-handling.rules.ts
+import { defineRules } from "archgate/rules";
+
+export default defineRules([
+  {
+    id: "use-log-error",
+    description:
+      "Use logError() instead of console.error() for user-facing errors",
+    severity: "error",
+    async check({ files }) {
+      const violations = [];
+      for (const file of files) {
+        const content = await Bun.file(file).text();
+        const lines = content.split("\n");
+        lines.forEach((line, i) => {
+          if (line.includes("console.error(")) {
+            violations.push({
+              file,
+              line: i + 1,
+              message: "Use logError() instead",
+            });
+          }
+        });
+      }
+      return violations;
+    },
+  },
+]);
+```
+
+Rules receive the list of files to check (filtered by the ADR's `files` glob if set), and return an array of violations with file paths and line numbers.
+
+## Commands
+
+### `archgate init`
+
+Initialize governance in the current project.
+
+```bash
+archgate init
+```
+
+Creates `.archgate/adrs/` with an example ADR and rules file, and optionally wires up the Claude Code plugin.
+
+### `archgate check`
+
+Run all automated ADR checks against your codebase.
+
+```bash
+archgate check            # check all files
+archgate check --staged   # check only git-staged files (for pre-commit hooks)
+archgate check --json     # machine-readable JSON output
+```
+
+Exits with code 0 if all checks pass, 1 if any violations are found.
+
+### `archgate adr create`
+
+Create a new ADR interactively.
+
+```bash
+archgate adr create
+```
+
+Prompts for a title, domain, and optional file glob. Generates a sequential ID (`ARCH-001`, `ARCH-002`, ...) and writes the markdown file.
+
+### `archgate adr list`
+
+List all ADRs in the project.
+
+```bash
+archgate adr list                  # table output
+archgate adr list --json           # JSON output
+archgate adr list --domain backend # filter by domain
+```
+
+### `archgate adr show <id>`
+
+Print a specific ADR.
+
+```bash
+archgate adr show ARCH-001
+```
+
+### `archgate adr update`
+
+Update an existing ADR's frontmatter.
+
+```bash
+archgate adr update ARCH-001 --title "New Title" --domain backend
+```
+
+### `archgate mcp`
+
+Start the MCP server for AI agent integration.
+
+```bash
+archgate mcp
+```
+
+Exposes four tools to MCP-compatible clients (Claude Code, Cursor, etc.):
+
+| Tool              | Description                                                       |
+| ----------------- | ----------------------------------------------------------------- |
+| `check`           | Run ADR compliance checks, optionally on staged files only        |
+| `list_adrs`       | List all ADRs with metadata                                       |
+| `review_context`  | Get changed files grouped by domain with applicable ADR briefings |
+| `session_context` | Read the current Claude Code session transcript                   |
+
+Also exposes `adr://{id}` resources for reading individual ADRs by ID.
+
+### `archgate upgrade`
+
+Upgrade to the latest release.
+
+```bash
+archgate upgrade
+```
+
+### `archgate clean`
+
+Remove the CLI cache directory (`~/.archgate/`).
+
+```bash
+archgate clean
+```
+
+## CI integration
+
+Add a check step to your pipeline:
+
+```yaml
+# GitHub Actions example
+- name: ADR compliance check
+  run: archgate check
+```
+
+For pre-commit hooks (using [lefthook](https://github.com/evilmartians/lefthook) or similar):
+
+```yaml
+pre-commit:
+  commands:
+    adr-check:
+      run: archgate check --staged
+```
+
+## Claude Code plugin
+
+The Claude Code plugin (`archgate:developer`) gives AI agents a full governance workflow:
+
+- Reads applicable ADRs before writing code
+- Validates changes after implementation
+- Captures new patterns back into ADRs
+
+Install the plugin from [archgate/claude-code-plugin](https://github.com/archgate/claude-code-plugin), then run `archgate:onboard` once in your project to initialize governance.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and workflow.
+
+## License
+
+[FSL-1.1-ALv2](LICENSE.md) — free to use, cannot be used to build a competing product.

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "archgate",
+  "version": "0.1.0",
+  "description": "AI governance for software development",
+  "readme": "README.md",
+  "license": "FSL-1.1-ALv2",
+  "homepage": "https://archgate.dev",
+  "exports": {
+    "./rules": "./src/formats/rules.ts"
+  },
+  "files": [
+    "src/formats/rules.ts"
+  ],
+  "author": {
+    "name": "Archgate",
+    "url": "https://archgate.dev"
+  },
+  "keywords": [
+    "archgate",
+    "cli",
+    "framework"
+  ],
+  "bugs": {
+    "url": "https://github.com/archgate/cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/archgate/cli.git"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "scripts": {
+    "cli": "bun run src/cli.ts",
+    "check": "bun run src/cli.ts check",
+    "lint": "oxlint .",
+    "typecheck": "tsc --build",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "bun test --timeout 60000",
+    "test:watch": "bun test --watch --timeout 60000",
+    "validate": "bun run lint && bun run typecheck && bun run format:check && bun test && bun run check",
+    "commit": "cz",
+    "build": "bun run scripts/build.ts",
+    "build:darwin": "bun run scripts/build.ts --target darwin-arm64",
+    "build:linux": "bun run scripts/build.ts --target linux-x64",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@commander-js/extra-typings": "14.0.0",
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "inquirer": "12.9.4",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "19.8.1",
+    "@commitlint/config-conventional": "19.8.1",
+    "@commitlint/cz-commitlint": "19.8.1",
+    "@simple-release/npm": "2.3.0",
+    "@types/bun": "1.3.9",
+    "commitizen": "4.3.1",
+    "conventional-changelog": "7.1.1",
+    "conventional-changelog-angular": "8.0.0",
+    "oxlint": "1.14.0",
+    "prettier": "3.6.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/formats/rules.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+// --- Severity ---
+
+export type Severity = "error" | "warning" | "info";
+
+// --- Grep Match ---
+
+export interface GrepMatch {
+  file: string;
+  line: number;
+  column: number;
+  content: string;
+}
+
+// --- Violation Detail ---
+
+export interface ViolationDetail {
+  ruleId: string;
+  adrId: string;
+  message: string;
+  file?: string;
+  line?: number;
+  fix?: string;
+  severity: Severity;
+}
+
+// --- Report interface (side-effect based) ---
+
+export interface RuleReport {
+  violation(
+    detail: Omit<ViolationDetail, "ruleId" | "adrId" | "severity">
+  ): void;
+  warning(detail: Omit<ViolationDetail, "ruleId" | "adrId" | "severity">): void;
+  info(detail: Omit<ViolationDetail, "ruleId" | "adrId" | "severity">): void;
+}
+
+// --- Rule Context ---
+
+export interface RuleContext {
+  projectRoot: string;
+  scopedFiles: string[];
+  changedFiles: string[];
+  glob(pattern: string): Promise<string[]>;
+  grep(file: string, pattern: RegExp): Promise<GrepMatch[]>;
+  grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>;
+  readFile(path: string): Promise<string>;
+  readJSON(path: string): Promise<unknown>;
+  report: RuleReport;
+}
+
+// --- Rule Config ---
+
+export interface RuleConfig {
+  description: string;
+  severity?: Severity;
+  check: (ctx: RuleContext) => Promise<void>;
+}
+
+// --- Rule Set ---
+
+export type RuleSet = {
+  rules: Record<string, RuleConfig>;
+};
+
+export const RuleSetSchema = z.object({
+  rules: z.record(
+    z.string(),
+    z.object({
+      description: z.string(),
+      severity: z.enum(["error", "warning", "info"]).optional(),
+      check: z.custom<(ctx: RuleContext) => Promise<void>>(
+        (val) => typeof val === "function",
+        "Expected a function"
+      ),
+    })
+  ),
+});
+
+/**
+ * Define rules in a .rules.ts companion file.
+ * Keys become rule IDs, preventing duplicates.
+ */
+export function defineRules(rules: Record<string, RuleConfig>): RuleSet {
+  return { rules };
+}