rhachet 1.1.0 → 1.3.0

package/dist/contract/cli/invokeReadme.integration.test.js.map

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

package/dist/contract/cli/invokeReadme.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indentLines = exports.invokeReadme = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const assureFindRole_1 = require("../../logic/invoke/assureFindRole");
+/**
+ * .what = main entrypoint for `readme` CLI command
+ * .why = allows devs to introspect registry, role, or skill documentation from the CLI
+ */
+const invokeReadme = ({ program, registries, }) => {
+    program
+        .command('readme')
+        .description('print documentation for the registry, a role, or a skill')
+        .option('--registry <slug>', 'which registry to inspect')
+        .option('--role <slug>', 'which role to inspect')
+        .option('--skill <slug>', 'which skill to inspect')
+        .action((opts) => {
+        // no inputs provided
+        if (!opts.registry && !opts.role)
+            helpful_errors_1.BadRequestError.throw('must provide --registry or --role');
+        // resolve registry
+        const registry = opts.registry
+            ? registries.find((r) => r.slug === opts.registry)
+            : null;
+        if (!opts.role) {
+            if (!registry)
+                helpful_errors_1.BadRequestError.throw(`no registry matches given options`);
+            // registry level readme
+            return printReadme(`${registry.slug}`, registry.readme);
+        }
+        // resolve role
+        const role = (0, assureFindRole_1.assureFindRole)({ registries, slug: opts.role });
+        if (!role)
+            helpful_errors_1.BadRequestError.throw(`no role named "${opts.role}" in configured registries`, {
+                registries: registries.map((thisRegistry) => thisRegistry.slug),
+            });
+        // role-level readme
+        if (!opts.skill)
+            return printReadme(`${role.slug}`, role.readme);
+        // resolve skill
+        const skill = role.skills.find((s) => s.slug === opts.skill);
+        if (!skill)
+            helpful_errors_1.BadRequestError.throw(`no skill "${opts.skill}" in role "${opts.role}"`, { skills: role.skills.map((thisSkill) => thisSkill.slug) });
+        // skill-level readme
+        return printReadme(`${role.slug}.${skill.slug}`, skill.readme);
+    });
+};
+exports.invokeReadme = invokeReadme;
+/**
+ * .what = logs a formatted markdown readme block with label
+ * .why = standardizes output for registry/role/skill readmes in CLI
+ */
+const printReadme = (slug, markdown) => {
+    console.log('');
+    console.log(`📜 ${slug}.readme`);
+    console.log('');
+    console.log((0, exports.indentLines)(markdown));
+    console.log('');
+};
+/**
+ * .what = indents each line of a string by a fixed number of spaces
+ * .why = ensures markdown blocks are consistently readable in nested output
+ */
+const indentLines = (text, spaces = 4) => {
+    const prefix = ' '.repeat(spaces);
+    return text
+        .split('\n')
+        .map((line) => `${prefix}${line}`)
+        .join('\n');
+};
+exports.indentLines = indentLines;
+//# sourceMappingURL=invokeReadme.js.map

package/dist/contract/cli/invokeReadme.js.map

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

package/dist/domain/objects/Role.d.ts

@@ -0,0 +1,47 @@
+import { DomainEntity } from 'domain-objects';
+import { RoleSkill } from './RoleSkill';
+import { RoleTrait } from './RoleTrait';
+/**
+ * .what = defines a role that can have traits, know skills, and be instantiated across thread.context
+ * .why =
+ *   - enables registration of usable roles (e.g., 'mechanic', 'designer', 'architect', 'ecologist')
+ *   - enables instantiation of thread.contexts
+ */
+export interface Role {
+    /**
+     * .what = a unique, readable identifier
+     * .example = "mechanic"
+     */
+    slug: string;
+    /**
+     * .what = a display name for the role
+     * .example = "Mechanic"
+     */
+    name: string;
+    /**
+     * .what = a brief on why this role exists
+     * .why =
+     *   - explain when and for what it should be used
+     *   - sets what you can expect from it
+     */
+    purpose: string;
+    /**
+     * .what = a readme that explains more about the role
+     * .why =
+     *   - give detail about what it does and how it does it
+     */
+    readme: string;
+    /**
+     * .what = the traits inherent to the role
+     * .why = declares how the role goes about things
+     */
+    traits: RoleTrait<any>[];
+    /**
+     * .what = the skills known by the role
+     * .why = declares what the role can do
+     */
+    skills: RoleSkill<any>[];
+}
+export declare class Role extends DomainEntity<Role> implements Role {
+    static unique: readonly ["slug"];
+}

