@oa-sdk/spec-bundler 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+++                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,240 @@
+# @oa-sdk/spec-bundler
+
+Declarative manifest-driven asset bundler, AST-free markdown link rewriter, and dependency reachability engine with cryptographic lockfile freshness verification.
+
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#zero-runtime-dependencies)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## 1. Overview & Architecture Boundaries
+
+`@oa-sdk/spec-bundler` is designed as a standalone, zero-dependency distribution packager within the specification ecosystem.
+
+```mermaid
+flowchart TD
+    subgraph Ecosystem ["Specification Ecosystem Boundaries"]
+        DP["@spec-platform/document-parser<br/>(Full AST & Knowledge Graph)"]
+        TE["@samchon/typespec-evidence<br/>(Compile-time Verification & CI Gate)"]
+        MB["@oa-sdk/spec-bundler<br/>(Zero-Dependency Bundler & Link Rewriter)"]
+    end
+
+    SRC["Source Specs & Documentation<br/>(Markdown, TypeSpec, Assets)"]
+    SRC --> DP
+    SRC --> TE
+    SRC --> MB
+
+    MB -->|1. BFS Reachability Traversal| TS["Tree-Shaking of Unused Docs"]
+    MB -->|2. Regex Masking| LR["Relative Link Coordinate Rewriting"]
+    MB -->|3. Anchor Integrity Auditing| AV["--check-anchors + 'Did you mean?'"]
+    MB -->|4. Cryptographic BOM| PK["Deterministic ZIP Archive + Lockfile"]
+```
+
+### Architectural Directives:
+- **Zero Runtime Dependencies**: Built strictly using Node.js built-ins (`node:fs`, `node:path`, `node:crypto`, `node:zlib`). Runs seamlessly via `npx` or `pnpm` without installing third-party parser runtimes.
+- **AST-Free Parsing via Code Fence Masking**: Avoids heavy AST parsers. Protects multi-line code fences (```` ```...``` ````), inline spans (`` `...` ``), and HTML blocks with temporary token masking to rewrite Markdown links at line/character-accurate offsets without mutating code samples.
+- **Single Source of Truth (SSOT) for Heading Slugs**: Implements GitHub-compliant Unicode slug normalization (`/[^\p{L}\p{N}\s-]/gu`), guaranteeing identical slug generation across Korean, CJK, and multilingual specifications.
+
+---
+
+## 2. Core Features
+
+### 2.1 BFS Tree-Shaking Reachability Traversal
+When `treeShake: true` is configured with entrypoints (e.g. `["META-GUIDE.md", "AGENTS.md"]`), the bundler performs a Breadth-First Search (BFS) over internal document links and TypeSpec `@evidence` citations:
+- Retains only explicitly referenced specifications, skills, and assets.
+- Automatically excludes unreferenced legacy guides, templates, and intermediate scratch files.
+- Operates safely on cyclic links and multi-hop references.
+
+### 2.2 Automated Markdown Link Rewriting
+- **Coordinate Recalculation**: Automatically updates relative paths when documents move to new positions in the bundle hierarchy.
+- **Protocol Normalization**: Converts absolute local `file:///...` links to portable bundle-relative paths.
+- **Fragment & Query Preservation**: Preserves URL fragments (`#heading-slug`) and search parameters (`?view=detail`).
+- **Reference Definition Support**: Seamlessly parses and rewrites CommonMark link reference definitions (`[id]: path/to/doc.md`).
+- **Unbundled Policy**: Configurable behavior for links pointing outside the bundle:
+  - `warn`: Emits a diagnostic warning.
+  - `error`: Blocks packaging with exit code 1.
+  - `preserve`: Retains the link as-is.
+  - `github-fallback`: Rewrites to GitHub repository URLs (using `gitRepositoryUrl`).
+
+### 2.3 Comprehensive Anchor Verification (`--check-anchors`)
+- Validates **intra-file anchors** (`[link](#heading)`) and **cross-file anchors** (`[link](./doc.md#heading)`).
+- Extracts heading slugs, explicit custom IDs (`{#custom-id}`), and HTML anchors (`<a id="...">`).
+- Employs a zero-dependency **Levenshtein distance matcher** to provide intelligent "Did you mean?" suggestions for broken anchor links.
+
+### 2.4 TypeSpec (`.tsp`) Bundle Reference Rewriting
+- Automatically rewrites outbound references in TypeSpec files during bundle assembly:
+  - `@evidence("path/to/doc.md#anchor", "reason")` rewritten to point to bundle-internal destination coordinates.
+  - Relative TypeSpec imports (`import "./common.tsp";`) rewritten to new bundle layout.
+  - Markdown links embedded within `@doc("... [Link](path) ...")` or `@doc("""...""")` rewritten.
+- Validates TypeSpec outbound references during `spec-bundler verify` with dead link detection and anchor fuzzy suggestions.
+
+### 2.5 Embedded Path-Mapping BOM & Bundle Path Resolver
+- Automatically embeds bidirectional path mappings in `META-INF/bundle.manifest.json`:
+  - `sourceToBundle`: Maps repository source paths to bundle-internal coordinates.
+  - `bundleToSource`: Maps bundle-internal coordinates back to original workspace source paths.
+- Provides `spec-bundler resolve` CLI and `resolveBundlePath()` API to instantly locate any workspace path or reference (including `#anchor` and `?query`) within a packaged archive with Levenshtein typo suggestions.
+
+### 2.6 Cryptographic Freshness & CI Gate
+- Tracks content hashes (SHA-256) of all bundled files in `bundle.manifest.lock.json`.
+- `spec-bundler check`: Instantaneous CI pre-commit gate (exits with code 1 if upstream sources drifted without regenerating the bundle).
+- Emits GitHub Actions workflow annotations (`::error file=...::...`) automatically in CI environments.
+
+### 2.7 Developer Experience & Visibility
+- **Dry-Run Preview (`--dry-run`)**: Simulates destination mappings, planned link rewrites, and lockfile updates with zero disk writes.
+- **Structured JSON (`--json`)**: Emits machine-readable output for orchestration pipelines.
+- **Detailed Diff Reporting (`--diff`)**: Prints terminal-colored line-by-line link rewriting plans.
+- **Visual ASCII Reachability Tree (`spec-bundler inspect`)**: Renders hierarchical entrypoint-to-dependency dependency trees.
+- **Reachability Provenance (`spec-bundler pack --explain <target>`)**: Explains exactly *why* a file was retained across hop-by-hop reference chains.
+- **JSON Schema Draft 2020-12 (`spec-bundler schema`)**: Emits and validates manifest configurations with typo detection.
+
+---
+
+## 3. CLI Usage Reference
+
+```bash
+# Package the bundle (auto-detects evidence-bundle.manifest.json or bundle.manifest.json)
+spec-bundler pack
+
+# Preview packaging with zero disk writes
+spec-bundler pack --dry-run
+
+# Output detailed terminal diff reporting of planned rewrites
+spec-bundler pack --dry-run --diff
+
+# Output structured machine-readable JSON
+spec-bundler pack --dry-run --json
+
+# Explain why a specific file was retained in the bundle
+spec-bundler pack --explain architecture-guides/core-flow.md
+
+# Force re-bundle even if files are fresh
+spec-bundler pack --force
+
+# Inspect hierarchical ASCII dependency reachability tree
+spec-bundler inspect
+
+# CI Gate: verify that bundle and lockfile are fresh
+spec-bundler check
+
+# Audit bundle links and verify anchor validity with fuzzy suggestions
+spec-bundler verify --check-anchors
+
+# Resolve workspace path or reference inside packaged bundle
+spec-bundler resolve dist/bundle.zip docs/requirements.md#user-profile
+spec-bundler resolve dist/bundle.zip docs/requirements.md#user-profile --json
+
+# Emit official JSON Schema (Draft 2020-12) for manifests
+spec-bundler schema --out docs/bundle-manifest.schema.json
+
+# Extract a bundle archive cleanly into a target directory
+spec-bundler unpack dist/bundle.zip --dest .agents/skills/
+```
+
+---
+
+## 4. Manifest Configuration (`bundle.manifest.json`)
+
+```json
+{
+  "$schema": "https://spec-platform.dev/schemas/bundle-manifest.v1.json",
+  "name": "evidence-meta-skill-bundle",
+  "version": "1.0.0",
+  "description": "Evidence meta skills and architecture contracts",
+  "archive": {
+    "output": "dist/evidence-bundle.zip"
+  },
+  "treeShake": true,
+  "entrypoints": [
+    "META-GUIDE.md",
+    "AGENTS.md"
+  ],
+  "targets": [
+    {
+      "source": "docs/**/*.md",
+      "dest": "docs/",
+      "include": ["**/*.md"]
+    },
+    {
+      "source": ".agents/skills/**",
+      "dest": "skills/"
+    },
+    {
+      "source": "specs/**/*.tsp",
+      "dest": "specs/"
+    }
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/tmp/**"
+  ],
+  "unbundledPolicy": "warn",
+  "gitRepositoryUrl": "https://github.com/organization/repository"
+}
+```
+
+---
+
+## 5. Programmatic API
+
+`@oa-sdk/spec-bundler` can be imported directly in Node.js / TypeScript:
+
+```typescript
+import {
+  createBundle,
+  verifyBundle,
+  checkFreshness,
+  inspectBundle,
+  explainReachability,
+  resolveBundlePath,
+  rewriteTypeSpecContent,
+  loadManifest,
+  normalizeSlug,
+  extractDocumentAnchors,
+} from "@oa-sdk/spec-bundler";
+
+// 1. Pack bundle programmatically
+const result = await createBundle("bundle.manifest.json", {
+  dryRun: false,
+  force: false,
+});
+console.log(`Generated ${result.outputPath} (${result.filesCount} files)`);
+
+// 2. Resolve references inside a bundle archive
+const resolution = resolveBundlePath(
+  result.outputPath,
+  "docs/requirements.md#user-profile",
+);
+console.log(resolution.bundlePath); // "docs/requirements.md"
+console.log(resolution.fullReference); // "docs/requirements.md#user-profile"
+
+// 3. Audit links and anchors
+const { freshness, deadLinks, warnings } = verifyBundle("bundle.manifest.json", {
+  checkAnchors: true,
+});
+if (deadLinks.length > 0) {
+  console.error("Dead links found:", deadLinks);
+}
+
+// 4. Inspect dependency reachability tree
+const tree = inspectBundle("bundle.manifest.json");
+console.log(tree.asciiTree);
+
+// 5. Trace reachability provenance
+const explanation = explainReachability("bundle.manifest.json", "docs/guide.md");
+console.log(explanation.retained ? `Retained via: ${explanation.chain?.join(" -> ")}` : "Eliminated");
+```
+
+---
+
+## 6. Conformance & Tolerance Rules
+
+| Rule | Specification | Example |
+| :--- | :--- | :--- |
+| **Unicode Slugification** | `/[^\p{L}\p{N}\s-]/gu` + `replace(/\s+/g, "-")` | `## 사용자 계정 검증` → `사용자-계정-검증` |
+| **Explicit Custom Anchor** | `{#custom-id}` syntax | `### 주문 정책 {#ca-order-policy}` → `ca-order-policy` |
+| **Dash Collapsing** | `replace(/-+/g, "-")` | `1. 개요 & 설정` → `1-개요-설정` |
+| **Numeric Prefix Tolerance** | Strips leading `^\d+[\.\)]\s*` | `1. 개요` matches `#1-개요` and `#개요` |
+| **HTML Anchors** | Matches `<a id="...">` and `<a name="...">` | `<a id="overview">` → `overview` |
+| **Fuzzy Suggestion** | Levenshtein distance $\le 3$ or substring ratio | `#user-prfole` → `(Did you mean '#user-profile'?)` |

