harnery 0.32.0 → 0.34.0

package/dist/lib/docs-metadata-sync.js

@@ -0,0 +1,222 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { dump as dumpYaml, JSON_SCHEMA } from "js-yaml";
+import { parseFrontmatter } from "./docs-frontmatter.js";
+import { managedDocsMetadataType } from "./docs-metadata-managed.js";
+import { isDocsMetadataV2, validateDocsMetadataV2 } from "./docs-metadata-v2.js";
+import { sh } from "./exec.js";
+let REPO_ROOT = "";
+let SUBMODULES = [];
+export function initDocsMetadataSyncContext(opts) {
+    REPO_ROOT = opts.repoRoot;
+    SUBMODULES = opts.submodules;
+}
+function targets(repo) {
+    const all = [
+        { name: "(root)", path: REPO_ROOT },
+        ...SUBMODULES.filter((name) => existsSync(join(REPO_ROOT, name, ".git"))).map((name) => ({
+            name,
+            path: resolve(REPO_ROOT, name),
+        })),
+    ];
+    const filter = repo === "." ? "(root)" : repo;
+    const selected = filter ? all.filter((target) => target.name === filter) : all;
+    if (filter && selected.length === 0)
+        throw new Error(`Unknown repository: ${repo}`);
+    return selected;
+}
+async function changedFiles(target, explicit) {
+    if (explicit.length > 0)
+        return explicit;
+    const result = await sh("git diff --cached --name-only --diff-filter=ACMR -- '*.md'", {
+        cwd: target.path,
+    });
+    if (result.exitCode !== 0)
+        throw new Error(result.stderr || "git diff failed");
+    return result.stdout.split("\n").filter(Boolean);
+}
+async function headContent(target, path) {
+    const result = await sh(`git show HEAD:${JSON.stringify(path)}`, { cwd: target.path });
+    return result.exitCode === 0 ? result.stdout : null;
+}
+function semanticMetadata(data) {
+    const copy = { ...data };
+    delete copy.created_at;
+    delete copy.updated_at;
+    delete copy.status_changed_at;
+    delete copy.reviewed_at;
+    delete copy.review_due_at;
+    delete copy.source_updated_at;
+    delete copy.resolved_at;
+    return copy;
+}
+function semanticChanged(before, after) {
+    if (!before || !isDocsMetadataV2(before.data))
+        return false;
+    return (JSON.stringify(semanticMetadata(before.data)) !==
+        JSON.stringify(semanticMetadata(after.data)) ||
+        before.body.replaceAll("\r\n", "\n").trimEnd() !== after.body.replaceAll("\r\n", "\n").trimEnd());
+}
+function serialize(data, body) {
+    const yaml = dumpYaml(data, {
+        schema: JSON_SCHEMA,
+        noRefs: true,
+        lineWidth: -1,
+        sortKeys: false,
+        quotingType: '"',
+    }).trimEnd();
+    return `---\n${yaml}\n---\n${body.replace(/^\n+/, "\n")}`;
+}
+function addDays(value, days) {
+    const date = new Date(value);
+    date.setUTCDate(date.getUTCDate() + days);
+    return date.toISOString().replace(".000Z", "Z");
+}
+export async function runDocsMetadataSync(opts) {
+    const now = opts.now ?? new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const rows = [];
+    for (const target of targets(opts.repo)) {
+        for (const path of await changedFiles(target, opts.files ?? [])) {
+            const full = join(target.path, path);
+            if (!existsSync(full))
+                continue;
+            const currentText = readFileSync(full, "utf8");
+            const current = parseFrontmatter(currentText);
+            if (!managedDocsMetadataType(path, current.data, current.raw !== null))
+                continue;
+            if (!isDocsMetadataV2(current.data)) {
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: "invalid",
+                    fields: [],
+                    message: "managed document must use harnery-doc/v2",
+                });
+                continue;
+            }
+            const beforeText = await headContent(target, path);
+            const before = beforeText === null ? null : parseFrontmatter(beforeText);
+            const contentChanged = semanticChanged(before, current);
+            const beforeV2 = before !== null && isDocsMetadataV2(before.data) ? before.data : null;
+            const statusChanged = beforeV2 !== null && beforeV2.status !== current.data.status;
+            const fields = [];
+            const expected = { ...current.data };
+            if (contentChanged) {
+                expected.updated_at = now;
+                fields.push("updated_at");
+            }
+            if (statusChanged) {
+                expected.status_changed_at = now;
+                fields.push("status_changed_at");
+                if (current.data.status === "resolved" && current.data.type === "issue") {
+                    expected.resolved_at = now;
+                    fields.push("resolved_at");
+                }
+            }
+            if (!statusChanged &&
+                beforeV2 &&
+                current.data.status_changed_at !== beforeV2.status_changed_at) {
+                expected.status_changed_at = beforeV2.status_changed_at;
+                fields.push("status_changed_at");
+            }
+            if (opts.reviewed) {
+                if (current.data.type !== "runbook") {
+                    rows.push({
+                        repo: target.name,
+                        path,
+                        status: "invalid",
+                        fields: [],
+                        message: "--reviewed applies only to runbooks",
+                    });
+                    continue;
+                }
+                expected.reviewed_at = now;
+                expected.review_due_at = addDays(now, 180);
+                expected.updated_at = now;
+                fields.push("reviewed_at", "review_due_at", "updated_at");
+            }
+            if (beforeV2 && expected.created_at !== beforeV2.created_at) {
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: "invalid",
+                    fields: ["created_at"],
+                    message: "created_at is immutable",
+                });
+                continue;
+            }
+            if (opts.check) {
+                const validation = validateDocsMetadataV2(current.data);
+                if (!validation.valid) {
+                    rows.push({
+                        repo: target.name,
+                        path,
+                        status: "invalid",
+                        fields,
+                        message: validation.issues
+                            .map((issue) => `${issue.field}: ${issue.message}`)
+                            .join("; "),
+                    });
+                    continue;
+                }
+                const drift = [];
+                if (beforeV2 && contentChanged && current.data.updated_at === beforeV2.updated_at) {
+                    drift.push("updated_at");
+                }
+                if (beforeV2 && statusChanged) {
+                    if (current.data.status_changed_at === beforeV2.status_changed_at) {
+                        drift.push("status_changed_at");
+                    }
+                    if (current.data.status_changed_at !== current.data.updated_at) {
+                        drift.push("status_changed_at");
+                    }
+                    if (current.data.type === "issue" &&
+                        current.data.status === "resolved" &&
+                        current.data.resolved_at !== current.data.status_changed_at) {
+                        drift.push("resolved_at");
+                    }
+                }
+                if (beforeV2 &&
+                    !statusChanged &&
+                    current.data.status_changed_at !== beforeV2.status_changed_at) {
+                    drift.push("status_changed_at");
+                }
+                if (opts.reviewed &&
+                    beforeV2 &&
+                    (current.data.reviewed_at === beforeV2.reviewed_at ||
+                        current.data.review_due_at !== addDays(String(current.data.reviewed_at), 180))) {
+                    drift.push("reviewed_at", "review_due_at");
+                }
+                const uniqueDrift = [...new Set(drift)];
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: uniqueDrift.length ? "drift" : "unchanged",
+                    fields: uniqueDrift,
+                    ...(uniqueDrift.length
+                        ? { message: `run docs metadata sync for ${uniqueDrift.join(", ")}` }
+                        : {}),
+                });
+                continue;
+            }
+            const validation = validateDocsMetadataV2(expected);
+            if (!validation.valid) {
+                rows.push({
+                    repo: target.name,
+                    path,
+                    status: "invalid",
+                    fields,
+                    message: validation.issues.map((issue) => `${issue.field}: ${issue.message}`).join("; "),
+                });
+                continue;
+            }
+            if (fields.length === 0) {
+                rows.push({ repo: target.name, path, status: "unchanged", fields: [] });
+                continue;
+            }
+            writeFileSync(full, serialize(expected, current.body), "utf8");
+            rows.push({ repo: target.name, path, status: "updated", fields: [...new Set(fields)] });
+        }
+    }
+    return rows;
+}

