@aitne/shared 0.1.0

package/dist/date-utils.js

@@ -0,0 +1,187 @@
+/**
+ * Timezone-aware date utilities for the Aitne system.
+ *
+ * The "agent day" starts at `dayBoundaryHour` (default 04:00) in the
+ * configured timezone, NOT at UTC midnight. All SQL queries that reference
+ * "today" must use getAgentDayBoundsUtc() to get correct UTC boundaries.
+ */
+// ── Local date string ──────────────────────────────────────────────
+/**
+ * Get YYYY-MM-DD string in the specified (or system-local) timezone.
+ *
+ * Unlike `date.toISOString().slice(0, 10)` which returns the UTC date,
+ * this respects the given timezone (or falls back to system local).
+ */
+export function localDateStr(date, timezone) {
+    if (timezone) {
+        const t = nowInTimezone(timezone, date);
+        return `${t.year}-${String(t.month).padStart(2, "0")}-${String(t.day).padStart(2, "0")}`;
+    }
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, "0");
+    const d = String(date.getDate()).padStart(2, "0");
+    return `${y}-${m}-${d}`;
+}
+// ── Timezone-aware "now" ───────────────────────────────────────────
+/**
+ * Get time components in the specified timezone.
+ * Falls back to system timezone if timezone is empty/undefined.
+ */
+export function nowInTimezone(timezone, now) {
+    const d = now ?? new Date();
+    if (!timezone) {
+        return {
+            hours: d.getHours(),
+            minutes: d.getMinutes(),
+            year: d.getFullYear(),
+            month: d.getMonth() + 1,
+            day: d.getDate(),
+            dayOfWeek: d.getDay(),
+        };
+    }
+    const offsetMs = getTimezoneOffsetMs(timezone, d);
+    const local = new Date(d.getTime() + offsetMs);
+    return {
+        hours: local.getUTCHours(),
+        minutes: local.getUTCMinutes(),
+        year: local.getUTCFullYear(),
+        month: local.getUTCMonth() + 1,
+        day: local.getUTCDate(),
+        dayOfWeek: local.getUTCDay(),
+    };
+}
+// ── Agent day boundaries ───────────────────────────────────────────
+/**
+ * Compute the UTC boundaries of the current "agent day".
+ *
+ * An agent day starts at `dayBoundaryHour` in the configured timezone.
+ * For example, with timezone "America/New_York" and dayBoundaryHour 4:
+ *   - Agent day starts at 04:00 ET = 09:00 UTC (current day, EST)
+ *   - Agent day ends   at 04:00 ET = 09:00 UTC (next day, EST)
+ *
+ * @returns start (inclusive) and end (exclusive) as 'YYYY-MM-DD HH:MM:SS'
+ *          UTC strings suitable for SQLite WHERE clauses.
+ */
+export function getAgentDayBoundsUtc(timezone, dayBoundaryHour, now) {
+    const d = now ?? new Date();
+    const offsetMs = timezone
+        ? getTimezoneOffsetMs(timezone, d)
+        : -d.getTimezoneOffset() * 60 * 1000;
+    // Shift UTC time into "local" space (UTC-shifted Date where UTC methods
+    // give local time components)
+    const localMs = d.getTime() + offsetMs;
+    const localDate = new Date(localMs);
+    const localHour = localDate.getUTCHours();
+    // Start of the agent day in local-shifted space
+    const dayStartLocal = new Date(localDate);
+    dayStartLocal.setUTCHours(dayBoundaryHour, 0, 0, 0);
+    if (localHour < dayBoundaryHour) {
+        // Before the boundary: still in previous agent day
+        dayStartLocal.setUTCDate(dayStartLocal.getUTCDate() - 1);
+    }
+    // Convert back to real UTC. We recompute the timezone offset *at the
+    // boundary instant* — using the offset captured at `d` would skew the
+    // result by an hour around DST transitions when `d` and the boundary
+    // straddle the change-over (e.g. inputs around 02:00–04:00 local on a
+    // spring-forward day in ET/CET). For non-DST zones (Asia/Tokyo, UTC)
+    // this is a no-op.
+    const provisionalUtcMs = dayStartLocal.getTime() - offsetMs;
+    const boundaryOffsetMs = timezone
+        ? getTimezoneOffsetMs(timezone, new Date(provisionalUtcMs))
+        : offsetMs;
+    const dayStartUtcMs = dayStartLocal.getTime() - boundaryOffsetMs;
+    const dayEndUtcMs = dayStartUtcMs + 24 * 60 * 60 * 1000;
+    return {
+        start: formatSqliteDatetime(new Date(dayStartUtcMs)),
+        end: formatSqliteDatetime(new Date(dayEndUtcMs)),
+    };
+}
+/**
+ * Return the local YYYY-MM-DD label of the current agent day.
+ *
+ * With a 04:00 boundary, times between 00:00 and 03:59 belong to the
+ * previous agent day and therefore return the previous local date.
+ */
+export function getAgentDayDateStr(timezone, dayBoundaryHour, now) {
+    const { start } = getAgentDayBoundsUtc(timezone, dayBoundaryHour, now);
+    return localDateStr(new Date(start.replace(" ", "T") + "Z"), timezone);
+}
+/**
+ * Return minutes elapsed since the start of the current agent day.
+ *
+ * Example: with a 04:00 boundary, 05:30 returns 90 and 02:15 returns 1335.
+ */
+export function getAgentDayProgressMinutes(timezone, dayBoundaryHour, now) {
+    const local = nowInTimezone(timezone, now);
+    const currentMinutes = local.hours * 60 + local.minutes;
+    const boundaryMinutes = dayBoundaryHour * 60;
+    return currentMinutes >= boundaryMinutes
+        ? currentMinutes - boundaryMinutes
+        : (24 * 60 - boundaryMinutes) + currentMinutes;
+}
+/**
+ * Project a candidate Date forward to the next start of an active-hours
+ * window in the configured timezone. The window is `[startHour, endHour)`
+ * in local time; `endHour=24` is treated as exclusive (no shift for
+ * candidate hour 23).
+ *
+ * - Candidate's local hour already inside the window → returns candidate
+ *   unchanged.
+ * - Local hour `< startHour` → returns today's `startHour:00:00.000` local.
+ * - Local hour `>= endHour`  → returns tomorrow's `startHour:00:00.000`
+ *   local.
+ *
+ * Mirrors the timezone-shift / DST-recompute pattern used in
+ * `getAgentDayBoundsUtc` so cross-DST transitions land on the correct
+ * wall-clock hour rather than an hour offset.
+ */
+export function nextActiveHoursStart(candidate, timezone, startHour, endHour) {
+    const local = nowInTimezone(timezone, candidate);
+    if (local.hours >= startHour && local.hours < endHour) {
+        return candidate;
+    }
+    const offsetMs = timezone
+        ? getTimezoneOffsetMs(timezone, candidate)
+        : -candidate.getTimezoneOffset() * 60 * 1000;
+    // Local-shifted Date — UTC accessors return the local-time components.
+    const localShifted = new Date(candidate.getTime() + offsetMs);
+    const target = new Date(localShifted);
+    target.setUTCHours(startHour, 0, 0, 0);
+    if (local.hours >= endHour) {
+        target.setUTCDate(target.getUTCDate() + 1);
+    }
+    // local.hours < startHour → today's startHour (no day shift needed).
+    // Convert back to UTC, recomputing TZ offset at the target instant so a
+    // candidate that straddles a DST change lands at the intended local hour.
+    const provisionalUtcMs = target.getTime() - offsetMs;
+    const targetOffsetMs = timezone
+        ? getTimezoneOffsetMs(timezone, new Date(provisionalUtcMs))
+        : offsetMs;
+    return new Date(target.getTime() - targetOffsetMs);
+}
+// ── Helpers ────────────────────────────────────────────────────────
+/** Format a Date as 'YYYY-MM-DD HH:MM:SS' UTC string for SQLite. */
+export function formatSqliteDatetime(date) {
+    return date.toISOString().replace("T", " ").slice(0, 19);
+}
+/**
+ * Parse a SQLite UTC datetime string ('YYYY-MM-DD HH:MM:SS') into epoch ms.
+ * More robust than ad-hoc `new Date(s + "Z")` — explicitly normalizes the
+ * format before parsing.
+ */
+export function parseSqliteUtcMs(s) {
+    // SQLite datetime('now') produces 'YYYY-MM-DD HH:MM:SS' (space-separated, no Z)
+    // Replace space with T and append Z to create a valid ISO 8601 UTC string
+    return new Date(s.replace(" ", "T") + "Z").getTime();
+}
+/**
+ * Get the timezone offset in milliseconds (positive = east of UTC).
+ * Uses toLocaleString comparison which handles DST correctly for
+ * the given instant.
+ */
+function getTimezoneOffsetMs(timezone, date) {
+    const utcStr = date.toLocaleString("en-US", { timeZone: "UTC" });
+    const localStr = date.toLocaleString("en-US", { timeZone: timezone });
+    return new Date(localStr).getTime() - new Date(utcStr).getTime();
+}
+//# sourceMappingURL=date-utils.js.map