package/dist/domain/objects/Role.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Role = void 0;
+const domain_objects_1 = require("domain-objects");
+class Role extends domain_objects_1.DomainEntity {
+}
+exports.Role = Role;
+Role.unique = ['slug'];
+//# sourceMappingURL=Role.js.map

package/dist/domain/objects/Role.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Role.js","sourceRoot":"","sources":["../../../src/domain/objects/Role.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAmD9C,MAAa,IAAK,SAAQ,6BAAkB;;AAA5C,oBAEC;AADe,WAAM,GAAG,CAAC,MAAM,CAAU,CAAC"}

package/dist/domain/objects/RoleContext.d.ts

@@ -0,0 +1,46 @@
+import { ThreadContextRole, ThreadRole } from './Threads';
+/**
+ * .what = a resolved RoleTrait, accessible in a thread's context
+ * .why = defines the default mindset or behavioral axioms that persist across all tasks performed in the role
+ * .examples =
+ *   - treat ubiquitous language as top priority
+ *   - treat consistency as top priority
+ *   - prefer given/when/then test suites
+ * todo:
+ *   - ensure that traits are always leveraged in every template that uses a role'd thread?
+ */
+export interface RoleContextTrait {
+    content: string;
+}
+/**
+ * .what = a reference to a skill which is learned and accessible to any actor which assumes the role
+ * .why = enables agents to perform tasks within the role using repeatable methods, patterns, or strategies
+ * .cases =
+ *   - domain distillation is a process where you extract domain terms and clarify their relationships; here's how to use
+ *   - given/when/then enables test suites with behavior-driven structure; here's how to use
+ * todo:
+ *   - update this to a shape that actually helps dynamic subskill execution, once we get to fluid routes
+ */
+export interface RoleContextSkill {
+    content: string;
+}
+/**
+ * .what = the context that each role carries with it
+ * .why = provides each role with a set of traits (inherent truths) and skills (learned abilities) to influence how they approach decisions, actions, and interpretations
+ */
+export interface RoleContext<TRole extends ThreadRole, TStash extends Record<string, any> | undefined> extends ThreadContextRole<TRole> {
+    role: TRole;
+    /**
+     * .what = the persistent traits and skills that define how this role behaves
+     * .why  = allows role-specific behavior, reasoning styles, and tool usage to persist across steps
+     */
+    inherit: {
+        traits: RoleContextTrait[];
+        skills: RoleContextSkill[];
+    };
+    /**
+     * .what = short-lived or dynamic data needed for the current task
+     * .why  = gives the thread situational context without polluting long-term role identity
+     */
+    stash: TStash;
+}

package/dist/domain/objects/RoleContext.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=RoleContext.js.map

package/dist/domain/objects/RoleContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoleContext.js","sourceRoot":"","sources":["../../../src/domain/objects/RoleContext.ts"],"names":[],"mappings":""}

package/dist/domain/objects/RoleRegistry.d.ts

