agentready-design-cli 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import {
+  TIER_LABELS,
+  renderMarkdown,
+  runAssessment
+} from "./chunk-GWF7PSLR.js";
+
+// src/cli.ts
+import { writeFile, mkdir } from "fs/promises";
+import { dirname, resolve } from "path";
+import { existsSync } from "fs";
+import kleur from "kleur";
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let target = ".";
+  let format = "both";
+  let out = ".";
+  let name;
+  let merge;
+  let help = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "-h" || a === "--help") help = true;
+    else if (a === "--format") format = args[++i] ?? "both";
+    else if (a === "--out") out = args[++i] ?? ".";
+    else if (a === "--target") name = args[++i];
+    else if (a === "--merge") merge = args[++i];
+    else if (!a.startsWith("-")) target = a;
+  }
+  return { target, format, out, name, merge, help };
+}
+var HELP = `
+${kleur.bold("agent-ready")} \u2014 score a design system against the Agent-Ready Design rubric.
+
+${kleur.bold("Usage")}
+  npx agentready-design-cli [path] [options]
+
+${kleur.bold("Options")}
+  --format <markdown|json|both>   Output format. Default: both.
+  --out <dir>                     Directory to write reports into. Default: <path>.
+  --target <name>                 Friendly name for the report header.
+  --merge <file.json>             Existing agent-ready-report.json to merge into (re-runs only pending rows).
+  -h, --help                      Show this help.
+
+${kleur.bold("Examples")}
+  npx agentready-design-cli ./packages/ui
+  npx agentready-design-cli ./ds --format markdown --target "Acme UI"
+  npx agentready-design-cli ./ds --merge ./ds/agent-ready-report.json
+`;
+async function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.help) {
+    console.log(HELP);
+    return;
+  }
+  const target = resolve(opts.target);
+  if (!existsSync(target)) {
+    console.error(kleur.red(`\u2716 Target path does not exist: ${target}`));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(kleur.dim(`Scoring ${target} against Agent-Ready Design v0.1...`));
+  const report = await runAssessment({ target, name: opts.name, merge: opts.merge });
+  const outDir = resolve(opts.out);
+  await mkdir(outDir, { recursive: true });
+  if (opts.format === "json" || opts.format === "both") {
+    const p = resolve(outDir, "agent-ready-report.json");
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, JSON.stringify(report, null, 2) + "\n", "utf8");
+    console.log(kleur.green(`\u2713 ${p}`));
+  }
+  if (opts.format === "markdown" || opts.format === "both") {
+    const p = resolve(outDir, "agent-ready-report.md");
+    await writeFile(p, renderMarkdown(report) + "\n", "utf8");
+    console.log(kleur.green(`\u2713 ${p}`));
+  }
+  const r = report.rollup;
+  console.log("");
+  console.log(
+    kleur.bold(
+      `Tier ${r.tier} \u2014 ${TIER_LABELS[r.tier]}  \xB7  floor ${r.foundationalFloor}/4  \xB7  retrieval ${r.retrievalLevel}/4  \xB7  median ${r.overallMedian.toFixed(1)}/4`
+    )
+  );
+  const pendingCount = report.criteria.filter((c) => c.status === "pending").length;
+  if (pendingCount > 0) {
+    console.log(
+      kleur.yellow(
+        `
+${pendingCount} criteria require an agent. Paste prompts/self-assessment.md from the rubric repo to complete the report.`
+      )
+    );
+  }
+}
+main().catch((err) => {
+  console.error(kleur.red("\u2716 "), err);
+  process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Mirror of report.schema.json for TypeScript consumers.
+ * Keep in sync — the JSON Schema is authoritative.
+ */
+
+type CriterionId =
+  | `1.${1 | 2 | 3 | 4}`
+  | `2.${1 | 2 | 3 | 4 | 5}`
+  | `3.${1 | 2 | 3 | 4}`
+  | `4.${1 | 2 | 3}`
+  | `5.${1 | 2 | 3 | 4}`
+  | `6.${1 | 2 | 3}`
+  | `7.${1 | 2 | 3 | 4}`
+  | `8.${1 | 2 | 3 | 4}`;
+
+type Score = 0 | 1 | 2 | 3 | 4;
+type Category = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+type CriterionStatus = "scored" | "pending" | "skipped" | "error";
+type PendingReason = "requires-agent" | "requires-human";
+type ProducerKind = "cli" | "prompt" | "skill" | "merged";
+type EvidenceKind = "file" | "glob" | "command" | "url" | "note";
+type EffortBucket = "hours" | "days" | "weeks" | "months";
+
+interface Evidence {
+  kind: EvidenceKind;
+  path?: string;
+  line?: number;
+  snippet?: string;
+  detail?: string;
+}
+
+interface Criterion {
+  id: CriterionId;
+  category: Category;
+  title: string;
+  score: Score | null;
+  status?: CriterionStatus;
+  pending?: PendingReason;
+  rationale?: string;
+  evidence: Evidence[];
+  suggestion?: string;
+}
+
+interface BacklogItem {
+  title: string;
+  rationale?: string;
+  criteria: CriterionId[];
+  priority: number;
+  estimatedEffort?: EffortBucket;
+}
+
+interface Rollup {
+  foundationalFloor: Score;
+  retrievalLevel: Score;
+  overallMedian: number;
+  tier: 0 | 1 | 2 | 3 | 4;
+  categoryFloors: Partial<Record<`${Category}`, Score>>;
+  categoryMedians: Partial<Record<`${Category}`, number>>;
+}
+
+interface Report {
+  schemaVersion: "0.1.0";
+  rubricVersion: "0.1.0";
+  generatedAt: string;
+  target: { path: string; name?: string; repository?: string };
+  producer: { kind: ProducerKind; name?: string; version?: string };
+  criteria: Criterion[];
+  rollup: Rollup;
+  backlog: BacklogItem[];
+}
+
+type CheckResult = {
+    score: Score | null;
+    status?: CriterionStatus;
+    pending?: PendingReason;
+    rationale?: string;
+    evidence?: Evidence[];
+    suggestion?: string;
+};
+type RubricEntry = {
+    id: CriterionId;
+    category: Category;
+    title: string;
+};
+
+type RunnerOptions = {
+    target: string;
+    name?: string;
+    /** Path to an existing report.json to merge into. If provided, the runner only re-runs checks for criteria the existing report marked `status: "pending"`. */
+    merge?: string;
+};
+declare function runAssessment(opts: RunnerOptions): Promise<Report>;
+
+declare function computeRollup(criteria: Criterion[]): Rollup;
+declare const TIER_LABELS: Record<number, string>;
+declare function generateBacklog(criteria: Criterion[]): BacklogItem[];
+
+declare function renderMarkdown(report: Report): string;
+
+declare const RUBRIC: RubricEntry[];
+declare const TOTAL_CRITERIA: number;
+
+export { type BacklogItem, type Category, type CheckResult, type Criterion, type CriterionId, type CriterionStatus, type EffortBucket, type Evidence, type EvidenceKind, type PendingReason, type ProducerKind, RUBRIC, type Report, type Rollup, type RubricEntry, type Score, TIER_LABELS, TOTAL_CRITERIA, computeRollup, generateBacklog, renderMarkdown, runAssessment };

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import {
+  RUBRIC,
+  TIER_LABELS,
+  TOTAL_CRITERIA,
+  computeRollup,
+  generateBacklog,
+  renderMarkdown,
+  runAssessment
+} from "./chunk-GWF7PSLR.js";
+export {
+  RUBRIC,
+  TIER_LABELS,
+  TOTAL_CRITERIA,
+  computeRollup,
+  generateBacklog,
+  renderMarkdown,
+  runAssessment
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "agentready-design-cli",
+  "version": "0.1.0",
+  "description": "Deterministic checks for the Agent-Ready Design rubric. Run against a design-system repo to score what can be scored without an LLM.",
+  "license": "MIT",
+  "author": "Hunter Gillispie <hunter@builder.io>",
+  "homepage": "https://github.com/hgillispie/Agent-Ready-Design",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hgillispie/Agent-Ready-Design.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "design-system",
+    "ai",
+    "llm",
+    "agent",
+    "rubric",
+    "audit"
+  ],
+  "type": "module",
+  "bin": {
+    "agentready-design-cli": "dist/cli.js",
+    "agent-ready": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CRITERIA.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.2",
+    "kleur": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}