faceted-prompting 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masanobu Naruse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,72 @@
 # faceted-prompting
 
-Faceted Prompting - A design pattern for composing structured AI prompts from multiple facets.
+Structured prompt composition for LLMs using the Faceted Prompting pattern.
 
-Work in progress.
+## Overview
+
+Faceted Prompting organizes LLM prompts into distinct facets:
+
+| Facet | Role | Placement |
+|-------|------|-----------|
+| **Persona** | WHO — defines the agent's identity | System prompt |
+| **Policy** | HOW — coding standards, rules | User message |
+| **Knowledge** | WHAT TO KNOW — domain context | User message |
+| **Instruction** | WHAT TO DO — the task itself | User message |
+
+## Install
+
+```bash
+npm install faceted-prompting
+```
+
+## Quick Start
+
+```typescript
+import { compose } from 'faceted-prompting';
+
+const result = compose(
+  {
+    persona: { body: 'You are a senior TypeScript developer.' },
+    policies: [{ body: 'Follow clean code principles. No any types.' }],
+    knowledge: [{ body: 'The project uses Vitest for testing.' }],
+    instruction: { body: 'Implement a retry function with exponential backoff.' },
+  },
+  { contextMaxChars: 8000 },
+);
+
+// result.systemPrompt → persona content
+// result.userMessage  → policy + knowledge + instruction (in order)
+```
+
+## API
+
+### `compose(facets, options)`
+
+Composes a `FacetSet` into a `ComposedPrompt` with `systemPrompt` and `userMessage`.
+
+### `FileDataEngine`
+
+File-system backed facet loader. Reads `{root}/{kind}/{key}.md`.
+
+```typescript
+import { FileDataEngine } from 'faceted-prompting';
+
+const engine = new FileDataEngine('./prompts');
+const persona = await engine.resolve('personas', 'coder');
+```
+
+### `CompositeDataEngine`
+
+Chains multiple engines with first-match-wins resolution.
+
+### `renderTemplate(template, vars)`
+
+Minimal template engine supporting `{{#if}}...{{else}}...{{/if}}` and `{{variable}}` substitution.
+
+### `escapeTemplateChars(str)`
+
+Escapes curly braces to prevent template injection.
+
+## License
+
+MIT

package/dist/compose.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Facet composition — the core placement rule.
+ *
+ *   system prompt:  persona only    (WHO)
+ *   user message:   policy + knowledge + instruction (HOW / WHAT TO KNOW / WHAT TO DO)
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+import type { FacetSet, ComposedPrompt, ComposeOptions } from './types.js';
+/**
+ * Compose facets into an LLM-ready prompt according to Faceted Prompting
+ * placement rules.
+ *
+ * - persona → systemPrompt
+ * - policy / knowledge / instruction → userMessage (in that order)
+ */
+export declare function compose(facets: FacetSet, options: ComposeOptions): ComposedPrompt;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG3E;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,GAAG,cAAc,CAoCjF"}

package/dist/compose.js