@@ -0,0 +1,31 @@
+import { DomainEntity } from 'domain-objects';
+import { Role } from './Role';
+/**
+ * .what = a curated collection of roles, available for use
+ * .why =
+ *   - acts as a declaration of available roles
+ *   - enables composition of registries
+ *   - supports cli and documentation introspection
+ *   - supports fluid composition of roles via delegation (e.g., one role can runtime delegate to another that it found via registry)
+ */
+export interface RoleRegistry {
+    /**
+     * .what = unique identifier for this registry
+     */
+    slug: string;
+    /**
+     * .what = markdown-formatted overview of what this registry contains
+     * .why = provides documentation, context, and intended use
+     */
+    readme: string;
+    /**
+     * .what = the roles that this registry has collected
+     */
+    roles: Role[];
+}
+export declare class RoleRegistry extends DomainEntity<RoleRegistry> implements RoleRegistry {
+    static unique: readonly ["slug"];
+    static nested: {
+        roles: typeof Role;
+    };
+}

package/dist/domain/objects/RoleRegistry.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleRegistry = void 0;
+const domain_objects_1 = require("domain-objects");
+const Role_1 = require("./Role");
+class RoleRegistry extends domain_objects_1.DomainEntity {
+}
+exports.RoleRegistry = RoleRegistry;
+RoleRegistry.unique = ['slug'];
+RoleRegistry.nested = {
+    roles: Role_1.Role,
+};
+//# sourceMappingURL=RoleRegistry.js.map

package/dist/domain/objects/RoleRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoleRegistry.js","sourceRoot":"","sources":["../../../src/domain/objects/RoleRegistry.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAE9C,iCAA8B;AA2B9B,MAAa,YACX,SAAQ,6BAA0B;;AADpC,oCAQC;AAJe,mBAAM,GAAG,CAAC,MAAM,CAAU,CAAC;AAC3B,mBAAM,GAAG;IACrB,KAAK,EAAE,WAAI;CACZ,CAAC"}

package/dist/domain/objects/RoleSkill.d.ts

@@ -0,0 +1,38 @@
+import { DomainEntity } from 'domain-objects';
+import { RoleSkillContextGetter, RoleSkillThreadsGetter } from './RoleSkillArgGetter';
+import { GStitcher, Stitcher } from './Stitcher';
+/**
+ * .what = a skill is an action a role can perform; a route it can weave
+ * .why =
+ *   - defines a reusable skill you can ask a role to perform
+ *   - usable for skill invocation, e.g., via the cli
+ */
+export interface RoleSkill<TStitcher extends GStitcher> {
+    /**
+     * .what = short, unique identifier
+     * .example = "summarize"
+     */
+    slug: string;
+    /**
+     * .what = a full description of the skill
+     * .why = explains what can be expected, how to use it, and details of operation
+     * .note =
+     *   - the first two lines of the readme will be used as a description
+     */
+    readme: string;
+    /**
+     * .what = the route via which the skill is executable
+     */
+    route: Stitcher<TStitcher>;
+    /**
+     * .what = how to instantiate the threads for this skill
+     */
+    threads: RoleSkillThreadsGetter<TStitcher['threads'], any>;
+    /**
+     * .what = how to instantiate the context for this skill
+     */
+    context: RoleSkillContextGetter<TStitcher['context'], any>;
+}
+export declare class RoleSkill<TStitcher extends GStitcher> extends DomainEntity<RoleSkill<TStitcher>> implements RoleSkill<TStitcher> {
+    static unique: readonly ["slug"];
+}

package/dist/domain/objects/RoleSkill.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleSkill = void 0;
+const domain_objects_1 = require("domain-objects");
+class RoleSkill extends domain_objects_1.DomainEntity {
+}
+exports.RoleSkill = RoleSkill;
+RoleSkill.unique = ['slug'];
+//# sourceMappingURL=RoleSkill.js.map

package/dist/domain/objects/RoleSkill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoleSkill.js","sourceRoot":"","sources":["../../../src/domain/objects/RoleSkill.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AA4C9C,MAAa,SACX,SAAQ,6BAAkC;;AAD5C,8BAKC;AADe,gBAAM,GAAG,CAAC,MAAM,CAAU,CAAC"}

