@bossmissing/agent-meta 0.1.0

package/dist/validators/context.d.ts

@@ -0,0 +1,12 @@
+import type { MetaConfig } from "../schemas/config.schema.js";
+import type { MetaIssue } from "../core/types.js";
+export interface ValidatorContext {
+    root: string;
+    config: MetaConfig;
+    /** Whether agent-meta.config.yaml was found on disk. */
+    configFound: boolean;
+}
+export interface ValidatorResult {
+    issues: MetaIssue[];
+    checkedFiles: number;
+}

package/dist/validators/context.js

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

package/dist/validators/docs-validator.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatorContext, ValidatorResult } from "./context.js";
+export declare const VALID_DOC_STATUSES: string[];
+export declare function validateDocs(ctx: ValidatorContext): ValidatorResult;

package/dist/validators/docs-validator.js

@@ -0,0 +1,129 @@
+import path from "node:path";
+import fg from "fast-glob";
+import { parseDocFile } from "../core/frontmatter.js";
+import { dateValueToString, daysSince } from "../core/paths.js";
+export const VALID_DOC_STATUSES = ["draft", "active", "deprecated", "archived"];
+const ARRAY_FIELDS = ["applies_to", "supersedes", "superseded_by", "tags"];
+export function validateDocs(ctx) {
+    const issues = [];
+    const { root, config } = ctx;
+    if (!config.features.docs_frontmatter)
+        return { issues, checkedFiles: 0 };
+    // AGENTS.md files are rule files, not documents — they have their own
+    // validator and the standard template carries no frontmatter.
+    const files = fg.sync(config.validation.require_doc_frontmatter, {
+        cwd: root,
+        dot: false,
+        ignore: ["**/AGENTS.md"],
+    });
+    for (const rel of files.sort()) {
+        const abs = path.join(root, rel);
+        let doc;
+        try {
+            doc = parseDocFile(abs);
+        }
+        catch (e) {
+            issues.push({
+                code: "DOC_UNREADABLE",
+                severity: "error",
+                file: rel,
+                message: `Cannot read file: ${e.message}`,
+            });
+            continue;
+        }
+        if (!doc.hasFrontmatter) {
+            issues.push({
+                code: "DOC_FRONTMATTER_MISSING",
+                severity: "error",
+                file: rel,
+                message: "Document is missing YAML frontmatter",
+                suggestion: "Add frontmatter with title, status, owner and last_reviewed.",
+            });
+            continue;
+        }
+        if (doc.parseError) {
+            issues.push({
+                code: "DOC_FRONTMATTER_INVALID",
+                severity: "error",
+                file: rel,
+                message: `Frontmatter YAML cannot be parsed: ${doc.parseError}`,
+            });
+            continue;
+        }
+        const data = doc.data;
+        for (const field of config.validation.required_frontmatter) {
+            const v = data[field];
+            const missing = v === undefined || v === null || (typeof v === "string" && v.trim() === "");
+            if (missing) {
+                issues.push({
+                    code: `DOC_FRONTMATTER_MISSING_${field.toUpperCase()}`,
+                    severity: "error",
+                    file: rel,
+                    message: `Required frontmatter field '${field}' is missing`,
+                    suggestion: `Add '${field}' to the document frontmatter.`,
+                });
+            }
+        }
+        const status = data["status"];
+        if (typeof status === "string" && !VALID_DOC_STATUSES.includes(status)) {
+            issues.push({
+                code: "DOC_FRONTMATTER_INVALID",
+                severity: "error",
+                file: rel,
+                message: `Invalid status '${status}'`,
+                suggestion: `Use one of: ${VALID_DOC_STATUSES.join(", ")}.`,
+            });
+        }
+        if (data["last_reviewed"] !== undefined && data["last_reviewed"] !== null) {
+            const dateStr = dateValueToString(data["last_reviewed"]);
+            if (!dateStr) {
+                issues.push({
+                    code: "DOC_FRONTMATTER_INVALID",
+                    severity: "error",
+                    file: rel,
+                    message: `'last_reviewed' is not a valid YYYY-MM-DD date`,
+                });
+            }
+            else if (typeof status === "string") {
+                const staleDays = status === "active"
+                    ? config.validation.stale_review_days.active
+                    : status === "draft"
+                        ? config.validation.stale_review_days.draft
+                        : null;
+                if (staleDays !== null) {
+                    const age = daysSince(dateStr);
+                    if (Number.isFinite(age) && age > staleDays) {
+                        issues.push({
+                            code: "DOC_STALE",
+                            severity: "warning",
+                            file: rel,
+                            message: `Document has not been reviewed for ${age} days (expected interval: ${staleDays} days)`,
+                            suggestion: "Review the document and update 'last_reviewed'.",
+                        });
+                    }
+                }
+            }
+        }
+        for (const field of ARRAY_FIELDS) {
+            const v = data[field];
+            if (v !== undefined && v !== null && !Array.isArray(v)) {
+                issues.push({
+                    code: "DOC_FRONTMATTER_INVALID",
+                    severity: "error",
+                    file: rel,
+                    message: `'${field}' must be an array`,
+                });
+            }
+        }
+        const sot = data["source_of_truth"];
+        if (sot !== undefined && sot !== null && typeof sot !== "boolean") {
+            issues.push({
+                code: "DOC_FRONTMATTER_INVALID",
+                severity: "error",
+                file: rel,
+                message: `'source_of_truth' must be a boolean`,
+            });
+        }
+    }
+    return { issues, checkedFiles: files.length };
+}