package/dist/date-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-utils.js","sourceRoot":"","sources":["../src/date-utils.ts"],"names":[],"mappings":"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"}

package/dist/docs-frontmatter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Minimal YAML frontmatter parser scoped to the docs corpus shape
+ * (DOCS_QA_DESIGN.md §7).
+ *
+ * Lives in `packages/shared` so the daemon (indexer) and the dashboard
+ * (page-doc-map drift guard) can both validate fixture frontmatter
+ * against the canonical Zod schema without two parsers drifting.
+ *
+ * Why hand-rolled. The codebase already carries two hand-rolled
+ * frontmatter readers (`context-frontmatter.ts`, `custom-routine-scheduler.ts`)
+ * but they are flat-scalar-only. Docs frontmatter needs arrays
+ * (`aliases:`, `tags:`, `related:`, ...) and a block-scalar `summary:`.
+ * Pulling in a full YAML library for this tightly-bounded use case is
+ * unnecessary; the tighter parser here
+ * fails loudly on shapes we don't expect (nested mappings, flow-style
+ * arrays) so authors stay inside the supported subset.
+ *
+ * Supported shapes:
+ *   - `key: scalar` (string, possibly quoted with `"` or `'`)
+ *   - `key: [number]` parsed as number when the value is bare-numeric
+ *   - `key: true` / `key: false` parsed as boolean
+ *   - `key:\n  - item\n  - item` parsed as `string[]` (or empty array
+ *     when followed by another key with no `-` lines in between)
+ *   - `key: |` (or `key: |-`) followed by indented block, joined with
+ *     `\n`. Trailing newline is dropped for `|-` and preserved for `|`.
+ *   - `key: {}` parsed as `Record<string, never>` (used by `extra:`)
+ *   - `# comment` and inline trailing `# comment` stripped
+ *
+ * Unsupported (rejected): nested mappings, flow-style arrays/objects
+ * other than `{}`, anchor / alias references.
+ *
+ * Validation against the Zod schema is the caller's job — this parser
+ * just produces a `Record<string, unknown>`.
+ */
+export interface ParsedFrontmatter {
+    /** Parsed YAML mapping. */
+    values: Record<string, unknown>;
+    /** Body content after the closing `---`. */
+    body: string;
+}
+export declare class FrontmatterParseError extends Error {
+    readonly line: number;
+    readonly raw: string;
+    constructor(line: number, raw: string, reason: string);
+}
+/**
+ * Split a Markdown source into `{ frontmatter, body }`. Returns `null`
+ * when the file does not start with `---` (no frontmatter).
+ */
+export declare function parseFrontmatter(source: string): ParsedFrontmatter | null;
+//# sourceMappingURL=docs-frontmatter.d.ts.map