package/dist/domain/objects/RoleSkillArgGetter.d.ts

@@ -0,0 +1,137 @@
+import { DomainLiteral } from 'domain-objects';
+import { Empty } from 'type-fns';
+import { GStitcher } from './Stitcher';
+import { Threads } from './Threads';
+/**
+ * .what = a generic specification for how to collect, verify, and instantiate skill arguments
+ * .why =
+ *   - enables runtime hydration of `threads` or `context` from dynamic sources (e.g., CLI args, env vars)
+ *   - supports unified handling for both declaration and execution paths
+ *   - decouples static input schema from runtime instantiation logic
+ * .how =
+ *   - supports lookup and passin mode
+ *   - for lookup mode, will lookup the vars based on the schema specified, then assure correctness
+ *   - for passin mode, will accept the passin declaration and simply assure correctness
+ */
+export interface RoleSkillArgGetter<TOutput, TVariables extends Record<string, any>> {
+    /**
+     * .what = declares how to collect required inputs (from CLI, env, etc)
+     */
+    lookup: Record<string, {
+        /**
+         * .what = where to get lookup from
+         */
+        source: 'process.env';
+        /**
+         * .what = a description of the input
+         */
+        desc: string;
+        /**
+         * .what = what envar key to dereference
+         */
+        envar: string;
+        /**
+         * .what = what type to expect
+         */
+        type: 'string';
+    } | {
+        /**
+         * .what = where to get lookup from
+         */
+        source: 'process.argv';
+        /**
+         * .what = a description of the input
+         */
+        desc: string;
+        /**
+         * .what = what shorthand char alias to use, if from process.argv
+         */
+        char?: string;
+        /**
+         * .what = what type to expect
+         */
+        type: 'string';
+    }>;
+    /**
+     * .what = assures the input from lookup or passin was correctly declared
+     */
+    assess: (input: any) => input is TVariables;
+    /**
+     * .what = instantiates the desired runtime object from the assured input
+     */
+    instantiate: (input: TVariables) => Promise<TOutput> | TOutput;
+}
+/**
+ * .what = a specification of the inputs required to instantiate the threads required for a skill
+ * .why =
+ *   - enables declaration of inputs required for threads.getter(inputs)
+ *   - unlocks cli usage where declaration is dynamic and runtime specified
+ * .how =
+ *   - supports lookup and passin mode
+ *   - for lookup mode, will lookup the vars based on the schema specified, then assure correctness
+ *   - for passin mode, will accept the passin declaration and simply assure correctness
+ */
+export interface RoleSkillThreadsGetter<TOutput extends Threads<any>, TVariables extends Record<string, string>> extends RoleSkillArgGetter<TOutput, TVariables> {
+    /**
+     * .what = how to lookup the required inputs for thread instantiation
+     * .example = { target: { char: t, desc: "the target file or dir to upsert against", shape: "string" } }
+     */
+    lookup: Record<string, {
+        /**
+         * .what = where to get lookup from
+         */
+        source: 'process.argv';
+        /**
+         * .what = a description of the input
+         */
+        desc: string;
+        /**
+         * .what = what shorthand single char alias to use
+         */
+        char?: string;
+        /**
+         * .what = what type to expect
+         */
+        type: 'string';
+    }> & {
+        ask?: Empty;
+    };
+}
+export declare class RoleSkillThreadsGetter<TOutput extends Threads<any>, TVariables extends Record<string, string>> extends DomainLiteral<RoleSkillThreadsGetter<TOutput, TVariables>> implements RoleSkillThreadsGetter<TOutput, TVariables> {
+}
+/**
+ * .what = a specification of the inputs required to instantiate the context required for a skill
+ * .why =
+ *   - enables declaration of inputs required for context.getter(inputs)
+ *   - unlocks cli usage where declaration is dynamic and runtime specified
+ * .how =
+ *   - supports lookup and passin mode
+ *   - for lookup mode, will lookup the vars based on the schema specified, then assure correctness
+ *   - for passin mode, will accept the passin declaration and simply assure correctness
+ */
+export interface RoleSkillContextGetter<TOutput extends GStitcher['context'], TVariables extends Record<string, string>> extends RoleSkillArgGetter<TOutput, TVariables> {
+    /**
+     * .what = how to lookup the required inputs for context instantiation
+     * .example = { openaiApiKey: { envar: "PREP_OPENAI_KEY" } }
+     */
+    lookup: Record<string, {
+        /**
+         * .what = where to get lookup from
+         */
+        source: 'process.env';
+        /**
+         * .what = a description of the input
+         */
+        desc: string;
+        /**
+         * .what = what envar key to dereference
+         */
+        envar: string;
+        /**
+         * .what = what type to expect
+         */
+        type: 'string';
+    }>;
+}
+export declare class RoleSkillContextGetter<TOutput extends GStitcher['context'], TVariables extends Record<string, string>> extends DomainLiteral<RoleSkillContextGetter<TOutput, TVariables>> implements RoleSkillContextGetter<TOutput, TVariables> {
+}