package/dist/validators/domain-validator.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatorContext, ValidatorResult } from "./context.js";
+export declare function listDomainDirs(root: string, domainDocs: string): string[];
+export declare function validateDomains(ctx: ValidatorContext): ValidatorResult;

package/dist/validators/domain-validator.js

@@ -0,0 +1,132 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseDocFile, hasSection } from "../core/frontmatter.js";
+import { matchRiskKeywords } from "../core/risk.js";
+export function listDomainDirs(root, domainDocs) {
+    const abs = path.join(root, domainDocs);
+    if (!fs.existsSync(abs))
+        return [];
+    return fs
+        .readdirSync(abs, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+}
+export function validateDomains(ctx) {
+    const issues = [];
+    const { root, config } = ctx;
+    const domainDirs = listDomainDirs(root, config.paths.domain_docs);
+    let checkedFiles = 0;
+    for (const domain of domainDirs) {
+        const relDir = path.join(config.paths.domain_docs, domain);
+        const absDir = path.join(root, relDir);
+        checkedFiles++;
+        const readmeAbs = path.join(absDir, "README.md");
+        const rulesAbs = path.join(absDir, "rules.md");
+        const agentsAbs = path.join(absDir, "AGENTS.md");
+        const stateMachineAbs = path.join(absDir, "state-machine.md");
+        const riskHits = matchRiskKeywords(domain, config.risk_keywords);
+        if (!fs.existsSync(readmeAbs)) {
+            issues.push({
+                code: "DOMAIN_README_MISSING",
+                severity: "error",
+                file: relDir,
+                message: `Domain directory has no README.md`,
+                suggestion: `Run \`meta new-domain ${domain} --force\` to create missing files.`,
+            });
+        }
+        else {
+            const readme = parseDocFile(readmeAbs);
+            // A linked state-machine.md must exist.
+            if (/\]\(\.\/?state-machine\.md\)/.test(readme.content) && !fs.existsSync(stateMachineAbs)) {
+                issues.push({
+                    code: "STATE_MACHINE_LINK_BROKEN",
+                    severity: "error",
+                    file: path.join(relDir, "README.md"),
+                    message: "README links to state-machine.md but the file does not exist",
+                });
+            }
+            const owner = readme.data["owner"];
+            const ownerEmpty = owner === undefined ||
+                owner === null ||
+                (typeof owner === "string" && owner.trim() === "") ||
+                (Array.isArray(owner) && owner.length === 0);
+            if (ownerEmpty) {
+                issues.push({
+                    code: "DOMAIN_NO_OWNER",
+                    severity: "warning",
+                    file: path.join(relDir, "README.md"),
+                    message: "Domain README has no owner",
+                });
+            }
+        }
+        if (fs.existsSync(agentsAbs)) {
+            const content = fs.readFileSync(agentsAbs, "utf8");
+            if (!hasSection(content, ["scope"])) {
+                issues.push({
+                    code: "LOCAL_AGENTS_MISSING_SCOPE",
+                    severity: "error",
+                    file: path.join(relDir, "AGENTS.md"),
+                    message: 'Local AGENTS.md is missing a "Scope" section',
+                });
+            }
+            if (!hasSection(content, ["required reading"])) {
+                issues.push({
+                    code: "LOCAL_AGENTS_MISSING_REQUIRED_READING",
+                    severity: "error",
+                    file: path.join(relDir, "AGENTS.md"),
+                    message: 'Local AGENTS.md is missing a "Required Reading" section',
+                });
+            }
+        }
+        if (fs.existsSync(stateMachineAbs)) {
+            const sm = parseDocFile(stateMachineAbs);
+            if (!hasSection(sm.content, ["状态列表", "states"])) {
+                issues.push({
+                    code: "STATE_MACHINE_MISSING_STATES",
+                    severity: "error",
+                    file: path.join(relDir, "state-machine.md"),
+                    message: 'state-machine.md is missing a "状态列表" section',
+                });
+            }
+            if (!hasSection(sm.content, ["状态流转", "transitions"])) {
+                issues.push({
+                    code: "STATE_MACHINE_MISSING_TRANSITIONS",
+                    severity: "error",
+                    file: path.join(relDir, "state-machine.md"),
+                    message: 'state-machine.md is missing a "状态流转" section',
+                });
+            }
+        }
+        if (riskHits.length > 0) {
+            if (!fs.existsSync(rulesAbs)) {
+                issues.push({
+                    code: "HIGH_RISK_DOMAIN_MISSING_RULES",
+                    severity: "warning",
+                    file: relDir,
+                    message: `High-risk domain '${domain}' (matched: ${riskHits.join(", ")}) has no rules.md`,
+                    suggestion: `Run \`meta new-domain ${domain} --force\` to create it.`,
+                });
+            }
+            if (!fs.existsSync(agentsAbs)) {
+                issues.push({
+                    code: "HIGH_RISK_DOMAIN_MISSING_AGENTS",
+                    severity: "warning",
+                    file: relDir,
+                    message: `High-risk domain '${domain}' has no local AGENTS.md`,
+                    suggestion: `Run \`meta new-domain ${domain} --force --with-local-agents\`.`,
+                });
+            }
+            if (!fs.existsSync(stateMachineAbs)) {
+                issues.push({
+                    code: "HIGH_RISK_DOMAIN_MISSING_STATE_MACHINE",
+                    severity: "warning",
+                    file: relDir,
+                    message: `High-risk domain '${domain}' may need a state machine but has none`,
+                    suggestion: `Run \`meta new-domain ${domain} --force --with-state-machine\`.`,
+                });
+            }
+        }
+    }
+    return { issues, checkedFiles };
+}

