archgate 0.14.0 → 0.16.0

package/README.md

@@ -42,10 +42,13 @@ When a rule is violated, `archgate check` reports the file, line, and which ADR
 
 ```bash
 # macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | sh
+curl -fsSL https://cli.archgate.dev/install-unix | sh
 
 # Windows (PowerShell)
-irm https://raw.githubusercontent.com/archgate/cli/main/install.ps1 | iex
+irm https://cli.archgate.dev/install-windows | iex
+
+# Windows (Git Bash / MSYS2)
+curl -fsSL https://cli.archgate.dev/install-unix | sh
 ```
 
 **Via npm** (or any Node.js package manager):
@@ -77,7 +80,7 @@ npx archgate check         # run via package manager
 
 ```bash
 # 1. Install
-curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | sh  # or: npm install -g archgate
+curl -fsSL https://cli.archgate.dev/install-unix | sh  # or: npm install -g archgate
 
 # 2. Initialize governance in your project
 cd my-project
@@ -95,29 +98,7 @@ archgate check
 
 ## Writing rules
 
-Each ADR can have a companion `.rules.ts` file that exports checks using `defineRules()` from the `archgate` package. Rules receive the list of files to check and return an array of violations with file paths and line numbers.
-
-See the [writing rules guide](https://cli.archgate.dev/guides/writing-rules/) for examples and the full [rule API reference](https://cli.archgate.dev/reference/rule-api/).
-
-## Commands
-
-| Command                  | Description                                                |
-| ------------------------ | ---------------------------------------------------------- |
-| `archgate init`          | Initialize `.archgate/` with example ADR and editor config |
-| `archgate check`         | Run ADR compliance checks (`--staged` for pre-commit)      |
-| `archgate adr create`    | Create a new ADR interactively                             |
-| `archgate adr list`      | List all ADRs (`--json`, `--domain`)                       |
-| `archgate adr show <id>` | Print a specific ADR                                       |
-| `archgate adr update`    | Update an ADR's frontmatter                                |
-| `archgate login`         | Authenticate with GitHub for editor plugins                |
-| `archgate upgrade`       | Upgrade to the latest release                              |
-| `archgate clean`         | Remove the CLI cache (`~/.archgate/`)                      |
-
-See the [CLI reference](https://cli.archgate.dev/reference/cli-commands/) for full usage and options.
-
-## CI and pre-commit hooks
-
-Add `archgate check` to your CI pipeline or pre-commit hooks to block merges that violate ADRs. See the [CI integration guide](https://cli.archgate.dev/guides/ci-integration/) and [pre-commit hooks guide](https://cli.archgate.dev/guides/pre-commit-hooks/) for setup instructions.
+Each ADR can have a companion `.rules.ts` file that exports automated checks. See the [writing rules guide](https://cli.archgate.dev/guides/writing-rules/) for examples and the full [rule API reference](https://cli.archgate.dev/reference/rule-api/).
 
 ## Supercharge with AI plugins
 

package/bin/archgate.cjs

@@ -2,6 +2,8 @@
 "use strict";
 
 const { execFileSync } = require("child_process");
+const https = require("https");
+const zlib = require("zlib");
 const path = require("path");
 const fs = require("fs");
 
@@ -15,9 +17,22 @@ function getPlatformPackageName() {
   );
 }
 
+function getBinaryName() {
+  return process.platform === "win32" ? "archgate.exe" : "archgate";
+}
+
+function getPackageVersion() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")
+  );
+  return pkg.version;
+}
+
 function getBinaryPath() {
   const pkgName = getPlatformPackageName();
-  const binaryName = process.platform === "win32" ? "archgate.exe" : "archgate";
+  const binaryName = getBinaryName();
+
+  // 1. Try the platform-specific optional dependency (normal path).
   try {
     const pkgDir = path.dirname(require.resolve(`${pkgName}/package.json`));
     const binaryPath = path.join(pkgDir, "bin", binaryName);
@@ -25,16 +40,146 @@ function getBinaryPath() {
   } catch {
     /* platform package not installed */
   }
-  throw new Error(
-    `archgate binary not found. "${getPlatformPackageName()}" may not be installed.\nTry reinstalling: npm install -g archgate`
+
+  // 2. Fallback: binary downloaded into our own bin/ by postinstall or a
+  //    previous on-demand download.
+  const fallbackPath = path.join(__dirname, binaryName);
+  if (fs.existsSync(fallbackPath)) return fallbackPath;
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// On-demand download from the npm registry
+// ---------------------------------------------------------------------------
+
+function fetchWithRedirects(url) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, (res) => {
+        if (
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          fetchWithRedirects(res.headers.location).then(resolve, reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`GET ${url} returned status ${res.statusCode}`));
+          return;
+        }
+        resolve(res);
+      })
+      .on("error", reject);
+  });
+}
+
+/** Strip null bytes from a buffer-decoded string. */
+function stripNulls(str) {
+  const idx = str.indexOf(String.fromCodePoint(0));
+  return idx === -1 ? str : str.slice(0, idx);
+}
+
+/**
+ * Download the platform-specific npm package tarball and extract the binary.
+ * Returns the path to the downloaded binary.
+ */
+async function downloadBinary() {
+  const pkgName = getPlatformPackageName();
+  const version = getPackageVersion();
+  const binaryName = getBinaryName();
+
+  const url = `https://registry.npmjs.org/${pkgName}/-/${pkgName}-${version}.tgz`;
+  console.error(
+    `archgate: binary not found, downloading ${pkgName}@${version}...`
   );