package/dist/domain/objects/RoleSkillArgGetter.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleSkillContextGetter = exports.RoleSkillThreadsGetter = void 0;
+const domain_objects_1 = require("domain-objects");
+class RoleSkillThreadsGetter extends domain_objects_1.DomainLiteral {
+}
+exports.RoleSkillThreadsGetter = RoleSkillThreadsGetter;
+class RoleSkillContextGetter extends domain_objects_1.DomainLiteral {
+}
+exports.RoleSkillContextGetter = RoleSkillContextGetter;
+//# sourceMappingURL=RoleSkillArgGetter.js.map

package/dist/domain/objects/RoleSkillArgGetter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoleSkillArgGetter.js","sourceRoot":"","sources":["../../../src/domain/objects/RoleSkillArgGetter.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AA8H/C,MAAa,sBAIX,SAAQ,8BAA0D;CACT;AAL3D,wDAK2D;AA6C3D,MAAa,sBAIX,SAAQ,8BAA0D;CACT;AAL3D,wDAK2D"}

package/dist/domain/objects/RoleTrait.d.ts

@@ -0,0 +1,34 @@
+import { DomainEntity } from 'domain-objects';
+import { Serializable } from 'serde-fns';
+import { Template } from './Template';
+/**
+ * .what = a trait is a reusable behavioral modifier for a role
+ *   - it's adopted as an inherent truth of any actor which assumes the role
+ *   - defines the default mindset or behavioral axioms leveraged by the role
+ * .why =
+ *   - helps cluster similar role behaviors (e.g. “asksQuestions”, “retriesUntilSolved”)
+ *   - enables composable role design
+ * .examples =
+ *   - treat ubiquitous language as top priority
+ *   - treat consistency as top priority
+ *   - prefer given/when/then test suites
+ */
+export interface RoleTrait<TVariables extends Serializable> {
+    /**
+     * .what = short identifier for this trait
+     * .example = "asksQuestions"
+     */
+    slug: string;
+    /**
+     * .what = what this trait describes
+     * .example = "asks clarifying questions before responding"
+     */
+    readme: string;
+    /**
+     * .what = the brief that houses this trait's declaration
+     */
+    brief: Template<TVariables>;
+}
+export declare class RoleTrait<TVariables extends Serializable> extends DomainEntity<RoleTrait<TVariables>> implements RoleTrait<TVariables> {
+    static unique: readonly ["slug"];
+}

package/dist/domain/objects/RoleTrait.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleTrait = void 0;
+const domain_objects_1 = require("domain-objects");
+class RoleTrait extends domain_objects_1.DomainEntity {
+}
+exports.RoleTrait = RoleTrait;
+RoleTrait.unique = ['slug'];
+//# sourceMappingURL=RoleTrait.js.map

