@oa-sdk/spec-bundler

Declarative manifest-driven specification bundler, AST-free markdown link rewriter, and author-defined bounded context platform with cryptographic lockfile freshness verification.

@oa-sdk/spec-bundler (also available internally as @spec-platform/meta-bundler) is a zero-dependency distribution packager, AST-free link rewriter, and author-defined context platform for documentation and specifications.

1. Quick Start & Installation

Zero-Install via npx

Run commands directly without installing:

# Package a bundle or slice
npx @oa-sdk/spec-bundler pack

# Create a new topic profile
npx @oa-sdk/spec-bundler topic create my-feature --phase develop --entry specs/feature.md

# Inspect reachability dependency tree
npx @oa-sdk/spec-bundler inspect

# Verify link and anchor integrity
npx @oa-sdk/spec-bundler verify --check-anchors

Global CLI Installation

npm install -g @oa-sdk/spec-bundler
# Now run with either command:
spec-bundler --help
meta-bundler --help

Project Dev Dependency

# In npm
npm install --save-dev @oa-sdk/spec-bundler

# In pnpm
pnpm add -D @oa-sdk/spec-bundler

2. Architecture & Core Directives

flowchart TD
    subgraph Ecosystem ["Specification Ecosystem Boundaries"]
        DP["@spec-platform/document-parser<br/>(Full AST & Knowledge Graph)"]
        MB["@oa-sdk/spec-bundler<br/>(Zero-Dependency Bundler & Link Rewriter)"]
    end

    SRC["Source Specs & Documentation<br/>(Markdown, TypeSpec, Assets)"]
    SRC --> DP
    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. Topic Slicing & Context| CTX["CONTEXT.md + BOM + Sliced Sections"]
    MB -->|5. 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 instantly 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.
• SSOT Heading Slug Normalization: Implements GitHub-compliant Unicode slug normalization (/[^\p{L}\p{N}\s-]/gu), guaranteeing identical slug generation across Korean, CJK, and multilingual specifications.
• Author-Defined Context Platform: Rejects opaque black-box AI automation in favor of explicit author declarations across 4 lifecycle work phases (develop, fix, test, review).

3. The 4 Workflow Lifecycle Phases (phase)

Before modifying code or reading the repository arbitrarily, authors declare a topic slice with a specific lifecycle phase:

| Phase | Purpose | Traversal Direction | Included Categories | Fidelity Strategy | | :--- | :--- | :--- | :--- | :--- | | develop | Initial feature implementation | downstream | feature, mechanism, convention | Full implementation details | | fix | Bug resolution & refactoring | bidirectional (upstreamDepth: 1) | feature, error, issue | Upstream callers: contract-onlyIssue docs: summary | | test | QA verification & invariant checks | downstream | feature, error, mechanism | Mechanism: contract-only | | review | Architecture review & RFC briefing | bidirectional (upstreamDepth: 1) | All 5 categories | Upstream: contract-onlyAll docs: summary |

4. CLI Usage Reference

pack — Package Bundle or Topic Slice

Builds the bundle, rewrites relative links to bundle coordinates (./), deduplicates entries, generates the ZIP/directory output, and synchronizes the lockfile.

# 1. Package default manifest (auto-detects evidence-bundle.manifest.json or bundle.manifest.json)
spec-bundler pack

# 2. Package a specific topic profile slice
spec-bundler pack --topic my-feature

# 3. Package all declared topic profiles sequentially
spec-bundler pack --all-topics

# 4. Preview packaging in memory with zero disk writes
spec-bundler pack --dry-run

# 5. Output structured JSON for automation pipelines
spec-bundler pack --dry-run --json

# 6. Terminal diff report showing exact planned link rewrites
spec-bundler pack --diff

# 7. Trace reachability provenance for a specific file
spec-bundler pack --explain specs/features/canvas.md

# 8. Force re-bundle even if files are fresh
spec-bundler pack --force

topic create — Register Topic Slice with Lifecycle Presets

Scaffolds a new topic profile directly into the manifest without editing JSON manually:

# Feature Development: downstream traversal, feature + mechanism + convention
spec-bundler topic create canvas-draw \
  --phase develop \
  --author alice \
  --entry specs/canvas.md \
  --desc "Canvas drawing feature implementation"

# Bugfix / Refactoring: 1-hop bidirectional, contract-only upstream callers, issue summary
spec-bundler topic create canvas-leak \
  --phase fix \
  --author bob \
  --entry specs/canvas.md \
  --issue BUG-101 \
  --desc "Fix VRAM memory leak with caller contract protection"

# Testing & QA: downstream, contract-only mechanisms, error catalogs
spec-bundler topic create test-canvas \
  --phase test \
  --author qa-lead \
  --entry specs/canvas.md \
  --desc "Verify buffer overflow and recovery invariants"

# Architecture / Peer Review: bidirectional, compact summary across all 5 pillars
spec-bundler topic create review-arch \
  --phase review \
  --author architect \
  --entry specs/canvas.md \
  --desc "High-level review slice for RFC"

topics — List Declared Topic Profiles

Lists all declared topic profiles configured in the manifest:

spec-bundler topics
# Or machine-readable JSON:
spec-bundler topics --json

inspect — Dependency Reachability Tree

Renders the visual hierarchical ASCII dependency reachability tree, size breakdown, upstream callers, and boundary terminals:

# Inspect global manifest:
spec-bundler inspect

# Inspect specific topic slice:
spec-bundler inspect --topic canvas-leak

check — CI Drift & Freshness Gate

