agency-rules 0.0.0-stage → 0.3.2

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "agency-rules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "Write rules once. Run them in every harness.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Deuri Vasquez <deuriib@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deuriib/agency-rules.git"
+  },
+  "bugs": {
+    "url": "https://github.com/deuriib/agency-rules/issues"
+  },
+  "homepage": "https://github.com/deuriib/agency-rules#readme",
+  "keywords": [
+    "ai",
+    "agents",
+    "rules",
+    "antigravity",
+    "pi-agent",
+    "opencode",
+    "oh-my-pi"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "files": [
+    "scripts/",
+    "tools.json",
+    "rules/_schema.json",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.5.0"
+  }
+}

package/rules/_schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "name",
+    "description"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "maxLength": 64
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024
+    },
+    "globs": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        }
+      ]
+    },
+    "alwaysApply": {
+      "type": "boolean"
+    },
+    "trigger": {
+      "enum": [
+        "always_on",
+        "glob",
+        "model_decision",
+        "manual"
+      ]
+    },
+    "match": {
+      "enum": [
+        "any",
+        "all"
+      ]
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

package/scripts/convert.mjs

@@ -0,0 +1,106 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { readRules } from './lib/frontmatter.mjs';
+import { renderers } from './lib/renderers/index.mjs';
+
+const { values: args } = parseArgs({
+    options: {
+        'dry-run': { type: 'boolean', default: false },
+        harness: { type: 'string' },
+    },
+});
+
+const dryRun = args['dry-run'];
+const prefix = dryRun ? '  [dry-run]' : ' ';
+
+const RULES_DIR = process.env.RULES_DIR || 'rules';
+const INTEGRATIONS_DIR = process.env.INTEGRATIONS_DIR || 'integrations';
+
+const tools = JSON.parse(await readFile('tools.json', '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`,
+);
+
+const harnessIds = args.harness ? [args.harness] : Object.keys(tools.harnesses);
+
+for (const id of harnessIds) {
+    if (!tools.harnesses[id]) {
+        console.error(`❌ Unknown harness: ${id}`);
+        process.exit(1);
+    }
+}
+
+let totalFiles = 0;
+
+for (const id of harnessIds) {
+    const harness = tools.harnesses[id];
+    const render = renderers[harness.format];
+    if (!render) {
+        console.error(`❌ No renderer for format "${harness.format}" (harness: ${id})`);
+        process.exit(1);
+    }
+
+    if (!harness.integrationPath) {
+        console.error(`❌ Missing "integrationPath" for harness "${id}" in tools.json`);
+        process.exit(1);
+    }
+
+    const harnessDir = join(INTEGRATIONS_DIR, id);
+    const manifest = [];
+
+    for (const rule of rules) {
+        let output;
+        try {
+            output = render(rule, harness);
+        } catch (err) {
+            console.error(`❌ ${id}: failed to render "${rule.slug}": ${err.message}`);
+            process.exit(1);
+        }
+
+        const relPath = harness.integrationPath.replace('{{slug}}', rule.slug);
+        const outPath = join(harnessDir, relPath);
+        manifest.push({ slug: rule.slug, path: relPath, size: output.length });
+        totalFiles++;
+
+        if (!dryRun) {
+            await mkdir(dirname(outPath), { recursive: true });
+            await writeFile(outPath, output);
+        }
+    }
+
+    if (!dryRun) {
+        await writeFile(
+            join(harnessDir, '_manifest.json'),
+            JSON.stringify(
+                {
+                    harness: id,
+                    format: harness.format,
+                    files: manifest.map(({ slug, path }) => ({ slug, path })),
+                },
+                null,
+                2,
+            ),
+        );
+    }
+
+    console.log(`✅ ${id.padEnd(12)} → ${manifest.length} file(s)`);
+    if (dryRun) {
+        for (const f of manifest) {
+            console.log(`${prefix} would write ${join(harnessDir, f.path)} (${f.size} bytes)`);
+        }
+    }
+}
+
+const summary = dryRun
+    ? `\n🔎 Dry-run: would write ${totalFiles} file(s) across ${harnessIds.length} harness(es). Nothing was written.`
+    : `\n🎉 Wrote ${totalFiles} file(s) across ${harnessIds.length} harness(es).`;
+
+console.log(summary);

package/scripts/install.mjs

@@ -0,0 +1,187 @@
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { stdin as input, stdout as output } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { detectHarnesses, expandHome, pathExists } from './lib/detect.mjs';
+
+const { values: args } = parseArgs({
+    options: {
+        scope: { type: 'string' },
+        harness: { type: 'string' },
+        all: { type: 'boolean', default: false },
+        'dry-run': { type: 'boolean', default: false },
+    },
+});
+
+const dryRun = args['dry-run'];
+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'));
+
+let finalScope = args.scope;
+let finalHarness = args.harness;
+
+// ── Interactive Mode (si no se pasan parámetros y es una terminal) ─────
+if (input.isTTY && ((!finalHarness && !args.all) || !finalScope)) {
+    const rl = createInterface({ input, output });
+
+    if (!finalHarness && !args.all) {
+        console.log('\n🎯 Select a harness to install into:');
+        const keys = Object.keys(tools.harnesses);
+        keys.forEach((k, i) => {
+            console.log(`  ${i + 1}) ${k} (${tools.harnesses[k].label})`);
+        });
+        console.log(`  ${keys.length + 1}) Detect automatically`);
+        console.log(`  ${keys.length + 2}) All harnesses`);
+
+        const answer = await rl.question(`\nChoice [1-${keys.length + 2}] (default: detect): `);
+        const num = parseInt(answer.trim(), 10);
+
+        if (!Number.isNaN(num) && num >= 1 && num <= keys.length) {
+            finalHarness = keys[num - 1];
+        } else if (num === keys.length + 2 || answer.trim().toLowerCase() === 'all') {
+            args.all = true;
+        }
+    }
+
+    if (!finalScope) {
+        console.log('\n🌍 Select installation scope:');
+        console.log('  1) project (local to this repo)');
+        console.log('  2) user (global for your user)');
+
+        const answer = await rl.question('\nChoice [1-2] (default: 1): ');
+        finalScope =
+            answer.trim() === '2' || answer.trim().toLowerCase() === 'user' ? 'user' : 'project';
+    }
+
+    rl.close();
+    console.log('');
+}
+
+// Fallback si no se seleccionó nada
+if (!finalScope) finalScope = 'project';
+
+if (!['project', 'user'].includes(finalScope)) {
+    console.error(`❌ Invalid --scope: ${finalScope} (use "project" or "user")`);
+    process.exit(1);
+}
+
+let targets;
+if (finalHarness) {
+    if (!tools.harnesses[finalHarness]) {
+        console.error(`❌ Unknown harness: ${finalHarness}`);
+        process.exit(1);
+    }
+    targets = [finalHarness];
+} else if (args.all) {
+    targets = Object.keys(tools.harnesses);
+} else {
+    targets = await detectHarnesses(tools);
+    if (targets.length === 0) {
+        console.warn('⚠️  No harness detected. Pass --harness <id> or --all to force.');
+        process.exit(0);
+    }
+}
+
+console.log(
+    `🔍 Targets: ${targets.join(', ')} (scope: ${finalScope})${
+        dryRun ? ' — dry-run, no changes will be made' : ''
+    }\n`,
+);
+
+let copied = 0;
+let skippedHarnesses = 0;
+let pluginChanges = 0;
+
+for (const id of targets) {
+    const harness = tools.harnesses[id];
+    const srcDir = join(INTEGRATIONS_DIR, id);
+
+    if (!(await pathExists(srcDir))) {
+        console.warn(
+            `⚠️  ${id}: no compiled output at ${srcDir}, skipping. Run "mise run convert" first.`,
+        );
+        skippedHarnesses++;
+        continue;
+    }
+
+    const manifest = JSON.parse(await readFile(join(srcDir, '_manifest.json'), 'utf8'));
+    const destTemplate = harness.dest[finalScope];
+    if (!destTemplate) {
+        console.warn(`⚠️  ${id}: no dest for scope "${finalScope}"`);
+        skippedHarnesses++;
+        continue;
+    }
+
+    for (const { slug, path: relPath } of manifest.files) {
+        const destPath = expandHome(destTemplate.replace('{{slug}}', slug));
+        if (dryRun) {
+            log(`${id}: would copy ${relPath} → ${destPath}`);
+        } else {
+            await mkdir(dirname(destPath), { recursive: true });
+            await copyFile(join(srcDir, relPath), destPath);
+            log(`${id}: ${destPath}`);
+        }
+        copied++;
+    }
+
+    if (harness.plugin) {
+        const changed = await handlePlugin(id, harness.plugin, finalScope, dryRun, log);
+        if (changed) pluginChanges++;
+    }
+}
+
+console.log(
+    dryRun
+        ? `\n🔎 Dry-run: would copy ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
+              (pluginChanges ? ` Would update ${pluginChanges} plugin config(s).` : '') +
+              ' Nothing was written.'
+        : `\n🎉 Installed ${copied} file(s) across ${targets.length - skippedHarnesses} harness(es).` +
+              (pluginChanges ? ` Updated ${pluginChanges} plugin config(s).` : ''),
+);
+
+if (dryRun && skippedHarnesses > 0) {
+    console.log(
+        `\n⚠️  ${skippedHarnesses} harness(es) skipped due to missing integrations. Run "mise run convert" first.`,
+    );
+}
+
+// ── Plugin registration ──────────────────────────────────────────────
+async function handlePlugin(id, plugin, scope, dry, logFn) {
+    const configPath =
+        scope === 'user'
+            ? expandHome('~/.config/opencode/opencode.json')
+            : join(process.cwd(), 'opencode.json');
+
+    let config = {};
+    let existed = false;
+    if (await pathExists(configPath)) {
+        existed = true;
+        try {
+            config = JSON.parse(await readFile(configPath, 'utf8'));
+        } catch {
+            console.warn(`⚠️  ${id}: ${configPath} is not valid JSON, skipping plugin registration`);
+            return false;
+        }
+    }
+
+    config.plugin = config.plugin || [];
+    if (config.plugin.includes(plugin.entry)) {
+        logFn(`${id}: plugin "${plugin.entry}" already registered in ${configPath}`);
+        return false;
+    }
+
+    const action = existed ? 'would add' : 'would create and add';
+    logFn(`${id}: ${action} "${plugin.entry}" to ${configPath}`);
+
+    if (!dry) {
+        config.plugin.push(plugin.entry);
+        await mkdir(dirname(configPath), { recursive: true });
+        await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    }
+
+    return true;
+}

package/scripts/lib/detect.mjs

@@ -0,0 +1,35 @@
+import { access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function expandHome(p) {
+    if (p === '~') return homedir();
+    if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+    return p;
+}
+
+export async function pathExists(p) {
+    try {
+        await access(expandHome(p));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export async function detectHarnesses(tools) {
+    const detected = [];
+    for (const [id, harness] of Object.entries(tools.harnesses)) {
+        const dirs = harness.detect?.dirs ?? [];
+        const files = harness.detect?.files ?? [];
+        let found = false;
+        for (const p of [...dirs, ...files]) {
+            if (await pathExists(p)) {
+                found = true;
+                break;
+            }
+        }
+        if (found) detected.push(id);
+    }
+    return detected;
+}

package/scripts/lib/frontmatter.mjs

@@ -0,0 +1,37 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+import matter from 'gray-matter';
+
+/**
+ * Reads every *.md file under `dir` (recursive), parses YAML frontmatter,
+ * and returns an array of { slug, source, data, body }.
+ *
+ * `slug` is derived from the frontmatter `name` (authoritative), with the
+ * filename as fallback. Files starting with `_` are skipped.
+ */
+export async function readRules(dir) {
+    const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+    const rules = [];
+
+    for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        if (!entry.name.endsWith('.md')) continue;
+        if (entry.name.startsWith('_')) continue;
+
+        const parent = entry.parentPath ?? entry.path;
+        const filePath = join(parent, entry.name);
+        const raw = await readFile(filePath, 'utf8');
+        const parsed = matter(raw);
+        const filename = basename(filePath, '.md');
+        const slug = typeof parsed.data?.name === 'string' ? parsed.data.name : filename;
+
+        rules.push({
+            slug,
+            source: relative(dir, filePath),
+            data: parsed.data ?? {},
+            body: (parsed.content ?? '').trim(),
+        });
+    }
+
+    return rules.sort((a, b) => a.slug.localeCompare(b.slug));
+}

package/scripts/lib/renderers/_util.mjs

@@ -0,0 +1,8 @@
+import { stringify as yamlStringify } from 'yaml';
+
+/** Wraps YAML frontmatter + body in a Markdown document. */
+export function wrap(data, body) {
+    const fm = yamlStringify(data).trimEnd();
+    const content = (body ?? '').trim();
+    return `---\n${fm}\n---\n\n${content}\n`;
+}

package/scripts/lib/renderers/antigravity.mjs

@@ -0,0 +1,30 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * Antigravity expects a YAML frontmatter with a mandatory `trigger` field.
+ * Precedence:
+ *   1. explicit `trigger` in the rule
+ *   2. `alwaysApply: true`           → always_on
+ *   3. `globs` present               → glob
+ *   4. only `description`            → model_decision
+ *   5. nothing                       → manual
+ */
+export function renderAntigravity(rule, _harness) {
+    const d = rule.data;
+    let trigger = d.trigger;
+
+    if (!trigger) {
+        if (d.alwaysApply === true) trigger = 'always_on';
+        else if (d.globs) trigger = 'glob';
+        else if (d.description) trigger = 'model_decision';
+        else trigger = 'manual';
+    }
+
+    const fm = { trigger };
+    if (trigger === 'glob' && d.globs) {
+        fm.globs = Array.isArray(d.globs) ? d.globs.join(',') : d.globs;
+    }
+    if (d.description) fm.description = d.description;
+
+    return wrap(fm, rule.body);
+}

package/scripts/lib/renderers/index.mjs

@@ -0,0 +1,12 @@
+import { renderAntigravity } from './antigravity.mjs';
+import { renderOhMyPi } from './oh-my-pi.mjs';
+import { renderOpencode } from './opencode.mjs';
+import { renderPiAgent } from './pi-agent.mjs';
+
+/** Maps `format` from tools.json → renderer function. */
+export const renderers = {
+    'md-yaml-trigger': renderAntigravity,
+    'md-rules-dir': renderPiAgent,
+    'md-or-mdc': renderOhMyPi,
+    'md-plugin': renderOpencode,
+};

package/scripts/lib/renderers/oh-my-pi.mjs

@@ -0,0 +1,16 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * oh-my-pi preserves `name`, `description`, optional `globs` and
+ * `alwaysApply` in the frontmatter. Accepts .md or .mdc; we emit .md.
+ */
+export function renderOhMyPi(rule, _harness) {
+    const d = rule.data;
+    const fm = {
+        name: d.name,
+        description: d.description,
+    };
+    if (d.globs !== undefined) fm.globs = d.globs;
+    if (d.alwaysApply !== undefined) fm.alwaysApply = d.alwaysApply;
+    return wrap(fm, rule.body);
+}

package/scripts/lib/renderers/opencode.mjs

@@ -0,0 +1,13 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * OpenCode's `opencode-rules` plugin discovers .md files with a `description`
+ * (used for matching) and optional `globs`/`match` controls.
+ */
+export function renderOpencode(rule, _harness) {
+    const d = rule.data;
+    const fm = { description: d.description };
+    if (d.globs !== undefined) fm.globs = d.globs;
+    if (d.match !== undefined) fm.match = d.match;
+    return wrap(fm, rule.body);
+}

package/scripts/lib/renderers/pi-agent.mjs

@@ -0,0 +1,17 @@
+import { wrap } from './_util.mjs';
+
+/**
+ * pi-agent expects each rule in its own directory as RULES.md with a
+ * frontmatter carrying `name`, `description`, and optionally `tools`.
+ */
+export function renderPiAgent(rule, _harness) {
+    const d = rule.data;
+    const fm = {
+        name: d.name,
+        description: d.description,
+    };
+    if (Array.isArray(d.tools) && d.tools.length > 0) {
+        fm.tools = d.tools;
+    }
+    return wrap(fm, rule.body);
+}

package/scripts/validate.mjs

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import Ajv from 'ajv';
+import { readRules } from './lib/frontmatter.mjs';
+
+const RULES_DIR = process.env.RULES_DIR || 'rules';
+
+const schema = JSON.parse(await readFile(join(RULES_DIR, '_schema.json'), 'utf8'));
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validate = ajv.compile(schema);
+
+const rules = await readRules(RULES_DIR);
+
+if (rules.length === 0) {
+    console.error(`❌ No rules found in ${RULES_DIR}`);
+    process.exit(1);
+}
+
+const seen = new Set();
+let failures = 0;
+
+for (const rule of rules) {
+    const errors = [];
+
+    if (seen.has(rule.slug)) {
+        errors.push({ instancePath: '/name', message: `duplicate rule name "${rule.slug}"` });
+    }
+    seen.add(rule.slug);
+
+    if (!validate(rule.data)) {
+        for (const e of validate.errors ?? []) {
+            errors.push(e);
+        }
+    }
+
+    if (errors.length > 0) {
+        failures++;
+        console.error(`❌ ${rule.source}`);
+        for (const e of errors) {
+            console.error(`   ${e.instancePath || '/'} ${e.message}`);
+        }
+    } else {
+        console.log(`✅ ${rule.source}`);
+    }
+}
+
+if (failures > 0) {
+    console.error(`\n💥 ${failures}/${rules.length} rule(s) failed validation.`);
+    process.exit(1);
+}
+
+console.log(`\n🎉 ${rules.length} rule(s) validated successfully.`);