package/dist/validators/openspec-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidatorContext, ValidatorResult } from "./context.js";
+export declare function validateOpenSpec(ctx: ValidatorContext): ValidatorResult;

package/dist/validators/openspec-validator.js

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+export function validateOpenSpec(ctx) {
+    const issues = [];
+    const { root, config } = ctx;
+    const openspecRel = config.paths.openspec;
+    const openspecAbs = path.join(root, openspecRel);
+    if (config.features.openspec === false)
+        return { issues, checkedFiles: 0 };
+    if (!fs.existsSync(openspecAbs)) {
+        if (config.features.openspec === true) {
+            issues.push({
+                code: "OPENSPEC_CONFIG_MISSING",
+                severity: "error",
+                file: openspecRel,
+                message: "features.openspec is enabled but the openspec/ directory does not exist",
+            });
+            return { issues, checkedFiles: 0 };
+        }
+        return { issues, checkedFiles: 0 };
+    }
+    let checkedFiles = 1;
+    if (!fs.existsSync(path.join(openspecAbs, "config.yaml"))) {
+        issues.push({
+            code: "OPENSPEC_CONFIG_MISSING",
+            severity: "error",
+            file: path.join(openspecRel, "config.yaml"),
+            message: "OpenSpec directory detected but openspec/config.yaml is missing",
+        });
+    }
+    for (const sub of ["specs", "changes"]) {
+        if (!fs.existsSync(path.join(openspecAbs, sub))) {
+            issues.push({
+                code: "OPENSPEC_STRUCTURE_INCOMPLETE",
+                severity: "warning",
+                file: path.join(openspecRel, sub),
+                message: `OpenSpec directory is missing ${sub}/`,
+            });
+        }
+    }
+    // Root AGENTS.md should reference OpenSpec entry points.
+    const rootAgentsAbs = path.join(root, config.paths.root_agents);
+    if (fs.existsSync(rootAgentsAbs)) {
+        checkedFiles++;
+        const content = fs.readFileSync(rootAgentsAbs, "utf8");
+        if (!content.includes("openspec")) {
+            issues.push({
+                code: "AGENTS_MISSING_OPENSPEC_ENTRY",
+                severity: "warning",
+                file: config.paths.root_agents,
+                message: "Root AGENTS.md does not reference openspec/ documentation entry points",
+                suggestion: "Add links to openspec/specs/ and openspec/changes/ in AGENTS.md.",
+            });
+        }
+    }
+    // Each change directory should contain at least a proposal or tasks file.
+    const changesAbs = path.join(openspecAbs, "changes");
+    if (fs.existsSync(changesAbs)) {
+        for (const entry of fs.readdirSync(changesAbs, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            checkedFiles++;
+            const changeDir = path.join(changesAbs, entry.name);
+            const hasCore = ["proposal.md", "tasks.md", "design.md"].some((f) => fs.existsSync(path.join(changeDir, f)));
+            if (!hasCore) {
+                issues.push({
+                    code: "OPENSPEC_CHANGE_INCOMPLETE",
+                    severity: "warning",
+                    file: path.join(openspecRel, "changes", entry.name),
+                    message: "Change directory has none of proposal.md / design.md / tasks.md",
+                });
+            }
+        }
+    }
+    return { issues, checkedFiles };
+}

package/dist/validators/project-validator.d.ts

@@ -0,0 +1,2 @@
+import type { ValidatorContext, ValidatorResult } from "./context.js";
+export declare function validateProject(ctx: ValidatorContext): ValidatorResult;

package/dist/validators/project-validator.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_FILENAME } from "../core/config.js";
+export function validateProject(ctx) {
+    const issues = [];
+    const { root, config } = ctx;
+    if (!ctx.configFound) {
+        issues.push({
+            code: "CONFIG_MISSING",
+            severity: "error",
+            file: CONFIG_FILENAME,
+            message: `${CONFIG_FILENAME} not found`,
+            suggestion: "Run `meta init` to create it.",
+        });
+    }
+    if (!fs.existsSync(path.join(root, config.paths.root_agents))) {
+        issues.push({
+            code: "ROOT_AGENTS_MISSING",
+            severity: "error",
+            file: config.paths.root_agents,
+            message: `Root ${config.paths.root_agents} is missing`,
+            suggestion: "Run `meta init` to generate the root AGENTS.md.",
+        });
+    }
+    for (const [key, rel] of [
+        ["paths.docs", config.paths.docs],
+        ["paths.domain_docs", config.paths.domain_docs],
+        ["paths.adr_docs", config.paths.adr_docs],
+    ]) {
+        if (!fs.existsSync(path.join(root, rel))) {
+            issues.push({
+                code: "PATH_MISSING",
+                severity: "error",
+                file: rel,
+                message: `Configured path does not exist: ${rel} (${key})`,
+                suggestion: `Create the directory or update ${key} in ${CONFIG_FILENAME}.`,
+            });
+        }
+    }
+    return { issues, checkedFiles: 1 };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@bossmissing/agent-meta",
+  "version": "0.1.0",
+  "description": "Agent Meta CLI - manage AI agent collaboration metadata (AGENTS.md, domain docs, ADRs, frontmatter checks)",
+  "keywords": [
+    "cli",
+    "agents",
+    "agents-md",
+    "adr",
+    "documentation",
+    "ai-coding",
+    "openspec",
+    "frontmatter",
+    "metadata"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "meta": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2",
+    "gray-matter": "^4.0.3",
+    "picocolors": "^1.1.0",
+    "yaml": "^2.5.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "packageManager": "pnpm@10.0.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}