+
+  const res = await fetchWithRedirects(url);
+
+  const binDir = __dirname;
+  const destPath = path.join(binDir, binaryName);
+
+  return new Promise((resolve, reject) => {
+    const gunzip = zlib.createGunzip();
+    const chunks = [];
+    const expectedSuffix = `bin/${binaryName}`;
+    let found = false;
+
+    res.pipe(gunzip);
+    gunzip.on("data", (chunk) => chunks.push(chunk));
+    gunzip.on("end", () => {
+      const data = Buffer.concat(chunks);
+      let offset = 0;
+
+      while (offset + 512 <= data.length) {
+        const header = data.subarray(offset, offset + 512);
+        offset += 512;
+
+        // Empty header block signals end of archive
+        if (header.every((b) => b === 0)) break;
+
+        let name = stripNulls(header.subarray(0, 100).toString("utf8"));
+        const prefix = stripNulls(header.subarray(345, 500).toString("utf8"));
+        if (prefix) name = `${prefix}/${name}`;
+
+        const sizeStr = stripNulls(
+          header.subarray(124, 136).toString("utf8")
+        ).trim();
+        const size = parseInt(sizeStr, 8) || 0;
+        const blocks = Math.ceil(size / 512);
+        const fileData = data.subarray(offset, offset + size);
+        offset += blocks * 512;
+
+        if (name.endsWith(expectedSuffix)) {
+          fs.writeFileSync(destPath, fileData, { mode: 0o755 });
+          found = true;
+          break;
+        }
+      }
+
+      if (found) {
+        console.error(`archgate: binary downloaded successfully.`);
+        resolve(destPath);
+      } else {
+        reject(
+          new Error(`Could not find ${expectedSuffix} in tarball from ${url}`)
+        );
+      }
+    });
+
+    gunzip.on("error", reject);
+  });
 }
 