package/dist/docs-frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-frontmatter.d.ts","sourceRoot":"","sources":["../src/docs-frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,IAAI,EAAE,MAAM;aACZ,GAAG,EAAE,MAAM;gBADX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EAC3B,MAAM,EAAE,MAAM;CAKjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAWzE"}

package/dist/docs-frontmatter.js

@@ -0,0 +1,184 @@
+/**
+ * Minimal YAML frontmatter parser scoped to the docs corpus shape
+ * (DOCS_QA_DESIGN.md §7).
+ *
+ * Lives in `packages/shared` so the daemon (indexer) and the dashboard
+ * (page-doc-map drift guard) can both validate fixture frontmatter
+ * against the canonical Zod schema without two parsers drifting.
+ *
+ * Why hand-rolled. The codebase already carries two hand-rolled
+ * frontmatter readers (`context-frontmatter.ts`, `custom-routine-scheduler.ts`)
+ * but they are flat-scalar-only. Docs frontmatter needs arrays
+ * (`aliases:`, `tags:`, `related:`, ...) and a block-scalar `summary:`.
+ * Pulling in a full YAML library for this tightly-bounded use case is
+ * unnecessary; the tighter parser here
+ * fails loudly on shapes we don't expect (nested mappings, flow-style
+ * arrays) so authors stay inside the supported subset.
+ *
+ * Supported shapes:
+ *   - `key: scalar` (string, possibly quoted with `"` or `'`)
+ *   - `key: [number]` parsed as number when the value is bare-numeric
+ *   - `key: true` / `key: false` parsed as boolean
+ *   - `key:\n  - item\n  - item` parsed as `string[]` (or empty array
+ *     when followed by another key with no `-` lines in between)
+ *   - `key: |` (or `key: |-`) followed by indented block, joined with
+ *     `\n`. Trailing newline is dropped for `|-` and preserved for `|`.
+ *   - `key: {}` parsed as `Record<string, never>` (used by `extra:`)
+ *   - `# comment` and inline trailing `# comment` stripped
+ *
+ * Unsupported (rejected): nested mappings, flow-style arrays/objects
+ * other than `{}`, anchor / alias references.
+ *
+ * Validation against the Zod schema is the caller's job — this parser
+ * just produces a `Record<string, unknown>`.
+ */
+export class FrontmatterParseError extends Error {
+    line;
+    raw;
+    constructor(line, raw, reason) {
+        super(`Frontmatter parse error at line ${line}: ${reason} (${JSON.stringify(raw)})`);
+        this.line = line;
+        this.raw = raw;
+        this.name = "FrontmatterParseError";
+    }
+}
+/**
+ * Split a Markdown source into `{ frontmatter, body }`. Returns `null`
+ * when the file does not start with `---` (no frontmatter).
+ */
+export function parseFrontmatter(source) {
+    const lines = source.split(/\r?\n/);
+    if ((lines[0] ?? "").trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx < 0) {
+        throw new FrontmatterParseError(1, "---", "missing closing '---'");
+    }
+    const fmLines = lines.slice(1, closeIdx);
+    const body = lines.slice(closeIdx + 1).join("\n");
+    const values = parseMapping(fmLines, /*lineOffset*/ 1);
+    return { values, body };
+}
+function stripInlineComment(value) {
+    // Inline comments only count when preceded by whitespace; `#` inside a
+    // quoted scalar is literal. Treat unquoted values: the first ` #`
+    // sequence ends the value.
+    if (value.startsWith('"') || value.startsWith("'"))
+        return value;
+    const idx = value.indexOf(" #");
+    if (idx === -1)
+        return value;
+    return value.slice(0, idx).trimEnd();
+}
+function parseScalar(rawValue) {
+    const v = stripInlineComment(rawValue.trim());
+    if (v === "" || v === "null" || v === "~")
+        return null;
+    if (v === "true")
+        return true;
+    if (v === "false")
+        return false;
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        return v.slice(1, -1);
+    }
+    if (/^-?\d+(\.\d+)?$/.test(v)) {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : v;
+    }
+    return v;
+}
+function parseMapping(lines, lineOffset) {
+    const out = {};
+    let i = 0;
+    while (i < lines.length) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        // Skip blank + comment lines.
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            i += 1;
+            continue;
+        }
+        // Top-level keys must start at column 0.
+        if (raw.startsWith(" ") || raw.startsWith("\t")) {
+            throw new FrontmatterParseError(lineOffset + i, raw, "unexpected indentation at top level (nested mappings not supported)");
+        }
+        const colon = raw.indexOf(":");
+        if (colon < 0) {
+            throw new FrontmatterParseError(lineOffset + i, raw, "expected 'key: value' at top level");
+        }
+        const key = raw.slice(0, colon).trim();
+        const valuePart = raw.slice(colon + 1);
+        // Detect block-scalar marker (`|` or `|-`).
+        const blockMatch = stripInlineComment(valuePart.trim());
+        if (blockMatch === "|" || blockMatch === "|-") {
+            const stripTrailingNewline = blockMatch === "|-";
+            const collected = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const next = lines[j];
+                if (next === "" || next.startsWith("  ") || next.startsWith("\t")) {
+                    // Strip the 2-space indent (tab counted as one indent level).
+                    const stripped = next.startsWith("\t") ? next.slice(1) : next.slice(2);
+                    collected.push(stripped);
+                    j += 1;
+                    continue;
+                }
+                break;
+            }
+            let joined = collected.join("\n");
+            if (stripTrailingNewline) {
+                joined = joined.replace(/\n+$/, "");
+            }
+            else {
+                // `|` preserves a single trailing newline; multiple are folded
+                // to one, no trailing newline → add one.
+                joined = joined.replace(/\n+$/, "\n");
+                if (!joined.endsWith("\n"))
+                    joined += "\n";
+            }
+            out[key] = joined;
+            i = j;
+            continue;
+        }
+        // Detect inline value vs list-form value.
+        const inlineValue = stripInlineComment(valuePart).trim();
+        if (inlineValue === "") {
+            // List form: subsequent indented lines starting with `- ` are items.
+            const items = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const next = lines[j];
+                const t = next.trim();
+                if (t === "" || t.startsWith("#")) {
+                    j += 1;
+                    continue;
+                }
+                if (!next.startsWith("  ") && !next.startsWith("\t")) {
+                    break;
+                }
+                const itemMatch = next.match(/^\s*-\s*(.*)$/);
+                if (!itemMatch) {
+                    throw new FrontmatterParseError(lineOffset + j, next, "expected list item starting with '- ' under multi-line key");
+                }
+                items.push(parseScalar(itemMatch[1]));
+                j += 1;
+            }
+            out[key] = items;
+            i = j;
+            continue;
+        }
+        if (inlineValue === "{}") {
+            out[key] = {};
+            i += 1;
+            continue;
+        }
+        // Reject inline flow-style arrays / objects we don't support.
+        if (inlineValue.startsWith("[") || inlineValue.startsWith("{")) {
+            throw new FrontmatterParseError(lineOffset + i, raw, "flow-style array/object literals not supported (use list form)");
+        }
+        out[key] = parseScalar(inlineValue);
+        i += 1;
+    }
+    return out;
+}
+//# sourceMappingURL=docs-frontmatter.js.map

