instrux 0.1.0

package/README.md

@@ -0,0 +1,279 @@
+# instrux
+
+A CLI tool for composing modular AI agent instruction files into complete system prompts — from simple merge to a full **instruction compiler** with frontmatter tagging and Handlebars templates.
+
+## Install
+
+```bash
+npm install -g instrux
+```
+
+Or use without installing:
+
+```bash
+npx instrux <command>
+```
+
+## Quick Start
+
+### Simple mode — ordered file merge
+
+```bash
+instrux init MyAgent
+# Edit agents/MyAgent/specialization.md
+instrux build MyAgent
+```
+
+### Template mode — frontmatter tags + Handlebars
+
+```bash
+instrux init --template MyAgent
+# Edit agents/base/*.md        (tagged components)
+# Edit agents/MyAgent/template.md  (Handlebars entry point)
+instrux build MyAgent
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `instrux init <name>` | Scaffold a simple-merge agent |
+| `instrux init -t <name>` | Scaffold a template-compiled agent |
+| `instrux build <name>` | Build (merge or compile) an agent |
+| `instrux build --all` | Build all agents |
+| `instrux list` | List all agents |
+| `instrux config <name>` | Show agent configuration |
+| `instrux validate <name>` | Check required source files |
+
+---
+
+## Simple Mode (v1)
+
+Files are merged in the order listed in `agent.json`:
+
+```json
+{
+  "name": "MyAgent",
+  "files": [
+    { "path": "agents/base/instructions.md", "required": true },
+    { "path": "agents/MyAgent/specialization.md", "required": true }
+  ],
+  "mergeSettings": { "addSeparators": true, "separatorStyle": "---" }
+}
+```
+
+---
+
+## Template Mode (v2) — The Instruction Compiler
+
+Template mode turns instrux into a build system for agent instructions:
+
+1. **Source files** declare themselves via YAML frontmatter tags
+2. An **entry template** uses Handlebars to compose them
+3. The compiler **recursively resolves** all references
+4. Output is a single, merged document
+
+### Frontmatter
+
+Every source file has YAML frontmatter. Standard fields (title, author, etc.) are yours to keep. The `instrux:` block drives compilation:
+
+```yaml
+---
+title: Safety Guidelines          # ← standard frontmatter (preserved if configured)
+author: Platform Team
+
+instrux:                           # ← compiler metadata (always stripped from output)
+  tags: [safety, compliance]       #    tags for referencing this file
+  order: 2                         #    sort order within a tag group
+  description: Core safety rules   #    description for iteration
+---
+
+# Safety Guidelines
+
+- Always provide accurate information
+- Decline harmful requests
+```
+
+### Handlebars Helpers
+
+Use these in your entry template (or any source file — they resolve recursively):
+
+#### `{{{tag "tagname"}}}`
+
+Includes **all files** matching the tag, sorted by `instrux.order`, separated by the configured separator. Each file is itself compiled (recursive).
+
+```markdown
+# System Prompt
+
+{{{tag "identity"}}}
+
+---
+
+{{{tag "safety"}}}
+
+---
+
+{{{tag "domain"}}}
+```
+
+#### `{{{file "path/to/file.md"}}}`
+
+Includes a **specific file** by path. Also recursively compiled.
+
+```markdown
+{{{file "agents/base/disclaimers.md"}}}
+```
+
+#### `{{#each (tagged "tagname")}} ... {{/each}}`
+
+Iterates over tagged files for custom rendering. Each item exposes:
+
+| Property | Description |
+|---|---|
+| `this.body` | Recursively compiled content |
+| `this.raw` | Uncompiled source content |
+| `this.title` | Frontmatter title |
+| `this.description` | Frontmatter or instrux description |
+| `this.path` | Relative file path |
+| `this.frontmatter` | Full frontmatter object |
+| `this.instrux` | instrux metadata block |
+
+```markdown
+## Knowledge Base
+
+{{#each (tagged "knowledge")}}
+### {{this.title}}
+
+{{{this.body}}}
+
+---
+
+{{/each}}
+```
+
+#### `{{meta "key"}}`
+
+Access the current file's frontmatter value:
+
+```markdown
+<!-- This document: {{meta "title"}} -->
+```
+
+### Agent Config (Template Mode)
+
+```json
+{
+  "name": "MyAgent",
+  "description": "Compiled instructions for MyAgent",
+  "outputDirectory": "out",
+  "outputFilePattern": "myagent_instructions.md",
+  "entry": "agents/MyAgent/template.md",
+  "sources": [
+    "agents/base/**/*.md",
+    "agents/MyAgent/**/*.md"
+  ],
+  "frontmatter": {
+    "output": "strip"
+  },
+  "mergeSettings": {
+    "addSeparators": true,
+    "separatorStyle": "---"
+  }
+}
+```
+
+| Field | Description |
+|---|---|
+| `entry` | The Handlebars template that drives compilation |
+| `sources` | Glob patterns for files to scan and index by tag |
+| `frontmatter.output` | `"strip"` (default) or `"preserve"` entry file's non-instrux frontmatter |
+
+### Project Layout (Template Mode)
+
+```
+agents/
+  base/
+    identity.md           ← instrux.tags: [identity]
+    safety.md             ← instrux.tags: [safety]
+    api_reference.md      ← instrux.tags: [knowledge, api]
+  MyAgent/
+    agent.json            ← config with entry + sources
+    template.md           ← Handlebars entry template
+    domain.md             ← instrux.tags: [domain]
+    protocols.md          ← instrux.tags: [domain], order: 2
+out/
+  myagent_instructions.md ← compiled output
+```
+
+### Recursive Compilation
+
+Templates can include files that themselves contain Handlebars expressions. The compiler resolves everything recursively with **cycle detection** — if file A includes file B which includes file A, you get a clear error:
+
+```
+Circular reference detected:
+  agents/MyAgent/template.md → agents/base/intro.md → agents/MyAgent/template.md
+```
+
+---
+
+## Merge Settings
+
+| Setting | Default | Description |
+|---|---|---|
+| `addSeparators` | `true` | Insert separator between sections |
+| `separatorStyle` | `"---"` | Separator string |
+| `includeFileHeaders` | `false` | Add HTML comments with source file info |
+| `preserveFormatting` | `true` | Keep original whitespace |
+| `generateHash` | `false` | Append content hash to filename |
+| `useTimestamp` | `false` | Append timestamp to filename |
+
+## Multiple Agents
+
+You can mix simple and template agents in the same project:
+
+```
+agents/
+  base/
+    identity.md
+    safety.md
+  CustomerSupport/         ← template mode
+    agent.json
+    template.md
+    product_knowledge.md
+  QuickBot/                ← simple mode
+    agent.json
+    specialization.md
+```
+
+```bash
+instrux build --all        # builds every agent
+```
+
+## Programmatic API
+
+```typescript
+import { InstruxEngine, InstruxCompiler, initTemplateAgent } from 'instrux';
+
+// Scaffold a template agent
+await initTemplateAgent(process.cwd(), 'MyAgent');
+
+// Build (auto-detects simple vs template mode)
+const engine = new InstruxEngine();
+const result = await engine.build('MyAgent');
+console.log(result.outputPath);
+
+// Or use the compiler directly
+import { buildSourceIndex } from 'instrux';
+const config = await engine.loadConfig('MyAgent');
+const compiler = new InstruxCompiler(process.cwd(), config);
+const { output, filesCompiled, tagsUsed } = await compiler.compile();
+```
+
+## License
+
+This project is dual-licensed under your choice of:
+
+- [MIT License](LICENSE-MIT)
+- [Apache License 2.0](LICENSE-APACHE)
+
+You may use this project under the terms of either license.

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * instrux — CLI for composing modular AI agent instructions.
+ *
+ * Commands:
+ *   instrux init <name>       Scaffold a new agent
+ *   instrux build <name>      Merge instruction files for an agent
+ *   instrux build --all       Build all agents
+ *   instrux list              List available agents
+ *   instrux config <name>     Show agent configuration
+ *   instrux validate <name>   Validate source files exist
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}

package/dist/cli.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * instrux — CLI for composing modular AI agent instructions.
+ *
+ * Commands:
+ *   instrux init <name>       Scaffold a new agent
+ *   instrux build <name>      Merge instruction files for an agent
+ *   instrux build --all       Build all agents
+ *   instrux list              List available agents
+ *   instrux config <name>     Show agent configuration
+ *   instrux validate <name>   Validate source files exist
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const engine_1 = require("./engine");
+const init_1 = require("./init");
+const pkg = require('../package.json');
+const program = new commander_1.Command();
+program
+    .name('instrux')
+    .description('Compose modular AI agent instruction files into complete system prompts')
+    .version(pkg.version);
+// ── init ───────────────────────────────────────────────────
+program
+    .command('init <name>')
+    .description('Scaffold a new agent with config and starter files')
+    .option('-t, --template', 'Use template mode with frontmatter tags & Handlebars')
+    .action(async (name, opts) => {
+    try {
+        const cwd = process.cwd();
+        const created = opts.template
+            ? await (0, init_1.initTemplateAgent)(cwd, name)
+            : await (0, init_1.initAgent)(cwd, name);
+        const mode = opts.template ? 'template' : 'simple';
+        console.log(`\n\u2705 Agent "${name}" initialized (${mode} mode)!\n`);
+        console.log('Created:');
+        created.forEach(f => console.log(`  ${f}`));
+        if (opts.template) {
+            console.log(`\nNext steps:`);
+            console.log(`  1. Edit agents/base/*.md to define shared instructions`);
+            console.log(`  2. Edit agents/${name}/domain.md with domain knowledge`);
+            console.log(`  3. Edit agents/${name}/template.md to compose via {{tag "..."}}`);
+            console.log(`  4. Run: instrux build ${name}\n`);
+        }
+        else {
+            console.log(`\nNext steps:`);
+            console.log(`  1. Edit agents/${name}/specialization.md with your instructions`);
+            console.log(`  2. Edit agents/${name}/agent.json to add more files if needed`);
+            console.log(`  3. Run: instrux build ${name}\n`);
+        }
+    }
+    catch (err) {
+        console.error(`❌ ${err.message}`);
+        process.exit(1);
+    }
+});
+// ── build ──────────────────────────────────────────────────
+program
+    .command('build [name]')
+    .description('Build (merge) instruction files for an agent')
+    .option('--all', 'Build all agents')
+    .action(async (name, opts) => {
+    const engine = new engine_1.InstruxEngine();
+    try {
+        if (opts.all) {
+            const agents = await engine.listAgents();
+            if (agents.length === 0) {
+                console.log('No agents found. Run "instrux init <name>" first.');
+                return;
+            }
+            for (const agent of agents) {
+                if (!agent.config) {
+                    console.log(`⚠  Skipping ${agent.name} (invalid config)`);
+                    continue;
+                }
+                console.log(`\n🔨 Building ${agent.name}...`);
+                const result = await engine.build(agent.name);
+                printBuildResult(agent.name, result);
+            }
+            return;
+        }
+        if (!name) {
+            console.error('❌ Agent name required. Usage: instrux build <name>');
+            console.log('   Run "instrux list" to see available agents.');
+            process.exit(1);
+        }
+        console.log(`\n🔨 Building ${name}...`);
+        const result = await engine.build(name);
+        printBuildResult(name, result);
+    }
+    catch (err) {
+        console.error(`❌ ${err.message}`);
+        process.exit(1);
+    }
+});
+// ── list ───────────────────────────────────────────────────
+program
+    .command('list')
+    .description('List all available agents')
+    .action(async () => {
+    const engine = new engine_1.InstruxEngine();
+    const agents = await engine.listAgents();
+    if (agents.length === 0) {
+        console.log('\nNo agents found.');
+        console.log('Run "instrux init <name>" to create one.\n');
+        return;
+    }
+    console.log('\nAvailable agents:\n');
+    for (const agent of agents) {
+        if (agent.config) {
+            const mode = agent.config.entry ? 'template' : 'simple';
+            console.log(`  ${agent.name}  [${mode}]`);
+            console.log(`    ${agent.config.description}`);
+            console.log(`    Files: ${agent.config.files?.length ?? agent.config.sources?.length ?? 0}  \u2192  ${agent.config.outputDirectory}/${agent.config.outputFilePattern}`);
+        }
+        else {
+            console.log(`  ${agent.name}  (invalid or missing agent.json)`);
+        }
+    }
+    console.log();
+});
+// ── config ─────────────────────────────────────────────────
+program
+    .command('config <name>')
+    .description('Display the configuration for an agent')
+    .action(async (name) => {
+    const engine = new engine_1.InstruxEngine();
+    try {
+        const config = await engine.loadConfig(name);
+        console.log(`\n📋 ${config.name}\n`);
+        console.log(`  Description:  ${config.description}`);
+        console.log(`  Output:       ${config.outputDirectory}/${config.outputFilePattern}`);
+        console.log();
+        console.log('  Files:');
+        (config.files ?? []).forEach((f, i) => {
+            const tag = f.required ? 'required' : 'optional';
+            console.log(`    ${i + 1}. ${f.path}  [${tag}]`);
+            console.log(`       ${f.description}`);
+        });
+        console.log();
+        console.log('  Merge settings:');
+        Object.entries(config.mergeSettings).forEach(([k, v]) => {
+            console.log(`    ${k}: ${v}`);
+        });
+        console.log();
+    }
+    catch (err) {
+        console.error(`❌ ${err.message}`);
+        process.exit(1);
+    }
+});
+// ── validate ───────────────────────────────────────────────
+program
+    .command('validate <name>')
+    .description('Check that all required instruction files exist')
+    .action(async (name) => {
+    const engine = new engine_1.InstruxEngine();
+    try {
+        const config = await engine.loadConfig(name);
+        const result = await engine.validate(config);
+        result.warnings.forEach(w => console.log(`  ⚠  ${w}`));
+        if (result.valid) {
+            console.log('✅ All required files are present.');
+        }
+        else {
+            console.log('❌ Missing required files:');
+            result.missing.forEach(f => console.log(`  - ${f}`));
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`❌ ${err.message}`);
+        process.exit(1);
+    }
+});
+// ── helpers ────────────────────────────────────────────────
+function printBuildResult(name, result) {
+    console.log(`✅ ${name} built successfully`);
+    console.log(`   Output: ${result.outputPath}`);
+    console.log(`   Size:   ${result.contentLength.toLocaleString()} chars`);
+    console.log(`   Hash:   ${result.contentHash}`);
+}
+// ── go ─────────────────────────────────────────────────────
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/compiler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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
+ */
+import { AgentConfig } from './types';
+export interface CompileResult {
+    /** Final compiled output (may include frontmatter block) */
+    output: string;
+    /** Number of unique files that were compiled */
+    filesCompiled: number;
+    /** Tags that were referenced during compilation */
+    tagsUsed: string[];
+}
+export declare class InstruxCompiler {
+    private rootDir;
+    private config;
+    private index;
+    private compileStack;
+    private compiledFiles;
+    private tagsUsed;
+    constructor(rootDir: string, config: AgentConfig);
+    compile(): Promise<CompileResult>;
+    private compileFile;
+    private registerHelpers;
+}
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EACL,WAAW,EAIZ,MAAM,SAAS,CAAC;AAQjB,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAA0B;gBAE9B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW;IAO1C,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IAgDvC,OAAO,CAAC,WAAW;IA+CnB,OAAO,CAAC,eAAe;CA2ExB"}