activate-agentmd 2.4.0

package/README.md

@@ -0,0 +1,158 @@
+# activate-agentmd
+
+> The package manager for AI coding-agent engineering standards.
+
+```bash
+npx activate-agentmd init
+```
+
+[![npm](https://img.shields.io/npm/v/activate-agentmd)](https://www.npmjs.com/package/activate-agentmd)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Scans your project, shows what it found, and installs the standards that match.
+
+```
+agentmd  scanning project…
+
+  ✓ Docker                   Dockerfile
+  ✓ TypeScript               tsconfig.json
+  ✓ Prisma                   prisma/
+  ✓ Next.js                  package.json (next)
+  ✓ PostgreSQL               package.json (pg)
+
+Recommended packages for claude:
+
+  Backend        nextjs
+  Database       prisma, orm, migration, schema-design, postgres, indexes
+  Frontend       typescript, nextjs, server-components, routing, react
+  Security       authentication, authorization, oauth, owasp
+  Testing        unit, test-strategy, e2e, accessibility
+
+  31 to install
+
+Install these? [Y/n]
+```
+
+Then wire them into whichever agent you use:
+
+```bash
+npx activate-agentmd link
+```
+
+That writes the installed package list into `CLAUDE.md`, `AGENTS.md`,
+`.cursor/rules/agentmd.mdc`, `GEMINI.md` or
+`.github/copilot-instructions.md` — inside a delimited block, so your own
+content is never touched.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init` | Scan the project, install what matches |
+| `link` | Wire installed packages into your agent config files |
+| `search <query>` | Search names, categories, descriptions |
+| `list [model/category]` | Browse the registry |
+| `list --installed` | What this project has |
+| `info <package>` | Details for one package |
+| `install <package>` | Install a package, or a whole category |
+| `remove <package>` | Uninstall |
+| `outdated` | What's changed upstream, and what you've edited |
+| `update` | Pull current versions |
+| `validate` | Check registry + manifest integrity |
+| `agents` | List supported agent config targets |
+
+Package paths are `<model>/<category>/<package>`. A trailing slash installs the
+whole category:
+
+```bash
+agentmd install claude/Security/owasp    # one
+agentmd install claude/Testing/          # all 11
+```
+
+Full reference:
+[docs/cli.md](https://github.com/Aaditya1273/Agent.md/blob/main/docs/cli.md)
+
+---
+
+## Updates respect your edits
+
+`agentmd update` never overwrites a package you've edited. It reports the
+conflict and leaves it alone until you pass `--force`.
+
+```
+$ agentmd outdated
+
+  ↑  claude/Testing/unit       update available
+  ✎  claude/Security/owasp     edited locally
+
+1 outdated, 1 modified, 24 current
+```
+
+The distinction comes from a SHA-256 checksum recorded at install time.
+
+---
+
+## Where things go
+
+| Path | What |
+| --- | --- |
+| `.agentmd/presets/` | Package content |
+| `.agentmd/manifest.json` | What's installed, with version, checksum and source |
+
+Commit both — that's how a team shares one set of standards, and how changes
+to your agent's instructions show up in code review.
+
+---
+
+## Registry
+
+304 canonical standards, tuned for 11 model families (3,344 total):
+`claude`, `deepseek`, `gemini`, `glm`, `grok`, `kimi`, `minimax`, `mistral`, `open-ai`, `qwen` and `sarvam-ai`.
+
+```bash
+agentmd list claude              # all categories
+agentmd list claude/Security     # packages, with descriptions
+```
+
+---
+
+## Security
+
+This CLI distributes content your agent reads as instructions, so:
+
+- Package content is **never executed** — it's markdown written to disk.
+- HTTPS only; a redirect to plaintext HTTP is refused.
+- Writes are resolved against `.agentmd/presets/` and refuse to escape it.
+- Fetches are bounded by timeout, redirect count and response size.
+- No accounts, no telemetry, one runtime dependency (`picocolors`).
+
+Packages are not signed — see
+[SECURITY.md](https://github.com/Aaditya1273/Agent.md/blob/main/SECURITY.md)
+for the full threat model, including what is *not* guaranteed.
+
+---
+
+## Environment
+
+| Variable | Meaning |
+| --- | --- |
+| `AGENTMD_REGISTRY_BASE` | Override the registry base URL (mirrors, testing) |
+| `AGENTMD_TIMEOUT_MS` | Per-request timeout, default 30000 |
+| `AGENTMD_DEBUG` | Print a stack trace on error |
+
+Requires Node 18+.
+
+---
+
+## Contributing
+
+Adding a package is a directory and one markdown file — see
+[CONTRIBUTING.md](https://github.com/Aaditya1273/Agent.md/blob/main/CONTRIBUTING.md).
+
+```bash
+cd packages/cli && npm ci && npm test
+```
+
+MIT licensed.

package/bin/agentmd.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+/**
+ * agentmd — the package manager for AI coding-agent engineering standards.
+ *
+ * Packages are markdown. `install` fetches them into .agentmd/presets/,
+ * `link` wires them into whichever agent config conventions your project
+ * uses, and `update`/`outdated` keep them current.
+ */
+
+"use strict";
+
+const pc = require("picocolors");
+const pkg = require("../package.json");
+const { cmd } = require("../src/lib/invocation");
+
+/**
+ * How the user invoked us. `npx activate-agentmd` does not put `agentmd` on PATH,
+ * so every example below has to match the form they actually typed — otherwise
+ * the first thing they copy out of --help is `command not found`.
+ */
+const A = cmd();
+
+const HELP = `
+${pc.bold("agentmd")} ${pc.dim("v" + pkg.version)} — engineering standards for AI coding agents
+
+${pc.bold("USAGE")}
+  ${A} <command> [options]
+
+${pc.bold("GETTING STARTED")}
+  ${pc.cyan("init")}                        Scan this project and install what matches
+  ${pc.cyan("link")}                        Wire installed packages into your agent config files
+  ${pc.cyan("extract")} ${pc.yellow("PRO")}                 Derive this repo's unwritten conventions into a local standard
+  ${pc.cyan("review")} ${pc.white("[--base ref]")}         Check a diff against the installed standards (--fast: offline patterns, --local: Ollama)
+  ${pc.cyan("test")}                        Benchmark whether the model actually obeys the installed standards
+
+${pc.bold("FINDING PACKAGES")}
+  ${pc.cyan("search")} ${pc.white("<query>")}              Search names, categories and descriptions
+  ${pc.cyan("list")} ${pc.white("[model[/category]]")}     Browse the registry
+  ${pc.cyan("list")} ${pc.white("--installed")}            Show what this project has
+  ${pc.cyan("info")} ${pc.white("<package>")}              Details for one package
+
+${pc.bold("MANAGING PACKAGES")}
+  ${pc.cyan("install")} ${pc.white("<package>…")}          Install packages, or a whole category
+  ${pc.cyan("remove")} ${pc.white("<package>")}            Uninstall a package
+  ${pc.cyan("outdated")}                    Show packages that have changed upstream
+  ${pc.cyan("update")}                      Pull the current version of each package
+  ${pc.cyan("validate")}                    Check registry and manifest integrity
+  ${pc.cyan("agents")}                      List supported agent config targets
+  ${pc.cyan("ci")}                          Write or check the CI workflow (${pc.yellow("--cloud")}: hosted, private preview)
+
+${pc.bold("ACCOUNT")}
+  ${pc.cyan("login")} ${pc.white("[--key <key>]")}         Sign in with an Agent.md Pro license key
+  ${pc.cyan("logout")}                      Forget the stored key
+  ${pc.cyan("whoami")}                      Show the current plan
+  ${pc.cyan("sync")} ${pc.white("--private")} ${pc.yellow("PRO")}          Push or pull your company's own standards
+  ${pc.cyan("analytics")} ${pc.yellow("PRO")}               What your standards actually caught
+  ${pc.cyan("telemetry")}                   Anonymous usage counters (off by default)
+
+${pc.bold("PACKAGE PATHS")}
+  ${pc.white("<model>/<category>/<package>")}   e.g. ${pc.white("claude/Security/owasp")}
+  ${pc.white("<model>/<category>/")}            installs the whole category
+
+${pc.bold("OPTIONS")}
+  --force        Overwrite existing files / local edits
+  --dry          Show what would happen, change nothing
+  --yes, -y      Skip the confirmation prompt (init)
+  --model=NAME   Choose a model (default: claude)
+  --agent=NAME   Choose link targets, comma-separated, or "all"
+  --help, -h     Show this help
+  --version, -v  Show the version
+
+${pc.bold("FREE AND PRO")}
+  ${pc.dim("Everything local is free, forever: init, link, install, update, list, search,")}
+  ${pc.dim("review --fast and review --local. No account, no key, no telemetry.")}
+  ${pc.dim("Pro adds extract, private sync, analytics and cloud CI — " + (process.env.AGENTMD_PRO_URL || "https://agent-dot-md.vercel.app/pro"))}
+  ${pc.dim("In CI, set AGENTMD_PRO_KEY instead of logging in.")}
+
+${pc.bold("EXAMPLES")}
+  ${pc.dim("# The one-minute path")}
+  ${A} init
+
+  ${pc.dim("# Find and install a specific standard")}
+  ${A} search authentication
+  ${A} install claude/Security/owasp
+  ${A} link
+
+  ${pc.dim("# Install every Testing standard, then keep it current")}
+  ${A} install claude/Testing/
+  ${A} outdated
+
+${pc.dim("  Files are written to .agentmd/presets/, tracked in .agentmd/manifest.json")}
+${pc.dim("  Docs: https://github.com/Aaditya1273/Agent.md")}
+`;
+
+/** Loaded lazily so `--help` and `--version` never parse the 348 KB index. */
+const { requirePro } = require("../src/lib/pro");
+
+const COMMANDS = {
+  init: () => require("../src/commands/init").init,
+  link: () => require("../src/commands/link").link,
+  install: () => require("../src/commands/install").install,
+  remove: () => require("../src/commands/remove").remove,
+  list: () => require("../src/commands/list").list,
+  search: () => require("../src/commands/search").search,
+  info: () => require("../src/commands/info").info,
+  outdated: () => require("../src/commands/outdated").outdated,
+  update: () => require("../src/commands/update").update,
+  validate: () => require("../src/commands/validate").validate,
+  agents: () => require("../src/commands/agents").agents,
+  review: () => require("../src/commands/review").review,
+  test: () => require("../src/commands/test").test,
+  ci: () => require("../src/commands/ci").ci,
+
+  // Account.
+  login: () => require("../src/commands/auth").login,
+  logout: () => require("../src/commands/auth").logout,
+  whoami: () => require("../src/commands/auth").whoami,
+  telemetry: () => require("../src/commands/telemetry").telemetry,
+
+  // Pro. The gate lives here, in one table, rather than inside each command —
+  // so what is paid for can be read at a glance and a command cannot
+  // accidentally half-gate itself. `ci --cloud` gates inside ci.js instead,
+  // because the command itself is free and only that one flag is not.
+  extract: () => requirePro("extract", require("../src/commands/extract").extract),
+  sync: () => requirePro("sync:private", require("../src/commands/sync").sync),
+  analytics: () => requirePro("analytics", require("../src/commands/analytics").analytics),
+};
+
+/** Short forms, plus the names other package managers train people to type. */
+const ALIASES = {
+  i: "install",
+  add: "install",
+  rm: "remove",
+  uninstall: "remove",
+  ls: "list",
+  s: "search",
+  find: "search",
+  show: "info",
+  up: "update",
+  upgrade: "update",
+  check: "outdated",
+  lint: "validate",
+};
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    console.log(HELP);
+    return;
+  }
+  if (argv.includes("--version") || argv.includes("-v")) {
+    console.log(pkg.version);
+    return;
+  }
+
+  const name = ALIASES[argv[0]] || argv[0];
+  const load = Object.prototype.hasOwnProperty.call(COMMANDS, name) ? COMMANDS[name] : null;
+
+  if (!load) {
+    console.error(pc.red(`Unknown command: "${argv[0]}"`));
+    console.error("");
+    console.error(pc.dim("  Available: " + Object.keys(COMMANDS).join(", ")));
+    console.error(pc.dim(`  Run '${A} --help' for usage.`));
+    process.exit(1);
+  }
+
+  // Telemetry is off unless the user opted in; `timed` is a no-op until then.
+  const { timed } = require("../src/lib/telemetry");
+  await timed(name, () => load()(argv.slice(1)));
+
+  // One ask, in one place, after the command succeeded. Throwing above skips
+  // it — a star request stapled to a stack trace is the wrong read of the
+  // room. star.js decides whether this particular moment earned one.
+  require("../src/lib/star").maybeAsk(name);
+}
+
+main().catch((err) => {
+  console.error("");
+  console.error(pc.red("Error: ") + err.message);
+  if (process.env.AGENTMD_DEBUG) console.error(pc.dim(err.stack));
+  else console.error(pc.dim("  Re-run with AGENTMD_DEBUG=1 for a stack trace."));
+  console.error("");
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "activate-agentmd",
+  "version": "2.4.0",
+  "description": "The package manager for AI coding-agent engineering standards. Install, link and update rules across Claude Code, Cursor, Codex, Gemini and Copilot.",
+  "keywords": [
+    "ai",
+    "agent",
+    "agents-md",
+    "claude",
+    "claude-code",
+    "cursor",
+    "cursor-rules",
+    "codex",
+    "copilot",
+    "gemini",
+    "llm",
+    "prompts",
+    "presets",
+    "engineering-standards",
+    "ai-coding"
+  ],
+  "homepage": "https://github.com/Aaditya1273/Agent.md#readme",
+  "bugs": {
+    "url": "https://github.com/Aaditya1273/Agent.md/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aaditya1273/Agent.md.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "agentmd": "bin/agentmd.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "smoke": "node bin/agentmd.js --help >/dev/null && node bin/agentmd.js validate",
+    "start": "node bin/agentmd.js",
+    "prepack": "node scripts/check-publish-safety.js",
+    "safety": "node scripts/check-publish-safety.js",
+    "test:pro": "node scripts/test-pro.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.125.0",
+    "picocolors": "1.1.1"
+  }
+}

package/src/commands/agents.js

@@ -0,0 +1,44 @@
+/**
+ * agents.js
+ *
+ * Handles: agentmd agents
+ *
+ * Lists every agent config convention `agentmd link` can write, and whether
+ * this project already has it. Deliberately short: it lists what is
+ * implemented, not what is planned.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const pc = require("picocolors");
+const { TARGETS } = require("../lib/agents");
+const { cmd } = require("../lib/invocation");
+
+/** How the user invoked us — "npx activate-agentmd" or "agentmd". */
+const A = cmd();
+
+function agents() {
+  const cwd = process.cwd();
+
+  console.log(pc.bold("\nAgent config targets\n"));
+  console.log(pc.dim("  Packages are plain markdown, so any agent can read them. These are the"));
+  console.log(pc.dim(`  config conventions '${A} link' writes automatically.\n`));
+
+  const width = Math.max(...Object.keys(TARGETS).map((k) => k.length));
+  for (const [name, target] of Object.entries(TARGETS)) {
+    const present = fs.existsSync(path.join(cwd, target.file));
+    const mark = present ? pc.green("✓") : pc.dim("·");
+    console.log(
+      `  ${mark} ${pc.cyan(name.padEnd(width))}  ${pc.white(target.file.padEnd(34))} ${pc.dim(target.label)}`
+    );
+  }
+
+  console.log("");
+  console.log(pc.dim("  ✓ = already present in this project"));
+  console.log(pc.dim(`  Write them:  ${A} link --agent=claude,cursor`));
+  console.log(pc.dim(`  Write all:   ${A} link --agent=all\n`));
+}
+
+module.exports = { agents };

package/src/commands/analytics.js

@@ -0,0 +1,128 @@
+/**
+ * analytics.js
+ *
+ * Handles: agentmd analytics [--since 30d] [--json]   (Pro)
+ *
+ * Reads the local ledger `review` writes and answers the question that decides
+ * whether any of this was worth it: which standards actually caught something,
+ * and which have never fired.
+ *
+ * The second half matters more than the first. A rule nobody ever violates is
+ * costing tokens on every prompt and buying nothing, and this is the only
+ * place that says so with a number.
+ */
+
+"use strict";
+
+const pc = require("picocolors");
+const { summarise, read } = require("../lib/analytics");
+const { readManifest } = require("../lib/manifest");
+const { cmd } = require("../lib/invocation");
+
+const A = cmd();
+
+/** `30d`, `12w`, `6m`, or `all`. */
+function parseSince(value) {
+  if (!value || value === "all") return null;
+  const m = /^(\d+)\s*([dwm])$/i.exec(value.trim());
+  if (!m) return undefined; // signals "unparseable" so the caller can complain
+  const days = Number(m[1]) * ({ d: 1, w: 7, m: 30 })[m[2].toLowerCase()];
+  return new Date(Date.now() - days * 86400000);
+}
+
+const flagValue = (args, name) => {
+  const inline = (args || []).find((a) => a.startsWith(`--${name}=`));
+  if (inline) return inline.slice(name.length + 3);
+  const i = (args || []).indexOf(`--${name}`);
+  return i !== -1 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : null;
+};
+
+/** A fixed-width bar for a value against the largest in its column. */
+const bar = (n, max, width = 18) =>
+  pc.dim("▁".repeat(0)) + "█".repeat(Math.max(1, Math.round((n / Math.max(1, max)) * width)));
+
+function analytics(args) {
+  args = args || [];
+  const cwd = process.cwd();
+  const sinceRaw = flagValue(args, "since") || "all";
+  const since = parseSince(sinceRaw);
+
+  if (since === undefined) {
+    console.error(pc.red(`\n  Could not read --since "${sinceRaw}". Use 30d, 12w, 6m or all.\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const ledger = read(cwd);
+  if (ledger.runs.length === 0) {
+    console.log(`\n  ${pc.dim("No review history in this project yet.")}`);
+    console.log(pc.dim(`  Run '${A} review --fast' — it records every run, free and offline.\n`));
+    return;
+  }
+
+  const s = summarise(cwd, since);
+
+  if (args.includes("--json")) {
+    console.log(JSON.stringify(s, null, 2));
+    return;
+  }
+
+  const window = since ? `since ${since.toISOString().slice(0, 10)}` : "all time";
+  console.log(pc.bold(`\nWhat your standards caught ${pc.dim("— " + window)}\n`));
+
+  if (s.runs === 0) {
+    console.log(pc.dim(`  No reviews in that window. ${ledger.runs.length} run(s) recorded overall.\n`));
+    return;
+  }
+
+  console.log(`  ${pc.white(String(s.total).padStart(5))} ${pc.dim("findings across")} ${pc.white(String(s.runs))} ${pc.dim("review" + (s.runs === 1 ? "" : "s"))}`);
+  console.log(`  ${pc.dim("      " + s.patterns + " caught offline by pattern rules — no model, no tokens")}`);
+  console.log("");
+  console.log(
+    `  ${pc.red(String(s.bySeverity.high || 0) + " high")}   ` +
+    `${pc.yellow(String(s.bySeverity.medium || 0) + " medium")}   ` +
+    `${pc.dim(String(s.bySeverity.low || 0) + " low")}`
+  );
+
+  if (s.byStandard.length) {
+    const max = s.byStandard[0][1];
+    console.log(pc.bold("\n  Per standard\n"));
+    for (const [standard, n] of s.byStandard.slice(0, 12)) {
+      console.log(`    ${pc.white(String(n).padStart(4))}  ${pc.dim(bar(n, max))}  ${standard}`);
+    }
+  }
+
+  if (s.byRule.length > 1) {
+    console.log(pc.bold("\n  Most-broken rules\n"));
+    for (const [rule, n] of s.byRule.slice(0, 5)) {
+      console.log(`    ${pc.white(String(n).padStart(4))}  ${rule}`);
+    }
+  }
+
+  // The expensive half: what you are paying context for and getting nothing from.
+  try {
+    const installed = readManifest(cwd).presets.map((p) => `${p.category}/${p.preset}`);
+    const idle = installed.filter((id) => !s.idle.seen.has(id));
+    if (idle.length) {
+      console.log(pc.bold(`\n  Never fired ${pc.dim(`(${idle.length} of ${installed.length} installed)`)}\n`));
+      for (const id of idle.slice(0, 10)) console.log(`    ${pc.dim("·")} ${pc.dim(id)}`);
+      if (idle.length > 10) console.log(pc.dim(`    … and ${idle.length - 10} more`));
+      console.log(pc.dim(`\n    These cost context on every prompt. Drop one with '${A} remove <id>' if it is not`));
+      console.log(pc.dim("    guarding something you simply have not broken yet."));
+    }
+  } catch {
+    // no manifest here — the per-standard table above still stands on its own
+  }
+
+  if (s.byWeek.length > 1) {
+    const max = Math.max(...s.byWeek.map(([, n]) => n));
+    console.log(pc.bold("\n  By week\n"));
+    for (const [week, n] of s.byWeek.slice(-8)) {
+      console.log(`    ${pc.dim(week)}  ${pc.white(String(n).padStart(4))}  ${pc.dim(bar(n, max, 24))}`);
+    }
+  }
+
+  console.log(pc.dim(`\n  Local only — this never leaves your machine. ${A} analytics --json for the raw numbers.\n`));
+}
+
+module.exports = { analytics, parseSince };