@bossmissing/agent-meta 0.1.0

package/dist/core/errors.d.ts

@@ -0,0 +1,12 @@
+export declare const EXIT_CODES: {
+    readonly OK: 0;
+    readonly CHECK_FAILED: 1;
+    readonly BAD_ARGS: 2;
+    readonly CONFIG_UNPARSABLE: 3;
+    readonly IO_ERROR: 4;
+    readonly TEMPLATE_ERROR: 5;
+};
+export declare class MetaError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/core/errors.js

@@ -0,0 +1,16 @@
+export const EXIT_CODES = {
+    OK: 0,
+    CHECK_FAILED: 1,
+    BAD_ARGS: 2,
+    CONFIG_UNPARSABLE: 3,
+    IO_ERROR: 4,
+    TEMPLATE_ERROR: 5,
+};
+export class MetaError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_CODES.CHECK_FAILED) {
+        super(message);
+        this.name = "MetaError";
+        this.exitCode = exitCode;
+    }
+}

package/dist/core/filesystem.d.ts

@@ -0,0 +1,33 @@
+export type FileActionType = "create" | "update" | "skip" | "backup";
+export interface FileAction {
+    type: FileActionType;
+    /** Path relative to the writer's root. */
+    path: string;
+}
+/**
+ * All file writes go through this class so that --dry-run can report the
+ * exact set of files that would be created or updated without touching disk.
+ */
+export declare class FileWriter {
+    readonly root: string;
+    readonly dryRun: boolean;
+    readonly actions: FileAction[];
+    constructor(root: string, dryRun?: boolean);
+    private rel;
+    private abs;
+    exists(p: string): boolean;
+    /** Write a new file; skips when the file exists (unless overwrite). */
+    write(p: string, content: string, opts?: {
+        overwrite?: boolean;
+    }): FileAction;
+    /**
+     * Exclusive create: fails if the file already exists, even in a race
+     * between two concurrent processes (uses the wx flag).
+     */
+    writeExclusive(p: string, content: string): FileAction;
+    backup(p: string): FileAction;
+    mkdir(p: string): void;
+    created(): FileAction[];
+    updated(): FileAction[];
+    skipped(): FileAction[];
+}