package/dist/lib/docs-metadata-v2-schema.d.ts

@@ -0,0 +1,273 @@
+/** Editor-facing JSON Schema. The TypeScript validator remains authoritative. */
+export declare const docsMetadataV2Schema: {
+    $schema: string;
+    $id: string;
+    title: string;
+    type: string;
+    required: string[];
+    properties: {
+        schema: {
+            const: string;
+        };
+        type: {
+            enum: readonly ["plan", "issue", "handoff", "runbook", "topic", "audit", "book", "entity", "concept", "query", "page", "inquiry", "quote-sheet", "weekly-post", "synced-page"];
+        };
+        created_at: {
+            type: string;
+            pattern: string;
+        };
+        updated_at: {
+            type: string;
+            pattern: string;
+        };
+        owner: {
+            type: string;
+            pattern: string;
+        };
+        summary: {
+            type: string;
+            minLength: number;
+        };
+        tags: {
+            items: {
+                type: string;
+                pattern: string;
+            };
+            type: string;
+            uniqueItems: boolean;
+        };
+        relations: {
+            type: string;
+            properties: {
+                [k: string]: {
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                    };
+                    uniqueItems: boolean;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        access: {
+            type: string;
+            properties: {
+                roles: {
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                    };
+                    uniqueItems: boolean;
+                };
+                viewers: {
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                    };
+                    uniqueItems: boolean;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        status: {
+            type: string;
+        };
+        status_changed_at: {
+            type: string;
+            pattern: string;
+        };
+        status_note: {
+            type: string;
+            minLength: number;
+        };
+        severity: {
+            enum: string[];
+        };
+        resolved_at: {
+            type: string;
+            pattern: string;
+        };
+        affected: {
+            type: string;
+            items: {
+                type: string;
+                minLength: number;
+            };
+            uniqueItems: boolean;
+        };
+        resolution: {
+            type: string;
+            required: string[];
+            properties: {
+                outcome: {
+                    type: string;
+                    minLength: number;
+                };
+                commits: {
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                    };
+                    uniqueItems: boolean;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        title: {
+            type: string;
+            minLength: number;
+        };
+        audience: {
+            type: string;
+            minLength: number;
+        };
+        source: {
+            type: string;
+            minLength: number;
+        };
+        reviewed_at: {
+            type: string;
+            pattern: string;
+        };
+        review_due_at: {
+            type: string;
+            pattern: string;
+        };
+        category: {
+            type: string;
+            minLength: number;
+        };
+        aliases: {
+            type: string;
+            items: {
+                type: string;
+                minLength: number;
+            };
+            uniqueItems: boolean;
+        };
+        source_count: {
+            type: string;
+            minimum: number;
+        };
+        provenance: {
+            type: string;
+            required: string[];
+            properties: {
+                sources: {
+                    type: string;
+                    items: {
+                        type: string;
+                        minLength: number;
+                    };
+                    uniqueItems: boolean;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        primary_entity: {
+            type: string;
+        };
+        source_pages: {};
+        source_tokens: {};
+        top_entities: {
+            type: string;
+            items: {
+                type: string;
+                minLength: number;
+            };
+            uniqueItems: boolean;
+        };
+        handle: {
+            type: string;
+            minLength: number;
+        };
+        published: {
+            type: string;
+        };
+        source_updated_at: {
+            type: string;
+            pattern: string;
+        };
+        source_id: {
+            type: string;
+            minLength: number;
+        };
+        source_template: {
+            type: string;
+            minLength: number;
+        };
+        product: {};
+        variant: {};
+        sku: {};
+        manufacturer: {};
+        customer: {};
+        bid_id: {};
+        drive_file_id: {};
+        drive_title: {};
+        quote_date: {};
+        revision: {};
+        batch_size: {};
+        order_size: {};
+        price: {};
+        source_pdf: {};
+        claims: {};
+        week: {};
+        coverage: {};
+    };
+    patternProperties: {
+        "^x_": {};
+    };
+    additionalProperties: boolean;
+    allOf: ({
+        if: {
+            properties: {
+                type: {
+                    const: string;
+                    enum?: undefined;
+                };
+            };
+            required: string[];
+        };
+        then: {
+            required: string[];
+            properties: {
+                status: {
+                    enum: string[];
+                };
+            };
+        };
+    } | {
+        if: {
+            properties: {
+                type: {
+                    const: string;
+                    enum?: undefined;
+                };
+            };
+            required: string[];
+        };
+        then: {
+            required: string[];
+            properties?: undefined;
+        };
+    } | {
+        if: {
+            properties: {
+                type: {
+                    enum: string[];
+                    const?: undefined;
+                };
+            };
+            required: string[];
+        };
+        then: {
+            required: string[];
+            properties?: undefined;
+        };
+    })[];
+};
+//# sourceMappingURL=docs-metadata-v2-schema.d.ts.map

package/dist/lib/docs-metadata-v2-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-metadata-v2-schema.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-v2-schema.ts"],"names":[],"mappings":"AAQA,iFAAiF;AACjF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgIhC,CAAC"}

package/dist/lib/docs-metadata-v2-schema.js

@@ -0,0 +1,134 @@
+import { DOCS_METADATA_TYPES } from "./docs-metadata-v2.js";
+const timestamp = {
+    type: "string",
+    pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+};
+const stringList = { type: "array", items: { type: "string", minLength: 1 }, uniqueItems: true };
+/** Editor-facing JSON Schema. The TypeScript validator remains authoritative. */
+export const docsMetadataV2Schema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://harnery.com/schemas/docs-metadata-v2.schema.json",
+    title: "Harnery Markdown metadata v2",
+    type: "object",
+    required: ["schema", "type", "created_at", "updated_at", "summary"],
+    properties: {
+        schema: { const: "harnery-doc/v2" },
+        type: { enum: DOCS_METADATA_TYPES },
+        created_at: timestamp,
+        updated_at: timestamp,
+        owner: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        summary: { type: "string", minLength: 1 },
+        tags: { ...stringList, items: { type: "string", pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" } },
+        relations: {
+            type: "object",
+            properties: Object.fromEntries(["depends_on", "supersedes", "superseded_by", "continues", "related"].map((key) => [
+                key,
+                stringList,
+            ])),
+            additionalProperties: false,
+        },
+        access: {
+            type: "object",
+            properties: { roles: stringList, viewers: stringList },
+            additionalProperties: false,
+        },
+        status: { type: "string" },
+        status_changed_at: timestamp,
+        status_note: { type: "string", minLength: 1 },
+        severity: { enum: ["low", "medium", "high", "critical"] },
+        resolved_at: timestamp,
+        affected: stringList,
+        resolution: {
+            type: "object",
+            required: ["outcome"],
+            properties: { outcome: { type: "string", minLength: 1 }, commits: stringList },
+            additionalProperties: false,
+        },
+        title: { type: "string", minLength: 1 },
+        audience: { type: "string", minLength: 1 },
+        source: { type: "string", minLength: 1 },
+        reviewed_at: timestamp,
+        review_due_at: timestamp,
+        category: { type: "string", minLength: 1 },
+        aliases: stringList,
+        source_count: { type: "integer", minimum: 0 },
+        provenance: {
+            type: "object",
+            required: ["sources"],
+            properties: { sources: stringList },
+            additionalProperties: false,
+        },
+        primary_entity: { type: "string" },
+        source_pages: {},
+        source_tokens: {},
+        top_entities: stringList,
+        handle: { type: "string", minLength: 1 },
+        published: { type: "boolean" },
+        source_updated_at: timestamp,
+        source_id: { type: "string", minLength: 1 },
+        source_template: { type: "string", minLength: 1 },
+        product: {},
+        variant: {},
+        sku: {},
+        manufacturer: {},
+        customer: {},
+        bid_id: {},
+        drive_file_id: {},
+        drive_title: {},
+        quote_date: {},
+        revision: {},
+        batch_size: {},
+        order_size: {},
+        price: {},
+        source_pdf: {},
+        claims: {},
+        week: {},
+        coverage: {},
+    },
+    patternProperties: { "^x_": {} },
+    additionalProperties: false,
+    allOf: [
+        {
+            if: { properties: { type: { const: "plan" } }, required: ["type"] },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+            then: {
+                required: ["status", "status_changed_at", "owner"],
+                properties: { status: { enum: ["proposed", "in-progress", "shipped", "abandoned"] } },
+            },
+        },
+        {
+            if: { properties: { type: { const: "issue" } }, required: ["type"] },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+            then: {
+                required: ["status", "status_changed_at", "owner", "severity"],
+                properties: { status: { enum: ["open", "resolved", "wontfix"] } },
+            },
+        },
+        {
+            if: { properties: { type: { const: "handoff" } }, required: ["type"] },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+            then: {
+                required: ["status", "status_changed_at", "owner"],
+                properties: { status: { enum: ["open", "resolved", "abandoned"] } },
+            },
+        },
+        {
+            if: { properties: { type: { const: "runbook" } }, required: ["type"] },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+            then: { required: ["owner", "reviewed_at", "review_due_at"] },
+        },
+        {
+            if: {
+                properties: { type: { enum: ["book", "entity", "concept", "query", "page"] } },
+                required: ["type"],
+            },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+            then: { required: ["title", "category", "source_count", "provenance"] },
+        },
+        {
+            if: { properties: { type: { const: "synced-page" } }, required: ["type"] },
+            // biome-ignore lint/suspicious/noThenProperty: JSON Schema requires the then keyword for conditional validation.
+            then: { required: ["title", "handle", "published", "source", "source_updated_at"] },
+        },
+    ],
+};

package/dist/lib/docs-metadata-v2.d.ts

@@ -0,0 +1,21 @@
+export declare const DOCS_METADATA_SCHEMA_V2 = "harnery-doc/v2";
+export declare const DOCS_METADATA_TYPES: readonly ["plan", "issue", "handoff", "runbook", "topic", "audit", "book", "entity", "concept", "query", "page", "inquiry", "quote-sheet", "weekly-post", "synced-page"];
+export type DocsMetadataType = (typeof DOCS_METADATA_TYPES)[number];
+export type DocsMetadataProfile = "lifecycle" | "runbook" | "wiki" | "synced" | "quote-sheet" | "weekly-post" | "inquiry" | "general";
+export interface DocsMetadataValidationIssue {
+    severity: "error" | "warning";
+    code: string;
+    field: string;
+    message: string;
+}
+export interface DocsMetadataValidationResult {
+    valid: boolean;
+    profile: DocsMetadataProfile | null;
+    issues: DocsMetadataValidationIssue[];
+}
+export declare function docsMetadataProfileForType(type: DocsMetadataType): DocsMetadataProfile;
+export declare function isDocsMetadataType(value: unknown): value is DocsMetadataType;
+/** Validate one parsed YAML frontmatter mapping against the harnery-doc/v2 contract. */
+export declare function validateDocsMetadataV2(data: Record<string, unknown>): DocsMetadataValidationResult;
+export declare function isDocsMetadataV2(data: Record<string, unknown>): boolean;
+//# sourceMappingURL=docs-metadata-v2.d.ts.map

package/dist/lib/docs-metadata-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-metadata-v2.d.ts","sourceRoot":"","sources":["../../src/lib/docs-metadata-v2.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AAExD,eAAO,MAAM,mBAAmB,0KAgBtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,SAAS,GACT,MAAM,GACN,QAAQ,GACR,aAAa,GACb,aAAa,GACb,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC;AAyHD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAStF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAkZD,wFAAwF;AACxF,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,4BAA4B,CA2D9B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAEvE"}