@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/expedition-metadata.js

@@ -0,0 +1,54 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read and patch an epic's `metadata.expedition` record (EPIC-059). Writers go through
+ * `patchExpeditionMetadata`, which carries the read stamp (STORY-428).
+ */
+import { ExpeditionMetadata } from '../schemas/expedition.js';
+import { getCurrentTimestamp } from '../utils/index.js';
+import { getItem } from './get.js';
+import { writeItemMetadata } from './item-store.js';
+/** The tag that makes an epic an expedition. */
+export const EXPEDITION_TAG = 'expedition';
+export function isExpeditionEpic(item) {
+    return item.type === 'epic' && item.tags.includes(EXPEDITION_TAG);
+}
+/** The epic's expedition record, or undefined when it has none; a malformed record throws. */
+export function readExpeditionMetadata(item) {
+    const raw = item.metadata?.expedition;
+    if (raw === undefined)
+        return undefined;
+    const parsed = ExpeditionMetadata.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`${item.id}: metadata.expedition is malformed: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+/** True once the human baseline pinned the epic. */
+export function isBaselined(record) {
+    return Boolean(record?.baseline_commit && record.epic_core_hash);
+}
+/**
+ * Merge `patch` into the epic's expedition record and write it. A key set to undefined in
+ * the patch is removed. Refuses an item that is not an expedition epic.
+ */
+export async function patchExpeditionMetadata(devstepsDir, epicId, patch) {
+    const { metadata, stamp } = await getItem(devstepsDir, epicId);
+    if (!isExpeditionEpic(metadata)) {
+        throw new Error(`${epicId} is not an expedition epic (type epic, tag "${EXPEDITION_TAG}")`);
+    }
+    const merged = { ...(readExpeditionMetadata(metadata) ?? {}) };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            delete merged[key];
+        else
+            merged[key] = value;
+    }
+    const record = ExpeditionMetadata.parse(merged);
+    metadata.metadata = { ...metadata.metadata, expedition: record };
+    metadata.updated = getCurrentTimestamp();
+    writeItemMetadata(devstepsDir, metadata, stamp);
+    return record;
+}
+//# sourceMappingURL=expedition-metadata.js.map

package/dist/core/expedition-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expedition-metadata.js","sourceRoot":"","sources":["../../src/core/expedition-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAC;AAE3C,MAAM,UAAU,gBAAgB,CAAC,IAAyC;IACxE,OAAO,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;AACpE,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,sBAAsB,CAAC,IAA2C;IAChF,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC;IACtC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,uCAAuC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,WAAW,CAAC,MAAsC;IAChE,OAAO,OAAO,CAAC,MAAM,EAAE,eAAe,IAAI,MAAM,CAAC,cAAc,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,WAAmB,EACnB,MAAc,EACd,KAAkC;IAElC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC/D,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,+CAA+C,cAAc,IAAI,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,MAAM,GAA4B,EAAE,GAAG,CAAC,sBAAsB,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;IACxF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;;YACvC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC3B,CAAC;IACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,QAAQ,CAAC,QAAQ,GAAG,EAAE,GAAG,QAAQ,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACjE,QAAQ,CAAC,OAAO,GAAG,mBAAmB,EAAE,CAAC;IACzC,iBAAiB,CAAC,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/expedition-paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The expedition logbook layout (EPIC-059, contract C-4) — the one place that knows it.
+ *
+ * ```
+ * <project root>/.expedition/EPIC-059/
+ *   coordinator.log   one builder's logbook, one line per choice point
+ *   types.log
+ * ```
+ *
+ * The folder sits beside `.devsteps/`, on the build branches, until the harvest attaches the
+ * logbooks to the epic and removes it.
+ */
+export declare const EXPEDITION_ROOT = ".expedition";
+export declare const LOGBOOK_EXTENSION = ".log";
+export interface ExpeditionPaths {
+    /** `<project root>/.expedition` */
+    root: string;
+    /** `<project root>/.expedition/<epic>` */
+    dir: string;
+    /** `<project root>/.expedition/<epic>/<agent>.log` */
+    logbook(agent: string): string;
+}
+/** The project root that holds `.devsteps/` and `.expedition/`. */
+export declare function projectRootOf(devstepsDir: string): string;
+export declare function expeditionPaths(projectRoot: string, epicId: string): ExpeditionPaths;
+/** The logbook files of one expedition, sorted by name; empty when the folder is absent. */
+export declare function listLogbookFiles(projectRoot: string, epicId: string): string[];
+//# sourceMappingURL=expedition-paths.d.ts.map

package/dist/core/expedition-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expedition-paths.d.ts","sourceRoot":"","sources":["../../src/core/expedition-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,iBAAiB,SAAS,CAAC;AAIxC,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAcpF;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAO9E"}

package/dist/core/expedition-paths.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The expedition logbook layout (EPIC-059, contract C-4) — the one place that knows it.
+ *
+ * ```
+ * <project root>/.expedition/EPIC-059/
+ *   coordinator.log   one builder's logbook, one line per choice point
+ *   types.log
+ * ```
+ *
+ * The folder sits beside `.devsteps/`, on the build branches, until the harvest attaches the
+ * logbooks to the epic and removes it.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseItemId } from '../utils/index.js';
+export const EXPEDITION_ROOT = '.expedition';
+export const LOGBOOK_EXTENSION = '.log';
+const AGENT_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+/** The project root that holds `.devsteps/` and `.expedition/`. */
+export function projectRootOf(devstepsDir) {
+    return dirname(devstepsDir);
+}
+export function expeditionPaths(projectRoot, epicId) {
+    if (parseItemId(epicId)?.type !== 'epic') {
+        throw new Error(`Not an epic ID: ${epicId}`);
+    }
+    const root = join(projectRoot, EXPEDITION_ROOT);
+    const dir = join(root, epicId);
+    return {
+        root,
+        dir,
+        logbook(agent) {
+            if (!AGENT_NAME.test(agent))
+                throw new Error(`Invalid logbook agent name: ${agent}`);
+            return join(dir, `${agent}${LOGBOOK_EXTENSION}`);
+        },
+    };
+}
+/** The logbook files of one expedition, sorted by name; empty when the folder is absent. */
+export function listLogbookFiles(projectRoot, epicId) {
+    const { dir } = expeditionPaths(projectRoot, epicId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(LOGBOOK_EXTENSION))
+        .map((entry) => join(dir, entry.name))
+        .sort();
+}
+//# sourceMappingURL=expedition-paths.js.map

package/dist/core/expedition-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expedition-paths.js","sourceRoot":"","sources":["../../src/core/expedition-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAW7C,mEAAmE;AACnE,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,MAAc;IACjE,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO;QACL,IAAI;QACJ,GAAG;QACH,OAAO,CAAC,KAAa;YACnB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,KAAK,EAAE,CAAC,CAAC;YACrF,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,iBAAiB,EAAE,CAAC,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,MAAc;IAClE,MAAM,EAAE,GAAG,EAAE,GAAG,eAAe,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAC7C,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;SAC3E,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;SACrC,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/dist/core/export-render.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Markdown and HTML renderers for a project export.
+ */
+export interface ExportProject {
+    project_name: string;
+    created: string;
+    updated: string;
+}
+export interface ExportStats {
+    total: number;
+    by_type: Record<string, number>;
+    by_status: Record<string, number>;
+}
+export interface ExportItem {
+    id: string;
+    type: string;
+    title: string;
+    status: string;
+    eisenhower?: string;
+    assignee?: string;
+    tags: string[];
+    description: string;
+}
+export declare function renderExportMarkdown(project: ExportProject, stats: ExportStats, items: readonly ExportItem[]): string;
+export declare function renderExportHtml(project: ExportProject, stats: ExportStats, items: readonly ExportItem[]): string;
+//# sourceMappingURL=export-render.d.ts.map

package/dist/core/export-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-render.d.ts","sourceRoot":"","sources":["../../src/core/export-render.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AA8BD,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,MAAM,CAyBR;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,MAAM,CAgDR"}

package/dist/core/export-render.js

@@ -0,0 +1,105 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Markdown and HTML renderers for a project export.
+ */
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function countsLine(counts) {
+    return Object.entries(counts)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join(', ');
+}
+function groupByType(items) {
+    const byType = {};
+    for (const item of items) {
+        const group = byType[item.type] ?? [];
+        group.push(item);
+        byType[item.type] = group;
+    }
+    return byType;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+export function renderExportMarkdown(project, stats, items) {
+    const lines = [
+        `# ${project.project_name}`,
+        '',
+        `**Created:** ${new Date(project.created).toLocaleDateString()}`,
+        `**Updated:** ${new Date(project.updated).toLocaleDateString()}`,
+        '',
+        '## Statistics',
+        '',
+        `- **Total Items:** ${stats.total}`,
+        `- **By Type:** ${countsLine(stats.by_type)}`,
+        `- **By Status:** ${countsLine(stats.by_status)}`,
+        '',
+    ];
+    for (const [type, typeItems] of Object.entries(groupByType(items))) {
+        lines.push(`## ${capitalize(type)}s`, '');
+        for (const item of typeItems) {
+            lines.push(`### ${item.id}: ${item.title}`, '', `- **Status:** ${item.status}`);
+            if (item.eisenhower)
+                lines.push(`- **Priority:** ${item.eisenhower}`);
+            if (item.assignee)
+                lines.push(`- **Assignee:** ${item.assignee}`);
+            if (item.tags.length > 0)
+                lines.push(`- **Tags:** ${item.tags.join(', ')}`);
+            lines.push('', item.description, '', '---', '');
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderExportHtml(project, stats, items) {
+    const head = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>${escapeHtml(project.project_name)} - DevSteps Export</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; max-width: 1200px; margin: 0 auto; padding: 2rem; }
+    h1 { color: #1a1a1a; }
+    h2 { color: #2563eb; margin-top: 2rem; }
+    h3 { color: #4b5563; }
+    .item { border: 1px solid #e5e7eb; padding: 1rem; margin: 1rem 0; border-radius: 0.5rem; }
+    .status { display: inline-block; padding: 0.25rem 0.75rem; border-radius: 0.25rem; font-size: 0.875rem; }
+    .draft { background: #fef3c7; }
+    .in-progress { background: #dbeafe; }
+    .done { background: #d1fae5; }
+  </style>
+</head>
+<body>
+  <h1>${escapeHtml(project.project_name)}</h1>
+  <p><strong>Created:</strong> ${new Date(project.created).toLocaleDateString()}</p>
+  <p><strong>Updated:</strong> ${new Date(project.updated).toLocaleDateString()}</p>
+  <h2>Statistics</h2>
+  <ul>
+    <li><strong>Total Items:</strong> ${stats.total}</li>
+    <li><strong>By Type:</strong> ${escapeHtml(countsLine(stats.by_type))}</li>
+    <li><strong>By Status:</strong> ${escapeHtml(countsLine(stats.by_status))}</li>
+  </ul>
+`;
+    const sections = [];
+    for (const [type, typeItems] of Object.entries(groupByType(items))) {
+        sections.push(`<h2>${escapeHtml(capitalize(type))}s</h2>`);
+        for (const item of typeItems) {
+            const priority = item.eisenhower ? ` | Priority: ${escapeHtml(item.eisenhower)}` : '';
+            sections.push('<div class="item">', `<h3>${escapeHtml(item.id)}: ${escapeHtml(item.title)}</h3>`, `<p><span class="status ${escapeHtml(item.status)}">${escapeHtml(item.status)}</span>${priority}</p>`);
+            if (item.assignee)
+                sections.push(`<p><strong>Assignee:</strong> ${escapeHtml(item.assignee)}</p>`);
+            if (item.tags.length > 0) {
+                sections.push(`<p><strong>Tags:</strong> ${escapeHtml(item.tags.join(', '))}</p>`);
+            }
+            sections.push(`<div>${escapeHtml(item.description).replace(/\n/g, '<br>')}</div>`, '</div>');
+        }
+    }
+    return `${head}${sections.join('\n')}\n</body></html>`;
+}
+//# sourceMappingURL=export-render.js.map

package/dist/core/export-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-render.js","sourceRoot":"","sources":["../../src/core/export-render.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,UAAU,CAAC,MAA8B;IAChD,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,KAAK,EAAE,CAAC;SACzC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,KAA4B;IAC/C,MAAM,MAAM,GAAiC,EAAE,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC5B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK;SACT,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,OAAsB,EACtB,KAAkB,EAClB,KAA4B;IAE5B,MAAM,KAAK,GAAG;QACZ,KAAK,OAAO,CAAC,YAAY,EAAE;QAC3B,EAAE;QACF,gBAAgB,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,kBAAkB,EAAE,EAAE;QAChE,gBAAgB,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,kBAAkB,EAAE,EAAE;QAChE,EAAE;QACF,eAAe;QACf,EAAE;QACF,sBAAsB,KAAK,CAAC,KAAK,EAAE;QACnC,kBAAkB,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE;QAC7C,oBAAoB,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;QACjD,EAAE;KACH,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnE,KAAK,CAAC,IAAI,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC1C,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,iBAAiB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YAChF,IAAI,IAAI,CAAC,UAAU;gBAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YACtE,IAAI,IAAI,CAAC,QAAQ;gBAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;YAClE,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC5E,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,OAAsB,EACtB,KAAkB,EAClB,KAA4B;IAE5B,MAAM,IAAI,GAAG;;;;WAIJ,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;QAcnC,UAAU,CAAC,OAAO,CAAC,YAAY,CAAC;iCACP,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,kBAAkB,EAAE;iCAC9C,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,kBAAkB,EAAE;;;wCAGvC,KAAK,CAAC,KAAK;oCACf,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;sCACnC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;;CAE5E,CAAC;IACA,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnE,QAAQ,CAAC,IAAI,CAAC,OAAO,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC3D,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtF,QAAQ,CAAC,IAAI,CACX,oBAAoB,EACpB,OAAO,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAC5D,0BAA0B,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,QAAQ,MAAM,CACtG,CAAC;YACF,IAAI,IAAI,CAAC,QAAQ;gBACf,QAAQ,CAAC,IAAI,CAAC,iCAAiC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAClF,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,IAAI,CAAC,6BAA6B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;YACrF,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,QAAQ,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IACD,OAAO,GAAG,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC;AACzD,CAAC"}

package/dist/core/export.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Project export as Markdown, JSON, or HTML.
+ * STORY-042: the CLI and the MCP server build the same document; adapters only write it.
+ */
+import type { ItemType } from '../schemas/index.js';
+export type ExportFormat = 'markdown' | 'json' | 'html';
+export interface ExportProjectArgs {
+    format: ExportFormat;
+    /** Restrict the export to these item types; every type when omitted or empty. */
+    include_types?: ItemType[];
+}
+export interface ExportProjectResult {
+    format: ExportFormat;
+    content: string;
+    default_filename: string;
+    item_count: number;
+}
+/** Accept the CLI spellings `md`, `markdown`, `json`, and `html`. */
+export declare function parseExportFormat(value: string): ExportFormat;
+export declare function buildProjectExport(devstepsDir: string, args: ExportProjectArgs): Promise<ExportProjectResult>;
+//# sourceMappingURL=export.d.ts.map

package/dist/core/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/core/export.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAWpD,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAQxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,iFAAiF;IACjF,aAAa,CAAC,EAAE,QAAQ,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAI7D;AAED,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAwC9B"}

package/dist/core/export.js

@@ -0,0 +1,61 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Project export as Markdown, JSON, or HTML.
+ * STORY-042: the CLI and the MCP server build the same document; adapters only write it.
+ */
+import { existsSync } from 'node:fs';
+import { getConfig } from './config.js';
+import { renderExportHtml, renderExportMarkdown, } from './export-render.js';
+import { getItem } from './get.js';
+import { listItems } from './list.js';
+const DEFAULT_FILENAMES = {
+    markdown: 'devsteps-export.md',
+    json: 'devsteps-export.json',
+    html: 'devsteps-export.html',
+};
+/** Accept the CLI spellings `md`, `markdown`, `json`, and `html`. */
+export function parseExportFormat(value) {
+    if (value === 'md' || value === 'markdown')
+        return 'markdown';
+    if (value === 'json' || value === 'html')
+        return value;
+    throw new Error(`Unsupported export format: ${value} (expected md, json, or html)`);
+}
+export async function buildProjectExport(devstepsDir, args) {
+    if (!existsSync(devstepsDir)) {
+        throw new Error('Project not initialized. Run devsteps-init first.');
+    }
+    const config = await getConfig(devstepsDir);
+    const includeTypes = new Set(args.include_types ?? []);
+    const { items } = await listItems(devstepsDir, {});
+    const selected = includeTypes.size > 0 ? items.filter((item) => includeTypes.has(item.type)) : items;
+    const stats = { total: selected.length, by_type: {}, by_status: {} };
+    for (const item of selected) {
+        stats.by_type[item.type] = (stats.by_type[item.type] || 0) + 1;
+        stats.by_status[item.status] = (stats.by_status[item.status] || 0) + 1;
+    }
+    const fullItems = [];
+    for (const item of selected) {
+        const { metadata, description } = await getItem(devstepsDir, item.id);
+        fullItems.push({ ...metadata, description });
+    }
+    const project = {
+        project_name: config.project_name,
+        created: config.created,
+        updated: config.updated,
+    };
+    const content = args.format === 'markdown'
+        ? renderExportMarkdown(project, stats, fullItems)
+        : args.format === 'html'
+            ? renderExportHtml(project, stats, fullItems)
+            : JSON.stringify({ config, stats, items: fullItems }, null, 2);
+    return {
+        format: args.format,
+        content,
+        default_filename: DEFAULT_FILENAMES[args.format],
+        item_count: fullItems.length,
+    };
+}
+//# sourceMappingURL=export.js.map

package/dist/core/export.js.map

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

package/dist/core/focus-work.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The WIP limit of the focus board. The board and the promote gate both read it, so their WIP
+ * checks cannot disagree. Both count every item in a tier; a tag carries no meaning beyond its
+ * tier (BUG-166).
+ *
+ * @see STORY-311 TASK-934 BUG-166
+ */
+/** Maximum number of work items in focus:now. */
+export declare const WIP_LIMIT = 2;
+//# sourceMappingURL=focus-work.d.ts.map

package/dist/core/focus-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-work.d.ts","sourceRoot":"","sources":["../../src/core/focus-work.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iDAAiD;AACjD,eAAO,MAAM,SAAS,IAAI,CAAC"}

package/dist/core/focus-work.js

@@ -0,0 +1,13 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The WIP limit of the focus board. The board and the promote gate both read it, so their WIP
+ * checks cannot disagree. Both count every item in a tier; a tag carries no meaning beyond its
+ * tier (BUG-166).
+ *
+ * @see STORY-311 TASK-934 BUG-166
+ */
+/** Maximum number of work items in focus:now. */
+export const WIP_LIMIT = 2; // TODO(STORY-311): make configurable
+//# sourceMappingURL=focus-work.js.map

package/dist/core/focus-work.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-work.js","sourceRoot":"","sources":["../../src/core/focus-work.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iDAAiD;AACjD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,CAAC,qCAAqC"}

package/dist/core/focus.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Focus state management — active box, WIP tracking.
+ * Atomic write pattern (.tmp → rename) per ADR-S2-11.
+ *
+ * @see STORY-308
+ */
+import { z } from 'zod';
+import type { ListItemEntry } from './list.js';
+export declare const focusStateSchema: z.ZodObject<{
+    active_box: z.ZodString;
+    box_wip_limit: z.ZodDefault<z.ZodNumber>;
+    started_at: z.ZodString;
+}, z.core.$strip>;
+export type FocusState = z.infer<typeof focusStateSchema>;
+/**
+ * Load focus state from disk. Returns null when file is missing or invalid.
+ */
+export declare function loadFocusState(devstepsDir: string): FocusState | null;
+/**
+ * Write focus state atomically (.tmp → rename).
+ */
+export declare function writeFocusState(devstepsDir: string, state: FocusState): Promise<void>;
+/**
+ * Remove focus state file idempotently (no error if missing).
+ */
+export declare function clearFocusState(devstepsDir: string): Promise<void>;
+/**
+ * Count items that carry the active box tag AND are in-progress.
+ * Pure function — no I/O.
+ */
+export declare function getFocusWipCount(items: ListItemEntry[], activeBox: string): number;
+//# sourceMappingURL=focus.d.ts.map

package/dist/core/focus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../src/core/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,eAAO,MAAM,gBAAgB;;;;iBAI3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAM1D;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAWrE;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAK3F;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKlF"}

package/dist/core/focus.js

@@ -0,0 +1,60 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Focus state management — active box, WIP tracking.
+ * Atomic write pattern (.tmp → rename) per ADR-S2-11.
+ *
+ * @see STORY-308
+ */
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+export const focusStateSchema = z.object({
+    active_box: z.string(),
+    box_wip_limit: z.number().int().min(1).default(10),
+    started_at: z.string(),
+});
+function focusPath(devstepsDir) {
+    return path.join(devstepsDir, 'focus.json');
+}
+/**
+ * Load focus state from disk. Returns null when file is missing or invalid.
+ */
+export function loadFocusState(devstepsDir) {
+    const fp = focusPath(devstepsDir);
+    if (!existsSync(fp))
+        return null;
+    try {
+        const raw = readFileSync(fp, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const result = focusStateSchema.safeParse(parsed);
+        return result.success ? result.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write focus state atomically (.tmp → rename).
+ */
+export async function writeFocusState(devstepsDir, state) {
+    const fp = focusPath(devstepsDir);
+    const tmp = `${fp}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf-8');
+    renameSync(tmp, fp);
+}
+/**
+ * Remove focus state file idempotently (no error if missing).
+ */
+export async function clearFocusState(devstepsDir) {
+    rmSync(focusPath(devstepsDir), { force: true });
+}
+/**
+ * Count items that carry the active box tag AND are in-progress.
+ * Pure function — no I/O.
+ */
+export function getFocusWipCount(items, activeBox) {
+    return items.filter((item) => Array.isArray(item.tags) && item.tags.includes(activeBox) && item.status === 'in-progress').length;
+}
+//# sourceMappingURL=focus.js.map

package/dist/core/focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../../src/core/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtF,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAClD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACvB,CAAC,CAAC;AAIH,SAAS,SAAS,CAAC,WAAmB;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,MAAM,EAAE,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,WAAmB,EAAE,KAAiB;IAC1E,MAAM,EAAE,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,GAAG,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC5D,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,WAAmB;IACvD,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAsB,EAAE,SAAiB;IACxE,OAAO,KAAK,CAAC,MAAM,CACjB,CAAC,IAAI,EAAE,EAAE,CACP,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,CAC7F,CAAC,MAAM,CAAC;AACX,CAAC"}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * YAML Frontmatter extraction and validation for doc-item .md files.
+ * Pure functions: no filesystem access, operates on string content.
+ *
+ * @see STORY-278
+ */
+import { z } from 'zod';
+/** Zod schema for doc-item YAML frontmatter */
+export declare const DocFrontmatterSchema: z.ZodObject<{
+    diataxis: z.ZodOptional<z.ZodEnum<{
+        architecture: "architecture";
+        explanation: "explanation";
+        "how-to": "how-to";
+        reference: "reference";
+        research: "research";
+        tutorial: "tutorial";
+    }>>;
+    related_items: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        approved: "approved";
+        draft: "draft";
+        review: "review";
+    }>>;
+    author: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+export type DocFrontmatter = z.infer<typeof DocFrontmatterSchema>;
+export interface FrontmatterWarning {
+    field: string;
+    message: string;
+}
+export interface FrontmatterResult {
+    /** Parsed and validated frontmatter (null if none present) */
+    frontmatter: DocFrontmatter | null;
+    /** Markdown body without frontmatter block */
+    body: string;
+    /** Warnings for unknown fields (non-fatal) */
+    warnings: FrontmatterWarning[];
+}
+/**
+ * Extract and validate YAML frontmatter from doc-item markdown content.
+ *
+ * Rules:
+ * - Frontmatter is optional — files without `---` delimiters return `frontmatter: null`
+ * - All fields are optional
+ * - Invalid YAML syntax → throws Error
+ * - Invalid field values (e.g. unknown diataxis type) → throws Error with details
+ * - Unknown fields → warning (non-fatal, for forward-compatibility)
+ *
+ * @param content  Full markdown content (may or may not have frontmatter)
+ * @returns Parsed frontmatter, body text, and any warnings
+ * @throws Error if frontmatter is present but contains invalid YAML or invalid values
+ */
+export declare function extractFrontmatter(rawContent: string): FrontmatterResult;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/core/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/core/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,+CAA+C;AAC/C,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;kBAWtB,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,WAAW,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAgGD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CA2DxE"}