package/dist/docs-frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-frontmatter.js","sourceRoot":"","sources":["../src/docs-frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/docs-schema.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+/**
+ * Docs & QA frontmatter schema (DOCS_QA_DESIGN.md §7).
+ *
+ * Shared between the daemon (indexer, FTS5 row builder) and dashboard
+ * (renderer, ?-button map). The schema is `.strict()` — unknown top-level
+ * keys must move under `extra:`. This is deliberate: loose passthrough lets
+ * typos like `tag:` (instead of `tags:`) silently bypass validation.
+ *
+ * Forward-compat is provided via `schema_version` + the `extra` bag.
+ */
+export declare const DOCS_SCHEMA_VERSION: 1;
+declare const DOC_CATEGORIES: readonly ["getting-started", "concepts", "features", "guides", "troubleshooting", "reference", "glossary"];
+export type DocCategory = (typeof DOC_CATEGORIES)[number];
+declare const DOC_STATUS: readonly ["stable", "beta", "draft", "deprecated"];
+export type DocStatus = (typeof DOC_STATUS)[number];
+export declare const docsFrontmatterSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    slug: z.ZodString;
+    title: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    category: z.ZodEnum<{
+        "getting-started": "getting-started";
+        concepts: "concepts";
+        features: "features";
+        guides: "guides";
+        troubleshooting: "troubleshooting";
+        reference: "reference";
+        glossary: "glossary";
+    }>;
+    summary: z.ZodString;
+    section: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        stable: "stable";
+        beta: "beta";
+        draft: "draft";
+        deprecated: "deprecated";
+    }>>;
+    ask_examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    locale: z.ZodOptional<z.ZodString>;
+    created: z.ZodOptional<z.ZodString>;
+    updated: z.ZodOptional<z.ZodString>;
+    review_due: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    prerequisites: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ui_anchors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    process_keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config_keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    api_endpoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    context_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type DocsFrontmatter = z.infer<typeof docsFrontmatterSchema>;
+/**
+ * Slugify an H1/H2/H3 heading text into the anchor id used inside
+ * `[doc:slug#anchor]` citations. Mirrors the rule the dashboard renderer
+ * is expected to use (lower, replace whitespace with `-`, drop punctuation).
+ *
+ * Kept in `shared` so the citation post-processor (daemon) and the
+ * citation pill renderer (dashboard) cannot drift.
+ */
+export declare function slugifyAnchor(heading: string): string;
+export interface ParsedCitationToken {
+    /** Index in the source string where `[doc:` starts. */
+    start: number;
+    /** Index in the source string just past the closing `]`. */
+    end: number;
+    slug: string;
+    anchor: string | null;
+    raw: string;
+}
+/** Find every `[doc:slug#anchor]` token in `text`. */
+export declare function parseCitationTokens(text: string): ParsedCitationToken[];
+export {};
+//# sourceMappingURL=docs-schema.d.ts.map

