@sicilianwildcat/aiready 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 harikrishn4a
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+
+declare const program: Command;
+
+export { program };

package/dist/cli.js

@@ -0,0 +1,488 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  program: () => program
+});
+module.exports = __toCommonJS(cli_exports);
+var import_commander = require("commander");
+
+// src/audit/index.ts
+var import_path2 = require("path");
+
+// src/audit/loader.ts
+var import_path = require("path");
+
+// src/utils/fs.ts
+var import_fs = require("fs");
+function readFile(filePath) {
+  try {
+    return (0, import_fs.readFileSync)(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function listDirs(dirPath) {
+  try {
+    return (0, import_fs.readdirSync)(dirPath, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+function listFiles(dirPath) {
+  try {
+    return (0, import_fs.readdirSync)(dirPath, { withFileTypes: true }).filter((f) => f.isFile()).map((f) => f.name);
+  } catch {
+    return [];
+  }
+}
+function statMtime(filePath) {
+  try {
+    return (0, import_fs.statSync)(filePath).mtime;
+  } catch {
+    return null;
+  }
+}
+
+// src/audit/loader.ts
+function loadRepo(targetDir) {
+  const read = (name) => readFile((0, import_path.join)(targetDir, name));
+  const packageJsonRaw = read("package.json");
+  let packageJson = null;
+  if (packageJsonRaw) {
+    try {
+      packageJson = JSON.parse(packageJsonRaw);
+    } catch {
+    }
+  }
+  const agentsMd = read("AGENTS.md") ?? read("agents.md") ?? read(".agents.md");
+  const architectureMd = read("ARCHITECTURE.md") ?? read("architecture.md");
+  const constraintsMd = read("CONSTRAINTS.md") ?? read("constraints.md");
+  const progressMd = read("PROGRESS.md") ?? read("progress.md");
+  const sessionHandoffMd = read("SESSION-HANDOFF.md") ?? read("session-handoff.md");
+  const progressMdModifiedAt = statMtime((0, import_path.join)(targetDir, "PROGRESS.md")) ?? statMtime((0, import_path.join)(targetDir, "progress.md"));
+  return {
+    agentsMd,
+    architectureMd,
+    constraintsMd,
+    progressMd,
+    sessionHandoffMd,
+    packageJsonRaw,
+    packageJson,
+    srcDirs: listDirs((0, import_path.join)(targetDir, "src")),
+    rootFiles: listFiles(targetDir),
+    progressMdModifiedAt,
+    targetDir
+  };
+}
+
+// src/audit/scorer.ts
+function scoreIdentity(files) {
+  const gaps = [];
+  if (!files.agentsMd) {
+    return {
+      score: 0,
+      gaps: ["No AGENTS.md \u2014 agents have no entry point for this repository"]
+    };
+  }
+  let score = 20;
+  const wordCount = files.agentsMd.split(/\s+/).filter(Boolean).length;
+  if (wordCount >= 50) {
+    score += 20;
+  } else {
+    gaps.push(`AGENTS.md description too short (${wordCount} words, need 50+)`);
+  }
+  if (/^##\s+stack/im.test(files.agentsMd)) {
+    score += 20;
+  } else {
+    gaps.push("No ## Stack section in AGENTS.md");
+  }
+  const hasVersion = typeof files.packageJson?.["version"] === "string" || /v?\d+\.\d+\.\d+/.test(files.agentsMd);
+  if (hasVersion) {
+    score += 20;
+  } else {
+    gaps.push("No version number found in AGENTS.md or package.json");
+  }
+  if (/^##\s+repo\s+structure/im.test(files.agentsMd) || /src\//m.test(files.agentsMd)) {
+    score += 20;
+  } else {
+    gaps.push("No repo structure section in AGENTS.md");
+  }
+  return { score, gaps };
+}
+function scoreVerification(files) {
+  const gaps = [];
+  let score = 0;
+  const hasVerificationSection = files.agentsMd != null && (/^##\s+verification/im.test(files.agentsMd) || /```(?:bash|sh)/.test(files.agentsMd));
+  if (hasVerificationSection) {
+    score += 30;
+  } else {
+    gaps.push("No verification commands section in AGENTS.md");
+  }
+  const npmCommandMatches = files.agentsMd?.match(/npm\s+(?:run\s+\w+|test|install|ci)/g) ?? [];
+  if (npmCommandMatches.length >= 2) {
+    score += 20;
+  } else {
+    gaps.push("Fewer than 2 verification commands documented in AGENTS.md");
+  }
+  const scripts = files.packageJson?.["scripts"];
+  const scriptNames = scripts != null && typeof scripts === "object" ? Object.keys(scripts) : [];
+  if (scriptNames.length >= 2) {
+    score += 30;
+  } else {
+    gaps.push("package.json missing scripts (need at least 2)");
+  }
+  if (scriptNames.includes("build") && scriptNames.includes("test")) {
+    score += 20;
+  } else {
+    gaps.push("package.json missing build or test script");
+  }
+  return { score, gaps };
+}
+function scoreState(files) {
+  const gaps = [];
+  let score = 0;
+  if (files.progressMd) {
+    score += 30;
+    if (/^##\s+(?:completed|in\s+progress|current)/im.test(files.progressMd)) {
+      score += 20;
+    } else {
+      gaps.push("PROGRESS.md lacks structured sections (## Completed / ## In progress)");
+    }
+  } else {
+    gaps.push("No PROGRESS.md \u2014 agents cannot resume sessions without project state");
+  }
+  if (files.sessionHandoffMd) {
+    score += 30;
+  } else {
+    gaps.push("No SESSION-HANDOFF.md \u2014 agents start blind each session");
+  }
+  if (files.progressMdModifiedAt) {
+    const ageMs = Date.now() - files.progressMdModifiedAt.getTime();
+    const ageDays = ageMs / (1e3 * 60 * 60 * 24);
+    if (ageDays <= 7) {
+      score += 20;
+    } else {
+      gaps.push(`PROGRESS.md last updated ${Math.round(ageDays)} days ago (threshold: 7)`);
+    }
+  }
+  return { score, gaps };
+}
+function scoreMemory(files) {
+  const gaps = [];
+  if (!files.architectureMd) {
+    return {
+      score: 0,
+      gaps: ["No ARCHITECTURE.md \u2014 agents cannot navigate the codebase without exploring"]
+    };
+  }
+  let score = 30;
+  const annotatedLines = (files.architectureMd.match(/←/g) ?? []).length;
+  if (annotatedLines >= 3) {
+    score += 30;
+  } else {
+    gaps.push("ARCHITECTURE.md has few module annotations (add \u2190 comments to explain modules)");
+  }
+  if (files.architectureMd.length > 300) {
+    score += 20;
+  } else {
+    gaps.push("ARCHITECTURE.md too short \u2014 add module responsibilities and data flow");
+  }
+  if (/src\//m.test(files.architectureMd)) {
+    score += 20;
+  } else {
+    gaps.push("ARCHITECTURE.md does not reference src/ directory structure");
+  }
+  return { score, gaps };
+}
+function scoreConstraints(files) {
+  const gaps = [];
+  let score = 0;
+  const hasSection = files.constraintsMd != null || /^##\s+constraints/im.test(files.agentsMd ?? "");
+  const constraintContent = files.constraintsMd ?? files.agentsMd ?? "";
+  if (hasSection) {
+    score += 30;
+  } else {
+    gaps.push("No CONSTRAINTS.md and no ## Constraints section in AGENTS.md");
+  }
+  if (/\bMUST\b/.test(constraintContent)) {
+    score += 40;
+  } else {
+    gaps.push("No MUST language in constraints \u2014 use imperative MUST / MUST NOT");
+  }
+  if (/\bMUST NOT\b/.test(constraintContent)) {
+    score += 30;
+  } else {
+    gaps.push("No MUST NOT language in constraints");
+  }
+  return { score, gaps };
+}
+function scoreRepo(files) {
+  const identity = scoreIdentity(files);
+  const verification = scoreVerification(files);
+  const state = scoreState(files);
+  const memory = scoreMemory(files);
+  const constraints = scoreConstraints(files);
+  const overall = Math.round(
+    (identity.score + verification.score + state.score + memory.score + constraints.score) / 5
+  );
+  return { identity, verification, state, memory, constraints, overall };
+}
+
+// src/audit/cross-ref.ts
+function extractNpmRunCommands(content) {
+  const commands = [];
+  const bashBlockRegex = /```(?:bash|sh|shell)\n([\s\S]*?)```/g;
+  let match;
+  while ((match = bashBlockRegex.exec(content)) !== null) {
+    const block = match[1] ?? "";
+    const runMatches = block.match(/npm\s+run\s+(\w[\w-]*)/g) ?? [];
+    for (const cmd of runMatches) {
+      const name = cmd.replace(/^npm\s+run\s+/, "");
+      commands.push(name);
+    }
+  }
+  return [...new Set(commands)];
+}
+function extractDocumentedModules(content) {
+  const moduleRegex = /^\s{2,}(\w[\w-]*)\/\s.*←/gm;
+  const modules = [];
+  let match;
+  while ((match = moduleRegex.exec(content)) !== null) {
+    modules.push(match[1]);
+  }
+  return [...new Set(modules)];
+}
+function checkCommands(files) {
+  if (!files.agentsMd) {
+    return [
+      {
+        name: "commands-in-agents-exist-in-package",
+        passed: false,
+        detail: "No AGENTS.md to extract commands from"
+      }
+    ];
+  }
+  const commands = extractNpmRunCommands(files.agentsMd);
+  if (commands.length === 0) {
+    return [
+      {
+        name: "commands-in-agents-exist-in-package",
+        passed: true,
+        detail: "No npm run commands found in AGENTS.md bash blocks"
+      }
+    ];
+  }
+  const scripts = files.packageJson?.["scripts"];
+  const scriptNames = scripts != null && typeof scripts === "object" ? Object.keys(scripts) : [];
+  const missing = commands.filter((cmd) => !scriptNames.includes(cmd));
+  if (missing.length === 0) {
+    return [
+      {
+        name: "commands-in-agents-exist-in-package",
+        passed: true,
+        detail: `All ${commands.length} npm run command(s) in AGENTS.md found in package.json scripts`
+      }
+    ];
+  }
+  return missing.map((cmd) => ({
+    name: "commands-in-agents-exist-in-package",
+    passed: false,
+    detail: `\`npm run ${cmd}\` in AGENTS.md not found in package.json scripts`
+  }));
+}
+function checkModules(files) {
+  if (!files.architectureMd) {
+    return {
+      name: "architecture-modules-match-src",
+      passed: false,
+      detail: "No ARCHITECTURE.md to extract documented modules from"
+    };
+  }
+  const documented = extractDocumentedModules(files.architectureMd);
+  if (documented.length === 0) {
+    return {
+      name: "architecture-modules-match-src",
+      passed: true,
+      detail: "No annotated module directories found in ARCHITECTURE.md"
+    };
+  }
+  const missing = documented.filter((mod) => !files.srcDirs.includes(mod));
+  if (missing.length === 0) {
+    return {
+      name: "architecture-modules-match-src",
+      passed: true,
+      detail: `All ${documented.length} documented module(s) found in src/`
+    };
+  }
+  return {
+    name: "architecture-modules-match-src",
+    passed: false,
+    detail: `Module(s) in ARCHITECTURE.md not found in src/: ${missing.join(", ")}`
+  };
+}
+function checkProgressFreshness(files) {
+  if (!files.progressMdModifiedAt) {
+    return {
+      name: "progress-md-is-fresh",
+      passed: false,
+      detail: "No PROGRESS.md found"
+    };
+  }
+  const ageDays = (Date.now() - files.progressMdModifiedAt.getTime()) / (1e3 * 60 * 60 * 24);
+  if (ageDays <= 7) {
+    return {
+      name: "progress-md-is-fresh",
+      passed: true,
+      detail: `PROGRESS.md updated ${Math.round(ageDays)} day(s) ago`
+    };
+  }
+  return {
+    name: "progress-md-is-fresh",
+    passed: false,
+    detail: `PROGRESS.md last updated ${Math.round(ageDays)} days ago (threshold: 7)`
+  };
+}
+function crossRef(files) {
+  return {
+    checks: [
+      ...checkCommands(files),
+      checkModules(files),
+      checkProgressFreshness(files)
+    ]
+  };
+}
+
+// src/audit/reporter.ts
+function bar(score) {
+  const filled = Math.round(score / 10);
+  return "\u2588".repeat(filled) + "\u2591".repeat(10 - filled);
+}
+function subsystemLine(name, score, gaps) {
+  const scoreStr = String(score).padStart(3);
+  const summary = gaps.length > 0 ? gaps[0] : "All checks passed";
+  return `${name.padEnd(14)}  ${bar(score)}  ${scoreStr}   ${summary}`;
+}
+function getRecommendation(scored) {
+  const subsystems = [
+    { name: "identity", score: scored.identity.score },
+    { name: "verification", score: scored.verification.score },
+    { name: "state", score: scored.state.score },
+    { name: "memory", score: scored.memory.score },
+    { name: "constraints", score: scored.constraints.score }
+  ];
+  const lowest = subsystems.reduce((a, b) => a.score <= b.score ? a : b);
+  const messages = {
+    identity: "Add or expand AGENTS.md so agents understand what this project is.",
+    verification: "Document verification commands so agents can confirm their work is correct.",
+    state: "Add PROGRESS.md and SESSION-HANDOFF.md so agents can resume without starting blind.",
+    memory: "Add ARCHITECTURE.md with module map so agents can navigate without exploring.",
+    constraints: "Add MUST / MUST NOT constraints so agents know what they must never do."
+  };
+  if (lowest.score >= 80) {
+    return "Repository is well-harnessed. Run `npx aiready audit` regularly to catch drift.";
+  }
+  return messages[lowest.name] ?? "Run `npx aiready init` to generate missing artifacts.";
+}
+function collectCriticalGaps(scored, xref) {
+  const gaps = [];
+  for (const [, value] of Object.entries(scored)) {
+    if (typeof value === "object" && "score" in value && "gaps" in value) {
+      const sub = value;
+      if (sub.score < 50) {
+        gaps.push(...sub.gaps.slice(0, 1));
+      }
+    }
+  }
+  for (const check of xref.checks) {
+    if (!check.passed) {
+      gaps.push(check.detail);
+    }
+  }
+  return gaps;
+}
+function report(scored, xref, opts) {
+  if (opts.json) {
+    const out = {
+      overall: scored.overall,
+      subsystems: {
+        identity: scored.identity,
+        verification: scored.verification,
+        state: scored.state,
+        memory: scored.memory,
+        constraints: scored.constraints
+      },
+      crossReference: xref,
+      recommendation: getRecommendation(scored)
+    };
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return;
+  }
+  const lines = [];
+  lines.push(`AI Readiness: ${scored.overall}/100`);
+  lines.push("");
+  lines.push(subsystemLine("identity", scored.identity.score, scored.identity.gaps));
+  lines.push(subsystemLine("verification", scored.verification.score, scored.verification.gaps));
+  lines.push(subsystemLine("state", scored.state.score, scored.state.gaps));
+  lines.push(subsystemLine("memory", scored.memory.score, scored.memory.gaps));
+  lines.push(subsystemLine("constraints", scored.constraints.score, scored.constraints.gaps));
+  const criticalGaps = collectCriticalGaps(scored, xref);
+  if (criticalGaps.length > 0) {
+    lines.push("");
+    lines.push("Critical gaps:");
+    for (const gap of criticalGaps) {
+      lines.push(`  \u2717 ${gap}`);
+    }
+  }
+  lines.push("");
+  lines.push(getRecommendation(scored));
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+// src/audit/index.ts
+function runAudit(target, opts) {
+  const targetDir = (0, import_path2.resolve)(target);
+  const files = loadRepo(targetDir);
+  const scored = scoreRepo(files);
+  const xref = crossRef(files);
+  report(scored, xref, { json: opts.json });
+  if (scored.overall < opts.minScore) {
+    process.exit(1);
+  }
+}
+
+// src/cli.ts
+var program = new import_commander.Command();
+program.name("aiready").description("Audit repositories for AI agent readiness").version("0.1.0");
+program.command("audit").description("Score a repository against the 5 AI-readiness subsystems").option("-t, --target <dir>", "target directory to audit", ".").option("--json", "output results as JSON", false).option("--min-score <n>", "exit 1 if overall score is below this threshold", "70").action((opts) => {
+  runAudit(opts.target, {
+    json: opts.json,
+    minScore: parseInt(opts.minScore, 10)
+  });
+});
+if (require.main === module) {
+  program.parse(process.argv);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  program
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sicilianwildcat/aiready",
+  "version": "0.1.0",
+  "description": "Audit repositories for AI agent readiness",
+  "license": "MIT",
+  "author": "harikrishn4a",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harikrishn4a/aiready.git"
+  },
+  "homepage": "https://github.com/harikrishn4a/aiready#readme",
+  "bugs": {
+    "url": "https://github.com/harikrishn4a/aiready/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "cli",
+    "audit",
+    "harness",
+    "cursor",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "aiready": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}