package/dist/archiver.d.ts

@@ -0,0 +1,22 @@
+export declare function computeCrc32(buffer: Buffer): number;
+export interface ZipArchiveEntry {
+    path: string;
+    data: Buffer;
+    mtime?: Date;
+}
+/**
+ * Creates a standard, deterministic PKZIP archive buffer in pure Node.js.
+ */
+export declare function createZipArchive(entries: ZipArchiveEntry[]): Buffer;
+/**
+ * Reads and decompresses all entries from a ZIP archive buffer into an in-memory Map.
+ */
+export declare function readZipArchive(zipBuffer: Buffer): Map<string, Buffer>;
+/**
+ * Extracts a ZIP archive buffer into destination directory in pure Node.js.
+ */
+export declare function extractZipArchive(zipBuffer: Buffer, destDir: string): {
+    extractedCount: number;
+    files: string[];
+};
+//# sourceMappingURL=archiver.d.ts.map

package/dist/archiver.js

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+// CRC-32 lookup table for universal fallback
+const CRC32_TABLE = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) {
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    CRC32_TABLE[i] = c >>> 0;
+}
+export function computeCrc32(buffer) {
+    if (typeof zlib.crc32 === "function") {
+        return zlib.crc32(buffer) >>> 0;
+    }
+    let crc = 0xffffffff;
+    for (let i = 0; i < buffer.length; i++) {
+        crc = (crc >>> 8) ^ CRC32_TABLE[(crc ^ buffer[i]) & 0xff];
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Converts a JavaScript Date or timestamp to MS-DOS date and time format.
+ */
+function toDosDateTime(date) {
+    const d = date.getFullYear() < 1980 ? new Date("1980-01-01T00:00:00Z") : date;
+    const dosTime = ((d.getHours() & 0x1f) << 11) |
+        ((d.getMinutes() & 0x3f) << 5) |
+        ((Math.floor(d.getSeconds() / 2)) & 0x1f);
+    const dosDate = (((d.getFullYear() - 1980) & 0x7f) << 9) |
+        (((d.getMonth() + 1) & 0x0f) << 5) |
+        (d.getDate() & 0x1f);
+    return { time: dosTime, date: dosDate };
+}
+/**
+ * Creates a standard, deterministic PKZIP archive buffer in pure Node.js.
+ */
+export function createZipArchive(entries) {
+    // Sort entries alphabetically by path for reproducible archive output
+    const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+    const localChunks = [];
+    const centralChunks = [];
+    let offset = 0;
+    for (const entry of sorted) {
+        const filenameBuf = Buffer.from(entry.path, "utf8");
+        const uncompressedSize = entry.data.length;
+        const crc = computeCrc32(entry.data);
+        const compressedData = zlib.deflateRawSync(entry.data);
+        const compressedSize = compressedData.length;
+        const { time: dosTime, date: dosDate } = toDosDateTime(entry.mtime ?? new Date("2026-01-01T00:00:00Z"));
+        // --- Local File Header (30 bytes + filename + compressed data) ---
+        const localHeader = Buffer.alloc(30);
+        localHeader.writeUInt32LE(0x04034b50, 0); // Signature
+        localHeader.writeUInt16LE(20, 4); // Version needed (2.0)
+        localHeader.writeUInt16LE(0x0800, 6); // General purpose bit flag (UTF-8 filename)
+        localHeader.writeUInt16LE(8, 8); // Compression method (8 = Deflate)
+        localHeader.writeUInt16LE(dosTime, 10);
+        localHeader.writeUInt16LE(dosDate, 12);
+        localHeader.writeUInt32LE(crc, 14);
+        localHeader.writeUInt32LE(compressedSize, 18);
+        localHeader.writeUInt32LE(uncompressedSize, 22);
+        localHeader.writeUInt16LE(filenameBuf.length, 26);
+        localHeader.writeUInt16LE(0, 28); // Extra field length
+        const localEntry = Buffer.concat([localHeader, filenameBuf, compressedData]);
+        localChunks.push(localEntry);
+        // --- Central Directory Header (46 bytes + filename) ---
+        const centralHeader = Buffer.alloc(46);
+        centralHeader.writeUInt32LE(0x02014b50, 0); // Signature
+        centralHeader.writeUInt16LE(0x031e, 4); // Version made by (UNIX 3.0)
+        centralHeader.writeUInt16LE(20, 6); // Version needed (2.0)
+        centralHeader.writeUInt16LE(0x0800, 8); // General purpose bit flag (UTF-8)
+        centralHeader.writeUInt16LE(8, 10); // Compression method (Deflate)
+        centralHeader.writeUInt16LE(dosTime, 12);
+        centralHeader.writeUInt16LE(dosDate, 14);
+        centralHeader.writeUInt32LE(crc, 16);
+        centralHeader.writeUInt32LE(compressedSize, 20);
+        centralHeader.writeUInt32LE(uncompressedSize, 24);
+        centralHeader.writeUInt16LE(filenameBuf.length, 28);
+        centralHeader.writeUInt16LE(0, 30); // Extra field length
+        centralHeader.writeUInt16LE(0, 32); // File comment length
+        centralHeader.writeUInt16LE(0, 34); // Disk number start
+        centralHeader.writeUInt16LE(0, 36); // Internal file attributes
+        centralHeader.writeUInt16LE(0, 38); // External file attributes (DOS)
+        centralHeader.writeUInt16LE(0o100644, 40); // External file attributes (UNIX permissions)
+        centralHeader.writeUInt32LE(offset, 42); // Relative offset of local header
+        const centralEntry = Buffer.concat([centralHeader, filenameBuf]);
+        centralChunks.push(centralEntry);
+        offset += localEntry.length;
+    }
+    const centralDirectoryOffset = offset;
+    const centralDirectoryBuf = Buffer.concat(centralChunks);
+    const centralDirectorySize = centralDirectoryBuf.length;
+    // --- End of Central Directory Record (22 bytes) ---
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0); // Signature
+    eocd.writeUInt16LE(0, 4); // Disk number
+    eocd.writeUInt16LE(0, 6); // Disk where central directory starts
+    eocd.writeUInt16LE(sorted.length, 8); // Records on this disk
+    eocd.writeUInt16LE(sorted.length, 10); // Total records
+    eocd.writeUInt32LE(centralDirectorySize, 12);
+    eocd.writeUInt32LE(centralDirectoryOffset, 16);
+    eocd.writeUInt16LE(0, 20); // Comment length
+    return Buffer.concat([...localChunks, centralDirectoryBuf, eocd]);
+}
+/**
+ * Reads and decompresses all entries from a ZIP archive buffer into an in-memory Map.
+ */
+export function readZipArchive(zipBuffer) {
+    const entries = new Map();
+    let offset = 0;
+    while (offset + 30 <= zipBuffer.length) {
+        const sig = zipBuffer.readUInt32LE(offset);
+        if (sig !== 0x04034b50) {
+            break;
+        }
+        const compressionMethod = zipBuffer.readUInt16LE(offset + 8);
+        const compressedSize = zipBuffer.readUInt32LE(offset + 18);
+        const filenameLen = zipBuffer.readUInt16LE(offset + 26);
+        const extraLen = zipBuffer.readUInt16LE(offset + 28);
+        const filename = zipBuffer
+            .subarray(offset + 30, offset + 30 + filenameLen)
+            .toString("utf8");
+        const dataStart = offset + 30 + filenameLen + extraLen;
+        const compressedData = zipBuffer.subarray(dataStart, dataStart + compressedSize);
+        let uncompressedData;
+        if (compressionMethod === 8) {
+            uncompressedData = zlib.inflateRawSync(compressedData);
+        }
+        else if (compressionMethod === 0) {
+            uncompressedData = Buffer.from(compressedData);
+        }
+        else {
+            throw new Error(`Unsupported compression method in ZIP: ${compressionMethod}`);
+        }
+        entries.set(filename, uncompressedData);
+        offset = dataStart + compressedSize;
+    }
+    return entries;
+}
+/**
+ * Extracts a ZIP archive buffer into destination directory in pure Node.js.
+ */
+export function extractZipArchive(zipBuffer, destDir) {
+    const entries = readZipArchive(zipBuffer);
+    const files = [];
+    for (const [filename, uncompressedData] of entries.entries()) {
+        const targetPath = path.join(destDir, filename);
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.writeFileSync(targetPath, uncompressedData);
+        files.push(filename);
+    }
+    return { extractedCount: files.length, files };
+}
+//# sourceMappingURL=archiver.js.map

package/dist/category-parser.d.ts

@@ -0,0 +1,15 @@
+import type { DocumentCategory, DocumentFidelity } from "./types.js";
+export declare const STANDARD_CONTRACT_HEADINGS: string[];
+/**
+ * Parses the document category from YAML frontmatter or infers it from path heuristics.
+ */
+export declare function parseDocumentCategory(content: string, filePath: string): DocumentCategory;
+/**
+ * Extracts document content according to requested fidelity level (full, contract-only, summary).
+ * Prevents bundle bloat by stripping non-contract details for background/upstream documents.
+ */
+export declare function extractDocumentFidelity(content: string, category: DocumentCategory, fidelity?: DocumentFidelity, customSections?: string[]): {
+    content: string;
+    isModified: boolean;
+};
+//# sourceMappingURL=category-parser.d.ts.map