agency-rules 0.3.2 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be 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.4.1](https://github.com/deuriib/agency-rules/compare/v0.4.0...v0.4.1) (2026-10-31)
+
+
+### Bug Fixes
+
+* **pkg:** include rules directory in npm bundle and resolve package paths ([3877a97](https://github.com/deuriib/agency-rules/commit/3877a97e22ec5b79c183c47f3ed7b026171684e5))
+
+## [0.4.0](https://github.com/deuriib/agency-rules/compare/v0.3.2...v0.4.0) (2026-10-31)
+
+
+### Features
+
+* **cli:** expose agency-rules binary and router ([dfb6b95](https://github.com/deuriib/agency-rules/commit/dfb6b95b8b6d9ac6f4622479527f182d9c1e637c))
+
 ## [0.3.2](https://github.com/deuriib/agency-rules/compare/v0.3.1...v0.3.2) (2026-10-31)
 
 

package/README.md

@@ -29,6 +29,23 @@ with a single command, driven by a declarative contract (`tools.json`).
 
 ---
 
+## Global CLI Usage
+
+You can also use `agency-rules` directly via `npx` without cloning the repository:
+
+```bash
+# Validate rules
+npx agency-rules validate
+
+# Compile rules
+npx agency-rules convert
+
+# Install rules interactively
+npx agency-rules install
+```
+
+---
+
 ## Quick Start
 
 ```bash
@@ -140,6 +157,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests welcome.
 
 See [SECURITY.md](SECURITY.md) for responsible disclosure.
 
+![Repobeats analytics](https://repobeats.com/deuriib/agency-rules?theme=light&size=medium&period=30)
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/bin/agency-rules.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const command = process.argv[2];
+
+// ── Read version dynamically ──────────────────────────────────────────
+const getVersion = async () => {
+    try {
+        const pkgPath = resolve(import.meta.dirname, '..', 'package.json');
+        const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+        return pkg.version || '0.0.0';
+    } catch {
+        return '0.0.0';
+    }
+};
+
+const version = await getVersion();
+
+// ── Help Menus ────────────────────────────────────────────────────────
+const showHelp = () => {
+    console.log(`
+\x1b[36magency-rules\x1b[0m v${version}
+Write rules once. Run them in every harness.
+
+\x1b[33mUsage:\x1b[0m
+  $ agency-rules <command> [options]
+
+\x1b[33mCommands:\x1b[0m
+  \x1b[32mconvert\x1b[0m     Compile rules/ into each harness's native format
+  \x1b[32minstall\x1b[0m     Install compiled artifacts into detected harnesses
+  \x1b[32mvalidate\x1b[0m    Validate each rule's frontmatter against the schema
+
+\x1b[33mGlobal Options:\x1b[0m
+  -h, --help      Show this help message
+  -v, --version   Show version number
+
+\x1b[33mExamples:\x1b[0m
+  $ agency-rules validate
+  $ agency-rules convert
+  $ agency-rules convert --dry-run
+  $ agency-rules install --scope user --harness opencode
+`);
+};
+
+const showCommandHelp = (cmd) => {
+    const helps = {
+        convert: `
+\x1b[36magency-rules convert\x1b[0m
+Compile rules/ into each harness's native format.
+
+\x1b[33mOptions:\x1b[0m
+  --dry-run         Preview which files would be written (no writes)
+  --harness <id>    Limit compilation to a specific harness (e.g., antigravity)
+
+\x1b[33mExamples:\x1b[0m
+  $ agency-rules convert
+  $ agency-rules convert --dry-run
+  $ agency-rules convert --harness pi-agent
+`,
+        install: `
+\x1b[36magency-rules install\x1b[0m
+Install compiled artifacts into detected harnesses.
+
+\x1b[33mOptions:\x1b[0m
+  --dry-run              Preview which files would be copied (no writes)
+  --scope <project|user> Install local to project or global to user (default: project)
+  --harness <id>         Install into a specific harness
+  --all                  Force installation for all harnesses, ignoring auto-detection
+
+\x1b[33mExamples:\x1b[0m
+  $ agency-rules install
+  $ agency-rules install --dry-run
+  $ agency-rules install --scope user
+  $ agency-rules install --harness opencode --scope project
+`,
+        validate: `
+\x1b[36magency-rules validate\x1b[0m
+Validate each rule's frontmatter against the schema.
+
+\x1b[33mOptions:\x1b[0m
+  (No specific options)
+
+\x1b[33mExamples:\x1b[0m
+  $ agency-rules validate
+`,
+    };
+    console.log(helps[cmd] || '');
+};
+
+// ── Global Flags ──────────────────────────────────────────────────────
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    console.log(version);
+    process.exit(0);
+}
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+    showHelp();
+    process.exit(0);
+}
+
+if (!['convert', 'install', 'validate'].includes(command)) {
+    console.error(`\x1b[31mError:\x1b[0m Unknown command '${command}'`);
+    showHelp();
+    process.exit(1);
+}
+
+// ── Command-specific Help ─────────────────────────────────────────────
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    showCommandHelp(command);
+    process.exit(0);
+}
+
+// ── Execute ───────────────────────────────────────────────────────────
+// Remove the command from argv so the downstream script's parseArgs works cleanly
+process.argv.splice(2, 1);
+
+const scriptPath = resolve(import.meta.dirname, '..', 'scripts', `${command}.mjs`);
+
+try {
+    await import(pathToFileURL(scriptPath).href);
+} catch (err) {
+    console.error(`\x1b[31m❌ Failed to execute '${command}':\x1b[0m`, err.message);
+    process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-rules",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Write rules once. Run them in every harness.",
   "type": "module",
   "license": "MIT",
@@ -22,13 +22,17 @@
     "opencode",
     "oh-my-pi"
   ],
+  "bin": {
+    "agency-rules": "./bin/agency-rules.mjs"
+  },
   "engines": {
     "node": ">=20.12"
   },
   "files": [
+    "bin/",
     "scripts/",
     "tools.json",
-    "rules/_schema.json",
+    "rules/",
     "docs/",
     "README.md",
     "LICENSE",

package/rules/base/coding-standards.md

@@ -0,0 +1,12 @@
+---
+name: coding-standards
+description: Baseline rules applied to every edit regardless of file type.
+alwaysApply: true
+tags: [base]
+---
+
+# Coding Standards
+
+- Keep functions under 40 lines.
+- Prefer named exports over default exports.
+- Never commit `console.log` or debug prints.

package/rules/base/commit-convention.md

@@ -0,0 +1,53 @@
+---
+name: commit-conventions
+description: Enforce Conventional Commits format for all git commit messages.
+alwaysApply: true
+tags: [git, commits, conventional-commits]
+---
+
+# Git Commit Conventions
+
+All commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+This is strictly required because automated release tooling (like `release-please`) uses these commits to calculate semantic versioning bumps and generate changelogs.
+
+## Format
+
+```
+<type>(<optional scope>): <subject>
+```
+
+- **type**: Must be one of the following:
+  - `feat`: A new feature (triggers a MINOR version bump).
+  - `fix`: A bug fix (triggers a PATCH version bump).
+  - `docs`: Documentation only changes.
+  - `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc).
+  - `refactor`: A code change that neither fixes a bug nor adds a feature.
+  - `perf`: A code change that improves performance.
+  - `test`: Adding missing tests or correcting existing tests.
+  - `build`: Changes that affect the build system or external dependencies.
+  - `ci`: Changes to CI configuration files and scripts.
+  - `chore`: Other changes that don't modify src or test files.
+- **scope** (optional): A noun describing a section of the codebase (e.g., `rules`, `convert`, `harness`, `docs`).
+- **subject**: A short description in the imperative mood (e.g., "add", not "added").
+
+## Rules
+
+- Use the **imperative, present tense** (e.g., "fix bug" not "fixed bug").
+- Do **not** capitalize the first letter of the subject.
+- Do **not** end the subject line with a period.
+- Keep the subject line under **72 characters**.
+- Separate the subject from the body with a blank line.
+- Use the body to explain *what* and *why* (not *how*).
+- Use footers for referencing issues (e.g., `Closes #123`) or declaring breaking changes (`BREAKING CHANGE: <description>`).
+
+## Examples
+
+```text
+feat(rules): add python async conventions
+fix(antigravity): join globs with comma instead of space
+docs(spec): clarify trigger precedence for model_decision
+chore(deps): bump biome to 2.5.1
+feat(harness): support Cursor rules format
+
+BREAKING CHANGE: The `trigger` field is now required for all Antigravity rules.
+```

package/rules/stacks/pyhton.md

@@ -0,0 +1,12 @@
+---
+name: python
+description: Rules for Python modules.
+globs: ["**/*.py"]
+tags: [language, python]
+---
+
+# Python Rules
+
+- Use type hints on public functions.
+- Prefer `pathlib` over `os.path`.
+- No wildcard imports.

package/rules/stacks/typescript.md

@@ -0,0 +1,25 @@
+---
+name: typescript
+description: Mandatory rules for editing TypeScript and TSX files.
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+alwaysApply: false
+trigger: glob          # preferencia para Antigravity; otros harnesses lo ignoran si no aplica
+tags: [language, typescript]
+---
+
+# TypeScript Rules
+
+- No `any` unless absolutely necessary.
+- Use top-level imports only.
+- Prefer `interface` over `type` for object shapes.
+
+## Examples
+
+```ts
+// ✅ good
+interface User { id: string; name: string; }
+
+// ❌ avoid
+type User = { id: string; name: string; };

package/scripts/convert.mjs

@@ -1,5 +1,5 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { readRules } from './lib/frontmatter.mjs';
 import { renderers } from './lib/renderers/index.mjs';
@@ -14,17 +14,25 @@ const { values: args } = parseArgs({
 const dryRun = args['dry-run'];
 const prefix = dryRun ? '  [dry-run]' : ' ';
 
-const RULES_DIR = process.env.RULES_DIR || 'rules';
+// Resolve paths: Use local if exists, otherwise fallback to the package's bundled files
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+const localRules = resolve(process.cwd(), 'rules');
+const localTools = resolve(process.cwd(), 'tools.json');
+
+const RULES_DIR =
+    process.env.RULES_DIR ||
+    ((await import('node:fs').then((fs) => fs.existsSync(localRules)))
+        ? localRules
+        : resolve(PACKAGE_ROOT, 'rules'));
+const TOOLS_PATH = (await import('node:fs').then((fs) => fs.existsSync(localTools)))
+    ? localTools
+    : resolve(PACKAGE_ROOT, 'tools.json');
+
 const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
 
-const tools = JSON.parse(await readFile('tools.json', 'utf8'));
+const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
 const rules = await readRules(RULES_DIR);
 
-if (rules.length === 0) {
-    console.error(`❌ No rules found in ${RULES_DIR}`);
-    process.exit(1);
-}
-
 console.log(
     `📚 Found ${rules.length} rule(s) in ${RULES_DIR}${dryRun ? ' (dry-run — nothing will be written)' : ''}\n`,
 );

package/scripts/install.mjs

@@ -1,5 +1,6 @@
+import { existsSync } from 'node:fs';
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { stdin as input, stdout as output } from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs } from 'node:util';
@@ -19,7 +20,12 @@ const tag = dryRun ? '[dry-run]' : '     ';
 const log = (msg) => console.log(`  ${tag} ${msg}`);
 
 const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
-const tools = JSON.parse(await readFile('tools.json', 'utf8'));
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+const localTools = resolve(process.cwd(), 'tools.json');
+const TOOLS_PATH = existsSync(localTools) ? localTools : resolve(PACKAGE_ROOT, 'tools.json');
+
+const tools = JSON.parse(await readFile(TOOLS_PATH, 'utf8'));
 
 let finalScope = args.scope;
 let finalHarness = args.harness;