@vibe-agent-toolkit/resource-compiler 0.1.11

package/README.md

@@ -0,0 +1,449 @@
+# @vibe-agent-toolkit/resource-compiler
+
+> Compile markdown resources to TypeScript with full IDE support
+
+## Status
+
+🚧 **Under Development** - Phase 1: Core Compiler (v0.2.0)
+
+## Overview
+
+The resource compiler transforms markdown files into TypeScript modules with:
+
+- **Type-safe imports**: Import `.md` files directly in TypeScript
+- **Fragment extraction**: H2 headings become typed properties
+- **IDE support**: Autocomplete, go-to-definition, hover tooltips
+- **Frontmatter parsing**: YAML metadata becomes typed objects
+
+## Installation
+
+```bash
+npm install -D @vibe-agent-toolkit/resource-compiler
+```
+
+## Quick Start
+
+### 1. Create a Markdown File
+
+```markdown
+<!-- src/prompts/system.md -->
+---
+title: System Prompts
+version: 1.0
+---
+
+# System Prompts
+
+## Welcome
+
+You are a helpful AI assistant.
+
+## Farewell
+
+Thank you for using our system.
+```
+
+### 2. Compile to TypeScript
+
+```bash
+# Compile markdown files
+npx vat-compile-resources compile src/prompts dist/prompts
+
+# Or generate type declarations only
+npx vat-compile-resources generate-types src/prompts
+```
+
+### 3. Import in TypeScript
+
+```typescript
+import prompts from './prompts/system.md';
+
+// Type-safe access to frontmatter
+console.log(prompts.meta.title);        // "System Prompts"
+console.log(prompts.meta.version);      // 1.0
+
+// Access full markdown text
+console.log(prompts.text);
+
+// Access specific fragments (H2 sections)
+console.log(prompts.fragments.welcome.text);
+console.log(prompts.fragments.farewell.body);
+
+// Get all fragment names (type-safe)
+const names: ('welcome' | 'farewell')[] = ['welcome', 'farewell'];
+```
+
+## Build Integration
+
+When using the `compile` command, you generate JavaScript modules in a separate `generated/` directory. To ensure these modules are available at runtime, you need to copy them to your build output directory.
+
+### Why Copy Generated Resources?
+
+TypeScript's type-checker needs to resolve imports **during compilation**. Your source files import from the `generated/` directory:
+
+```typescript
+// src/agent.ts
+import * as Core from '../generated/resources/core.js';
+```
+
+When TypeScript compiles to `dist/`, it only copies compiled TypeScript files - not the generated JavaScript resources. You must copy `generated/` to `dist/` separately.
+
+### Recommended Pattern
+
+**Directory structure:**
+```
+your-package/
+├── resources/            # Source markdown (author these)
+│   └── prompts/
+│       └── core.md
+├── generated/            # Generated JS/TS (from compile command)
+│   └── resources/
+│       └── prompts/
+│           ├── core.js
+│           └── core.d.ts
+├── src/                  # Your TypeScript source
+│   └── agent.ts
+└── dist/                 # Build output
+    ├── src/              # Compiled TypeScript
+    │   └── agent.js
+    └── generated/        # Copied resources (post-build step)
+        └── resources/
+```
+
+**Build flow:**
+1. `compile` resources → `generated/`
+2. TypeScript compilation → `dist/src/`
+3. Copy `generated/` → `dist/generated/`
+
+### Method 1: Using the Provided Utility (Recommended)
+
+Create a post-build script using the provided cross-platform utility:
+
+```typescript
+// scripts/post-build.ts
+import { createPostBuildScript } from '@vibe-agent-toolkit/resource-compiler/utils';
+
+createPostBuildScript({
+  generatedDir: 'generated',
+  distDir: 'dist',
+  verbose: true,
+});
+```
+
+Update `package.json`:
+
+```json
+{
+  "scripts": {
+    "generate:resources": "vat-compile-resources compile resources/ generated/resources/",
+    "build": "npm run generate:resources && tsc && node scripts/post-build.js"
+  }
+}
+```
+
+### Method 2: Manual Copy (Custom Logic)
+
+For more control, use the `copyResources` utility directly:
+
+```typescript
+// scripts/post-build.ts
+import { copyResources } from '@vibe-agent-toolkit/resource-compiler/utils';
+
+copyResources({
+  sourceDir: 'generated',
+  targetDir: 'dist/generated',
+  verbose: true,
+});
+
+// Add custom logic here
+console.log('Build complete!');
+```
+
+### Method 3: Build Tool Integration
+
+Integrate with your build tool (Vite, Rollup, etc.):
+
+```typescript
+// vite.config.ts
+import { copyResources } from '@vibe-agent-toolkit/resource-compiler/utils';
+
+export default {
+  plugins: [
+    {
+      name: 'copy-resources',
+      closeBundle() {
+        copyResources({
+          sourceDir: 'generated',
+          targetDir: 'dist/generated',
+        });
+      },
+    },
+  ],
+};
+```
+
+### Cross-Platform Considerations
+
+**❌ Don't use shell commands:**
+```json
+"build": "tsc && cp -r generated dist/"  // Unix only!
+```
+
+**✅ Use Node.js APIs:**
+```typescript
+import { cpSync } from 'node:fs';
+cpSync('generated', 'dist/generated', { recursive: true });
+```
+
+The provided utilities use Node's built-in `cpSync()` which works on Windows, macOS, and Linux.
+
+### Alternative: Co-located Generation (Not Recommended)
+
+You could generate `.md.js` files alongside `.md` files:
+
+```
+resources/
+  ├── core.md
+  ├── core.md.js      # Generated - clutters source directory
+  └── core.md.d.ts    # Generated - clutters source directory
+```
+
+**Why we don't recommend this:**
+- ❌ Clutters your clean markdown directory with generated files
+- ❌ Makes `.gitignore` patterns more complex
+- ❌ Harder to clean generated files
+
+**Use a separate `generated/` directory instead** - it keeps source files clean and makes the build process explicit.
+
+## Documentation
+
+### CLI Commands
+
+#### `compile` - Compile Markdown to JavaScript/TypeScript
+
+Compiles markdown files to JavaScript modules and TypeScript declarations.
+
+```bash
+npx vat-compile-resources compile <input> <output> [options]
+```
+
+**Arguments:**
+- `<input>` - Input directory containing markdown files
+- `<output>` - Output directory for compiled files
+
+**Options:**
+- `-p, --pattern <pattern>` - Glob pattern for markdown files (default: `**/*.md`)
+- `-v, --verbose` - Enable verbose logging
+- `-w, --watch` - Watch mode for automatic recompilation
+
+**Example:**
+
+```bash
+# Compile all markdown files
+npx vat-compile-resources compile src/prompts dist/prompts
+
+# Compile with custom pattern
+npx vat-compile-resources compile src docs --pattern "guides/**/*.md"
+
+# Watch mode
+npx vat-compile-resources compile src dist --watch
+```
+
+#### `generate-types` - Generate .md.d.ts Declaration Files
+
+Generates TypeScript declaration files (`.md.d.ts`) alongside markdown files for use with the TypeScript transformer.
+
+```bash
+npx vat-compile-resources generate-types <input> [options]
+```
+
+**Arguments:**
+- `<input>` - Input directory containing markdown files
+
+**Options:**
+- `-p, --pattern <pattern>` - Glob pattern for markdown files (default: `**/*.md`)
+- `-v, --verbose` - Enable verbose logging
+
+**Example:**
+
+```bash
+# Generate declarations for all markdown files
+npx vat-compile-resources generate-types src/prompts
+
+# Generate with custom pattern
+npx vat-compile-resources generate-types docs --pattern "**/*.md"
+```
+
+### TypeScript Transformer
+
+The TypeScript transformer enables direct `.md` imports in TypeScript without pre-compilation.
+
+#### Setup with ts-patch
+
+1. Install dependencies:
+
+```bash
+npm install -D @vibe-agent-toolkit/resource-compiler ts-patch typescript
+```
+
+2. Update `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "transform": "@vibe-agent-toolkit/resource-compiler/transformer"
+      }
+    ]
+  }
+}
+```
+
+3. Patch TypeScript:
+
+```bash
+npx ts-patch install
+```
+
+4. Generate type declarations:
+
+```bash
+npx vat-compile-resources generate-types src/
+```
+
+5. Import markdown files:
+
+```typescript
+import prompts from './prompts/system.md';
+
+console.log(prompts.text);
+console.log(prompts.fragments.welcome.text);
+```
+
+#### How It Works
+
+1. **Generate Declarations**: `generate-types` creates `.md.d.ts` files alongside your markdown files
+2. **Transform Imports**: The transformer detects `.md` imports and inlines the compiled resource
+3. **Type Safety**: TypeScript uses `.md.d.ts` files to provide autocomplete and type checking
+
+#### Import Styles
+
+The transformer supports all TypeScript import styles:
+
+```typescript
+// Default import
+import doc from './doc.md';
+
+// Namespace import
+import * as doc from './doc.md';
+
+// Named imports
+import { text, fragments, meta } from './doc.md';
+```
+
+### API Reference
+
+#### Exported Types
+
+```typescript
+// From compiled markdown
+export interface Fragment {
+  readonly header: string;  // H2 heading with ##
+  readonly body: string;    // Content below heading
+  readonly text: string;    // header + body
+}
+
+export const meta: Record<string, unknown>;  // Frontmatter
+export const text: string;                   // Full markdown text
+export const fragments: Record<string, Fragment>;  // H2 sections
+export type FragmentName = keyof typeof fragments;
+```
+
+#### Compiler API
+
+```typescript
+import { compileMarkdownResources } from '@vibe-agent-toolkit/resource-compiler/compiler';
+
+const results = await compileMarkdownResources({
+  inputDir: 'src/prompts',
+  outputDir: 'dist/prompts',
+  pattern: '**/*.md',
+  verbose: true,
+});
+
+// Each result contains:
+interface CompileResult {
+  sourcePath: string;
+  jsPath: string;
+  dtsPath: string;
+  success: boolean;
+  error?: string;
+}
+```
+
+#### Transformer API
+
+```typescript
+import { createTransformer } from '@vibe-agent-toolkit/resource-compiler/transformer';
+import ts from 'typescript';
+
+const transformer = createTransformer({
+  verbose: true,
+});
+
+// Use with TypeScript compiler API
+const result = program.emit(
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  { before: [transformer] }
+);
+```
+
+#### Build Utilities API
+
+```typescript
+import { copyResources, createPostBuildScript } from '@vibe-agent-toolkit/resource-compiler/utils';
+
+// Copy resources with options
+copyResources({
+  sourceDir: 'generated',
+  targetDir: 'dist/generated',
+  verbose: true,
+});
+
+// Create a complete post-build script
+createPostBuildScript({
+  generatedDir: 'generated',
+  distDir: 'dist',
+  verbose: true,
+});
+```
+
+**Options:**
+
+```typescript
+interface CopyResourcesOptions {
+  sourceDir: string;   // Source directory with generated files
+  targetDir: string;   // Target directory in dist
+  verbose?: boolean;   // Enable logging (default: false)
+}
+```
+
+**Throws:**
+- Error if source directory doesn't exist
+- Error if copy operation fails
+
+### Language Service Plugin
+
+Coming soon - TypeScript language service plugin for enhanced IDE support.
+
+## Development
+
+See the implementation plan for development details.
+
+## License
+
+MIT

