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

package/dist/core/description-patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"description-patch.js","sourceRoot":"","sources":["../../src/core/description-patch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC;IACjC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CACrD,CAAC,CAAC;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AA8BnG,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CACpC,IAIC;IAED,MAAM,KAAK,GAAG,CAAC,aAAa,EAAE,oBAAoB,EAAE,SAAS,EAAE,iBAAiB,CAAU,CAAC;IAC3F,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,qCAAqC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAA2B;IAC7D,OAAO,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,CAAC;AAC1E,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACnC,wEAAwE;IACxE,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,KAAc;IACnD,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QACtD,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACzC,OAAO,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,YAAY,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CACb,WAAW,KAAK,eAAe,SAAS,CAAC,YAAY,yBAAyB,OAAO,CAAC,MAAM,kBAAkB,CAC/G,CAAC;QACJ,CAAC;QACD,IAAI,SAAS,CAAC,GAAG,KAAK,SAAS,CAAC,GAAG,EAAE,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC;gBACX,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;gBACpC,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;gBAC9E,OAAO,EAAE,OAAO,CAAC,MAAM;aACxB,CAAC,CAAC;QACL,CAAC;QACD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,KAAc;IAClD,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,0CAA0C,QAAQ,YAAY,OAAO,CAAC,MAAM,kBAAkB,CAC/F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACvE,IAAI,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC;IACjC,IAAI,WAAW,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;IACxE,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,WAAW,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC;QAAE,WAAW,IAAI,OAAO,CAAC;IAC7F,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnF,OAAO;QACL,IAAI,EAAE,SAAS;QACf,OAAO,EACL,SAAS,KAAK,IAAI;YAChB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE;oBACE,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC;oBAC3C,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;oBAC5D,OAAO,EAAE,CAAC;iBACX;aACF;KACR,CAAC;AACJ,CAAC;AAED,SAAS,yBAAyB,CAAC,MAAc,EAAE,KAAa;IAC9D,MAAM,SAAS,GAAG,uEAAuE,CAAC;IAC1F,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;AACH,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,KAA4B;IAE5B,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,MAAM,MAAM,GACV,KAAK,CAAC,OAAO,KAAK,SAAS;QACzB,CAAC,CAAC,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;QACtC,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAClD,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/docs-assemble.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * docs-assemble — generic BOM-to-Markdown assembler.
+ *
+ * Reads docs-map.json, walks the BOM tree depth-first, and concatenates
+ * each node's DOC item content into a single coherent Markdown document.
+ *
+ * Design decisions:
+ * - Uses sync fs calls (same pattern as docs-map.ts) to keep this pure/sync.
+ * - Heading shift rule: node at depth D shifts all headings by D.
+ *   (root depth=0 → no shift; L1 depth=1 → H1→H2; L2 depth=2 → H1→H3)
+ * - Missing DOC items are silently skipped with a comment placeholder.
+ * - BOM node order within siblings is determined by `node.order` (ascending).
+ *
+ * @see STORY-298
+ */
+/**
+ * Thrown when a circular parent_id reference is detected in the BOM tree.
+ * This prevents infinite recursion and stack overflow (TASK-564).
+ */
+export declare class CircularBOMError extends Error {
+    constructor(nodeId: string, path: string[]);
+}
+/**
+ * Thrown when a doc_id fails path traversal validation.
+ * Prevents directory traversal attacks (TASK-565).
+ */
+export declare class PathTraversalError extends Error {
+    constructor(docId: string);
+}
+/**
+ * Thrown when strict mode is enabled and missing DOC items are found (TASK-566).
+ */
+export declare class MissingDocItemsError extends Error {
+    constructor(missingNodes: string[]);
+}
+export interface AssembleOptions {
+    /** .devsteps directory path (absolute) */
+    devstepsDir: string;
+    /**
+     * ARCH-NNN node id to start assembly from.
+     * Defaults to all root nodes (parent_id === null), assembled in order.
+     */
+    rootId?: string;
+    /**
+     * If provided, write the assembled markdown to this file path (absolute or
+     * relative to cwd). Parent directories are created if missing.
+     */
+    outputPath?: string;
+    /**
+     * Return the assembled text in the result object (default: true).
+     * Set to false for large documents when you only need the file output.
+     */
+    returnContent?: boolean;
+    /**
+     * Strip YAML frontmatter from each DOC item fragment (default: false).
+     * When false, frontmatter blocks are preserved in the output.
+     */
+    includeFrontmatter?: boolean;
+    /**
+     * Maximum BOM tree depth to traverse (1 = root only, 2 = root + L1, …).
+     * Absent or 0 = unlimited depth.
+     */
+    maxDepth?: number;
+    /**
+     * Strict mode: fail when missing DOC items are found (default: true).
+     * When true, throws MissingDocItemsError if any nodes lack doc_id or .md files.
+     * Set to false to allow placeholder comments for missing items (TASK-566).
+     */
+    strict?: boolean;
+}
+export interface AssembleResult {
+    /** Assembled markdown (undefined when returnContent is false) */
+    content?: string;
+    /** Number of BOM nodes processed */
+    nodesProcessed: number;
+    /** Node IDs that could not be resolved (missing doc_id or missing .md file) */
+    missingNodes: string[];
+    /** File path written to (if outputPath was given) */
+    outputPath?: string;
+}
+/**
+ * Assemble a BOM tree (or sub-tree) into a single Markdown document.
+ *
+ * @param opts - Assembly options (see AssembleOptions)
+ * @returns AssembleResult with content, stats, and missing-node list
+ */
+export declare function assembleDocument(opts: AssembleOptions): AssembleResult;
+//# sourceMappingURL=docs-assemble.d.ts.map

package/dist/core/docs-assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-assemble.d.ts","sourceRoot":"","sources":["../../src/core/docs-assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAwBH;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAKzC;CACF;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,KAAK,EAAE,MAAM,EAKxB;CACF;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,YAAY,EAAE,MAAM,EAAE,EAKjC;CACF;AAMD,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAwDD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CA+GtE"}

package/dist/core/docs-assemble.js

@@ -0,0 +1,210 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * docs-assemble — generic BOM-to-Markdown assembler.
+ *
+ * Reads docs-map.json, walks the BOM tree depth-first, and concatenates
+ * each node's DOC item content into a single coherent Markdown document.
+ *
+ * Design decisions:
+ * - Uses sync fs calls (same pattern as docs-map.ts) to keep this pure/sync.
+ * - Heading shift rule: node at depth D shifts all headings by D.
+ *   (root depth=0 → no shift; L1 depth=1 → H1→H2; L2 depth=2 → H1→H3)
+ * - Missing DOC items are silently skipped with a comment placeholder.
+ * - BOM node order within siblings is determined by `node.order` (ascending).
+ *
+ * @see STORY-298
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { readTextFile } from '../utils/text-file.js';
+import { readDocsMap } from './docs-map.js';
+import { extractFrontmatter } from './frontmatter.js';
+import { itemPaths } from './item-paths.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Valid DevSteps work item ID pattern.
+ * Used for path traversal defense (TASK-565).
+ */
+const WORK_ITEM_ID_PATTERN = /^(EPIC|STORY|TASK|REQ|FEAT|BUG|SPIKE|TEST|DOC)-\d{3,}$/;
+// ---------------------------------------------------------------------------
+// Custom Errors
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a circular parent_id reference is detected in the BOM tree.
+ * This prevents infinite recursion and stack overflow (TASK-564).
+ */
+export class CircularBOMError extends Error {
+    constructor(nodeId, path) {
+        super(`Circular BOM reference detected: node "${nodeId}" is already in the traversal path [${path.join(' → ')}]`);
+        this.name = 'CircularBOMError';
+    }
+}
+/**
+ * Thrown when a doc_id fails path traversal validation.
+ * Prevents directory traversal attacks (TASK-565).
+ */
+export class PathTraversalError extends Error {
+    constructor(docId) {
+        super(`Path traversal detected: doc_id "${docId}" does not match required pattern ${WORK_ITEM_ID_PATTERN.source}`);
+        this.name = 'PathTraversalError';
+    }
+}
+/**
+ * Thrown when strict mode is enabled and missing DOC items are found (TASK-566).
+ */
+export class MissingDocItemsError extends Error {
+    constructor(missingNodes) {
+        super(`Strict mode: ${missingNodes.length} missing DOC item(s) detected: ${missingNodes.join(', ')}`);
+        this.name = 'MissingDocItemsError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+/**
+ * Shift all ATX heading levels in a markdown string by `shift` positions.
+ * Headings that would exceed H6 are clamped to H6.
+ * Only shifts lines that start with `#` followed by a space (ATX style).
+ */
+function shiftHeadings(markdown, shift) {
+    if (shift === 0)
+        return markdown;
+    return markdown.replace(/^(#{1,6})( )/gm, (_match, hashes, space) => {
+        const newLevel = Math.min(hashes.length + shift, 6);
+        return '#'.repeat(newLevel) + space;
+    });
+}
+/**
+ * Build a child-lookup map from a flat adjacency list.
+ * Returns Map<parentId|null, sortedChildren>.
+ */
+function buildChildMap(nodes) {
+    const map = new Map();
+    for (const node of nodes) {
+        const key = node.parent_id;
+        if (!map.has(key))
+            map.set(key, []);
+        // biome-ignore lint/style/noNonNullAssertion: key was just set
+        map.get(key).push(node);
+    }
+    // Sort each sibling group by `order` ascending
+    for (const siblings of map.values()) {
+        siblings.sort((a, b) => a.order - b.order);
+    }
+    return map;
+}
+/**
+ * Resolve the filesystem path to a DOC item's master document.
+ * Pattern: `{devstepsDir}/items/docs/{docId}/{docId}.md` (STORY-427)
+ *
+ * SECURITY (TASK-565): Validates doc_id matches WORK_ITEM_ID_PATTERN
+ * to prevent path traversal attacks (e.g., "../../../secrets").
+ */
+function docItemMdPath(devstepsDir, docId) {
+    if (!WORK_ITEM_ID_PATTERN.test(docId)) {
+        throw new PathTraversalError(docId);
+    }
+    return itemPaths(devstepsDir, docId).description;
+}
+// ---------------------------------------------------------------------------
+// Core assembler
+// ---------------------------------------------------------------------------
+/**
+ * Assemble a BOM tree (or sub-tree) into a single Markdown document.
+ *
+ * @param opts - Assembly options (see AssembleOptions)
+ * @returns AssembleResult with content, stats, and missing-node list
+ */
+export function assembleDocument(opts) {
+    const { devstepsDir, rootId, outputPath, returnContent = true, includeFrontmatter = false, maxDepth, strict = true, } = opts;
+    const docsMap = readDocsMap(devstepsDir);
+    const childMap = buildChildMap(docsMap.nodes);
+    const fragments = [];
+    const missingNodes = [];
+    let nodesProcessed = 0;
+    /**
+     * DFS traversal. `depth` tracks distance from the assembly root (0-based).
+     * TASK-564: Added cycle detection via path tracking.
+     * TASK-569: Fixed to use path-scoped detection (not global visited Set).
+     */
+    function visit(node, depth, path) {
+        // TASK-569: Path-scoped cycle detection (prevents false positives on diamond patterns)
+        if (path.includes(node.id)) {
+            throw new CircularBOMError(node.id, path);
+        }
+        // Respect maxDepth (0 or absent = unlimited)
+        if (maxDepth && maxDepth > 0 && depth >= maxDepth)
+            return;
+        nodesProcessed++;
+        let fragment;
+        if (!node.doc_id) {
+            // BOM structural node without a DOC item — emit a comment placeholder
+            missingNodes.push(node.id);
+            fragment = `<!-- no-doc: ${node.id} (${node.title}) -->`;
+        }
+        else {
+            const mdPath = docItemMdPath(devstepsDir, node.doc_id);
+            if (!existsSync(mdPath)) {
+                missingNodes.push(node.id);
+                fragment = `<!-- missing: ${node.doc_id} (${node.title}) -->`;
+            }
+            else {
+                let raw = readTextFile(mdPath);
+                if (!includeFrontmatter) {
+                    const parsed = extractFrontmatter(raw);
+                    raw = parsed.body;
+                }
+                fragment = shiftHeadings(raw.trimEnd(), depth);
+            }
+        }
+        if (fragment)
+            fragments.push(fragment);
+        // Recurse into children (TASK-564: pass updated path for cycle detection)
+        const children = childMap.get(node.id) ?? [];
+        for (const child of children) {
+            visit(child, depth + 1, [...path, node.id]);
+        }
+    }
+    // Determine starting nodes
+    let startNodes;
+    if (rootId) {
+        const rootNode = docsMap.nodes.find((n) => n.id === rootId);
+        if (!rootNode) {
+            throw new Error(`docs_assemble: unknown root_id "${rootId}". ` +
+                `Available node IDs: ${docsMap.nodes.map((n) => n.id).join(', ') || '(none)'}`);
+        }
+        startNodes = [rootNode];
+    }
+    else {
+        // All root-level nodes (parent_id === null), sorted by order
+        startNodes = childMap.get(null) ?? [];
+    }
+    // TASK-568: Pre-flight root node check (detects fully-circular BOMs)
+    if (startNodes.length === 0 && docsMap.nodes.length > 0) {
+        throw new CircularBOMError('(no root nodes)', docsMap.nodes.map((n) => n.id));
+    }
+    for (const node of startNodes) {
+        visit(node, 0, []); // TASK-564: pass empty path array for cycle detection
+    }
+    const assembled = fragments.join('\n\n');
+    // TASK-566: Strict mode validation
+    if (strict && missingNodes.length > 0) {
+        throw new MissingDocItemsError(missingNodes);
+    }
+    // Write to file if requested
+    if (outputPath) {
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, assembled, 'utf-8');
+    }
+    return {
+        content: returnContent ? assembled : undefined,
+        nodesProcessed,
+        missingNodes,
+        outputPath: outputPath ?? undefined,
+    };
+}
+//# sourceMappingURL=docs-assemble.js.map

package/dist/core/docs-assemble.js.map

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

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

@@ -0,0 +1,74 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Core docs-map module — read/write/append/rebuild-shadow API for docs-map.json.
+ *
+ * Design decisions: SPIKE-036, ADR-007
+ * - ADR-S2-10: docs-map.json lives at .devsteps/docs-map.json
+ * - ADR-S2-11: Atomic dual-write (JSON primary + JSON shadow) via .tmp → rename
+ * - ADR-007: JSON adjacency list format (parent_id + order replace children[])
+ * - ADR-S2-06/07: position and level are derived at runtime, never stored
+ */
+import type { DocsMapDocument, DocsMapNode, DocsMapNodeUpsert } from '../types/docs-map.js';
+/**
+ * Read docs-map.json from .devsteps/docs-map.json.
+ * Returns an empty document if the file does not exist yet.
+ */
+export declare function readDocsMap(devstepsDir: string): DocsMapDocument;
+/**
+ * Atomic dual-write: persist docs-map.json + rebuild JSON shadow.
+ * Uses .tmp → rename to prevent partial writes (ADR-S2-11).
+ */
+export declare function writeDocsMap(devstepsDir: string, document: DocsMapDocument): void;
+/**
+ * Append a new node to the adjacency list.
+ * If parentId is not null, validates that the parent exists before appending.
+ * The node must already have parent_id set (should match parentId parameter).
+ * Performs atomic dual-write after mutation.
+ *
+ * @returns true if the node was appended, false if parentId was not found.
+ */
+export declare function appendDocsMapNode(devstepsDir: string, parentId: string | null, node: DocsMapNode): boolean;
+/**
+ * Insert or update a node in the adjacency list by its `id`.
+ * - If a node with `node.id` already exists: sets the supplied fields and keeps every omitted
+ *   one (title, order, doc_id, description, devsteps_items) as stored (BUG-168).
+ * - If no node with `node.id` exists: appends it, with order 0, its id as title and no items
+ *   where the input names none.
+ * A non-null parent must be another node of the map; `""`, the node itself or an unknown id is
+ * refused, and `null` makes the node a root. Performs atomic dual-write after mutation.
+ *
+ * @returns `{ action: 'updated' | 'created', found }`, or `{ action: 'error', found }` when the
+ *   parent is refused.
+ */
+export declare function upsertDocsMapNode(devstepsDir: string, node: DocsMapNodeUpsert): {
+    action: 'updated' | 'created' | 'error';
+    found: boolean;
+};
+/**
+ * Remove a node from the adjacency list, never its referenced DOC items or source files.
+ * Legacy two-argument calls remove descendants; public consumers explicitly default recursive
+ * to false. A dry run returns the same IDs without writing the map or its positions shadow.
+ *
+ * @returns IDs of all removed nodes (root + children).
+ */
+export declare function removeDocsMapNode(devstepsDir: string, id: string, options?: {
+    recursive?: boolean;
+    dryRun?: boolean;
+}): string[];
+/**
+ * Update the `devsteps_items` array on an existing node.
+ * - mode 'replace': replaces the array entirely.
+ * - mode 'append': adds new IDs (deduplicates).
+ * Performs atomic dual-write after mutation.
+ *
+ * @returns true if the node was found and updated, false if not found.
+ */
+export declare function patchDocsMapNodeItems(devstepsDir: string, id: string, itemIds: string[], mode?: 'replace' | 'append'): boolean;
+/**
+ * Rebuild the JSON shadow from the current docs-map.json without rewriting the primary file.
+ * Use this for index recovery or after external edits to docs-map.json.
+ */
+export declare function rebuildDocsMapShadow(devstepsDir: string): void;
+//# sourceMappingURL=docs-map.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docs-map.d.ts","sourceRoot":"","sources":["../../src/core/docs-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,iBAAiB,EAGlB,MAAM,sBAAsB,CAAC;AAsB9B;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAmBhE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAYjF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,IAAI,EAAE,WAAW,GAChB,OAAO,CAeT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,iBAAiB,GACtB;IAAE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAsB7D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACtD,MAAM,EAAE,CAkCV;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,GAAE,SAAS,GAAG,QAAmB,GACpC,OAAO,CAYT;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAG9D"}

package/dist/core/docs-map.js

@@ -0,0 +1,247 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Core docs-map module — read/write/append/rebuild-shadow API for docs-map.json.
+ *
+ * Design decisions: SPIKE-036, ADR-007
+ * - ADR-S2-10: docs-map.json lives at .devsteps/docs-map.json
+ * - ADR-S2-11: Atomic dual-write (JSON primary + JSON shadow) via .tmp → rename
+ * - ADR-007: JSON adjacency list format (parent_id + order replace children[])
+ * - ADR-S2-06/07: position and level are derived at runtime, never stored
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getCurrentTimestamp } from '../utils/index.js';
+const DOCS_MAP_PATH = 'docs-map.json';
+const POSITIONS_INDEX_DIR = 'index';
+const POSITIONS_INDEX_FILE = 'docs-map-positions.json';
+const SCHEMA_VERSION = '1.0';
+/**
+ * Resolve the docs-map.json path within a devstepsDir.
+ */
+function docsMapPath(devstepsDir) {
+    return join(devstepsDir, DOCS_MAP_PATH);
+}
+/**
+ * Resolve the docs-map-positions.json shadow path.
+ */
+function positionsIndexPath(devstepsDir) {
+    return join(devstepsDir, POSITIONS_INDEX_DIR, POSITIONS_INDEX_FILE);
+}
+/**
+ * Read docs-map.json from .devsteps/docs-map.json.
+ * Returns an empty document if the file does not exist yet.
+ */
+export function readDocsMap(devstepsDir) {
+    const filePath = docsMapPath(devstepsDir);
+    if (!existsSync(filePath)) {
+        return { version: SCHEMA_VERSION, nodes: [] };
+    }
+    const raw = readFileSync(filePath, 'utf-8');
+    let parsed = null;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { version: SCHEMA_VERSION, nodes: [] };
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return { version: SCHEMA_VERSION, nodes: [] };
+    }
+    return {
+        version: parsed.version ?? SCHEMA_VERSION,
+        nodes: Array.isArray(parsed.nodes) ? parsed.nodes : [],
+    };
+}
+/**
+ * Atomic dual-write: persist docs-map.json + rebuild JSON shadow.
+ * Uses .tmp → rename to prevent partial writes (ADR-S2-11).
+ */
+export function writeDocsMap(devstepsDir, document) {
+    const filePath = docsMapPath(devstepsDir);
+    const tmpPath = `${filePath}.tmp`;
+    // Ensure .devsteps/ directory exists
+    mkdirSync(devstepsDir, { recursive: true });
+    writeFileSync(tmpPath, JSON.stringify(document, null, 2), 'utf-8');
+    renameSync(tmpPath, filePath);
+    // Dual-write JSON shadow
+    _writePositionsShadow(devstepsDir, document);
+}
+/**
+ * Append a new node to the adjacency list.
+ * If parentId is not null, validates that the parent exists before appending.
+ * The node must already have parent_id set (should match parentId parameter).
+ * Performs atomic dual-write after mutation.
+ *
+ * @returns true if the node was appended, false if parentId was not found.
+ */
+export function appendDocsMapNode(devstepsDir, parentId, node) {
+    const document = readDocsMap(devstepsDir);
+    if (_findNode(document.nodes, node.id)) {
+        throw new Error(`BOM node already exists: ${node.id}`);
+    }
+    if (parentId !== null) {
+        const parent = _findNode(document.nodes, parentId);
+        if (!parent)
+            return false;
+    }
+    document.nodes.push({ ...node, parent_id: parentId });
+    writeDocsMap(devstepsDir, document);
+    return true;
+}
+/**
+ * Insert or update a node in the adjacency list by its `id`.
+ * - If a node with `node.id` already exists: sets the supplied fields and keeps every omitted
+ *   one (title, order, doc_id, description, devsteps_items) as stored (BUG-168).
+ * - If no node with `node.id` exists: appends it, with order 0, its id as title and no items
+ *   where the input names none.
+ * A non-null parent must be another node of the map; `""`, the node itself or an unknown id is
+ * refused, and `null` makes the node a root. Performs atomic dual-write after mutation.
+ *
+ * @returns `{ action: 'updated' | 'created', found }`, or `{ action: 'error', found }` when the
+ *   parent is refused.
+ */
+export function upsertDocsMapNode(devstepsDir, node) {
+    const document = readDocsMap(devstepsDir);
+    const existingIndex = document.nodes.findIndex((n) => n.id === node.id);
+    const found = existingIndex !== -1;
+    if (node.parent_id !== null &&
+        (node.parent_id === node.id || !_findNode(document.nodes, node.parent_id))) {
+        return { action: 'error', found };
+    }
+    const supplied = Object.fromEntries(Object.entries(node).filter(([, value]) => value !== undefined));
+    if (found) {
+        document.nodes[existingIndex] = { ...document.nodes[existingIndex], ...supplied };
+        writeDocsMap(devstepsDir, document);
+        return { action: 'updated', found };
+    }
+    document.nodes.push({ order: 0, title: node.id, devsteps_items: [], ...supplied });
+    writeDocsMap(devstepsDir, document);
+    return { action: 'created', found };
+}
+/**
+ * Remove a node from the adjacency list, never its referenced DOC items or source files.
+ * Legacy two-argument calls remove descendants; public consumers explicitly default recursive
+ * to false. A dry run returns the same IDs without writing the map or its positions shadow.
+ *
+ * @returns IDs of all removed nodes (root + children).
+ */
+export function removeDocsMapNode(devstepsDir, id, options = {}) {
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new Error('id is required and must be a non-empty string.');
+    }
+    for (const key of ['recursive', 'dryRun']) {
+        if (options[key] !== undefined && typeof options[key] !== 'boolean') {
+            throw new Error(`${key} must be a boolean.`);
+        }
+    }
+    id = id.trim();
+    const document = readDocsMap(devstepsDir);
+    const removed = [];
+    const visited = new Set();
+    function collectIds(nodeId) {
+        if (visited.has(nodeId))
+            return;
+        visited.add(nodeId);
+        removed.push(nodeId);
+        const children = document.nodes.filter((n) => n.parent_id === nodeId);
+        for (const child of children)
+            collectIds(child.id);
+    }
+    const target = _findNode(document.nodes, id);
+    if (!target)
+        return [];
+    if (options.recursive === false && document.nodes.some((node) => node.parent_id === id)) {
+        throw new Error(`Node '${id}' has children; set recursive=true to remove its subtree.`);
+    }
+    collectIds(id);
+    if (options.dryRun)
+        return removed;
+    document.nodes = document.nodes.filter((n) => !visited.has(n.id));
+    writeDocsMap(devstepsDir, document);
+    return removed;
+}
+/**
+ * Update the `devsteps_items` array on an existing node.
+ * - mode 'replace': replaces the array entirely.
+ * - mode 'append': adds new IDs (deduplicates).
+ * Performs atomic dual-write after mutation.
+ *
+ * @returns true if the node was found and updated, false if not found.
+ */
+export function patchDocsMapNodeItems(devstepsDir, id, itemIds, mode = 'append') {
+    const document = readDocsMap(devstepsDir);
+    const existingIndex = document.nodes.findIndex((n) => n.id === id);
+    if (existingIndex === -1)
+        return false;
+    const existing = document.nodes[existingIndex].devsteps_items ?? [];
+    document.nodes[existingIndex] = {
+        ...document.nodes[existingIndex],
+        devsteps_items: mode === 'replace' ? itemIds : [...new Set([...existing, ...itemIds])],
+    };
+    writeDocsMap(devstepsDir, document);
+    return true;
+}
+/**
+ * Rebuild the JSON shadow from the current docs-map.json without rewriting the primary file.
+ * Use this for index recovery or after external edits to docs-map.json.
+ */
+export function rebuildDocsMapShadow(devstepsDir) {
+    const document = readDocsMap(devstepsDir);
+    _writePositionsShadow(devstepsDir, document);
+}
+// ─── Private helpers ──────────────────────────────────────────────────────────
+/**
+ * Write the flat JSON shadow to .devsteps/index/docs-map-positions.json.
+ * Uses .tmp → rename for atomicity.
+ */
+function _writePositionsShadow(devstepsDir, document) {
+    const entries = _flattenNodes(document.nodes);
+    const index = {
+        updated: getCurrentTimestamp(),
+        entries,
+    };
+    const indexDir = join(devstepsDir, POSITIONS_INDEX_DIR);
+    mkdirSync(indexDir, { recursive: true });
+    const filePath = positionsIndexPath(devstepsDir);
+    const tmpPath = `${filePath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(index, null, 2), 'utf-8');
+    renameSync(tmpPath, filePath);
+}
+/**
+ * Flatten the adjacency list into DocsMapPositionEntry[] with derived position + depth.
+ * Position is dot-notation (e.g. "1.2.3") computed by traversing the parent_id chain.
+ * Nodes are sorted by `order` within each sibling group.
+ */
+function _flattenNodes(nodes) {
+    const result = [];
+    function processChildren(parentId, parentPosition, depth) {
+        const siblings = nodes
+            .filter((n) => n.parent_id === parentId)
+            .sort((a, b) => a.order - b.order);
+        for (let i = 0; i < siblings.length; i++) {
+            const node = siblings[i];
+            const position = parentPosition ? `${parentPosition}.${i + 1}` : `${i + 1}`;
+            result.push({
+                id: node.id,
+                doc_id: node.doc_id,
+                parent_arch_id: node.parent_id,
+                title: node.title,
+                devsteps_items: node.devsteps_items,
+                position,
+                depth,
+            });
+            processChildren(node.id, position, depth + 1);
+        }
+    }
+    processChildren(null, '', 0);
+    return result;
+}
+/**
+ * Find a node by ARCH-NNN id in the flat adjacency list.
+ */
+function _findNode(nodes, id) {
+    return nodes.find((n) => n.id === id) ?? null;
+}
+//# sourceMappingURL=docs-map.js.map