instrux 0.1.0

package/dist/compiler.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * instrux — Recursive Handlebars compiler.
+ *
+ * Compiles an entry template by resolving {{tag}}, {{file}}, and {{tagged}}
+ * helpers recursively, producing a single merged output document.
+ *
+ * Compilation pipeline:
+ *   1. Scan sources → parse frontmatter → build tag index
+ *   2. Starting from the entry file, compile as Handlebars template
+ *   3. Helpers resolve tags/files → each is itself compiled (recursion)
+ *   4. Cycle detection via a compile stack
+ *   5. Emit final output with optional frontmatter passthrough
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstruxCompiler = void 0;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const handlebars_1 = __importDefault(require("handlebars"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const frontmatter_1 = require("./frontmatter");
+class InstruxCompiler {
+    constructor(rootDir, config) {
+        this.compileStack = new Set();
+        this.compiledFiles = new Set();
+        this.tagsUsed = new Set();
+        this.rootDir = rootDir;
+        this.config = config;
+    }
+    // ── Public API ───────────────────────────────────────────
+    async compile() {
+        if (!this.config.entry) {
+            throw new Error('No "entry" field in agent config. Use "files" for simple merge mode.');
+        }
+        if (!this.config.sources || this.config.sources.length === 0) {
+            throw new Error('No "sources" patterns defined. Add source globs to agent config.');
+        }
+        // 1. Build the source index
+        console.log('  📑 Scanning sources...');
+        this.index = await (0, frontmatter_1.buildSourceIndex)(this.rootDir, this.config.sources);
+        console.log(`     Found ${this.index.files.length} source files, ${this.index.tags.size} unique tags`);
+        // 2. Compile starting from entry
+        console.log('  🔧 Compiling templates...');
+        this.compileStack.clear();
+        this.compiledFiles.clear();
+        this.tagsUsed.clear();
+        const entryPath = this.config.entry.replace(/\\/g, '/');
+        const body = this.compileFile(entryPath);
+        // 3. Handle output frontmatter
+        let output = '';
+        const fmMode = this.config.frontmatter?.output ?? 'strip';
+        if (fmMode === 'preserve') {
+            const entrySource = this.index.paths.get(entryPath);
+            if (entrySource) {
+                const cleanFm = (0, frontmatter_1.stripInstruxMeta)(entrySource.frontmatter);
+                output += (0, frontmatter_1.serializeFrontmatter)(cleanFm);
+            }
+        }
+        output += body;
+        // Ensure trailing newline
+        if (!output.endsWith('\n'))
+            output += '\n';
+        return {
+            output,
+            filesCompiled: this.compiledFiles.size,
+            tagsUsed: [...this.tagsUsed],
+        };
+    }
+    // ── Recursive file compilation ───────────────────────────
+    compileFile(relPath) {
+        const normalised = relPath.replace(/\\/g, '/');
+        // Cycle detection
+        if (this.compileStack.has(normalised)) {
+            const chain = [...this.compileStack, normalised].join(' → ');
+            throw new Error(`Circular reference detected:\n  ${chain}`);
+        }
+        this.compileStack.add(normalised);
+        this.compiledFiles.add(normalised);
+        // Resolve content — from index or from disk
+        let content;
+        const indexed = this.index.paths.get(normalised);
+        if (indexed) {
+            content = indexed.content;
+        }
+        else {
+            // File not in source index — try reading directly
+            const absPath = path.join(this.rootDir, normalised);
+            if (!fs.pathExistsSync(absPath)) {
+                throw new Error(`File not found: ${normalised}`);
+            }
+            const raw = fs.readFileSync(absPath, 'utf-8');
+            const parsed = (0, gray_matter_1.default)(raw);
+            content = parsed.content;
+        }
+        // Create a sandboxed Handlebars instance
+        const hbs = handlebars_1.default.create();
+        this.registerHelpers(hbs);
+        // Compile as Handlebars template (noEscape: markdown, not HTML)
+        const template = hbs.compile(content, { noEscape: true });
+        const rendered = template({
+            agent: {
+                name: this.config.name,
+                description: this.config.description,
+            },
+            meta: indexed?.frontmatter ?? {},
+        });
+        this.compileStack.delete(normalised);
+        return rendered;
+    }
+    // ── Handlebars helpers ───────────────────────────────────
+    registerHelpers(hbs) {
+        const self = this;
+        const sep = this.config.mergeSettings.addSeparators
+            ? `\n${this.config.mergeSettings.separatorStyle}\n\n`
+            : '\n\n';
+        /**
+         * {{tag "tagname"}}
+         *
+         * Include all files matching the given tag, sorted by instrux.order.
+         * Each file is recursively compiled.
+         */
+        hbs.registerHelper('tag', function (tagName) {
+            self.tagsUsed.add(tagName);
+            const files = self.index.tags.get(tagName);
+            if (!files || files.length === 0) {
+                console.log(`     ⚠  Tag "${tagName}" matched 0 files`);
+                return '';
+            }
+            const sorted = (0, frontmatter_1.sortSourceFiles)(files);
+            const rendered = sorted.map(f => self.compileFile(f.path));
+            return new hbs.SafeString(rendered.join(sep));
+        });
+        /**
+         * {{file "path/to/file.md"}}
+         *
+         * Include a specific file by path. Recursively compiled.
+         */
+        hbs.registerHelper('file', function (filePath) {
+            return new hbs.SafeString(self.compileFile(filePath));
+        });
+        /**
+         * {{#each (tagged "tagname")}} ... {{/each}}
+         *
+         * Returns an array of objects for iteration. Each object has:
+         *   - body:        recursively compiled content
+         *   - raw:         uncompiled content
+         *   - path:        relative file path
+         *   - title:       frontmatter title (shortcut)
+         *   - description: frontmatter description (shortcut)
+         *   - frontmatter: full frontmatter object
+         *   - instrux:     instrux metadata
+         */
+        hbs.registerHelper('tagged', function (tagName) {
+            self.tagsUsed.add(tagName);
+            const files = self.index.tags.get(tagName);
+            if (!files || files.length === 0) {
+                console.log(`     ⚠  Tag "${tagName}" matched 0 files`);
+                return [];
+            }
+            const sorted = (0, frontmatter_1.sortSourceFiles)(files);
+            return sorted.map(f => ({
+                body: self.compileFile(f.path),
+                raw: f.content,
+                path: f.path,
+                title: f.frontmatter.title ?? path.basename(f.path, '.md'),
+                description: f.frontmatter.description ?? f.instrux.description ?? '',
+                frontmatter: f.frontmatter,
+                instrux: f.instrux,
+            }));
+        });
+        /**
+         * {{meta "key"}}
+         *
+         * Access a frontmatter value from the current file's context.
+         */
+        hbs.registerHelper('meta', function (key, options) {
+            return options.data?.root?.meta?.[key] ?? '';
+        });
+    }
+}
+exports.InstruxCompiler = InstruxCompiler;
+//# sourceMappingURL=compiler.js.map

package/dist/compiler.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,39 @@
+/**
+ * instrux - Core engine
+ *
+ * Loads agent configs, validates source files, and either:
+ *   - Simple merge: concatenates files in order (v1)
+ *   - Compile: resolves Handlebars templates + frontmatter tags (v2)
+ */
+import { AgentConfig, BuildResult, ValidationResult } from './types';
+export declare class InstruxEngine {
+    private rootDir;
+    constructor(rootDir?: string);
+    /**
+     * Resolve the config path for a given agent name.
+     * Looks in `agents/<name>/agent.json`.
+     */
+    private agentConfigPath;
+    /**
+     * Load an agent configuration by name.
+     */
+    loadConfig(agentName: string): Promise<AgentConfig>;
+    /**
+     * List all agents found in the `agents/` directory.
+     */
+    listAgents(): Promise<{
+        name: string;
+        config: AgentConfig | null;
+    }[]>;
+    validate(config: AgentConfig): Promise<ValidationResult>;
+    merge(config: AgentConfig): Promise<string>;
+    writeOutput(config: AgentConfig, content: string): Promise<string>;
+    /**
+     * Returns true if the agent config uses the template compiler (v2)
+     * instead of simple ordered merge.
+     */
+    isCompileMode(config: AgentConfig): boolean;
+    build(agentName: string): Promise<BuildResult>;
+    contentHash(content: string): string;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EACL,WAAW,EACX,WAAW,EACX,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAGjB,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,CAAC,EAAE,MAAM;IAM5B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBzD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC;IAgCrE,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqBxD,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA+C3C,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BxE;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAIrC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgDpD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAOrC"}

package/dist/engine.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * instrux - Core engine
+ *
+ * Loads agent configs, validates source files, and either:
+ *   - Simple merge: concatenates files in order (v1)
+ *   - Compile: resolves Handlebars templates + frontmatter tags (v2)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstruxEngine = void 0;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const compiler_1 = require("./compiler");
+class InstruxEngine {
+    constructor(rootDir) {
+        this.rootDir = rootDir ?? process.cwd();
+    }
+    // ── Config loading ───────────────────────────────────────
+    /**
+     * Resolve the config path for a given agent name.
+     * Looks in `agents/<name>/agent.json`.
+     */
+    agentConfigPath(agentName) {
+        return path.join(this.rootDir, 'agents', agentName, 'agent.json');
+    }
+    /**
+     * Load an agent configuration by name.
+     */
+    async loadConfig(agentName) {
+        const configPath = this.agentConfigPath(agentName);
+        if (!(await fs.pathExists(configPath))) {
+            throw new Error(`Agent config not found: ${path.relative(this.rootDir, configPath)}\n` +
+                `Run "instrux init <name>" to create one.`);
+        }
+        const raw = await fs.readFile(configPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    // ── Discovery ────────────────────────────────────────────
+    /**
+     * List all agents found in the `agents/` directory.
+     */
+    async listAgents() {
+        const agentsDir = path.join(this.rootDir, 'agents');
+        if (!(await fs.pathExists(agentsDir))) {
+            return [];
+        }
+        const entries = await fs.readdir(agentsDir, { withFileTypes: true });
+        const dirs = entries.filter(e => e.isDirectory() && e.name !== 'base');
+        const agents = [];
+        for (const dir of dirs) {
+            const configPath = path.join(agentsDir, dir.name, 'agent.json');
+            let config = null;
+            if (await fs.pathExists(configPath)) {
+                try {
+                    config = JSON.parse(await fs.readFile(configPath, 'utf-8'));
+                }
+                catch {
+                    // invalid JSON — still list the directory
+                }
+            }
+            agents.push({ name: dir.name, config });
+        }
+        return agents;
+    }
+    // ── Validation ───────────────────────────────────────────
+    async validate(config) {
+        const missing = [];
+        const warnings = [];
+        const files = config.files ?? [];
+        for (const file of files) {
+            const fullPath = path.join(this.rootDir, file.path);
+            const exists = await fs.pathExists(fullPath);
+            if (!exists && file.required) {
+                missing.push(file.path);
+            }
+            else if (!exists && !file.required) {
+                warnings.push(`Optional file not found: ${file.path}`);
+            }
+        }
+        return { valid: missing.length === 0, missing, warnings };
+    }
+    // ── Merge ────────────────────────────────────────────────
+    async merge(config) {
+        const { mergeSettings } = config;
+        let merged = '';
+        let first = true;
+        const files = config.files ?? [];
+        if (mergeSettings.includeFileHeaders) {
+            merged += `<!-- Generated by instrux -->\n`;
+            merged += `<!-- Agent: ${config.name} -->\n`;
+            merged += `<!-- Generated: ${new Date().toISOString()} -->\n\n`;
+        }
+        for (const file of files) {
+            const fullPath = path.join(this.rootDir, file.path);
+            let content = '';
+            if (await fs.pathExists(fullPath)) {
+                content = await fs.readFile(fullPath, 'utf-8');
+            }
+            if (!content || content.trim().length === 0) {
+                const kind = file.required ? 'required' : 'optional';
+                console.log(`  ⚠  Skipping empty ${kind} file: ${file.path}`);
+                continue;
+            }
+            // separator between sections (not before the first)
+            if (!first && mergeSettings.addSeparators) {
+                merged += `\n${mergeSettings.separatorStyle}\n\n`;
+            }
+            if (mergeSettings.includeFileHeaders) {
+                merged += `<!-- File: ${file.path} -->\n`;
+                merged += `<!-- ${file.description} -->\n\n`;
+            }
+            merged += content;
+            if (!content.endsWith('\n'))
+                merged += '\n';
+            first = false;
+        }
+        return merged;
+    }
+    // ── Write output ─────────────────────────────────────────
+    async writeOutput(config, content) {
+        const outputDir = path.join(this.rootDir, config.outputDirectory);
+        await fs.ensureDir(outputDir);
+        let fileName = config.outputFilePattern;
+        if (config.mergeSettings.useTimestamp) {
+            const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+            fileName = fileName.replace('{timestamp}', ts);
+        }
+        else {
+            fileName = fileName
+                .replace('_{timestamp}', '')
+                .replace('{timestamp}_', '')
+                .replace('{timestamp}', '');
+        }
+        if (config.mergeSettings.generateHash) {
+            const hash = this.contentHash(content);
+            fileName = fileName.replace('.md', `_${hash}.md`);
+        }
+        const outputPath = path.join(outputDir, fileName);
+        await fs.writeFile(outputPath, content, 'utf-8');
+        return outputPath;
+    }
+    // ── Build (validate → merge/compile → write) ───────────
+    /**
+     * Returns true if the agent config uses the template compiler (v2)
+     * instead of simple ordered merge.
+     */
+    isCompileMode(config) {
+        return !!config.entry;
+    }
+    async build(agentName) {
+        const config = await this.loadConfig(agentName);
+        // ── Template compilation mode ──────────────────────
+        if (this.isCompileMode(config)) {
+            const compiler = new compiler_1.InstruxCompiler(this.rootDir, config);
+            const result = await compiler.compile();
+            const outputPath = await this.writeOutput(config, result.output);
+            return {
+                outputPath: path.relative(this.rootDir, outputPath),
+                contentLength: result.output.length,
+                contentHash: this.contentHash(result.output),
+                filesIncluded: result.filesCompiled,
+                filesSkipped: 0,
+            };
+        }
+        // ── Simple merge mode (v1) ─────────────────────────
+        if (!config.files || config.files.length === 0) {
+            throw new Error('Agent config must define either "entry" (template mode) or "files" (simple merge mode).');
+        }
+        const validation = await this.validate(config);
+        for (const w of validation.warnings)
+            console.log(`  ⚠  ${w}`);
+        if (!validation.valid) {
+            throw new Error(`Missing required files:\n${validation.missing.map(f => `  - ${f}`).join('\n')}`);
+        }
+        const content = await this.merge(config);
+        const outputPath = await this.writeOutput(config, content);
+        return {
+            outputPath: path.relative(this.rootDir, outputPath),
+            contentLength: content.length,
+            contentHash: this.contentHash(content),
+            filesIncluded: config.files.length,
+            filesSkipped: 0,
+        };
+    }
+    // ── Helpers ──────────────────────────────────────────────
+    contentHash(content) {
+        return crypto
+            .createHash('md5')
+            .update(content)
+            .digest('hex')
+            .substring(0, 8);
+    }
+}
+exports.InstruxEngine = InstruxEngine;
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

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

package/dist/frontmatter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * instrux — Frontmatter parsing and source file indexing.
+ *
+ * Scans source directories, parses YAML frontmatter from each markdown file,
+ * and builds a tag-based index for the compiler to resolve references.
+ */
+import { SourceFile, SourceIndex } from './types';
+/**
+ * Scan source file globs, parse frontmatter, and return an indexed collection.
+ */
+export declare function buildSourceIndex(rootDir: string, sourcePatterns: string[]): Promise<SourceIndex>;
+/**
+ * Sort source files by instrux.order (ascending), then by path.
+ */
+export declare function sortSourceFiles(files: SourceFile[]): SourceFile[];
+/**
+ * Strip the instrux block from frontmatter, returning only standard fields.
+ * Used when emitting frontmatter in the final output.
+ */
+export declare function stripInstruxMeta(frontmatter: Record<string, any>): Record<string, any>;
+/**
+ * Serialize a frontmatter object back to a YAML block (--- delimited).
+ * Returns empty string if the object has no keys.
+ */
+export declare function serializeFrontmatter(data: Record<string, any>): string;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AAE/D;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,WAAW,CAAC,CA2CtB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAOjE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAGrB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAItE"}

package/dist/frontmatter.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * instrux — Frontmatter parsing and source file indexing.
+ *
+ * Scans source directories, parses YAML frontmatter from each markdown file,
+ * and builds a tag-based index for the compiler to resolve references.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSourceIndex = buildSourceIndex;
+exports.sortSourceFiles = sortSourceFiles;
+exports.stripInstruxMeta = stripInstruxMeta;
+exports.serializeFrontmatter = serializeFrontmatter;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+/**
+ * Scan source file globs, parse frontmatter, and return an indexed collection.
+ */
+async function buildSourceIndex(rootDir, sourcePatterns) {
+    // Resolve globs relative to rootDir
+    const matched = await (0, fast_glob_1.default)(sourcePatterns, {
+        cwd: rootDir,
+        onlyFiles: true,
+        dot: false,
+        ignore: ['**/node_modules/**'],
+    });
+    const files = [];
+    const tags = new Map();
+    const paths = new Map();
+    for (const relPath of matched) {
+        const absPath = path.join(rootDir, relPath);
+        const raw = await fs.readFile(absPath, 'utf-8');
+        const { data: frontmatter, content } = (0, gray_matter_1.default)(raw);
+        const instrux = frontmatter.instrux ?? {};
+        const sourceFile = {
+            path: relPath.replace(/\\/g, '/'), // normalise to forward slashes
+            frontmatter,
+            instrux,
+            content,
+        };
+        files.push(sourceFile);
+        // normalised path → file
+        paths.set(sourceFile.path, sourceFile);
+        // build tag index
+        if (instrux.tags) {
+            for (const tag of instrux.tags) {
+                const bucket = tags.get(tag) ?? [];
+                bucket.push(sourceFile);
+                tags.set(tag, bucket);
+            }
+        }
+    }
+    return { files, tags, paths };
+}
+/**
+ * Sort source files by instrux.order (ascending), then by path.
+ */
+function sortSourceFiles(files) {
+    return [...files].sort((a, b) => {
+        const oa = a.instrux.order ?? 999;
+        const ob = b.instrux.order ?? 999;
+        if (oa !== ob)
+            return oa - ob;
+        return a.path.localeCompare(b.path);
+    });
+}
+/**
+ * Strip the instrux block from frontmatter, returning only standard fields.
+ * Used when emitting frontmatter in the final output.
+ */
+function stripInstruxMeta(frontmatter) {
+    const { instrux, ...rest } = frontmatter;
+    return rest;
+}
+/**
+ * Serialize a frontmatter object back to a YAML block (--- delimited).
+ * Returns empty string if the object has no keys.
+ */
+function serializeFrontmatter(data) {
+    const keys = Object.keys(data);
+    if (keys.length === 0)
+        return '';
+    return gray_matter_1.default.stringify('', data).trimEnd() + '\n\n';
+}
+//# sourceMappingURL=frontmatter.js.map