Exits with code 0 if the bundle and lockfile are fresh, or code 1 if upstream source files were modified without regenerating the bundle:

# Standard CI check:
spec-bundler check

# Check specific topic lockfile:
spec-bundler check --topic canvas-leak

verify — Link Integrity & Anchor Auditing

Validates link integrity (detects dead links with fuzzy "Did you mean?" suggestions), anchor validity (#heading-slug, custom IDs {#custom-id}, HTML <a id="...">), and collision warnings:

# Full verification with anchor checks:
spec-bundler verify --check-anchors

# Verify a topic profile:
spec-bundler verify --topic canvas-leak --check-anchors

resolve — Locate Coordinates in Bundle Archive

Resolves a source path, relative reference, or TypeSpec target to its coordinate inside a compressed .zip archive using the BOM:

spec-bundler resolve dist/bundle.zip "specs/canvas.md#drawing-modes"
spec-bundler resolve dist/bundle.zip "specs/canvas.md#drawing-modes" --json

schema — JSON Schema Export

Emits the official JSON Schema (Draft 2020-12) for validation and IDE autocomplete:

spec-bundler schema --out schemas/bundle.manifest.schema.json

unpack — Extract Archive

Extracts a bundle archive cleanly into a target directory:

spec-bundler unpack dist/bundle.zip --dest ./extracted

5. Manifest Configuration Format (bundle.manifest.json)

{
  "$schema": "https://spec-platform.dev/schemas/bundle-manifest.v1.json",
  "name": "paint-system",
  "version": "1.0.0",
  "description": "Paint system specification and architecture contracts",
  "output": "dist/paint-system.zip",
  "format": "zip",
  "targets": [
    { "source": "specs/**", "dest": "specs/" }
  ],
  "linkResolution": {
    "unbundledPolicy": "warn",
    "gitRepositoryUrl": "https://github.com/my-org/my-repo"
  },
  "treeShake": {
    "enabled": true,
    "entrypoints": ["specs/features/canvas.md"],
    "stopAt": ["**/external/**", "**/contributing.md"],
    "maxDepth": 5
  },
  "topics": {
    "canvas-fix": {
      "phase": "fix",
      "author": "junwoo",
      "description": "Fix memory leak under heavy zoom",
      "targets": [{ "source": "specs/**", "dest": "specs/" }],
      "scope": {
        "direction": "bidirectional",
        "upstreamDepth": 1,
        "entrypoints": ["specs/features/canvas.md"],
        "includeCategories": ["feature", "error", "issue"],
        "categoryFidelity": {
          "upstream": "contract-only",
          "issue": "summary"
        }
      },
      "context": {
        "issue": "BUG-101",
        "generateContextDoc": true
      }
    }
  }
}

6. Programmatic TypeScript API

@oa-sdk/spec-bundler can be imported directly in Node.js / TypeScript:

import {
  createBundle,
  verifyBundle,
  checkFreshness,
  inspectBundle,
  explainReachability,
  resolveBundlePath,
  createTopicProfile,
  addTopicToManifest,
  normalizeSlug,
  extractDocumentAnchors,
} from "@oa-sdk/spec-bundler";

// 1. Pack bundle or topic slice programmatically
const result = await createBundle("bundle.manifest.json", {
  topic: "canvas-fix",
  dryRun: false,
  force: true,
});
console.log(`Generated ${result.outputPath} (${result.filesCount} files)`);

// 2. Resolve references inside a bundle archive
const resolution = resolveBundlePath(
  result.outputPath,
  "specs/canvas.md#drawing-modes",
);
console.log(resolution.bundlePath); // "specs/canvas.md"
console.log(resolution.fullReference); // "specs/canvas.md#drawing-modes"

// 3. Audit links and anchors with fuzzy suggestions
const { freshness, deadLinks, warnings } = verifyBundle("bundle.manifest.json", {
  checkAnchors: true,
  topic: "canvas-fix",
});
if (deadLinks.length > 0) {
  console.error("Dead links found:", deadLinks);
}

// 4. Inspect dependency reachability tree
const tree = inspectBundle("bundle.manifest.json", { topic: "canvas-fix" });
console.log(tree.asciiTree);

// 5. Scaffold and register topic profile
const profile = createTopicProfile({
  name: "export-svg",
  phase: "develop",
  author: "junwoo",
  entrypoints: ["specs/svg-exporter.md"],
  description: "SVG exporter implementation",
});
addTopicToManifest("bundle.manifest.json", "export-svg", profile);

7. 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'?) |

8. Declared Syntaxes & Directory Context (.context.json) Integration

For complete syntax specifications and ground-truth conventions, consult the authoritative guide: 👉 Spec Platform Syntax & Directory Context Guide

Key Declarations Overview:

1. bundle.manifest.json Grammars: Declarative manifest syntax controlling targets, link rewriting, deduplication, tree-shaking, and topic scopes.
2. Topic Slicing & Work Phases: 4 lifecycle phases (develop, fix, test, review) with curated directions (downstream, bidirectional) and category filters.
3. Document Category Taxonomy: Frontmatter (category: feature | mechanism | error | issue | convention) and contract heading extraction (contract-only, summary).
4. Local Directory Context (.context.json):
   • Ground Truth Anchor: Eliminates AI agent cold starts (Zero Search Overhead) by providing pre-task alignment per directory.
   • 3 WorkMode Perspectives: design (Why & What), implementation (How & Standards), and review (Invariants & Compliance).
   • Delta Sensing: Automatically detects Platform Blindspots (DESIGN_GAP) and enforces local governance compliance.