package/dist/domain/objects/RoleTrait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoleTrait.js","sourceRoot":"","sources":["../../../src/domain/objects/RoleTrait.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAmC9C,MAAa,SACX,SAAQ,6BAAmC;;AAD7C,8BAKC;AADe,gBAAM,GAAG,CAAC,MAAM,CAAU,CAAC"}

package/dist/domain/objects/StitchStep.d.ts

@@ -32,7 +32,7 @@ export interface StitchStepImagine<TStitcher extends GStitcher<Threads<any, any>
      */
     enprompt: (input: {
         threads: TStitcher['threads'];
-    }) => string;
+    }) => string | Promise<string>;
     /**
      * .what = invokes an llm to imagine based on a prompt
      */

package/dist/domain/objects/StitchStep.js.map

@@ -1 +1 @@
-{"version":3,"file":"StitchStep.js","sourceRoot":"","sources":["../../../src/domain/objects/StitchStep.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AA4B/C,MAAa,iBAGX,SAAQ,8BAA2C;CACT;AAJ5C,8CAI4C;AAiC5C,MAAa,iBAGX,SAAQ,8BAA2C;CACT;AAJ5C,8CAI4C"}
+{"version":3,"file":"StitchStep.js","sourceRoot":"","sources":["../../../src/domain/objects/StitchStep.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AA4B/C,MAAa,iBAGX,SAAQ,8BAA2C;CACT;AAJ5C,8CAI4C;AAmC5C,MAAa,iBAGX,SAAQ,8BAA2C;CACT;AAJ5C,8CAI4C"}

package/dist/domain/objects/Template.d.ts

@@ -0,0 +1,21 @@
+import { DomainEntity, RefByUnique } from 'domain-objects';
+import { GitFile } from 'rhachet-artifact-git';
+/**
+ * .what = a template reference that can be hydrated with variables
+ * .why = enables rendering reusable text templates with custom input
+ *
+ * .cases =
+ *   - load a GitFile template from a known uri
+ *   - hydrate the template using input variables
+ *   - return the final string with placeholders filled
+ */
+export interface Template<TVariables = any> {
+    ref: RefByUnique<typeof GitFile>;
+    /**
+     * .what = renders the template with the given variables
+     * .why = supports consistent formatting for any templated output
+     */
+    use: (input: TVariables) => Promise<string>;
+}
+export declare class Template<TVariables = any> extends DomainEntity<Template<TVariables>> implements Template<TVariables> {
+}

package/dist/domain/objects/Template.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Template = void 0;
+const domain_objects_1 = require("domain-objects");
+class Template extends domain_objects_1.DomainEntity {
+}
+exports.Template = Template;
+//# sourceMappingURL=Template.js.map

package/dist/domain/objects/Template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Template.js","sourceRoot":"","sources":["../../../src/domain/objects/Template.ts"],"names":[],"mappings":";;;AAAA,mDAA2D;AAsB3D,MAAa,QACX,SAAQ,6BAAkC;CACR;AAFpC,4BAEoC"}

package/dist/domain/objects/Template.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/domain/objects/Template.test.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const test_fns_1 = require("test-fns");
+const Template_1 = require("./Template");
+describe('Template', () => {
+    const mockUri = 'templates/hello.md';
+    (0, test_fns_1.given)('a Template that uses input variables to render', () => {
+        const template = new Template_1.Template({
+            ref: { uri: mockUri },
+            use: async ({ name }) => `Hello, ${name}!`,
+        });
+        (0, test_fns_1.when)('calling use with a variable object', () => {
+            (0, test_fns_1.then)('it returns the correctly hydrated string', async () => {
+                const result = await template.use({ name: 'Casey' });
+                expect(result).toBe('Hello, Casey!');
+            });
+        });
+    });
+    (0, test_fns_1.given)('a Template with empty variable usage', () => {
+        const template = new Template_1.Template({
+            ref: { uri: mockUri },
+            use: async () => '',
+        });
+        (0, test_fns_1.when)('calling use with an empty object', () => {
+            (0, test_fns_1.then)('it returns an empty string', async () => {
+                const result = await template.use({});
+                expect(result).toBe('');
+            });
+        });
+    });
+    it('should error if required variable is missing', async () => {
+        const template = new Template_1.Template({
+            ref: { uri: mockUri },
+            use: async ({ name }) => `Hi ${name}`,
+        });
+        // @ts-expect-error - missing required field `name`
+        await template.use({});
+    });
+    it('should error if variable shape is incompatible', () => {
+        const template = new Template_1.Template({
+            ref: { uri: mockUri },
+            // @ts-expect-error - attempting to access a nonexistent property on age
+            use: async ({ age }) => `Age: ${age.name}`,
+        });
+        expect(template);
+    });
+});
+//# sourceMappingURL=Template.test.js.map

package/dist/domain/objects/Template.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Template.test.js","sourceRoot":"","sources":["../../../src/domain/objects/Template.test.ts"],"names":[],"mappings":";;AAAA,uCAA6C;AAG7C,yCAAsC;AAEtC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,MAAM,OAAO,GAAG,oBAAoB,CAAC;IAErC,IAAA,gBAAK,EAAC,gDAAgD,EAAE,GAAG,EAAE;QAC3D,MAAM,QAAQ,GAAG,IAAI,mBAAQ,CAAmB;YAC9C,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE;YACrB,GAAG,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,UAAU,IAAI,GAAG;SAC3C,CAAC,CAAC;QAEH,IAAA,eAAI,EAAC,oCAAoC,EAAE,GAAG,EAAE;YAC9C,IAAA,eAAI,EAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;gBAC1D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;gBACrD,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YACvC,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,IAAA,gBAAK,EAAC,sCAAsC,EAAE,GAAG,EAAE;QACjD,MAAM,QAAQ,GAAG,IAAI,mBAAQ,CAAQ;YACnC,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE;YACrB,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE;SACpB,CAAC,CAAC;QAEH,IAAA,eAAI,EAAC,kCAAkC,EAAE,GAAG,EAAE;YAC5C,IAAA,eAAI,EAAC,4BAA4B,EAAE,KAAK,IAAI,EAAE;gBAC5C,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACtC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC1B,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;QAC5D,MAAM,QAAQ,GAAG,IAAI,mBAAQ,CAAmB;YAC9C,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE;YACrB,GAAG,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,MAAM,IAAI,EAAE;SACtC,CAAC,CAAC;QAEH,mDAAmD;QACnD,MAAM,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,QAAQ,GAAG,IAAI,mBAAQ,CAAkB;YAC7C,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE;YACrB,wEAAwE;YACxE,GAAG,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,QAAQ,GAAG,CAAC,IAAI,EAAE;SAC3C,CAAC,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/domain/objects/index.d.ts

@@ -9,3 +9,10 @@ export * from './StitchStep';
 export * from './StitchTrail';
 export * from './Thread';
 export * from './Threads';
+export * from './Role';
+export * from './RoleContext';
+export * from './RoleRegistry';
+export * from './RoleSkill';
+export * from './RoleSkillArgGetter';
+export * from './RoleTrait';
+export * from './Template';

package/dist/domain/objects/index.js

@@ -27,4 +27,11 @@ __exportStar(require("./Thread"), exports);
 __exportStar(require("./Threads"), exports);
 // export * from './Weave';
 // export * from './Weaver';
+__exportStar(require("./Role"), exports);
+__exportStar(require("./RoleContext"), exports);
+__exportStar(require("./RoleRegistry"), exports);
+__exportStar(require("./RoleSkill"), exports);
+__exportStar(require("./RoleSkillArgGetter"), exports);
+__exportStar(require("./RoleTrait"), exports);
+__exportStar(require("./Template"), exports);
 //# sourceMappingURL=index.js.map