package/bin/vat-compile-resources

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCLI } from '../dist/cli/index.js';
+
+runCLI().catch((error) => {
+  console.error('CLI error:', error);
+  process.exit(1);
+});

package/dist/cli/compile-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI compile command implementation
+ */
+import type { Command } from 'commander';
+/**
+ * Register the compile command with Commander
+ *
+ * @param program - Commander program instance
+ */
+export declare function registerCompileCommand(program: Command): void;
+//# sourceMappingURL=compile-command.d.ts.map

package/dist/cli/compile-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-command.d.ts","sourceRoot":"","sources":["../../src/cli/compile-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyB7D"}

package/dist/cli/compile-command.js

@@ -0,0 +1,34 @@
+/**
+ * CLI compile command implementation
+ */
+import { compileMarkdownResources } from '../compiler/markdown-compiler.js';
+import { addCompileOptions, printCompilationSummary, exitWithResults } from './compile-utils.js';
+/**
+ * Register the compile command with Commander
+ *
+ * @param program - Commander program instance
+ */
+export function registerCompileCommand(program) {
+    addCompileOptions(program
+        .command('compile')
+        .description('Compile markdown resources to JavaScript and TypeScript')).action(async (input, output, options) => {
+        try {
+            const results = await compileMarkdownResources({
+                inputDir: input,
+                outputDir: output,
+                pattern: options.pattern,
+                verbose: options.verbose,
+            });
+            // Summary
+            console.log('');
+            console.log('Compilation complete:');
+            printCompilationSummary(results);
+            exitWithResults(results);
+        }
+        catch (error) {
+            console.error('Compilation error:', error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=compile-command.js.map

package/dist/cli/compile-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-command.js","sourceRoot":"","sources":["../../src/cli/compile-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,wBAAwB,EAAE,MAAM,kCAAkC,CAAC;AAE5E,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEjG;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,iBAAiB,CACf,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,yDAAyD,CAAC,CAC1E,CAAC,MAAM,CAAC,KAAK,EAAE,KAAa,EAAE,MAAc,EAAE,OAA8C,EAAE,EAAE;QAC7F,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,wBAAwB,CAAC;gBAC7C,QAAQ,EAAE,KAAK;gBACf,SAAS,EAAE,MAAM;gBACjB,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,OAAO,EAAE,OAAO,CAAC,OAAO;aACzB,CAAC,CAAC;YAEH,UAAU;YACV,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;YACrC,uBAAuB,CAAC,OAAO,CAAC,CAAC;YAEjC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/compile-utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared utilities for CLI commands
+ */
+import type { Command } from 'commander';
+import type { CompileResult } from '../compiler/types.js';
+/**
+ * Generic result type for CLI operations
+ */
+interface OperationResult {
+    sourcePath: string;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Print operation summary (generic)
+ *
+ * @param results - Operation results
+ * @param operationName - Name of the operation (e.g., "Recompiled", "Generated")
+ */
+export declare function printOperationSummary(results: OperationResult[], operationName: string): void;
+/**
+ * Print compilation summary
+ *
+ * @param results - Compilation results
+ */
+export declare function printCompilationSummary(results: CompileResult[]): void;
+/**
+ * Exit with appropriate code based on results
+ *
+ * @param results - Operation results
+ */
+export declare function exitWithResults(results: OperationResult[]): never;
+/**
+ * Add common compile/watch options to a command
+ *
+ * @param command - Commander command instance
+ * @returns Command with options added
+ */
+export declare function addCompileOptions(command: Command): Command;
+export {};
+//# sourceMappingURL=compile-utils.d.ts.map

package/dist/cli/compile-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-utils.d.ts","sourceRoot":"","sources":["../../src/cli/compile-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,UAAU,eAAe;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAY7F;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,KAAK,CAGjE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAM3D"}

package/dist/cli/compile-utils.js

@@ -0,0 +1,51 @@
+/**
+ * Shared utilities for CLI commands
+ */
+/**
+ * Print operation summary (generic)
+ *
+ * @param results - Operation results
+ * @param operationName - Name of the operation (e.g., "Recompiled", "Generated")
+ */
+export function printOperationSummary(results, operationName) {
+    const successCount = results.filter((r) => r.success).length;
+    const failureCount = results.filter((r) => !r.success).length;
+    console.log(`  ${operationName}: ${successCount} succeeded, ${failureCount} failed`);
+    if (failureCount > 0) {
+        const failures = results.filter((r) => !r.success);
+        for (const failure of failures) {
+            console.error(`  Error: ${failure.sourcePath}: ${failure.error ?? 'Unknown error'}`);
+        }
+    }
+}
+/**
+ * Print compilation summary
+ *
+ * @param results - Compilation results
+ */
+export function printCompilationSummary(results) {
+    printOperationSummary(results, 'Recompiled');
+}
+/**
+ * Exit with appropriate code based on results
+ *
+ * @param results - Operation results
+ */
+export function exitWithResults(results) {
+    const failureCount = results.filter((r) => !r.success).length;
+    process.exit(failureCount > 0 ? 1 : 0);
+}
+/**
+ * Add common compile/watch options to a command
+ *
+ * @param command - Commander command instance
+ * @returns Command with options added
+ */
+export function addCompileOptions(command) {
+    return command
+        .argument('<input>', 'Input directory containing markdown files')
+        .argument('<output>', 'Output directory for compiled files')
+        .option('-p, --pattern <pattern>', 'Glob pattern for markdown files', '**/*.md')
+        .option('-v, --verbose', 'Enable verbose logging', false);
+}
+//# sourceMappingURL=compile-utils.js.map

package/dist/cli/compile-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-utils.js","sourceRoot":"","sources":["../../src/cli/compile-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA0B,EAAE,aAAqB;IACrF,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IAC7D,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IAE9D,OAAO,CAAC,GAAG,CAAC,KAAK,aAAa,KAAK,YAAY,eAAe,YAAY,SAAS,CAAC,CAAC;IAErF,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACnD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,YAAY,OAAO,CAAC,UAAU,KAAK,OAAO,CAAC,KAAK,IAAI,eAAe,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAwB;IAC9D,qBAAqB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAA0B;IACxD,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IAC9D,OAAO,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,OAAO,OAAO;SACX,QAAQ,CAAC,SAAS,EAAE,2CAA2C,CAAC;SAChE,QAAQ,CAAC,UAAU,EAAE,qCAAqC,CAAC;SAC3D,MAAM,CAAC,yBAAyB,EAAE,iCAAiC,EAAE,SAAS,CAAC;SAC/E,MAAM,CAAC,eAAe,EAAE,wBAAwB,EAAE,KAAK,CAAC,CAAC;AAC9D,CAAC"}

package/dist/cli/generate-types-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI generate-types command implementation
+ */
+import type { Command } from 'commander';
+/**
+ * Register the generate-types command with Commander
+ *
+ * @param program - Commander program instance
+ */
+export declare function registerGenerateTypesCommand(program: Command): void;
+//# sourceMappingURL=generate-types-command.d.ts.map

package/dist/cli/generate-types-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-types-command.d.ts","sourceRoot":"","sources":["../../src/cli/generate-types-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyGzC;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2BnE"}