package/dist/core/filesystem.js

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * All file writes go through this class so that --dry-run can report the
+ * exact set of files that would be created or updated without touching disk.
+ */
+export class FileWriter {
+    root;
+    dryRun;
+    actions = [];
+    constructor(root, dryRun = false) {
+        this.root = root;
+        this.dryRun = dryRun;
+    }
+    rel(p) {
+        return path.isAbsolute(p) ? path.relative(this.root, p) : p;
+    }
+    abs(p) {
+        return path.isAbsolute(p) ? p : path.join(this.root, p);
+    }
+    exists(p) {
+        return fs.existsSync(this.abs(p));
+    }
+    /** Write a new file; skips when the file exists (unless overwrite). */
+    write(p, content, opts = {}) {
+        const abs = this.abs(p);
+        const rel = this.rel(p);
+        const exists = fs.existsSync(abs);
+        if (exists && !opts.overwrite) {
+            const action = { type: "skip", path: rel };
+            this.actions.push(action);
+            return action;
+        }
+        const action = { type: exists ? "update" : "create", path: rel };
+        if (!this.dryRun) {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, content, "utf8");
+        }
+        this.actions.push(action);
+        return action;
+    }
+    /**
+     * Exclusive create: fails if the file already exists, even in a race
+     * between two concurrent processes (uses the wx flag).
+     */
+    writeExclusive(p, content) {
+        const abs = this.abs(p);
+        const rel = this.rel(p);
+        if (this.dryRun) {
+            if (fs.existsSync(abs))
+                throw new Error(`File already exists: ${rel}`);
+            const action = { type: "create", path: rel };
+            this.actions.push(action);
+            return action;
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        try {
+            fs.writeFileSync(abs, content, { encoding: "utf8", flag: "wx" });
+        }
+        catch (e) {
+            if (e.code === "EEXIST") {
+                throw new Error(`File already exists: ${rel}`);
+            }
+            throw e;
+        }
+        const action = { type: "create", path: rel };
+        this.actions.push(action);
+        return action;
+    }
+    backup(p) {
+        const abs = this.abs(p);
+        const rel = this.rel(p);
+        const action = { type: "backup", path: `${rel}.bak` };
+        if (!this.dryRun)
+            fs.copyFileSync(abs, `${abs}.bak`);
+        this.actions.push(action);
+        return action;
+    }
+    mkdir(p) {
+        if (!this.dryRun)
+            fs.mkdirSync(this.abs(p), { recursive: true });
+    }
+    created() {
+        return this.actions.filter((a) => a.type === "create");
+    }
+    updated() {
+        return this.actions.filter((a) => a.type === "update");
+    }
+    skipped() {
+        return this.actions.filter((a) => a.type === "skip");
+    }
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,19 @@
+export interface ParsedDoc {
+    file: string;
+    data: Record<string, unknown>;
+    content: string;
+    hasFrontmatter: boolean;
+    parseError: string | null;
+}
+export declare function parseDocFile(absPath: string): ParsedDoc;
+/** Extract markdown heading texts (any level) from content. */
+export declare function extractHeadings(content: string): string[];
+/** True if any heading contains one of the given texts (case-insensitive). */
+export declare function hasSection(content: string, names: string[]): boolean;
+/**
+ * True if there is any non-empty, non-comment body text under a matching
+ * heading. Sub-headings (deeper levels) belong to the section, so their body
+ * text counts; the section ends at the next heading of the same or shallower
+ * level.
+ */
+export declare function sectionHasContent(content: string, names: string[]): boolean;

package/dist/core/frontmatter.js

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import matter from "gray-matter";
+export function parseDocFile(absPath) {
+    const raw = fs.readFileSync(absPath, "utf8");
+    const hasFrontmatter = /^---\r?\n/.test(raw);
+    try {
+        const parsed = matter(raw);
+        return {
+            file: absPath,
+            data: parsed.data ?? {},
+            content: parsed.content,
+            hasFrontmatter,
+            parseError: null,
+        };
+    }
+    catch (e) {
+        return {
+            file: absPath,
+            data: {},
+            content: raw,
+            hasFrontmatter,
+            parseError: e.message,
+        };
+    }
+}
+/** Extract markdown heading texts (any level) from content. */
+export function extractHeadings(content) {
+    const headings = [];
+    let inFence = false;
+    for (const line of content.split(/\r?\n/)) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const m = /^#{1,6}\s+(.+?)\s*$/.exec(line);
+        if (m)
+            headings.push(m[1]);
+    }
+    return headings;
+}
+/** True if any heading contains one of the given texts (case-insensitive). */
+export function hasSection(content, names) {
+    const headings = extractHeadings(content).map((h) => h.toLowerCase());
+    return names.some((n) => headings.some((h) => h.includes(n.toLowerCase())));
+}
+/**
+ * True if there is any non-empty, non-comment body text under a matching
+ * heading. Sub-headings (deeper levels) belong to the section, so their body
+ * text counts; the section ends at the next heading of the same or shallower
+ * level.
+ */
+export function sectionHasContent(content, names) {
+    const lines = content.split(/\r?\n/);
+    let capturing = false;
+    let sectionLevel = 0;
+    let inFence = false;
+    for (const line of lines) {
+        if (/^\s*(```|~~~)/.test(line))
+            inFence = !inFence;
+        const m = !inFence ? /^(#{1,6})\s+(.+?)\s*$/.exec(line) : null;
+        if (m) {
+            const level = m[1].length;
+            if (names.some((n) => m[2].toLowerCase().includes(n.toLowerCase()))) {
+                capturing = true;
+                sectionLevel = level;
+            }
+            else if (capturing && level <= sectionLevel) {
+                capturing = false;
+            }
+            continue;
+        }
+        if (!capturing)
+            continue;
+        const text = line
+            .replace(/<!--[\s\S]*?-->/g, "")
+            .replace(/^[-*+]\s*/, "")
+            .trim();
+        if (text.length > 0 && !/^<!--/.test(line.trim()))
+            return true;
+    }
+    return false;
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,8 @@
+export declare const logger: {
+    ok(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    info(msg: string): void;
+    heading(msg: string): void;
+    blank(): void;
+};

package/dist/core/logger.js

@@ -0,0 +1,22 @@
+import pc from "picocolors";
+export const logger = {
+    ok(msg) {
+        console.log(`${pc.green("✓")} ${msg}`);
+    },
+    warn(msg) {
+        console.log(`${pc.yellow("WARN")} ${msg}`);
+    },
+    error(msg) {
+        console.error(`${pc.red("✗")} ${msg}`);
+    },
+    info(msg) {
+        console.log(msg);
+    },
+    heading(msg) {
+        console.log(pc.bold(msg));
+        console.log();
+    },
+    blank() {
+        console.log();
+    },
+};

package/dist/core/paths.d.ts

@@ -0,0 +1,8 @@
+/** Convert an arbitrary name ("Payment Callback", "withdrawal_v2") to kebab-case. */
+export declare function slugify(input: string): string;
+export declare function todayISO(): string;
+/** Days elapsed since the given YYYY-MM-DD date; NaN when unparsable. */
+export declare function daysSince(dateStr: string): number;
+export declare function isValidISODate(value: unknown): boolean;
+/** Normalize a frontmatter date value (gray-matter may parse it as Date). */
+export declare function dateValueToString(value: unknown): string | null;

package/dist/core/paths.js

@@ -0,0 +1,39 @@
+/** Convert an arbitrary name ("Payment Callback", "withdrawal_v2") to kebab-case. */
+export function slugify(input) {
+    const slug = input
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return slug;
+}
+export function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Days elapsed since the given YYYY-MM-DD date; NaN when unparsable. */
+export function daysSince(dateStr) {
+    const d = new Date(`${dateStr}T00:00:00Z`);
+    if (Number.isNaN(d.getTime()))
+        return NaN;
+    return Math.floor((Date.now() - d.getTime()) / 86_400_000);
+}
+export function isValidISODate(value) {
+    if (value instanceof Date)
+        return !Number.isNaN(value.getTime());
+    if (typeof value !== "string")
+        return false;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    return !Number.isNaN(new Date(`${value}T00:00:00Z`).getTime());
+}
+/** Normalize a frontmatter date value (gray-matter may parse it as Date). */
+export function dateValueToString(value) {
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString().slice(0, 10);
+    }
+    if (typeof value === "string" && isValidISODate(value))
+        return value;
+    return null;
+}

package/dist/core/risk.d.ts

@@ -0,0 +1,3 @@
+/** Returns the risk keywords matched by the given name/title, empty when low-risk. */
+export declare function matchRiskKeywords(name: string, keywords: string[]): string[];
+export declare function isHighRisk(name: string, keywords: string[]): boolean;

package/dist/core/risk.js

@@ -0,0 +1,8 @@
+/** Returns the risk keywords matched by the given name/title, empty when low-risk. */
+export function matchRiskKeywords(name, keywords) {
+    const lower = name.toLowerCase();
+    return keywords.filter((k) => lower.includes(k.toLowerCase()));
+}
+export function isHighRisk(name, keywords) {
+    return matchRiskKeywords(name, keywords).length > 0;
+}

package/dist/core/templates.d.ts

@@ -0,0 +1,10 @@
+import { type TemplateName } from "../templates/index.js";
+export type TemplateVars = Record<string, string>;
+/** Simple {{variable}} substitution; unknown variables are replaced with "". */
+export declare function renderTemplate(template: string, vars: TemplateVars): string;
+/**
+ * Resolve a template by name: a project-level override under
+ * `<templatesDir>/<name>.tmpl` wins over the built-in template.
+ */
+export declare function loadTemplate(name: TemplateName, root: string, templatesDir: string): string;
+export declare function renderNamedTemplate(name: TemplateName, root: string, templatesDir: string, vars: TemplateVars): string;

package/dist/core/templates.js

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+import { EXIT_CODES, MetaError } from "./errors.js";
+import { BUILTIN_TEMPLATES } from "../templates/index.js";
+/** Simple {{variable}} substitution; unknown variables are replaced with "". */
+export function renderTemplate(template, vars) {
+    return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => vars[key] ?? "");
+}
+/**
+ * Resolve a template by name: a project-level override under
+ * `<templatesDir>/<name>.tmpl` wins over the built-in template.
+ */
+export function loadTemplate(name, root, templatesDir) {
+    const override = path.join(root, templatesDir, `${name}.tmpl`);
+    if (fs.existsSync(override)) {
+        try {
+            return fs.readFileSync(override, "utf8");
+        }
+        catch (e) {
+            throw new MetaError(`Cannot read template override ${override}: ${e.message}`, EXIT_CODES.TEMPLATE_ERROR);
+        }
+    }
+    const builtin = BUILTIN_TEMPLATES[name];
+    if (!builtin) {
+        throw new MetaError(`Unknown template: ${name}`, EXIT_CODES.TEMPLATE_ERROR);
+    }
+    return builtin;
+}
+export function renderNamedTemplate(name, root, templatesDir, vars) {
+    return renderTemplate(loadTemplate(name, root, templatesDir), vars);
+}

package/dist/core/types.d.ts

@@ -0,0 +1,21 @@
+export type Severity = "error" | "warning" | "info";
+export interface MetaIssue {
+    code: string;
+    severity: Severity;
+    file?: string;
+    line?: number;
+    message: string;
+    suggestion?: string;
+}
+export type CheckStatus = "passed" | "passed_with_warnings" | "failed";
+export interface MetaCheckResult {
+    status: CheckStatus;
+    issues: MetaIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+        infos: number;
+        checkedFiles: number;
+    };
+}
+export declare function summarize(issues: MetaIssue[], checkedFiles: number): MetaCheckResult;

package/dist/core/types.js

@@ -0,0 +1,7 @@
+export function summarize(issues, checkedFiles) {
+    const errors = issues.filter((i) => i.severity === "error").length;
+    const warnings = issues.filter((i) => i.severity === "warning").length;
+    const infos = issues.filter((i) => i.severity === "info").length;
+    const status = errors > 0 ? "failed" : warnings > 0 ? "passed_with_warnings" : "passed";
+    return { status, issues, summary: { errors, warnings, infos, checkedFiles } };
+}

package/dist/generators/adr-generator.d.ts

@@ -0,0 +1,11 @@
+export declare const ADR_FILE_RE: RegExp;
+export interface AdrFileInfo {
+    file: string;
+    number: number;
+    numberStr: string;
+    slug: string;
+}
+export declare function listAdrFiles(adrDirAbs: string): AdrFileInfo[];
+/** Next ADR number = max existing valid number + 1. Deleted numbers are never reused. */
+export declare function nextAdrNumber(adrDirAbs: string): number;
+export declare function padAdrNumber(n: number, padding: number): string;

package/dist/generators/adr-generator.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import path from "node:path";
+export const ADR_FILE_RE = /^(\d{4,})-(.+)\.md$/;
+export function listAdrFiles(adrDirAbs) {
+    if (!fs.existsSync(adrDirAbs))
+        return [];
+    return fs
+        .readdirSync(adrDirAbs)
+        .filter((f) => ADR_FILE_RE.test(f))
+        .map((f) => {
+        const m = ADR_FILE_RE.exec(f);
+        return { file: path.join(adrDirAbs, f), number: parseInt(m[1], 10), numberStr: m[1], slug: m[2] };
+    })
+        .sort((a, b) => a.number - b.number);
+}
+/** Next ADR number = max existing valid number + 1. Deleted numbers are never reused. */
+export function nextAdrNumber(adrDirAbs) {
+    const files = listAdrFiles(adrDirAbs);
+    if (files.length === 0)
+        return 1;
+    return Math.max(...files.map((f) => f.number)) + 1;
+}
+export function padAdrNumber(n, padding) {
+    return String(n).padStart(padding, "0");
+}

package/dist/generators/index-generator.d.ts

@@ -0,0 +1,6 @@
+import type { MetaConfig } from "../schemas/config.schema.js";
+import type { FileWriter } from "../core/filesystem.js";
+export declare function buildDomainIndexTable(root: string, config: MetaConfig): string;
+export declare function buildAdrIndexTable(root: string, config: MetaConfig): string;
+export declare function updateDomainIndex(writer: FileWriter, root: string, config: MetaConfig): void;
+export declare function updateAdrIndex(writer: FileWriter, root: string, config: MetaConfig): void;

package/dist/generators/index-generator.js

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseDocFile } from "../core/frontmatter.js";
+import { dateValueToString } from "../core/paths.js";
+import { listAdrFiles } from "./adr-generator.js";
+import { renderNamedTemplate } from "../core/templates.js";
+import { todayISO } from "../core/paths.js";
+const DOMAIN_MARKERS = ["<!-- meta:domain-index:start -->", "<!-- meta:domain-index:end -->"];
+const ADR_MARKERS = ["<!-- meta:adr-index:start -->", "<!-- meta:adr-index:end -->"];
+function replaceBetweenMarkers(content, [start, end], body) {
+    const startIdx = content.indexOf(start);
+    const endIdx = content.indexOf(end);
+    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+        // No markers: append a managed section at the end.
+        return `${content.trimEnd()}\n\n${start}\n${body}\n${end}\n`;
+    }
+    return (content.slice(0, startIdx + start.length) + "\n" + body + "\n" + content.slice(endIdx));
+}
+function frontmatterStr(data, key) {
+    const v = data[key];
+    if (Array.isArray(v))
+        return v.join(", ");
+    if (v instanceof Date)
+        return v.toISOString().slice(0, 10);
+    if (v === undefined || v === null)
+        return "";
+    return String(v);
+}
+export function buildDomainIndexTable(root, config) {
+    const domainDir = path.join(root, config.paths.domain_docs);
+    const rows = [];
+    if (fs.existsSync(domainDir)) {
+        const dirs = fs
+            .readdirSync(domainDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .sort();
+        for (const dir of dirs) {
+            const readme = path.join(domainDir, dir, "README.md");
+            if (!fs.existsSync(readme)) {
+                rows.push(`| [${dir}](./${dir}/) | — | — | — |`);
+                continue;
+            }
+            const doc = parseDocFile(readme);
+            const title = frontmatterStr(doc.data, "title") || dir;
+            rows.push(`| [${title}](./${dir}/README.md) | ${frontmatterStr(doc.data, "status")} | ${frontmatterStr(doc.data, "owner")} | ${dateValueToString(doc.data["last_reviewed"]) ?? frontmatterStr(doc.data, "last_reviewed")} |`);
+        }
+    }
+    return [
+        "| Domain | Status | Owner | Last Reviewed |",
+        "|---|---|---|---|",
+        ...rows,
+    ].join("\n");
+}
+export function buildAdrIndexTable(root, config) {
+    const adrDir = path.join(root, config.paths.adr_docs);
+    const rows = listAdrFiles(adrDir).map((info) => {
+        const doc = parseDocFile(info.file);
+        const title = frontmatterStr(doc.data, "title") || info.slug;
+        const rel = path.basename(info.file);
+        return `| ${info.numberStr} | [${title}](./${rel}) | ${frontmatterStr(doc.data, "status")} | ${dateValueToString(doc.data["date"]) ?? frontmatterStr(doc.data, "date")} |`;
+    });
+    return ["| # | Title | Status | Date |", "|---|---|---|---|", ...rows].join("\n");
+}
+function updateIndexFile(writer, relPath, markers, table, templateName, root, config) {
+    const abs = path.join(root, relPath);
+    let content;
+    if (fs.existsSync(abs)) {
+        content = fs.readFileSync(abs, "utf8");
+    }
+    else {
+        content = renderNamedTemplate(templateName, root, config.paths.templates, {
+            owner: config.project.name || "team",
+            date: todayISO(),
+        });
+    }
+    const updated = replaceBetweenMarkers(content, markers, table);
+    writer.write(relPath, updated, { overwrite: true });
+}
+export function updateDomainIndex(writer, root, config) {
+    const rel = path.join(config.paths.domain_docs, "README.md");
+    updateIndexFile(writer, rel, DOMAIN_MARKERS, buildDomainIndexTable(root, config), "domain-index-readme.md", root, config);
+}
+export function updateAdrIndex(writer, root, config) {
+    const rel = path.join(config.paths.adr_docs, "README.md");
+    updateIndexFile(writer, rel, ADR_MARKERS, buildAdrIndexTable(root, config), "adr-index-readme.md", root, config);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { runCheck, checkExitCode, toJsonOutput } from "./commands/check.js";
+export { runInit } from "./commands/init.js";
+export { runNewDomain } from "./commands/new-domain.js";
+export { runNewAdr } from "./commands/new-adr.js";
+export { runAudit } from "./commands/audit.js";
+export { runSync } from "./commands/sync.js";
+export { loadConfig, CONFIG_FILENAME } from "./core/config.js";
+export { configSchema, DEFAULT_CONFIG, type MetaConfig } from "./schemas/config.schema.js";
+export type { MetaIssue, MetaCheckResult, Severity } from "./core/types.js";
+export { slugify } from "./core/paths.js";
+export { nextAdrNumber, padAdrNumber, listAdrFiles } from "./generators/adr-generator.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { runCheck, checkExitCode, toJsonOutput } from "./commands/check.js";
+export { runInit } from "./commands/init.js";
+export { runNewDomain } from "./commands/new-domain.js";
+export { runNewAdr } from "./commands/new-adr.js";
+export { runAudit } from "./commands/audit.js";
+export { runSync } from "./commands/sync.js";
+export { loadConfig, CONFIG_FILENAME } from "./core/config.js";
+export { configSchema, DEFAULT_CONFIG } from "./schemas/config.schema.js";
+export { slugify } from "./core/paths.js";
+export { nextAdrNumber, padAdrNumber, listAdrFiles } from "./generators/adr-generator.js";