package/dist/docs-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-schema.d.ts","sourceRoot":"","sources":["../src/docs-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;GASG;AAEH,eAAO,MAAM,mBAAmB,EAAG,CAAU,CAAC;AAE9C,QAAA,MAAM,cAAc,4GAQV,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,QAAA,MAAM,UAAU,oDAAqD,CAAC;AACtE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AA+CpD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiDvB,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOrD;AAKD,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,sDAAsD;AACtD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAcvE"}

package/dist/docs-schema.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+/**
+ * Docs & QA frontmatter schema (DOCS_QA_DESIGN.md §7).
+ *
+ * Shared between the daemon (indexer, FTS5 row builder) and dashboard
+ * (renderer, ?-button map). The schema is `.strict()` — unknown top-level
+ * keys must move under `extra:`. This is deliberate: loose passthrough lets
+ * typos like `tag:` (instead of `tags:`) silently bypass validation.
+ *
+ * Forward-compat is provided via `schema_version` + the `extra` bag.
+ */
+export const DOCS_SCHEMA_VERSION = 1;
+const DOC_CATEGORIES = [
+    "getting-started",
+    "concepts",
+    "features",
+    "guides",
+    "troubleshooting",
+    "reference",
+    "glossary",
+];
+const DOC_STATUS = ["stable", "beta", "draft", "deprecated"];
+/**
+ * Slug grammar: lowercase ASCII letters/digits with `/` separators and
+ * `-` inside a segment. The first segment must be one of the known
+ * categories, but the schema enforces only the shape — the cross-check
+ * `slug.split('/')[0] === category` lives in the indexer because it
+ * needs the runtime category value.
+ *
+ * Example: `features/routines/morning-routine`
+ */
+const slugSchema = z
+    .string()
+    .min(1)
+    .max(160)
+    .regex(/^[a-z0-9]+(?:[-_][a-z0-9]+)*(?:\/[a-z0-9]+(?:[-_][a-z0-9]+)*)*$/, "slug must be lowercase kebab-case path segments separated by '/'");
+/**
+ * Cross-link target: same shape as `slug`, but used in `related:` /
+ * `prerequisites:` / `supersedes:` lists. Kept as a separate alias so a
+ * future grammar change to one side doesn't silently widen the other.
+ */
+const slugRefSchema = slugSchema;
+/** Short id used in `[[id]]` cross-references. ASCII kebab-case only. */
+const docIdSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "id must be lowercase kebab-case");
+/** YAML date — ISO-8601 calendar date (`YYYY-MM-DD`). */
+const isoDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "must be YYYY-MM-DD");
+/**
+ * Dashboard route used as a `ui_anchors` entry. Must start with `/` and
+ * may carry a query string. The drift-guard test cross-checks each
+ * value against `dashboard/src/app/**\/page.tsx` (DOCS_QA_DESIGN.md §8.3).
+ */
+const uiAnchorSchema = z
+    .string()
+    .min(1)
+    .regex(/^\/[A-Za-z0-9\-_/?=&%.]*$/, "ui_anchors entries must look like a dashboard path");
+export const docsFrontmatterSchema = z
+    .object({
+    // === Identity (required) ===
+    schema_version: z.literal(DOCS_SCHEMA_VERSION),
+    slug: slugSchema,
+    title: z.string().min(1).max(200),
+    // === Identity (recommended) ===
+    id: docIdSchema.optional(),
+    aliases: z.array(z.string().min(1).max(120)).max(32).optional(),
+    // === Classification (required) ===
+    category: z.enum(DOC_CATEGORIES),
+    summary: z.string().min(1).max(2000),
+    // === Classification (recommended) ===
+    section: z.string().min(1).max(64).optional(),
+    tags: z.array(z.string().min(1).max(64)).max(32).optional(),
+    status: z.enum(DOC_STATUS).optional(),
+    ask_examples: z.array(z.string().min(1).max(240)).max(16).optional(),
+    // === Classification (optional) ===
+    locale: z.string().min(2).max(16).optional(),
+    // === Lifecycle (optional) ===
+    created: isoDateSchema.optional(),
+    updated: isoDateSchema.optional(),
+    review_due: isoDateSchema.optional(),
+    supersedes: z.array(slugRefSchema).max(16).optional(),
+    // === Search (optional but valuable) ===
+    keywords: z.array(z.string().min(1).max(120)).max(32).optional(),
+    // === Cross-links (optional) ===
+    related: z.array(slugRefSchema).max(32).optional(),
+    prerequisites: z.array(slugRefSchema).max(16).optional(),
+    // === System bindings (optional — drives ?-button + filtering) ===
+    ui_anchors: z.array(uiAnchorSchema).max(32).optional(),
+    process_keys: z.array(z.string().min(1).max(120)).max(32).optional(),
+    config_keys: z.array(z.string().min(1).max(120)).max(32).optional(),
+    api_endpoints: z.array(z.string().min(1).max(160)).max(32).optional(),
+    context_files: z.array(z.string().min(1).max(160)).max(32).optional(),
+    // === Forward-compat escape hatch ===
+    // Zod 4.x: z.record(keySchema, valueSchema). The previous one-arg
+    // form (`z.record(z.unknown())`) compiled but threw at parse time.
+    extra: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+/**
+ * Slugify an H1/H2/H3 heading text into the anchor id used inside
+ * `[doc:slug#anchor]` citations. Mirrors the rule the dashboard renderer
+ * is expected to use (lower, replace whitespace with `-`, drop punctuation).
+ *
+ * Kept in `shared` so the citation post-processor (daemon) and the
+ * citation pill renderer (dashboard) cannot drift.
+ */
+export function slugifyAnchor(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-");
+}
+/** Citation token shape: `[doc:slug#anchor]`. Anchor is optional. */
+const CITATION_RE = /\[doc:([a-z0-9][a-z0-9\-_/]*)(?:#([a-z0-9][a-z0-9-]*))?\]/g;
+/** Find every `[doc:slug#anchor]` token in `text`. */
+export function parseCitationTokens(text) {
+    const out = [];
+    CITATION_RE.lastIndex = 0;
+    let m;
+    while ((m = CITATION_RE.exec(text)) !== null) {
+        out.push({
+            start: m.index,
+            end: m.index + m[0].length,
+            slug: m[1],
+            anchor: m[2] ?? null,
+            raw: m[0],
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=docs-schema.js.map