activate-agentmd 2.4.0

package/src/lib/patterns.js

@@ -0,0 +1,135 @@
+/**
+ * patterns.js
+ *
+ * The free, offline half of `review`: deterministic checks that run over the
+ * added lines of a diff in milliseconds, with no API key and nothing leaving
+ * the machine. Each pattern is high-precision on purpose — a false positive
+ * in CI costs more trust than a missed catch — and names the standard that
+ * explains the rule.
+ *
+ * `files` limits a pattern to extensions; `not` suppresses lines that also
+ * match a safe form (a parameterised query still contains "SELECT").
+ */
+
+"use strict";
+
+const PATTERNS = [
+  {
+    id: "sql-string-interpolation", standard: "Security/sql-injection", severity: "high",
+    files: [".js", ".ts", ".tsx", ".jsx", ".py", ".go", ".rb", ".php"],
+    test: /(SELECT|INSERT|UPDATE|DELETE)\b[^\n]*(\$\{|" ?\+ ?[a-zA-Z_]|' ?\+ ?[a-zA-Z_]|%s|\.format\(|f"[^"]*\{)/i,
+    message: "SQL built by string interpolation — use a parameterised query.",
+  },
+  {
+    id: "select-star", standard: "Database/query-optimization", severity: "low",
+    files: [".js", ".ts", ".tsx", ".py", ".go", ".sql", ".rb", ".php"],
+    test: /\bSELECT\s+\*\s+FROM\b/i,
+    message: "`SELECT *` — name the columns you need.",
+  },
+  {
+    id: "pydantic-v1-api", standard: "Backend/pydantic", severity: "medium", files: [".py"],
+    test: /\.(dict|json|parse_obj|parse_raw)\(|@(validator|root_validator)\b|class Config:/,
+    not: /model_dump|model_validate/,
+    message: "Pydantic v1 API (`.dict()`, `.json()`, `@validator`, `class Config`) — use `model_dump`, `model_validate`, `field_validator`, `ConfigDict`.",
+  },
+  {
+    id: "eval-exec", standard: "Security/command-injection", severity: "high",
+    files: [".js", ".ts", ".tsx", ".py", ".rb", ".php"],
+    test: /(^|[^.\w])(eval|exec)\s*\(/,
+    message: "`eval`/`exec` on runtime data is code injection — parse, don't evaluate.",
+  },
+  {
+    id: "child-process-shell", standard: "Security/command-injection", severity: "high", files: [".js", ".ts"],
+    test: /\b(exec|execSync)\s*\(\s*(`[^`]*\$\{|["'][^"']*["']\s*\+)/,
+    message: "Shell command built from variables — use `execFile`/`spawn` with an argument array.",
+  },
+  {
+    id: "subprocess-shell", standard: "Security/command-injection", severity: "high", files: [".py"],
+    test: /subprocess\.[a-z_]+\([^)]*shell\s*=\s*True/,
+    message: "`shell=True` with a built string is command injection — pass an argument list.",
+  },
+  {
+    id: "weak-hash-for-secrets", standard: "Security/passwords", severity: "high",
+    files: [".js", ".ts", ".py", ".go", ".rb", ".php"],
+    test: /\b(md5|sha1)\s*\(|createHash\(\s*["'](md5|sha1)["']|hashlib\.(md5|sha1)\(/i,
+    message: "MD5/SHA-1 — not for passwords or tokens; use bcrypt/argon2 for passwords, SHA-256+ elsewhere.",
+  },
+  {
+    id: "math-random-token", standard: "Security/secret-management", severity: "high", files: [".js", ".ts", ".tsx"],
+    test: /(token|secret|nonce|otp|session|password)[^\n]*Math\.random\(/i,
+    message: "`Math.random()` is not a CSPRNG — use `crypto.randomBytes` / `crypto.randomUUID`.",
+  },
+  {
+    id: "jwt-decode-without-verify", standard: "Security/jwt", severity: "high", files: [".js", ".ts", ".py"],
+    test: /jwt\.decode\(/,
+    not: /verify/,
+    message: "`jwt.decode` does not verify the signature — use `jwt.verify` (or `decode(..., verify=True)`) before trusting claims.",
+  },
+  {
+    id: "dangerously-set-inner-html", standard: "Security/xss", severity: "medium", files: [".tsx", ".jsx"],
+    test: /dangerouslySetInnerHTML/,
+    message: "`dangerouslySetInnerHTML` — sanitise the HTML (DOMPurify) or render text.",
+  },
+  {
+    id: "cors-wildcard-credentials", standard: "Security/cors", severity: "high", files: [".js", ".ts", ".py", ".go"],
+    test: /Access-Control-Allow-Origin["']?\s*[:,]\s*["']\*["']|origin:\s*["']\*["']|allow_origins\s*=\s*\[\s*["']\*["']\s*\]/,
+    message: "Wildcard CORS origin — allow-list the origins that need access.",
+  },
+  {
+    id: "hardcoded-secret", standard: "Security/secret-management", severity: "high",
+    files: [".js", ".ts", ".tsx", ".py", ".go", ".rb", ".php", ".yml", ".yaml", ".env"],
+    test: /(api[_-]?key|secret|password|token)\s*[:=]\s*["'][A-Za-z0-9_\-/+]{16,}["']/i,
+    not: /process\.env|os\.environ|getenv|\$\{|<[A-Z_]+>|example|placeholder|changeme|xxx/i,
+    message: "Looks like a hard-coded secret — read it from the environment or a secret store.",
+  },
+  {
+    id: "next-sync-request-api", standard: "Frontend/nextjs", severity: "medium", files: [".ts", ".tsx"],
+    test: /\b(cookies|headers)\(\)\.(get|set|getAll|has)\(/,
+    message: "Next.js 15+: `cookies()` / `headers()` are async — `(await cookies()).get(...)`.",
+  },
+  {
+    id: "console-log-in-server", standard: "Backend/logging", severity: "low", files: [".ts", ".js"],
+    test: /^\s*console\.log\(/,
+    message: "`console.log` in server code — use the structured logger.",
+  },
+];
+
+/**
+ * Run the patterns over a unified diff. Only added lines are checked, and the
+ * file's extension must be in the pattern's list. Returns review-shaped
+ * findings: { file, line, severity, standard, rule, issue, fix, pattern }.
+ */
+function runPatterns(diff, installedStandardIds) {
+  const findings = [];
+  let file = null, ext = "", line = 0;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      file = raw.replace(/^\+\+\+ (b\/)?/, "").trim();
+      ext = file.includes(".") ? file.slice(file.lastIndexOf(".")) : "";
+      continue;
+    }
+    if (raw.startsWith("@@")) {
+      const m = /\+(\d+)/.exec(raw);
+      line = m ? Number(m[1]) - 1 : 0;
+      continue;
+    }
+    if (!file || raw.startsWith("---")) continue;
+    if (raw.startsWith("-")) continue;
+    line++;
+    if (!raw.startsWith("+")) continue;
+    const code = raw.slice(1);
+    if (/^\s*(\/\/|#|\*|<!--)/.test(code)) continue; // comments
+    for (const p of PATTERNS) {
+      if (!p.files.includes(ext)) continue;
+      if (!p.test.test(code)) continue;
+      if (p.not && p.not.test(code)) continue;
+      // Only report against standards the project actually installed, unless
+      // the caller passes null to mean "everything".
+      if (installedStandardIds && !installedStandardIds.has(p.standard)) continue;
+      findings.push({ file, line, severity: p.severity, standard: p.standard, rule: p.id, issue: p.message, fix: null, pattern: true });
+    }
+  }
+  return findings;
+}
+
+module.exports = { PATTERNS, runPatterns };

package/src/lib/pro.js

@@ -0,0 +1,149 @@
+/**
+ * pro.js
+ *
+ * The free/Pro boundary, in one file so it can be read in one sitting.
+ *
+ * The rule the boundary follows: **anything that runs entirely on your
+ * machine against the public registry is free, forever.** `init`, `link`,
+ * `list`, `search`, `install`, `update`, `review --fast`, `review --local` —
+ * the whole local loop, no account, no key, no telemetry. Pro is for the
+ * things that cost us money to run or that only a company needs: a private
+ * registry, cloud enforcement, and the deep analysis commands.
+ *
+ * Gating is a wrapper rather than a check inside each command, so the list
+ * below is the single source of truth and a command cannot half-gate itself.
+ */
+
+"use strict";
+
+const pc = require("picocolors");
+const { verify, fingerprint, daysLeft } = require("./license");
+const { resolveKey } = require("./credentials");
+const { cmd } = require("./invocation");
+
+const UPGRADE_URL = process.env.AGENTMD_PRO_URL || "https://agent-dot-md.vercel.app/pro";
+
+/**
+ * Every gated capability, with the sentence shown when it is reached without
+ * a license. Free commands are deliberately absent: a command that is not in
+ * here is free, and adding a key to this table is the only way to gate one.
+ */
+const PRO_FEATURES = {
+  extract: {
+    label: "agentmd extract",
+    pitch: "Reads your repo and writes down the conventions your team repeats in every review.",
+  },
+  "sync:private": {
+    label: "agentmd sync --private",
+    pitch: "Push and pull your company's own standards to a private registry.",
+  },
+  analytics: {
+    label: "agentmd analytics",
+    pitch: "What your standards actually caught, per rule and per week.",
+  },
+  "ci:cloud": {
+    label: "agentmd ci --cloud --preview",
+    pitch: "Hosted pull-request enforcement, with no API key in your CI secrets. Private preview.",
+  },
+};
+
+/**
+ * Current entitlement.
+ *
+ * `{ pro, plan, claims, source, reason }`. `reason` is set only when a key was
+ * found and rejected, so "no key" and "bad key" stay distinguishable — they
+ * need different advice.
+ */
+function status(cwd = process.cwd()) {
+  const { key, source } = resolveKey(cwd);
+  if (!key) return { pro: false, plan: "free", claims: null, source: null, reason: null, key: null };
+
+  const result = verify(key);
+  if (!result.valid) {
+    return { pro: false, plan: "free", claims: result.claims ?? null, source, reason: result.reason, key };
+  }
+  return { pro: true, plan: result.claims.plan, claims: result.claims, source, reason: null, key };
+}
+
+const isPro = (cwd) => status(cwd).pro;
+
+/** Open a URL in the user's browser. Best effort: never fails the command. */
+function openBrowser(url) {
+  // Opening a browser is a courtesy, not the point of the command. A headless
+  // box, a locked-down CI runner or a missing xdg-open must not turn a
+  // paywall message into a crash, so failures are swallowed and the URL is
+  // always printed for the user to copy.
+  if (process.env.AGENTMD_NO_BROWSER || process.env.CI) return false;
+  const opener =
+    process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : ["xdg-open", [url]];
+  try {
+    const { spawn } = require("child_process");
+    const child = spawn(opener[0], opener[1], { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The paywall itself: what it is, why it costs, and how to get past it. */
+function printUpgrade(featureKey, state) {
+  const feature = PRO_FEATURES[featureKey] || { label: featureKey, pitch: "" };
+  const A = cmd();
+
+  console.log("");
+  console.log(`  ${pc.yellow("✨")} ${pc.bold(feature.label)} is an Agent.md Pro feature.`);
+  if (feature.pitch) console.log(`     ${pc.dim(feature.pitch)}`);
+  console.log("");
+
+  if (state.reason) {
+    // A key was found and rejected. Say which key, and what is wrong with it,
+    // or the user re-pastes the same one and gets the same wall.
+    console.log(`  ${pc.red("✗")} The key from ${pc.white(state.source)} ${pc.red(state.reason)}.`);
+    console.log(`     ${pc.dim(`Key ${fingerprint(state.key)} · replace it with '${A} login'`)}`);
+  } else {
+    console.log(`     ${pc.dim(`Start a free trial: ${pc.underline(UPGRADE_URL)}`)}`);
+    console.log(`     ${pc.dim(`Already have a key? '${A} login' — or set AGENTMD_PRO_KEY in CI.`)}`);
+  }
+
+  console.log("");
+  console.log(`  ${pc.dim("Free, and staying free: init · link · install · update · list · search · review --fast · review --local")}`);
+  console.log("");
+
+  if (!state.reason) openBrowser(UPGRADE_URL);
+}
+
+/**
+ * Wrap a command so it only runs with a license.
+ *
+ * Returns a function with the same signature, so the dispatcher in
+ * bin/agentmd.js does not need to know which commands are gated.
+ *
+ * `process.exitCode` rather than `process.exit()`: the paywall is not a crash,
+ * and an abrupt exit truncates buffered stdout on Windows. 2 distinguishes
+ * "you may not run this" from a command that ran and found problems (1).
+ */
+function requirePro(featureKey, run) {
+  return async function gated(...args) {
+    const state = status();
+    if (!state.pro) {
+      printUpgrade(featureKey, state);
+      process.exitCode = 2;
+      return;
+    }
+
+    // A license nearing its end is worth one line, once it is close enough to
+    // matter. Renewal failing silently is how a CI pipeline breaks on a Monday.
+    const left = daysLeft(state.claims);
+    if (left !== null && left <= 14) {
+      console.log(pc.yellow(`  ! Your Agent.md ${state.plan} license expires in ${left} day${left === 1 ? "" : "s"}.`));
+    }
+
+    return run(...args);
+  };
+}
+
+module.exports = { status, isPro, requirePro, printUpgrade, openBrowser, PRO_FEATURES, UPGRADE_URL };

package/src/lib/ranking.js

@@ -0,0 +1,287 @@
+/**
+ * ranking.js
+ *
+ * Query ranking for `agentmd search`.
+ *
+ * The CLI previously matched substrings against names and categories. Measured
+ * against ten realistic queries it failed six, including the registry's own
+ * flagship content:
+ *
+ *   BMW design → nothing        PostgreSQL → nothing      TDD → nothing
+ *   JWT security → nothing      AI agents → nothing       premium SaaS → nothing
+ *
+ * This is the same algorithm the website uses, ported to CommonJS. It handles
+ * stemming, domain synonyms, transposition typos and multi-word queries where
+ * no single package matches every term.
+ *
+ * Known duplication: src/app/lib/search.ts holds an equivalent implementation
+ * for the browser, because that one is TypeScript, ESM, and reads a different
+ * (smaller) index. Duplicating a pure scoring function is tolerable; the two
+ * must not be allowed to duplicate *data*, which is what caused the registry
+ * to drift from the extension previously.
+ */
+
+"use strict";
+
+/**
+ * Domain synonyms — what people type on the left, what the registry calls it
+ * on the right. Deliberately small: a broad thesaurus makes results worse.
+ */
+const SYNONYMS = {
+  auth: ["authentication", "authorization", "oauth", "jwt"],
+  login: ["authentication", "oauth"],
+  signin: ["authentication", "oauth"],
+  sso: ["oauth", "authentication"],
+  token: ["jwt", "oauth"],
+  password: ["passwords", "authentication"],
+  rbac: ["authorization"],
+
+  db: ["database", "postgres", "mysql", "mongodb", "schema-design"],
+  sql: ["postgres", "mysql", "sql-injection", "query-optimization"],
+  postgresql: ["postgres"],
+  mongo: ["mongodb"],
+  index: ["indexes"],
+  query: ["query-optimization", "queries"],
+
+  k8s: ["kubernetes"],
+  container: ["docker", "docker-compose"],
+  compose: ["docker-compose"],
+  ci: ["cicd", "github-actions"],
+  cd: ["cicd", "deployment"],
+  pipeline: ["cicd", "github-actions"],
+  deploy: ["deployment", "rollback"],
+  infra: ["kubernetes", "docker", "aws"],
+
+  a11y: ["accessibility"],
+  perf: ["performance", "optimization", "caching"],
+  speed: ["performance", "optimization"],
+  slow: ["performance", "query-optimization", "caching"],
+  bundle: ["bundle-size", "code-splitting"],
+  cache: ["caching"],
+
+  sec: ["security", "owasp"],
+  vuln: ["owasp", "security-review", "sql-injection", "xss"],
+  vulnerability: ["owasp", "security-review"],
+  injection: ["sql-injection", "command-injection"],
+  secrets: ["secret-management"],
+  env: ["environments", "secret-management"],
+  ratelimit: ["rate-limiting"],
+  throttle: ["rate-limiting"],
+
+  hallucinate: ["hallucination", "verification", "reasoning"],
+  hallucinating: ["hallucination", "verification"],
+  hallucinations: ["hallucination"],
+  prompt: ["prompt-engineering", "context"],
+  prompting: ["prompt-engineering"],
+  rag: ["context", "memory"],
+  agent: ["agent-rules", "multi-agent", "tool-use"],
+  agents: ["agent-rules", "multi-agent"],
+  tools: ["tool-use"],
+
+  test: ["unit", "integration", "e2e", "test-strategy"],
+  tests: ["unit", "integration", "e2e", "test-strategy"],
+  testing: ["test-strategy", "unit", "e2e"],
+  tdd: ["unit", "test-strategy"],
+
+  ts: ["typescript"],
+  next: ["nextjs"],
+  "next.js": ["nextjs"],
+  css: ["tailwind"],
+  ui: ["client-components", "tailwind"],
+  state: ["state-management"],
+  form: ["forms", "validation"],
+  ssr: ["server-components", "hydration"],
+  rsc: ["server-components"],
+
+  api: ["rest", "graphql", "open-api", "api-security"],
+  gql: ["graphql"],
+  swagger: ["open-api"],
+  webhook: ["webhooks"],
+  queue: ["queues", "background-jobs"],
+  cron: ["background-jobs", "workers"],
+  job: ["background-jobs", "workers"],
+  log: ["logging"],
+  logs: ["logging"],
+  monitor: ["monitoring"],
+  observability: ["monitoring", "logging"],
+  error: ["error-handling"],
+  errors: ["error-handling"],
+
+  docs: ["readme", "api-docs", "architecture-docs"],
+  license: ["license-check"],
+  review: ["code-review", "security-review", "architecture-review"],
+  refactor: ["refactoring", "modernization"],
+  migrate: ["migration", "modernization"],
+  scale: ["horizontal-scaling", "vertical-scaling", "load-balancing"],
+  micro: ["microservices"],
+  arch: ["architecture", "clean-architecture"],
+  saas: ["saas-template", "monetization", "pricing"],
+  premium: ["saas-template", "pricing"],
+};
+
+/** Words carrying no signal in a query like "my app is slow". */
+const STOPWORDS = new Set([
+  "a", "an", "and", "the", "is", "are", "was", "be", "to", "of", "in", "on", "for", "with",
+  "my", "our", "your", "i", "we", "it", "its", "how", "do", "does", "should", "can", "what",
+  "when", "why", "me", "you", "app", "apps", "project", "code", "keeps", "keep", "get",
+  "getting", "make", "makes", "need", "want", "please", "help", "best", "practice", "practices",
+]);
+
+/** Strip common suffixes so "hallucinating" reaches "hallucination". */
+function stem(word) {
+  if (word.length <= 4) return word;
+  for (const suffix of ["ingly", "ating", "ations", "ation", "ings", "ing", "ies", "ied", "es", "ed", "ly", "s"]) {
+    if (word.length - suffix.length >= 4 && word.endsWith(suffix)) return word.slice(0, -suffix.length);
+  }
+  return word;
+}
+
+function normalize(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9.\-\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Damerau-Levenshtein, abandoned past `max`.
+ * Transposition costs one edit — "owsap" is one swap from "owasp", and plain
+ * Levenshtein scored it two, dropping it below the threshold.
+ */
+function editDistance(a, b, max) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+
+  let twoAgo = [];
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const curr = [i];
+    let best = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        curr[j] = Math.min(curr[j], twoAgo[j - 2] + 1);
+      }
+      if (curr[j] < best) best = curr[j];
+    }
+    if (best > max) return max + 1;
+    twoAgo = prev;
+    prev = curr;
+  }
+  return prev[b.length];
+}
+
+/** Typo tolerance scales with word length; short words get none. */
+function fuzzyThreshold(word) {
+  if (word.length <= 4) return 0;
+  if (word.length <= 7) return 1;
+  return 2;
+}
+
+/**
+ * A query token plus everything it should also match, weighted.
+ * Without weights a synonym scored as strongly as the typed word, so
+ * "hallucinating" ranked `verification` above `hallucination`.
+ */
+function expand(word) {
+  const weights = new Map();
+  const consider = (text, weight) => {
+    if (text) weights.set(text, Math.max(weights.get(text) || 0, weight));
+  };
+
+  consider(word, 1);
+  const stemmed = stem(word);
+  if (stemmed !== word) consider(stemmed, 0.95);
+
+  for (const key of [word, stemmed]) {
+    (SYNONYMS[key] || []).forEach((s, i) => consider(s, 0.88 - i * 0.06));
+  }
+  if (word.includes("-")) {
+    for (const part of word.split("-")) if (part.length > 2) consider(part, 0.8);
+  }
+
+  return { raw: word, variants: [...weights].map(([text, weight]) => ({ text, weight })) };
+}
+
+/** Score one token against one field. 0 means no match. */
+function scoreField(token, field, weights) {
+  const [exact, prefix, contains, fuzzy] = weights;
+  let best = 0;
+
+  for (const { text, weight } of token.variants) {
+    if (field === text) {
+      best = Math.max(best, exact * weight);
+      continue;
+    }
+    if (field.startsWith(text)) best = Math.max(best, prefix * weight);
+    else if (field.includes(text)) best = Math.max(best, contains * weight);
+    else {
+      for (const word of field.split(/[\s\-.]+/)) {
+        if (word === text) best = Math.max(best, (exact - 10) * weight);
+        else if (word.startsWith(text) && text.length >= 3) best = Math.max(best, (prefix - 10) * weight);
+      }
+    }
+  }
+  if (best > 0) return best;
+
+  const threshold = fuzzyThreshold(token.raw);
+  if (threshold > 0) {
+    for (const word of field.split(/[\s\-.]+/)) {
+      if (Math.abs(word.length - token.raw.length) > threshold) continue;
+      if (editDistance(token.raw, word, threshold) <= threshold) return fuzzy;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Rank `entries` (registry rows with .preset, .category, .description) for a query.
+ *
+ * Scoring is coordination-weighted rather than a strict AND. Requiring every
+ * token to match returned nothing for "postgres index" and "nextjs server
+ * components", because no single package covers every word.
+ */
+function rank(entries, query) {
+  const normalized = normalize(query);
+  if (!normalized) return [];
+
+  const terms = normalized.split(" ").filter((w) => w && !STOPWORDS.has(w));
+  if (terms.length === 0) return [];
+
+  const tokens = terms.map(expand);
+  const results = [];
+
+  for (const entry of entries) {
+    const name = entry.preset.toLowerCase();
+    const category = entry.category.toLowerCase();
+    const description = (entry.description || "").toLowerCase();
+
+    let total = 0;
+    let matched = 0;
+
+    for (const token of tokens) {
+      const best = Math.max(
+        scoreField(token, name, [100, 72, 52, 38]),
+        scoreField(token, category, [46, 32, 24, 16]),
+        scoreField(token, description, [18, 14, 11, 0])
+      );
+      if (best === 0) continue;
+      matched++;
+      total += best;
+    }
+
+    if (matched === 0) continue;
+
+    total *= 0.45 + 0.55 * (matched / tokens.length);
+    // Shorter names are likelier to be the thing meant: "cors" over "cors-preflight".
+    total += Math.max(0, 12 - name.length / 2);
+
+    results.push({ ...entry, score: total });
+  }
+
+  return results.sort((a, b) => b.score - a.score || a.preset.localeCompare(b.preset));
+}
+
+module.exports = { rank, stem, expand, editDistance, normalize, SYNONYMS, STOPWORDS };