instrux 0.1.0

package/dist/frontmatter.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * instrux — public API
+ *
+ * Exports the engine, compiler, and types for programmatic use.
+ */
+export { InstruxEngine } from './engine';
+export { InstruxCompiler } from './compiler';
+export type { CompileResult } from './compiler';
+export { initAgent, initTemplateAgent } from './init';
+export { buildSourceIndex, sortSourceFiles, stripInstruxMeta, serializeFrontmatter } from './frontmatter';
+export type { AgentConfig, InstruxFile, MergeSettings, ValidationResult, BuildResult, FrontmatterOutput, InstruxMeta, SourceFile, SourceIndex, } from './types';
+export { DEFAULT_MERGE_SETTINGS } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1G,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * instrux — public API
+ *
+ * Exports the engine, compiler, and types for programmatic use.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MERGE_SETTINGS = exports.serializeFrontmatter = exports.stripInstruxMeta = exports.sortSourceFiles = exports.buildSourceIndex = exports.initTemplateAgent = exports.initAgent = exports.InstruxCompiler = exports.InstruxEngine = void 0;
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "InstruxEngine", { enumerable: true, get: function () { return engine_1.InstruxEngine; } });
+var compiler_1 = require("./compiler");
+Object.defineProperty(exports, "InstruxCompiler", { enumerable: true, get: function () { return compiler_1.InstruxCompiler; } });
+var init_1 = require("./init");
+Object.defineProperty(exports, "initAgent", { enumerable: true, get: function () { return init_1.initAgent; } });
+Object.defineProperty(exports, "initTemplateAgent", { enumerable: true, get: function () { return init_1.initTemplateAgent; } });
+var frontmatter_1 = require("./frontmatter");
+Object.defineProperty(exports, "buildSourceIndex", { enumerable: true, get: function () { return frontmatter_1.buildSourceIndex; } });
+Object.defineProperty(exports, "sortSourceFiles", { enumerable: true, get: function () { return frontmatter_1.sortSourceFiles; } });
+Object.defineProperty(exports, "stripInstruxMeta", { enumerable: true, get: function () { return frontmatter_1.stripInstruxMeta; } });
+Object.defineProperty(exports, "serializeFrontmatter", { enumerable: true, get: function () { return frontmatter_1.serializeFrontmatter; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "DEFAULT_MERGE_SETTINGS", { enumerable: true, get: function () { return types_1.DEFAULT_MERGE_SETTINGS; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AACtB,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AAExB,+BAAsD;AAA7C,iGAAA,SAAS,OAAA;AAAE,yGAAA,iBAAiB,OAAA;AACrC,6CAA0G;AAAjG,+GAAA,gBAAgB,OAAA;AAAE,8GAAA,eAAe,OAAA;AAAE,+GAAA,gBAAgB,OAAA;AAAE,mHAAA,oBAAoB,OAAA;AAYlF,iCAAiD;AAAxC,+GAAA,sBAAsB,OAAA"}

package/dist/init.d.ts

@@ -0,0 +1,34 @@
+/**
+ * instrux init — scaffold a new agent project or add an agent to an existing one.
+ */
+/**
+ * Create the directory structure and starter files for a new agent.
+ *
+ * Resulting layout (relative to `rootDir`):
+ *
+ *   agents/
+ *     base/
+ *       instructions.md        ← shared base instructions
+ *     <agentName>/
+ *       agent.json             ← agent configuration
+ *       specialization.md      ← agent-specific content
+ *   out/                       ← default output directory
+ */
+export declare function initAgent(rootDir: string, agentName: string): Promise<string[]>;
+/**
+ * Scaffold a template-based agent with frontmatter tagging and Handlebars.
+ *
+ * Resulting layout:
+ *
+ *   agents/
+ *     base/
+ *       identity.md            ← tagged: [identity]
+ *       safety.md              ← tagged: [safety]
+ *     <agentName>/
+ *       agent.json             ← config with entry + sources
+ *       template.md            ← Handlebars entry template
+ *       domain.md              ← tagged: [domain]
+ *   out/
+ */
+export declare function initTemplateAgent(rootDir: string, agentName: string): Promise<string[]>;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;;;;;;;;;;;GAYG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CAqEnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,EAAE,CAAC,CAwJnB"}

package/dist/init.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * instrux init — scaffold a new agent project or add an agent to an existing one.
+ */
+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.initAgent = initAgent;
+exports.initTemplateAgent = initTemplateAgent;
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const types_1 = require("./types");
+/**
+ * Create the directory structure and starter files for a new agent.
+ *
+ * Resulting layout (relative to `rootDir`):
+ *
+ *   agents/
+ *     base/
+ *       instructions.md        ← shared base instructions
+ *     <agentName>/
+ *       agent.json             ← agent configuration
+ *       specialization.md      ← agent-specific content
+ *   out/                       ← default output directory
+ */
+async function initAgent(rootDir, agentName) {
+    const created = [];
+    const agentDir = path.join(rootDir, 'agents', agentName);
+    const baseDir = path.join(rootDir, 'agents', 'base');
+    const outDir = path.join(rootDir, 'out');
+    // ── agents/base/instructions.md ───────────────────────
+    const baseInstructions = path.join(baseDir, 'instructions.md');
+    if (!(await fs.pathExists(baseInstructions))) {
+        await fs.ensureDir(baseDir);
+        await fs.writeFile(baseInstructions, `# Base Instructions\n\nShared instructions that apply to all agents.\nAdd common behavioral guidelines, tone, and constraints here.\n`, 'utf-8');
+        created.push(path.relative(rootDir, baseInstructions));
+    }
+    // ── agents/<name>/agent.json ──────────────────────────
+    if (await fs.pathExists(agentDir)) {
+        throw new Error(`Agent "${agentName}" already exists at ${path.relative(rootDir, agentDir)}`);
+    }
+    await fs.ensureDir(agentDir);
+    const config = {
+        name: agentName,
+        description: `Instructions for the ${agentName} agent`,
+        outputDirectory: 'out',
+        outputFilePattern: `${agentName.toLowerCase()}_instructions.md`,
+        files: [
+            {
+                path: 'agents/base/instructions.md',
+                description: 'Shared base instructions',
+                required: true,
+            },
+            {
+                path: `agents/${agentName}/specialization.md`,
+                description: `${agentName}-specific knowledge and instructions`,
+                required: true,
+            },
+        ],
+        mergeSettings: { ...types_1.DEFAULT_MERGE_SETTINGS },
+    };
+    const configPath = path.join(agentDir, 'agent.json');
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    created.push(path.relative(rootDir, configPath));
+    // ── agents/<name>/specialization.md ───────────────────
+    const specPath = path.join(agentDir, 'specialization.md');
+    await fs.writeFile(specPath, `# ${agentName} — Specialization\n\n` +
+        `## Capabilities\n\n` +
+        `- Describe this agent's unique capabilities here\n\n` +
+        `## Domain Knowledge\n\n` +
+        `Add domain-specific reference material, terminology, or protocols.\n`, 'utf-8');
+    created.push(path.relative(rootDir, specPath));
+    // ── out/ directory ────────────────────────────────────
+    if (!(await fs.pathExists(outDir))) {
+        await fs.ensureDir(outDir);
+        created.push('out/');
+    }
+    return created;
+}
+/**
+ * Scaffold a template-based agent with frontmatter tagging and Handlebars.
+ *
+ * Resulting layout:
+ *
+ *   agents/
+ *     base/
+ *       identity.md            ← tagged: [identity]
+ *       safety.md              ← tagged: [safety]
+ *     <agentName>/
+ *       agent.json             ← config with entry + sources
+ *       template.md            ← Handlebars entry template
+ *       domain.md              ← tagged: [domain]
+ *   out/
+ */
+async function initTemplateAgent(rootDir, agentName) {
+    const created = [];
+    const agentDir = path.join(rootDir, 'agents', agentName);
+    const baseDir = path.join(rootDir, 'agents', 'base');
+    const outDir = path.join(rootDir, 'out');
+    // ── agents/base/identity.md ───────────────────────────
+    const identityPath = path.join(baseDir, 'identity.md');
+    if (!(await fs.pathExists(identityPath))) {
+        await fs.ensureDir(baseDir);
+        await fs.writeFile(identityPath, [
+            '---',
+            'title: Core Identity',
+            'instrux:',
+            '  tags: [identity]',
+            '  order: 1',
+            '---',
+            '',
+            '# Core Identity',
+            '',
+            'You are a helpful AI assistant.',
+            'Define your core behavioral guidelines here.',
+            '',
+        ].join('\n'), 'utf-8');
+        created.push(path.relative(rootDir, identityPath));
+    }
+    // ── agents/base/safety.md ─────────────────────────────
+    const safetyPath = path.join(baseDir, 'safety.md');
+    if (!(await fs.pathExists(safetyPath))) {
+        await fs.writeFile(safetyPath, [
+            '---',
+            'title: Safety Guidelines',
+            'instrux:',
+            '  tags: [safety]',
+            '  order: 2',
+            '---',
+            '',
+            '# Safety Guidelines',
+            '',
+            '- Always provide accurate information',
+            '- Decline harmful requests',
+            '- Protect user privacy',
+            '',
+        ].join('\n'), 'utf-8');
+        created.push(path.relative(rootDir, safetyPath));
+    }
+    // ── agents/<name>/ ────────────────────────────────────
+    if (await fs.pathExists(agentDir)) {
+        throw new Error(`Agent "${agentName}" already exists at ${path.relative(rootDir, agentDir)}`);
+    }
+    await fs.ensureDir(agentDir);
+    // ── agent.json (template mode) ────────────────────────
+    const config = {
+        name: agentName,
+        description: `Compiled instructions for the ${agentName} agent`,
+        outputDirectory: 'out',
+        outputFilePattern: `${agentName.toLowerCase()}_instructions.md`,
+        entry: `agents/${agentName}/template.md`,
+        sources: [
+            'agents/base/**/*.md',
+            `agents/${agentName}/**/*.md`,
+        ],
+        frontmatter: { output: 'strip' },
+        mergeSettings: { ...types_1.DEFAULT_MERGE_SETTINGS },
+    };
+    const configPath = path.join(agentDir, 'agent.json');
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    created.push(path.relative(rootDir, configPath));
+    // ── template.md (Handlebars entry point) ──────────────
+    const templatePath = path.join(agentDir, 'template.md');
+    await fs.writeFile(templatePath, [
+        '---',
+        `title: ${agentName} System Prompt`,
+        'instrux:',
+        '  tags: [template]',
+        '---',
+        '',
+        '{{!-- Core sections pulled in by tag --}}',
+        '',
+        '{{{tag "identity"}}}',
+        '',
+        '---',
+        '',
+        '{{{tag "safety"}}}',
+        '',
+        '---',
+        '',
+        '{{{tag "domain"}}}',
+        '',
+        '{{!-- You can also iterate over tagged files:',
+        '',
+        '{{#each (tagged "knowledge")}}',
+        '### {{this.title}}',
+        '{{{this.body}}}',
+        '{{/each}}',
+        '',
+        '--}}',
+        '',
+    ].join('\n'), 'utf-8');
+    created.push(path.relative(rootDir, templatePath));
+    // ── domain.md (agent-specific content) ────────────────
+    const domainPath = path.join(agentDir, 'domain.md');
+    await fs.writeFile(domainPath, [
+        '---',
+        `title: ${agentName} Domain Knowledge`,
+        'instrux:',
+        '  tags: [domain]',
+        '  order: 1',
+        '---',
+        '',
+        `# ${agentName} — Domain Knowledge`,
+        '',
+        '## Capabilities',
+        '',
+        '- Describe this agent\'s unique capabilities here',
+        '',
+        '## Reference Material',
+        '',
+        'Add domain-specific terminology, protocols, or schemas.',
+        '',
+    ].join('\n'), 'utf-8');
+    created.push(path.relative(rootDir, domainPath));
+    // ── out/ directory ────────────────────────────────────
+    if (!(await fs.pathExists(outDir))) {
+        await fs.ensureDir(outDir);
+        created.push('out/');
+    }
+    return created;
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * instrux - Configuration and type definitions
+ */
+export interface InstruxFile {
+    /** Relative path to the instruction file */
+    path: string;
+    /** Human-readable description of this file's purpose */
+    description: string;
+    /** Whether this file must exist for a build to succeed */
+    required: boolean;
+}
+export interface MergeSettings {
+    /** Add visual separators between merged files */
+    addSeparators: boolean;
+    /** Separator string (e.g., "---") */
+    separatorStyle: string;
+    /** Include HTML comments showing source file info */
+    includeFileHeaders: boolean;
+    /** Preserve original whitespace and formatting */
+    preserveFormatting: boolean;
+    /** Append a content hash to the output filename */
+    generateHash: boolean;
+    /** Append a timestamp to the output filename */
+    useTimestamp: boolean;
+}
+export interface AgentConfig {
+    /** Display name of the agent */
+    name: string;
+    /** Description of the agent's purpose */
+    description: string;
+    /** Output directory for the merged file (relative to project root) */
+    outputDirectory: string;
+    /** Output filename pattern — supports {timestamp} placeholder */
+    outputFilePattern: string;
+    /** Ordered list of instruction files to merge (simple mode) */
+    files?: InstruxFile[];
+    /**
+     * Entry template file that drives compilation.
+     * When set, instrux uses Handlebars + frontmatter tags instead of simple merge.
+     */
+    entry?: string;
+    /**
+     * Glob patterns for source files to scan for frontmatter tags.
+     * Example: ["agents/base/*.md", "agents/MyAgent/*.md"]
+     */
+    sources?: string[];
+    /** Controls how frontmatter is handled in the compiled output */
+    frontmatter?: FrontmatterOutput;
+    /** Controls how files are merged together */
+    mergeSettings: MergeSettings;
+}
+export interface ValidationResult {
+    valid: boolean;
+    missing: string[];
+    warnings: string[];
+}
+export interface BuildResult {
+    outputPath: string;
+    contentLength: number;
+    contentHash: string;
+    filesIncluded: number;
+    filesSkipped: number;
+}
+export interface FrontmatterOutput {
+    /**
+     * How to handle frontmatter in the final output:
+     *   - "strip":    Remove all frontmatter (default)
+     *   - "preserve": Keep non-instrux frontmatter from the entry file
+     */
+    output: 'strip' | 'preserve';
+}
+/** instrux-specific metadata nested under `instrux:` in frontmatter */
+export interface InstruxMeta {
+    /** Tags used to reference this file from templates */
+    tags?: string[];
+    /** Sort order when multiple files share a tag (lower = first) */
+    order?: number;
+    /** Description (used in {{#each (tagged ...)}} iteration) */
+    description?: string;
+    [key: string]: any;
+}
+/** A parsed source file with separated frontmatter and content */
+export interface SourceFile {
+    /** Relative path from project root (forward slashes) */
+    path: string;
+    /** Full parsed YAML frontmatter */
+    frontmatter: Record<string, any>;
+    /** instrux-specific metadata extracted from frontmatter.instrux */
+    instrux: InstruxMeta;
+    /** Markdown body content (without frontmatter) */
+    content: string;
+}
+/** Tag-indexed collection of source files */
+export interface SourceIndex {
+    /** All scanned source files */
+    files: SourceFile[];
+    /** tag → SourceFile[] lookup */
+    tags: Map<string, SourceFile[]>;
+    /** normalised path → SourceFile lookup */
+    paths: Map<string, SourceFile>;
+}
+/** Default merge settings used by `instrux init` */
+export declare const DEFAULT_MERGE_SETTINGS: MergeSettings;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,aAAa,EAAE,OAAO,CAAC;IACvB,qCAAqC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kDAAkD;IAClD,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,eAAe,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,CAAC;IAI1B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,WAAW,EAAE,CAAC;IAItB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAEhC,6CAA6C;IAC7C,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAID,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,MAAM,EAAE,OAAO,GAAG,UAAU,CAAC;CAC9B;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,mEAAmE;IACnE,OAAO,EAAE,WAAW,CAAC;IACrB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,gCAAgC;IAChC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAChC,0CAA0C;IAC1C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAChC;AAID,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,EAAE,aAOpC,CAAC"}

package/dist/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * instrux - Configuration and type definitions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MERGE_SETTINGS = void 0;
+// ── Defaults ─────────────────────────────────────────────
+/** Default merge settings used by `instrux init` */
+exports.DEFAULT_MERGE_SETTINGS = {
+    addSeparators: true,
+    separatorStyle: '---',
+    includeFileHeaders: false,
+    preserveFormatting: true,
+    generateHash: false,
+    useTimestamp: false,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAwHH,4DAA4D;AAE5D,oDAAoD;AACvC,QAAA,sBAAsB,GAAkB;IACnD,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,KAAK;IACrB,kBAAkB,EAAE,KAAK;IACzB,kBAAkB,EAAE,IAAI;IACxB,YAAY,EAAE,KAAK;IACnB,YAAY,EAAE,KAAK;CACpB,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "instrux",
+  "version": "0.1.0",
+  "description": "A CLI tool for composing modular AI agent instruction files into complete system prompts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsharp/instrux.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tsharp/instrux/issues"
+  },
+  "homepage": "https://github.com/tsharp/instrux#readme",
+  "main": "dist/index.js",
+  "bin": {
+    "instrux": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/cli.ts",
+    "watch": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"No tests yet\" && exit 0",
+    "publish:script": "pwsh -File publish.ps1"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "instructions",
+    "system-prompt",
+    "prompt-engineering",
+    "llm",
+    "merge",
+    "compose",
+    "cli"
+  ],
+  "author": "",
+  "license": "(MIT OR Apache-2.0)",
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.0",
+    "fs-extra": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "handlebars": "^4.7.8"
+  }
+}