@@ -0,0 +1,45 @@
+/**
+ * Facet composition — the core placement rule.
+ *
+ *   system prompt:  persona only    (WHO)
+ *   user message:   policy + knowledge + instruction (HOW / WHAT TO KNOW / WHAT TO DO)
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+import { prepareKnowledgeContent, preparePolicyContent } from './truncation.js';
+/**
+ * Compose facets into an LLM-ready prompt according to Faceted Prompting
+ * placement rules.
+ *
+ * - persona → systemPrompt
+ * - policy / knowledge / instruction → userMessage (in that order)
+ */
+export function compose(facets, options) {
+    const systemPrompt = facets.persona?.body ?? '';
+    const userParts = [];
+    // Policy (HOW)
+    if (facets.policies && facets.policies.length > 0) {
+        const joined = facets.policies.map(p => p.body).join('\n\n---\n\n');
+        const sourcePath = facets.policies.length === 1
+            ? facets.policies[0].sourcePath
+            : undefined;
+        userParts.push(preparePolicyContent(joined, options.contextMaxChars, sourcePath));
+    }
+    // Knowledge (WHAT TO KNOW)
+    if (facets.knowledge && facets.knowledge.length > 0) {
+        const joined = facets.knowledge.map(k => k.body).join('\n\n---\n\n');
+        const sourcePath = facets.knowledge.length === 1
+            ? facets.knowledge[0].sourcePath
+            : undefined;
+        userParts.push(prepareKnowledgeContent(joined, options.contextMaxChars, sourcePath));
+    }
+    // Instruction (WHAT TO DO)
+    if (facets.instruction) {
+        userParts.push(facets.instruction.body);
+    }
+    return {
+        systemPrompt,
+        userMessage: userParts.join('\n\n'),
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,MAAgB,EAAE,OAAuB;IAC/D,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;IAEhD,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,eAAe;IACf,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACpE,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAC7C,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,UAAU;YAChC,CAAC,CAAC,SAAS,CAAC;QACd,SAAS,CAAC,IAAI,CACZ,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC,CAClE,CAAC;IACJ,CAAC;IAED,2BAA2B;IAC3B,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACrE,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YAC9C,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,UAAU;YACjC,CAAC,CAAC,SAAS,CAAC;QACd,SAAS,CAAC,IAAI,CACZ,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC,CACrE,CAAC;IACJ,CAAC;IAED,2BAA2B;IAC3B,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO;QACL,YAAY;QACZ,WAAW,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;KACpC,CAAC;AACJ,CAAC"}

package/dist/data-engine.d.ts

@@ -0,0 +1,49 @@
+/**
+ * DataEngine — abstract interface for facet data retrieval.
+ *
+ * Compose logic depends only on this interface; callers wire
+ * concrete implementations (FileDataEngine, SqliteDataEngine, etc.).
+ *
+ * This module depends only on node:fs, node:path.
+ */
+import type { FacetKind, FacetContent } from './types.js';
+/**
+ * Abstract interface for facet data retrieval.
+ *
+ * Methods return Promises so that implementations backed by
+ * async I/O (database, network) can be used without changes.
+ */
+export interface DataEngine {
+    /**
+     * Resolve a single facet by kind and key (name without extension).
+     * Returns undefined if the facet does not exist.
+     */
+    resolve(kind: FacetKind, key: string): Promise<FacetContent | undefined>;
+    /** List available facet keys for a given kind. */
+    list(kind: FacetKind): Promise<string[]>;
+}
+/**
+ * File-system backed DataEngine.
+ *
+ * Resolves facets from a single root directory using the convention:
+ *   {root}/{kind}/{key}.md
+ */
+export declare class FileDataEngine implements DataEngine {
+    private readonly root;
+    constructor(root: string);
+    resolve(kind: FacetKind, key: string): Promise<FacetContent | undefined>;
+    list(kind: FacetKind): Promise<string[]>;
+}
+/**
+ * Chains multiple DataEngines with first-match-wins resolution.
+ *
+ * resolve() returns the first non-undefined result.
+ * list() returns deduplicated keys from all engines.
+ */
+export declare class CompositeDataEngine implements DataEngine {
+    private readonly engines;
+    constructor(engines: readonly DataEngine[]);
+    resolve(kind: FacetKind, key: string): Promise<FacetContent | undefined>;
+    list(kind: FacetKind): Promise<string[]>;
+}
+//# sourceMappingURL=data-engine.d.ts.map

package/dist/data-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-engine.d.ts","sourceRoot":"","sources":["../src/data-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAW1D;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAEzE,kDAAkD;IAClD,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,UAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAEnC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAQxE,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAQ/C;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,SAAS,UAAU,EAAE;IAMrD,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAQxE,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAc/C"}

package/dist/data-engine.js

@@ -0,0 +1,85 @@
+/**
+ * DataEngine — abstract interface for facet data retrieval.
+ *
+ * Compose logic depends only on this interface; callers wire
+ * concrete implementations (FileDataEngine, SqliteDataEngine, etc.).
+ *
+ * This module depends only on node:fs, node:path.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Plural-kind to directory name mapping (identity for all current kinds). */
+const KIND_DIR = {
+    personas: 'personas',
+    policies: 'policies',
+    knowledge: 'knowledge',
+    instructions: 'instructions',
+    'output-contracts': 'output-contracts',
+};
+/**
+ * File-system backed DataEngine.
+ *
+ * Resolves facets from a single root directory using the convention:
+ *   {root}/{kind}/{key}.md
+ */
+export class FileDataEngine {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async resolve(kind, key) {
+        const dir = KIND_DIR[kind];
+        const filePath = join(this.root, dir, `${key}.md`);
+        if (!existsSync(filePath))
+            return undefined;
+        const body = readFileSync(filePath, 'utf-8');
+        return { body, sourcePath: filePath };
+    }
+    async list(kind) {
+        const dir = KIND_DIR[kind];
+        const dirPath = join(this.root, dir);
+        if (!existsSync(dirPath))
+            return [];
+        return readdirSync(dirPath)
+            .filter(f => f.endsWith('.md'))
+            .map(f => f.slice(0, -3));
+    }
+}
+/**
+ * Chains multiple DataEngines with first-match-wins resolution.
+ *
+ * resolve() returns the first non-undefined result.
+ * list() returns deduplicated keys from all engines.
+ */
+export class CompositeDataEngine {
+    engines;
+    constructor(engines) {
+        this.engines = engines;
+        if (engines.length === 0) {
+            throw new Error('CompositeDataEngine requires at least one engine');
+        }
+    }
+    async resolve(kind, key) {
+        for (const engine of this.engines) {
+            const result = await engine.resolve(kind, key);
+            if (result !== undefined)
+                return result;
+        }
+        return undefined;
+    }
+    async list(kind) {
+        const seen = new Set();
+        const result = [];
+        for (const engine of this.engines) {
+            const keys = await engine.list(kind);
+            for (const key of keys) {
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    result.push(key);
+                }
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=data-engine.js.map

package/dist/data-engine.js.map

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

package/dist/escape.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Template injection prevention.
+ *
+ * Escapes curly braces in dynamic content so they are not
+ * interpreted as template variables by the template engine.
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+/**
+ * Replace ASCII curly braces with full-width equivalents
+ * to prevent template variable injection in user-supplied content.
+ */
+export declare function escapeTemplateChars(str: string): string;
+//# sourceMappingURL=escape.d.ts.map

package/dist/escape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.d.ts","sourceRoot":"","sources":["../src/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/escape.js

@@ -0,0 +1,16 @@
+/**
+ * Template injection prevention.
+ *
+ * Escapes curly braces in dynamic content so they are not
+ * interpreted as template variables by the template engine.
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+/**
+ * Replace ASCII curly braces with full-width equivalents
+ * to prevent template variable injection in user-supplied content.
+ */
+export function escapeTemplateChars(str) {
+    return str.replace(/\{/g, '\uff5b').replace(/\}/g, '\uff5d');
+}
+//# sourceMappingURL=escape.js.map

package/dist/escape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.js","sourceRoot":"","sources":["../src/escape.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * faceted-prompting — Public API
+ *
+ * Re-exports all public types, interfaces, and functions.
+ * Consumers should import from this module only.
+ */
+export type { FacetKind, FacetContent, FacetSet, ComposedPrompt, ComposeOptions, } from './types.js';
+export { compose } from './compose.js';
+export type { DataEngine } from './data-engine.js';
+export { FileDataEngine, CompositeDataEngine } from './data-engine.js';
+export { trimContextContent, renderConflictNotice, prepareKnowledgeContent, preparePolicyContent, } from './truncation.js';
+export { renderTemplate } from './template.js';
+export { escapeTemplateChars } from './escape.js';
+export type { PieceSections } from './resolve.js';
+export { isResourcePath, resolveFacetPath, resolveFacetByName, resolveResourcePath, resolveResourceContent, resolveRefToContent, resolveRefList, resolveSectionMap, extractPersonaDisplayName, resolvePersona, } from './resolve.js';
+export type { ScopeRef } from './scope.js';
+export { isScopeRef, parseScopeRef, resolveScopeRef, validateScopeOwner, validateScopeRepo, validateScopeFacetName, } from './scope.js';
+//# 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;;;;;GAKG;AAGH,YAAY,EACV,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * faceted-prompting — Public API
+ *
+ * Re-exports all public types, interfaces, and functions.
+ * Consumers should import from this module only.
+ */
+// Compose
+export { compose } from './compose.js';
+export { FileDataEngine, CompositeDataEngine } from './data-engine.js';
+// Truncation
+export { trimContextContent, renderConflictNotice, prepareKnowledgeContent, preparePolicyContent, } from './truncation.js';
+// Template engine
+export { renderTemplate } from './template.js';
+// Escape
+export { escapeTemplateChars } from './escape.js';
+export { isResourcePath, resolveFacetPath, resolveFacetByName, resolveResourcePath, resolveResourceContent, resolveRefToContent, resolveRefList, resolveSectionMap, extractPersonaDisplayName, resolvePersona, } from './resolve.js';
+export { isScopeRef, parseScopeRef, resolveScopeRef, validateScopeOwner, validateScopeRepo, validateScopeFacetName, } from './scope.js';
+//# 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;;;;;GAKG;AAWH,UAAU;AACV,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAIvC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,aAAa;AACb,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAEzB,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,SAAS;AACT,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,GACf,MAAM,cAAc,CAAC;AAItB,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Facet reference resolution utilities.
+ *
+ * Resolves facet names / paths / content from section maps
+ * and candidate directories. Directory construction is delegated
+ * to the caller (TAKT provides project/global/builtin dirs).
+ *
+ * This module depends only on node:fs, node:os, node:path.
+ */
+/** Pre-resolved section maps passed to movement normalization. */
+export interface PieceSections {
+    /** Persona name -> file path (raw, not content-resolved) */
+    personas?: Record<string, string>;
+    /** Policy name -> resolved content */
+    resolvedPolicies?: Record<string, string>;
+    /** Knowledge name -> resolved content */
+    resolvedKnowledge?: Record<string, string>;
+    /** Instruction name -> resolved content */
+    resolvedInstructions?: Record<string, string>;
+    /** Report format name -> resolved content */
+    resolvedReportFormats?: Record<string, string>;
+}
+/**
+ * Check if a spec looks like a resource path (vs. a facet name).
+ * Paths start with './', '../', '/', '~' or end with '.md'.
+ */
+export declare function isResourcePath(spec: string): boolean;
+/**
+ * Resolve a facet name to its file path by scanning candidate directories.
+ *
+ * The caller builds the candidate list (e.g. project/.takt/{kind},
+ * ~/.takt/{kind}, builtins/{lang}/{kind}) and passes it in.
+ *
+ * @returns Absolute file path if found, undefined otherwise.
+ */
+export declare function resolveFacetPath(name: string, candidateDirs: readonly string[]): string | undefined;
+/**
+ * Resolve a facet name to its file content via candidate directories.
+ *
+ * @returns File content if found, undefined otherwise.
+ */
+export declare function resolveFacetByName(name: string, candidateDirs: readonly string[]): string | undefined;
+/** Resolve a resource spec to an absolute file path. */
+export declare function resolveResourcePath(spec: string, pieceDir: string): string;
+/**
+ * Resolve a resource spec to its file content.
+ * If the spec ends with .md and the file exists, returns file content.
+ * Otherwise returns the spec as-is (treated as inline content).
+ */
+export declare function resolveResourceContent(spec: string | undefined, pieceDir: string): string | undefined;
+/**
+ * Resolve a section reference to content.
+ * Looks up ref in resolvedMap first, then falls back to path resolution.
+ * If candidateDirs are provided and ref is a name (not a path),
+ * falls back to facet resolution via candidate directories.
+ */
+export declare function resolveRefToContent(ref: string, resolvedMap: Record<string, string> | undefined, pieceDir: string, candidateDirs?: readonly string[]): string | undefined;
+/** Resolve multiple references to content strings (for fields that accept string | string[]). */
+export declare function resolveRefList(refs: string | string[] | undefined, resolvedMap: Record<string, string> | undefined, pieceDir: string, candidateDirs?: readonly string[]): string[] | undefined;
+/** Resolve a piece-level section map (each value resolved to file content or inline). */
+export declare function resolveSectionMap(raw: Record<string, string> | undefined, pieceDir: string): Record<string, string> | undefined;
+/** Extract display name from persona path (e.g., "coder.md" -> "coder"). */
+export declare function extractPersonaDisplayName(personaPath: string): string;
+/**
+ * Resolve persona from YAML field to spec + absolute path.
+ *
+ * Candidate directories for name-based lookup are provided by the caller.
+ */
+export declare function resolvePersona(rawPersona: string | undefined, sections: PieceSections, pieceDir: string, candidateDirs?: readonly string[]): {
+    personaSpec?: string;
+    personaPath?: string;
+};
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,sCAAsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,2CAA2C;IAC3C,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,6CAA6C;IAC7C,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQpD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,MAAM,GAAG,SAAS,CAQpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,MAAM,GAAG,SAAS,CAMpB;AAED,wDAAwD;AACxD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC/C,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,GAAG,SAAS,CAcpB;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC/C,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,EAAE,GAAG,SAAS,CAStB;AAED,yFAAyF;AACzF,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACvC,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAQpC;AAED,4EAA4E;AAC5E,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAChC;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CA8BhD"}

package/dist/resolve.js

@@ -0,0 +1,160 @@
+/**
+ * Facet reference resolution utilities.
+ *
+ * Resolves facet names / paths / content from section maps
+ * and candidate directories. Directory construction is delegated
+ * to the caller (TAKT provides project/global/builtin dirs).
+ *
+ * This module depends only on node:fs, node:os, node:path.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+/**
+ * Check if a spec looks like a resource path (vs. a facet name).
+ * Paths start with './', '../', '/', '~' or end with '.md'.
+ */
+export function isResourcePath(spec) {
+    return (spec.startsWith('./') ||
+        spec.startsWith('../') ||
+        spec.startsWith('/') ||
+        spec.startsWith('~') ||
+        spec.endsWith('.md'));
+}
+/**
+ * Resolve a facet name to its file path by scanning candidate directories.
+ *
+ * The caller builds the candidate list (e.g. project/.takt/{kind},
+ * ~/.takt/{kind}, builtins/{lang}/{kind}) and passes it in.
+ *
+ * @returns Absolute file path if found, undefined otherwise.
+ */
+export function resolveFacetPath(name, candidateDirs) {
+    for (const dir of candidateDirs) {
+        const filePath = join(dir, `${name}.md`);
+        if (existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a facet name to its file content via candidate directories.
+ *
+ * @returns File content if found, undefined otherwise.
+ */
+export function resolveFacetByName(name, candidateDirs) {
+    const filePath = resolveFacetPath(name, candidateDirs);
+    if (filePath) {
+        return readFileSync(filePath, 'utf-8');
+    }
+    return undefined;
+}
+/** Resolve a resource spec to an absolute file path. */
+export function resolveResourcePath(spec, pieceDir) {
+    if (spec.startsWith('./'))
+        return join(pieceDir, spec.slice(2));
+    if (spec.startsWith('~'))
+        return join(homedir(), spec.slice(1));
+    if (spec.startsWith('/'))
+        return spec;
+    return join(pieceDir, spec);
+}
+/**
+ * Resolve a resource spec to its file content.
+ * If the spec ends with .md and the file exists, returns file content.
+ * Otherwise returns the spec as-is (treated as inline content).
+ */
+export function resolveResourceContent(spec, pieceDir) {
+    if (spec == null)
+        return undefined;
+    if (spec.endsWith('.md')) {
+        const resolved = resolveResourcePath(spec, pieceDir);
+        if (existsSync(resolved))
+            return readFileSync(resolved, 'utf-8');
+    }
+    return spec;
+}
+/**
+ * Resolve a section reference to content.
+ * Looks up ref in resolvedMap first, then falls back to path resolution.
+ * If candidateDirs are provided and ref is a name (not a path),
+ * falls back to facet resolution via candidate directories.
+ */
+export function resolveRefToContent(ref, resolvedMap, pieceDir, candidateDirs) {
+    const mapped = resolvedMap?.[ref];
+    if (mapped)
+        return mapped;
+    if (isResourcePath(ref)) {
+        return resolveResourceContent(ref, pieceDir);
+    }
+    if (candidateDirs) {
+        const facetContent = resolveFacetByName(ref, candidateDirs);
+        if (facetContent !== undefined)
+            return facetContent;
+    }
+    return resolveResourceContent(ref, pieceDir);
+}
+/** Resolve multiple references to content strings (for fields that accept string | string[]). */
+export function resolveRefList(refs, resolvedMap, pieceDir, candidateDirs) {
+    if (refs == null)
+        return undefined;
+    const list = Array.isArray(refs) ? refs : [refs];
+    const contents = [];
+    for (const ref of list) {
+        const content = resolveRefToContent(ref, resolvedMap, pieceDir, candidateDirs);
+        if (content)
+            contents.push(content);
+    }
+    return contents.length > 0 ? contents : undefined;
+}
+/** Resolve a piece-level section map (each value resolved to file content or inline). */
+export function resolveSectionMap(raw, pieceDir) {
+    if (!raw)
+        return undefined;
+    const resolved = {};
+    for (const [name, value] of Object.entries(raw)) {
+        const content = resolveResourceContent(value, pieceDir);
+        if (content)
+            resolved[name] = content;
+    }
+    return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+/** Extract display name from persona path (e.g., "coder.md" -> "coder"). */
+export function extractPersonaDisplayName(personaPath) {
+    return basename(personaPath, '.md');
+}
+/**
+ * Resolve persona from YAML field to spec + absolute path.
+ *
+ * Candidate directories for name-based lookup are provided by the caller.
+ */
+export function resolvePersona(rawPersona, sections, pieceDir, candidateDirs) {
+    if (!rawPersona)
+        return {};
+    // If section map has explicit mapping, use it (path-based)
+    const sectionMapping = sections.personas?.[rawPersona];
+    if (sectionMapping) {
+        const resolved = resolveResourcePath(sectionMapping, pieceDir);
+        const personaPath = existsSync(resolved) ? resolved : undefined;
+        return { personaSpec: sectionMapping, personaPath };
+    }
+    // If rawPersona is a path, resolve it directly
+    if (isResourcePath(rawPersona)) {
+        const resolved = resolveResourcePath(rawPersona, pieceDir);
+        const personaPath = existsSync(resolved) ? resolved : undefined;
+        return { personaSpec: rawPersona, personaPath };
+    }
+    // Name-based: try candidate directories
+    if (candidateDirs) {
+        const filePath = resolveFacetPath(rawPersona, candidateDirs);
+        if (filePath) {
+            return { personaSpec: rawPersona, personaPath: filePath };
+        }
+    }
+    // Fallback: try as relative path from pieceDir
+    const resolved = resolveResourcePath(rawPersona, pieceDir);
+    const personaPath = existsSync(resolved) ? resolved : undefined;
+    return { personaSpec: rawPersona, personaPath };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

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

package/dist/scope.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @scope reference resolution utilities for TAKT repertoire packages.
+ *
+ * Provides:
+ * - isScopeRef(): detect @{owner}/{repo}/{facet-name} format
+ * - parseScopeRef(): parse and normalize components
+ * - resolveScopeRef(): build file path in repertoire directory
+ * - validateScopeOwner/Repo/FacetName(): name constraint validation
+ */
+/** Parsed components of an @scope reference. */
+export interface ScopeRef {
+    /** GitHub owner (lowercase). */
+    owner: string;
+    /** Repository name (lowercase). */
+    repo: string;
+    /** Facet name. */
+    name: string;
+}
+/**
+ * Return true if the string is an @{owner}/{repo}/{facet-name} scope reference.
+ */
+export declare function isScopeRef(ref: string): boolean;
+/**
+ * Parse an @scope reference into its components.
+ * Normalizes owner and repo to lowercase.
+ *
+ * @param ref - e.g. "@nrslib/takt-fullstack/expert-coder"
+ */
+export declare function parseScopeRef(ref: string): ScopeRef;
+/**
+ * Resolve a scope reference to a file path in the repertoire directory.
+ *
+ * Path: {repertoireDir}/@{owner}/{repo}/facets/{facetType}/{name}.md
+ *
+ * @param scopeRef      - parsed scope reference
+ * @param facetType     - e.g. "personas", "policies", "knowledge"
+ * @param repertoireDir - root repertoire directory (e.g. ~/.takt/repertoire)
+ * @returns Absolute path to the facet file.
+ */
+export declare function resolveScopeRef(scopeRef: ScopeRef, facetType: string, repertoireDir: string): string;
+/** Validate owner name: must match /^[a-z0-9][a-z0-9-]*$/ */
+export declare function validateScopeOwner(owner: string): void;
+/** Validate repo name: must match /^[a-z0-9][a-z0-9._-]*$/ */
+export declare function validateScopeRepo(repo: string): void;
+/** Validate facet name: must match /^[a-z0-9][a-z0-9-]*$/ */
+export declare function validateScopeFacetName(name: string): void;
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,gDAAgD;AAChD,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAKD;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAYnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,MAAM,CASR;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMtD;AAED,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMzD"}

package/dist/scope.js

@@ -0,0 +1,69 @@
+/**
+ * @scope reference resolution utilities for TAKT repertoire packages.
+ *
+ * Provides:
+ * - isScopeRef(): detect @{owner}/{repo}/{facet-name} format
+ * - parseScopeRef(): parse and normalize components
+ * - resolveScopeRef(): build file path in repertoire directory
+ * - validateScopeOwner/Repo/FacetName(): name constraint validation
+ */
+import { join } from 'node:path';
+/** Matches @{owner}/{repo}/{facet-name} format. */
+const SCOPE_REF_PATTERN = /^@[^/]+\/[^/]+\/[^/]+$/;
+/**
+ * Return true if the string is an @{owner}/{repo}/{facet-name} scope reference.
+ */
+export function isScopeRef(ref) {
+    return SCOPE_REF_PATTERN.test(ref);
+}
+/**
+ * Parse an @scope reference into its components.
+ * Normalizes owner and repo to lowercase.
+ *
+ * @param ref - e.g. "@nrslib/takt-fullstack/expert-coder"
+ */
+export function parseScopeRef(ref) {
+    const withoutAt = ref.slice(1);
+    const firstSlash = withoutAt.indexOf('/');
+    const owner = withoutAt.slice(0, firstSlash).toLowerCase();
+    const rest = withoutAt.slice(firstSlash + 1);
+    const secondSlash = rest.indexOf('/');
+    const repo = rest.slice(0, secondSlash).toLowerCase();
+    const name = rest.slice(secondSlash + 1);
+    validateScopeOwner(owner);
+    validateScopeRepo(repo);
+    validateScopeFacetName(name);
+    return { owner, repo, name };
+}
+/**
+ * Resolve a scope reference to a file path in the repertoire directory.
+ *
+ * Path: {repertoireDir}/@{owner}/{repo}/facets/{facetType}/{name}.md
+ *
+ * @param scopeRef      - parsed scope reference
+ * @param facetType     - e.g. "personas", "policies", "knowledge"
+ * @param repertoireDir - root repertoire directory (e.g. ~/.takt/repertoire)
+ * @returns Absolute path to the facet file.
+ */
+export function resolveScopeRef(scopeRef, facetType, repertoireDir) {
+    return join(repertoireDir, `@${scopeRef.owner}`, scopeRef.repo, 'facets', facetType, `${scopeRef.name}.md`);
+}
+/** Validate owner name: must match /^[a-z0-9][a-z0-9-]*$/ */
+export function validateScopeOwner(owner) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(owner)) {
+        throw new Error(`Invalid scope owner: "${owner}". Must match /^[a-z0-9][a-z0-9-]*$/ (lowercase alphanumeric and hyphens, not starting with hyphen).`);
+    }
+}
+/** Validate repo name: must match /^[a-z0-9][a-z0-9._-]*$/ */
+export function validateScopeRepo(repo) {
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(repo)) {
+        throw new Error(`Invalid scope repo: "${repo}". Must match /^[a-z0-9][a-z0-9._-]*$/ (lowercase alphanumeric, hyphens, dots, underscores, not starting with hyphen).`);
+    }
+}
+/** Validate facet name: must match /^[a-z0-9][a-z0-9-]*$/ */
+export function validateScopeFacetName(name) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+        throw new Error(`Invalid scope facet name: "${name}". Must match /^[a-z0-9][a-z0-9-]*$/ (lowercase alphanumeric and hyphens, not starting with hyphen).`);
+    }
+}
+//# sourceMappingURL=scope.js.map

package/dist/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAYjC,mDAAmD;AACnD,MAAM,iBAAiB,GAAG,wBAAwB,CAAC;AAEnD;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3D,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,WAAW,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;IACzC,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC1B,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACxB,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAkB,EAClB,SAAiB,EACjB,aAAqB;IAErB,OAAO,IAAI,CACT,aAAa,EACb,IAAI,QAAQ,CAAC,KAAK,EAAE,EACpB,QAAQ,CAAC,IAAI,EACb,QAAQ,EACR,SAAS,EACT,GAAG,QAAQ,CAAC,IAAI,KAAK,CACtB,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,yBAAyB,KAAK,sGAAsG,CACrI,CAAC;IACJ,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,wHAAwH,CACrJ,CAAC;IACJ,CAAC;AACH,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,8BAA8B,IAAI,sGAAsG,CACzI,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/template.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal template engine for Markdown prompt templates.
+ *
+ * Supports:
+ * - {{#if variable}}...{{else}}...{{/if}} conditional blocks (no nesting)
+ * - {{variableName}} substitution
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+/**
+ * Process {{#if variable}}...{{else}}...{{/if}} conditional blocks.
+ *
+ * A variable is truthy when it is a non-empty string or boolean true.
+ * Nesting is NOT supported.
+ */
+export declare function processConditionals(template: string, vars: Record<string, string | boolean>): string;
+/**
+ * Replace {{variableName}} placeholders with values from vars.
+ * Undefined or false variables are replaced with empty string.
+ * True is replaced with the string "true".
+ */
+export declare function substituteVariables(template: string, vars: Record<string, string | boolean>): string;
+/**
+ * Render a template string by processing conditionals then substituting variables.
+ */
+export declare function renderTemplate(template: string, vars: Record<string, string | boolean>): string;
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GACrC,MAAM,CAcR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GACrC,MAAM,CAUR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GACrC,MAAM,CAGR"}

package/dist/template.js

@@ -0,0 +1,49 @@
+/**
+ * Minimal template engine for Markdown prompt templates.
+ *
+ * Supports:
+ * - {{#if variable}}...{{else}}...{{/if}} conditional blocks (no nesting)
+ * - {{variableName}} substitution
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+/**
+ * Process {{#if variable}}...{{else}}...{{/if}} conditional blocks.
+ *
+ * A variable is truthy when it is a non-empty string or boolean true.
+ * Nesting is NOT supported.
+ */
+export function processConditionals(template, vars) {
+    return template.replace(/\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_match, varName, body) => {
+        const value = vars[varName];
+        const isTruthy = value !== undefined && value !== false && value !== '';
+        const elseIndex = body.indexOf('{{else}}');
+        if (isTruthy) {
+            return elseIndex >= 0 ? body.slice(0, elseIndex) : body;
+        }
+        return elseIndex >= 0 ? body.slice(elseIndex + '{{else}}'.length) : '';
+    });
+}
+/**
+ * Replace {{variableName}} placeholders with values from vars.
+ * Undefined or false variables are replaced with empty string.
+ * True is replaced with the string "true".
+ */
+export function substituteVariables(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_match, varName) => {
+        const value = vars[varName];
+        if (value === undefined || value === false)
+            return '';
+        if (value === true)
+            return 'true';
+        return value;
+    });
+}
+/**
+ * Render a template string by processing conditionals then substituting variables.
+ */
+export function renderTemplate(template, vars) {
+    const afterConditionals = processConditionals(template, vars);
+    return substituteVariables(afterConditionals, vars);
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,IAAsC;IAEtC,OAAO,QAAQ,CAAC,OAAO,CACrB,4CAA4C,EAC5C,CAAC,MAAM,EAAE,OAAe,EAAE,IAAY,EAAU,EAAE;QAChD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,EAAE,CAAC;QAExE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1D,CAAC;QACD,OAAO,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,IAAsC;IAEtC,OAAO,QAAQ,CAAC,OAAO,CACrB,gBAAgB,EAChB,CAAC,MAAM,EAAE,OAAe,EAAE,EAAE;QAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,KAAK;YAAE,OAAO,EAAE,CAAC;QACtD,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,IAAsC;IAEtC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC9D,OAAO,mBAAmB,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;AACtD,CAAC"}

package/dist/truncation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Context truncation for knowledge and policy facets.
+ *
+ * When facet content exceeds a character limit, it is trimmed and
+ * annotated with source-path metadata so the LLM can consult the
+ * original file.
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+interface PreparedContextBlock {
+    readonly content: string;
+    readonly truncated: boolean;
+}
+/**
+ * Trim content to a maximum character length, appending a
+ * "...TRUNCATED..." marker when truncation occurs.
+ */
+export declare function trimContextContent(content: string, maxChars: number): PreparedContextBlock;
+/**
+ * Standard notice appended to knowledge and policy blocks.
+ */
+export declare function renderConflictNotice(): string;
+/**
+ * Prepare a knowledge facet for inclusion in a prompt.
+ *
+ * Trims to maxChars, appends truncation notice and source path if available.
+ */
+export declare function prepareKnowledgeContent(content: string, maxChars: number, sourcePath?: string): string;
+/**
+ * Prepare a policy facet for inclusion in a prompt.
+ *
+ * Trims to maxChars, appends authoritative-source notice and source path if available.
+ */
+export declare function preparePolicyContent(content: string, maxChars: number, sourcePath?: string): string;
+export {};
+//# sourceMappingURL=truncation.d.ts.map

package/dist/truncation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.d.ts","sourceRoot":"","sources":["../src/truncation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,oBAAoB,CAQtB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAcR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAcR"}

package/dist/truncation.js

@@ -0,0 +1,63 @@
+/**
+ * Context truncation for knowledge and policy facets.
+ *
+ * When facet content exceeds a character limit, it is trimmed and
+ * annotated with source-path metadata so the LLM can consult the
+ * original file.
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+/**
+ * Trim content to a maximum character length, appending a
+ * "...TRUNCATED..." marker when truncation occurs.
+ */
+export function trimContextContent(content, maxChars) {
+    if (content.length <= maxChars) {
+        return { content, truncated: false };
+    }
+    return {
+        content: `${content.slice(0, maxChars)}\n...TRUNCATED...`,
+        truncated: true,
+    };
+}
+/**
+ * Standard notice appended to knowledge and policy blocks.
+ */
+export function renderConflictNotice() {
+    return 'If prompt content conflicts with source files, source files take precedence.';
+}
+/**
+ * Prepare a knowledge facet for inclusion in a prompt.
+ *
+ * Trims to maxChars, appends truncation notice and source path if available.
+ */
+export function prepareKnowledgeContent(content, maxChars, sourcePath) {
+    const prepared = trimContextContent(content, maxChars);
+    const lines = [prepared.content];
+    if (prepared.truncated && sourcePath) {
+        lines.push('', `Knowledge is truncated. You MUST consult the source files before making decisions. Source: ${sourcePath}`);
+    }
+    if (sourcePath) {
+        lines.push('', `Knowledge Source: ${sourcePath}`);
+    }
+    lines.push('', renderConflictNotice());
+    return lines.join('\n');
+}
+/**
+ * Prepare a policy facet for inclusion in a prompt.
+ *
+ * Trims to maxChars, appends authoritative-source notice and source path if available.
+ */
+export function preparePolicyContent(content, maxChars, sourcePath) {
+    const prepared = trimContextContent(content, maxChars);
+    const lines = [prepared.content];
+    if (prepared.truncated && sourcePath) {
+        lines.push('', `Policy is authoritative. If truncated, you MUST read the full policy file and follow it strictly. Source: ${sourcePath}`);
+    }
+    if (sourcePath) {
+        lines.push('', `Policy Source: ${sourcePath}`);
+    }
+    lines.push('', renderConflictNotice());
+    return lines.join('\n');
+}
+//# sourceMappingURL=truncation.js.map

package/dist/truncation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.js","sourceRoot":"","sources":["../src/truncation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,QAAgB;IAEhB,IAAI,OAAO,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IACD,OAAO;QACL,OAAO,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,mBAAmB;QACzD,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,8EAA8E,CAAC;AACxF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAe,EACf,QAAgB,EAChB,UAAmB;IAEnB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,KAAK,GAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,QAAQ,CAAC,SAAS,IAAI,UAAU,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CACR,EAAE,EACF,8FAA8F,UAAU,EAAE,CAC3G,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,qBAAqB,UAAU,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,oBAAoB,EAAE,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,QAAgB,EAChB,UAAmB;IAEnB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvD,MAAM,KAAK,GAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,QAAQ,CAAC,SAAS,IAAI,UAAU,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CACR,EAAE,EACF,6GAA6G,UAAU,EAAE,CAC1H,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,kBAAkB,UAAU,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,oBAAoB,EAAE,CAAC,CAAC;IACvC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Core type definitions for Faceted Prompting.
+ *
+ * Defines the vocabulary of facets (persona, policy, knowledge, instruction,
+ * output-contract) and the structures used by compose() and DataEngine.
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+/** Plural directory names used in facet resolution. */
+export type FacetKind = 'personas' | 'policies' | 'knowledge' | 'instructions' | 'output-contracts';
+/** A single piece of facet content with optional metadata. */
+export interface FacetContent {
+    /** Raw text body of the facet. */
+    readonly body: string;
+    /** Filesystem path the content was loaded from, if applicable. */
+    readonly sourcePath?: string;
+}
+/**
+ * A complete set of resolved facet contents to be composed.
+ *
+ * All fields are optional — a FacetSet may contain only a subset of facets.
+ */
+export interface FacetSet {
+    readonly persona?: FacetContent;
+    readonly policies?: readonly FacetContent[];
+    readonly knowledge?: readonly FacetContent[];
+    readonly instruction?: FacetContent;
+}
+/**
+ * The output of compose(): facet content assigned to LLM message slots.
+ *
+ * persona → systemPrompt
+ * policy + knowledge + instruction → userMessage
+ */
+export interface ComposedPrompt {
+    readonly systemPrompt: string;
+    readonly userMessage: string;
+}
+/** Options controlling compose() behaviour. */
+export interface ComposeOptions {
+    /** Maximum character length for knowledge/policy content before truncation. */
+    readonly contextMaxChars: number;
+}
+//# 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;;;;;;;GAOG;AAEH,uDAAuD;AACvD,MAAM,MAAM,SAAS,GACjB,UAAU,GACV,UAAU,GACV,WAAW,GACX,cAAc,GACd,kBAAkB,CAAC;AAEvB,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Core type definitions for Faceted Prompting.
+ *
+ * Defines the vocabulary of facets (persona, policy, knowledge, instruction,
+ * output-contract) and the structures used by compose() and DataEngine.
+ *
+ * This module has ZERO dependencies on TAKT internals.
+ */
+export {};
+//# 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;;;;;;;GAOG"}

package/package.json

@@ -1,11 +1,42 @@
 {
   "name": "faceted-prompting",
-  "version": "0.0.0",
-  "description": "Faceted Prompting - A design pattern for composing structured AI prompts from multiple facets (persona, policy, knowledge, instruction)",
-  "author": "nrslib",
+  "version": "0.1.0",
+  "description": "Faceted Prompting \u2014 structured prompt composition for LLMs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "prompt",
+    "llm",
+    "faceted-prompting",
+    "prompt-engineering",
+    "ai"
+  ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nrslib/faceted-prompting"
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "eslint": "^9.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   }
-}
+}