-try {
-  const binary = getBinaryPath();
-  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
-} catch (e) {
-  if (typeof e.status === "number") process.exit(e.status);
-  console.error(e.message);
-  process.exit(2);
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  let binary = getBinaryPath();
+
+  // If the binary is missing (optional dep skipped AND postinstall blocked),
+  // download it on-demand from the npm registry.
+  if (!binary) {
+    try {
+      binary = await downloadBinary();
+    } catch (err) {
+      console.error(
+        `archgate: failed to download binary: ${err.message}\n` +
+          `Try reinstalling: npm install archgate`
+      );
+      process.exit(2);
+    }
+  }
+
+  try {
+    execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+  } catch (e) {
+    if (typeof e.status === "number") process.exit(e.status);
+    console.error(e.message);
+    process.exit(2);
+  }
 }
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgate",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Enforce Architecture Decision Records as executable rules — for both humans and AI agents",
   "keywords": [
     "adr",
@@ -27,8 +27,8 @@
     "archgate": "bin/archgate.cjs"
   },
   "files": [
-    "src/formats/rules.ts",
-    "bin/archgate.cjs"
+    "bin/archgate.cjs",
+    "scripts/postinstall.cjs"
   ],
   "os": [
     "darwin",
@@ -36,9 +36,6 @@
     "win32"
   ],
   "type": "module",
-  "exports": {
-    "./rules": "./src/formats/rules.ts"
-  },
   "scripts": {
     "build:check": "bun build src/cli.ts --compile --bytecode --outfile dist/.build-check && rm -f dist/.build-check dist/.build-check.exe",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
@@ -51,6 +48,7 @@
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
     "lint": "oxlint --deny-warnings .",
+    "postinstall": "node scripts/postinstall.cjs",
     "test": "bun test --timeout 60000",
     "test:watch": "bun test --watch --timeout 60000",
     "typecheck": "tsc --build",
@@ -75,9 +73,9 @@
     "typescript": "^5"
   },
   "optionalDependencies": {
-    "archgate-darwin-arm64": "0.14.0",
-    "archgate-linux-x64": "0.14.0",
-    "archgate-win32-x64": "0.14.0"
+    "archgate-darwin-arm64": "0.16.0",
+    "archgate-linux-x64": "0.16.0",
+    "archgate-win32-x64": "0.16.0"
   },
   "readme": "README.md"
 }

package/scripts/postinstall.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+"use strict";
+
+// Best-effort pre-download: tries to fetch the binary during install so the
+// first `archgate` invocation is instant. If this script is blocked by the
+// package manager (--ignore-scripts, etc.), the bin shim will download
+// on-demand at runtime instead.
+
+const path = require("path");
+const fs = require("fs");
+
+const PACKAGE_NAME_MAP = {
+  "darwin-arm64": "archgate-darwin-arm64",
+  "linux-x64": "archgate-linux-x64",
+  "win32-x64": "archgate-win32-x64",
+};
+
+function isBinaryPresent() {
+  const key = `${process.platform}-${process.arch}`;
+  const pkgName = PACKAGE_NAME_MAP[key];
+  if (!pkgName) return true; // unsupported platform — skip silently
+
+  const binaryName = process.platform === "win32" ? "archgate.exe" : "archgate";
+
+  // Check optional dependency
+  try {
+    const pkgDir = path.dirname(require.resolve(`${pkgName}/package.json`));
+    if (fs.existsSync(path.join(pkgDir, "bin", binaryName))) return true;
+  } catch {
+    /* not installed */
+  }
+
+  // Check local fallback
+  if (fs.existsSync(path.join(__dirname, "..", "bin", binaryName))) return true;
+
+  return false;
+}
+
+if (!isBinaryPresent()) {
+  // Delegate to the bin shim's download logic by running it with --version.
+  // This triggers the on-demand download without side effects.
+  try {
+    require("child_process").execFileSync(
+      process.execPath,
+      [path.join(__dirname, "..", "bin", "archgate.cjs"), "--version"],
+      { stdio: "inherit" }
+    );
+  } catch {
+    // Postinstall must never block `npm install`.
+    console.warn(
+      "archgate: could not pre-download binary. It will be downloaded on first run."
+    );
+  }
+}

package/src/formats/rules.ts

@@ -1,68 +0,0 @@
-// --- 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> };
-
-/**
- * Define rules in a .rules.ts companion file.
- * Keys become rule IDs, preventing duplicates.
- */
-export function defineRules(rules: Record<string, RuleConfig>): RuleSet {
-  return { rules };
-}