@helmiq/crew 0.1.0

package/dist/config/schemas.js

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+export const ProviderSchema = z.object({
+    api_key_env: z.string().min(1),
+    models: z.record(z.string(), z.string()),
+});
+export const LlmConfigSchema = z
+    .object({
+    default_model: z.string().min(1),
+    allowed_models: z.array(z.string()).optional(),
+    providers: z.record(z.string(), ProviderSchema),
+})
+    .refine((data) => {
+    const allAliases = Object.values(data.providers).flatMap((p) => Object.keys(p.models));
+    return allAliases.includes(data.default_model);
+}, { message: 'default_model must be an alias present in a provider models map' });
+export const SourceConfigSchema = z.object({
+    repo: z.string().min(1),
+    path: z.string().min(1),
+});
+export const WorkspaceConfigSchema = z.object({
+    path: z.string().min(1),
+    work: z.string().min(1),
+    runs: z.string().min(1),
+});
+export const ProjectConfigSchema = z.object({
+    project: z.object({
+        name: z.string().min(1),
+        key: z.string().min(1),
+    }),
+    workspace: WorkspaceConfigSchema,
+    source: SourceConfigSchema,
+    llm: LlmConfigSchema,
+});
+export const ContextRefSchema = z.object({
+    artifact: z.string().min(1),
+    scope: z.record(z.string(), z.string()).optional(),
+    sections: z.array(z.string()).optional(),
+    when: z.string().optional(),
+});
+export const SubAgentSchema = z.object({
+    name: z.string().min(1),
+    skill: z.string().min(1),
+    reads: z.array(z.string()),
+    produces: z.string().min(1),
+    tools: z.array(z.string()).optional(),
+    max_iterations: z.number().int().positive().optional(),
+    gate: z.string().optional(),
+    on_fail: z.string().optional(),
+    max_loops: z.number().int().positive().optional(),
+});
+const TriggerTypeSchema = z.enum(['manual', 'scheduled', 'event']);
+const QualityGateTypeSchema = z.enum(['self-eval', 'human-review', 'multi-model']);
+export const SimpleTaskSchema = z.object({
+    mode: z.literal('simple'),
+    trigger: z.array(TriggerTypeSchema),
+    skill: z.string().min(1),
+    reads: z.array(z.string()).optional(),
+    produces: z.string().min(1),
+    tools: z.array(z.string()).optional(),
+    published_artifact: z.string().optional(),
+    quality_gate: QualityGateTypeSchema.optional(),
+});
+export const CompositeTaskSchema = z.object({
+    mode: z.literal('composite'),
+    trigger: z.array(TriggerTypeSchema),
+    sub_agents: z.array(SubAgentSchema).min(1),
+    published_artifact: z.string().min(1),
+    quality_gate: QualityGateTypeSchema.optional(),
+});
+export const TaskSchema = z.discriminatedUnion('mode', [SimpleTaskSchema, CompositeTaskSchema]);
+export const PersonaSpecSchema = z.object({
+    persona: z.object({
+        name: z.string().min(1),
+        identity: z.object({
+            role: z.string().min(1),
+        }),
+        skills: z.array(z.string().min(1)).min(1),
+        perception: z.object({
+            always_read: z.array(ContextRefSchema).optional(),
+            per_task: z.record(z.string(), z.array(ContextRefSchema)),
+        }),
+        tasks: z.record(z.string(), TaskSchema),
+        tools: z.object({
+            permitted: z.array(z.string()),
+            denied: z.array(z.string()),
+            writable_paths: z.array(z.string()).optional(),
+        }),
+        cadence: z.object({
+            scheduled: z.array(z.object({ cron: z.string().min(1), task: z.string().min(1) })).optional(),
+            event: z.array(z.object({ on: z.string().min(1), task: z.string().min(1) })).optional(),
+        }),
+        evaluation: z.object({
+            self_eval_model: z.string().optional(),
+            rubric: z.string().min(1),
+            multi_model: z.boolean().optional(),
+        }),
+    }),
+});
+export const CriterionWeightSchema = z.enum(['blocking', 'important', 'advisory']);
+export const CriterionSchema = z.object({
+    name: z.string().min(1),
+    weight: CriterionWeightSchema,
+    description: z.string().optional(),
+});
+export const EvaluationRubricSchema = z.object({
+    rubric: z.object({
+        artifact_type: z.string().min(1),
+        scoring_scale: z.number().positive().optional(),
+        pass_threshold: z.number(),
+        aggregate_threshold: z.number().optional(),
+        divergence_threshold: z.number().optional(),
+        models: z.array(z.string()).optional(),
+        criteria: z.array(CriterionSchema).min(1),
+    }),
+});

package/dist/context/artifact-reader.d.ts

@@ -0,0 +1,12 @@
+import type { ContextRef, ProjectConfig } from '../types/index.js';
+export interface ArtifactReadResult {
+    content: string | null;
+    path: string;
+    found: boolean;
+}
+/**
+ * Read a single artifact from the filesystem based on its ContextRef and project config.
+ * Returns null content (with found=false) if the file does not exist.
+ */
+export declare function readArtifact(ref: ContextRef, config: ProjectConfig, workspacePath: string): Promise<ArtifactReadResult>;
+//# sourceMappingURL=artifact-reader.d.ts.map

package/dist/context/artifact-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-reader.d.ts","sourceRoot":"","sources":["../../src/context/artifact-reader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAsFnE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAY7B"}

package/dist/context/artifact-reader.js

@@ -0,0 +1,92 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Map an artifact type + scope to a filesystem path within the workspace repo.
+ *
+ * Uses the project config's artifact paths to resolve the location.
+ * Template variables in the path pattern (e.g., `{EPIC_ID}`) are interpolated
+ * from the scope record on the ContextRef.
+ */
+function resolveArtifactPath(ref, config, workspacePath) {
+    const artifactType = ref.artifact;
+    const scope = ref.scope ?? {};
+    let basePath;
+    let appendFilename = false;
+    switch (artifactType) {
+        case 'requirements':
+        case 'design':
+        case 'review':
+            basePath = config.workspace.work;
+            appendFilename = true;
+            break;
+        case 'standards':
+            basePath = 'architecture/';
+            break;
+        case 'architecture':
+            basePath = 'architecture/';
+            break;
+        case 'adr-register':
+            return join(workspacePath, 'architecture', 'decisions', 'register.md');
+        case 'adr':
+        case 'decision':
+            basePath = 'architecture/decisions/';
+            break;
+        case 'product':
+        case 'backlog':
+            basePath = 'product/';
+            break;
+        default:
+            basePath = config.workspace.work;
+            break;
+    }
+    let resolvedPath = interpolatePath(basePath, scope);
+    if (appendFilename) {
+        resolvedPath = join(resolvedPath, `${artifactType}.md`);
+    }
+    // For directory-style artifact types (standards, product), look for the
+    // scope "type" value as a filename hint, or fall back to a conventional name.
+    if (!appendFilename && ref.scope?.['type']) {
+        resolvedPath = join(resolvedPath, `${ref.scope['type']}.md`);
+    }
+    return join(workspacePath, resolvedPath);
+}
+/**
+ * Replace `{PLACEHOLDER}` patterns in a path template using scope values.
+ *
+ * Matching strategy for each `{VAR}` placeholder:
+ * 1. Exact match against a scope key (case-insensitive)
+ * 2. Match by stripping common suffixes (_ID, _PATH) from the placeholder
+ */
+function interpolatePath(template, scope) {
+    return template.replace(/\{([^}]+)\}/g, (_match, varName) => {
+        const upper = varName.toUpperCase();
+        for (const [key, value] of Object.entries(scope)) {
+            if (key.toUpperCase() === upper)
+                return value;
+        }
+        const stripped = upper.replace(/_(ID|PATH)$/, '');
+        for (const [key, value] of Object.entries(scope)) {
+            if (key.toUpperCase() === stripped)
+                return value;
+        }
+        return `{${varName}}`;
+    });
+}
+/**
+ * Read a single artifact from the filesystem based on its ContextRef and project config.
+ * Returns null content (with found=false) if the file does not exist.
+ */
+export async function readArtifact(ref, config, workspacePath) {
+    const filePath = resolveArtifactPath(ref, config, workspacePath);
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return { content, path: filePath, found: true };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'EISDIR') {
+            return { content: null, path: filePath, found: false };
+        }
+        throw err;
+    }
+}

package/dist/context/assembler.d.ts

@@ -0,0 +1,22 @@
+import type { Perception, ProjectConfig, ArtifactReference } from '../types/index.js';
+export interface ContextBlock {
+    source: ArtifactReference;
+    content: string;
+    tokens: number;
+    priority: 'required' | 'conditional';
+}
+export interface AssembledContext {
+    blocks: ContextBlock[];
+    totalTokens: number;
+    budgetLimit: number;
+    gaps: string[];
+}
+/**
+ * Assemble context for a persona task run.
+ *
+ * Gathers artifacts from the persona's perception (always_read + per_task),
+ * interpolates template variables, extracts named sections, enforces a token
+ * budget, and returns a structured result ready for the LLM call.
+ */
+export declare function assembleContext(perception: Perception, taskName: string, scopeVars: Record<string, string>, config: ProjectConfig, workspacePath: string, budgetTokens?: number): Promise<AssembledContext>;
+//# sourceMappingURL=assembler.d.ts.map

package/dist/context/assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembler.d.ts","sourceRoot":"","sources":["../../src/context/assembler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAc,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAMlG,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,GAAG,aAAa,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAoBD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,MAAM,EACrB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,gBAAgB,CAAC,CA0F3B"}

package/dist/context/assembler.js

@@ -0,0 +1,126 @@
+import { readArtifact } from './artifact-reader.js';
+import { readCodeFiles } from './code-reader.js';
+import { extractSections } from './section-extractor.js';
+import { countTokens, defaultTokenBudget } from './token-budget.js';
+/**
+ * Interpolate `{{ .VAR }}` template variables in a ContextRef's scope values.
+ */
+function interpolateRef(ref, scopeVars) {
+    if (!ref.scope)
+        return ref;
+    const interpolated = {};
+    for (const [key, value] of Object.entries(ref.scope)) {
+        let resolved = value;
+        for (const [varName, varValue] of Object.entries(scopeVars)) {
+            resolved = resolved.replace(`{{ .${varName} }}`, varValue);
+        }
+        interpolated[key] = resolved;
+    }
+    return { ...ref, scope: interpolated };
+}
+/**
+ * Assemble context for a persona task run.
+ *
+ * Gathers artifacts from the persona's perception (always_read + per_task),
+ * interpolates template variables, extracts named sections, enforces a token
+ * budget, and returns a structured result ready for the LLM call.
+ */
+export async function assembleContext(perception, taskName, scopeVars, config, workspacePath, budgetTokens) {
+    const budget = budgetTokens ?? defaultTokenBudget();
+    const taskRefs = perception.per_task[taskName] ?? [];
+    const allRefs = [...(perception.always_read ?? []), ...taskRefs];
+    const interpolatedRefs = allRefs.map((ref) => interpolateRef(ref, scopeVars));
+    const requiredRefs = interpolatedRefs.filter((r) => !r.when);
+    const conditionalRefs = interpolatedRefs.filter((r) => !!r.when);
+    const blocks = [];
+    const gaps = [];
+    let usedTokens = 0;
+    // --- Process required refs ---
+    for (const ref of requiredRefs) {
+        if (ref.artifact === 'codebase') {
+            const codeBlocks = await readCodeContext(ref, config, workspacePath);
+            for (const block of codeBlocks) {
+                usedTokens += block.tokens;
+                blocks.push(block);
+            }
+            continue;
+        }
+        const result = await readArtifact(ref, config, workspacePath);
+        if (!result.found || result.content === null) {
+            gaps.push(`${ref.artifact}${ref.scope ? ` (scope: ${JSON.stringify(ref.scope)})` : ''}`);
+            continue;
+        }
+        let content = result.content;
+        if (ref.sections && ref.sections.length > 0) {
+            content = extractSections(content, ref.sections);
+        }
+        const tokens = countTokens(content);
+        usedTokens += tokens;
+        blocks.push({
+            source: {
+                type: ref.artifact,
+                path: result.path,
+                sections: ref.sections,
+            },
+            content,
+            tokens,
+            priority: 'required',
+        });
+    }
+    // --- Process conditional refs (budget-aware) ---
+    for (const ref of conditionalRefs) {
+        if (usedTokens >= budget)
+            break;
+        const result = await readArtifact(ref, config, workspacePath);
+        if (!result.found || result.content === null) {
+            gaps.push(`${ref.artifact}${ref.scope ? ` (scope: ${JSON.stringify(ref.scope)})` : ''} [conditional]`);
+            continue;
+        }
+        let content = result.content;
+        if (ref.sections && ref.sections.length > 0) {
+            content = extractSections(content, ref.sections);
+        }
+        const tokens = countTokens(content);
+        if (usedTokens + tokens > budget)
+            break;
+        usedTokens += tokens;
+        blocks.push({
+            source: {
+                type: ref.artifact,
+                path: result.path,
+                sections: ref.sections,
+            },
+            content,
+            tokens,
+            priority: 'conditional',
+        });
+    }
+    return {
+        blocks,
+        totalTokens: usedTokens,
+        budgetLimit: budget,
+        gaps,
+    };
+}
+async function readCodeContext(ref, config, workspacePath) {
+    const targetPath = config.source.path;
+    const pathPatterns = ref.scope?.['paths']
+        ? ref.scope['paths'].split(',').map((p) => p.trim())
+        : [];
+    if (pathPatterns.length === 0)
+        return [];
+    const codeFiles = await readCodeFiles(targetPath, pathPatterns);
+    return codeFiles.map((file) => {
+        const content = `// File: ${file.relativePath}\n${file.content}`;
+        return {
+            source: {
+                type: 'codebase',
+                path: file.relativePath,
+                repo: config.source.repo,
+            },
+            content,
+            tokens: countTokens(content),
+            priority: 'required',
+        };
+    });
+}

package/dist/context/code-reader.d.ts

@@ -0,0 +1,14 @@
+export interface CodeFileResult {
+    relativePath: string;
+    content: string;
+}
+/**
+ * Read code files from the target repo matching the given path patterns.
+ *
+ * Patterns are relative paths or simple glob-like prefixes within the target repo.
+ * For Phase 1, supports:
+ * - Exact file paths (e.g., "src/index.ts")
+ * - Directory paths (e.g., "src/config/") -- reads all files in the directory recursively
+ */
+export declare function readCodeFiles(targetRepoPath: string, pathPatterns: string[]): Promise<CodeFileResult[]>;
+//# sourceMappingURL=code-reader.d.ts.map

package/dist/context/code-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-reader.d.ts","sourceRoot":"","sources":["../../src/context/code-reader.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,cAAc,EAAE,CAAC,CA4B3B"}

package/dist/context/code-reader.js

@@ -0,0 +1,56 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+/**
+ * Read code files from the target repo matching the given path patterns.
+ *
+ * Patterns are relative paths or simple glob-like prefixes within the target repo.
+ * For Phase 1, supports:
+ * - Exact file paths (e.g., "src/index.ts")
+ * - Directory paths (e.g., "src/config/") -- reads all files in the directory recursively
+ */
+export async function readCodeFiles(targetRepoPath, pathPatterns) {
+    const results = [];
+    for (const pattern of pathPatterns) {
+        const fullPath = join(targetRepoPath, pattern);
+        try {
+            const fileStat = await stat(fullPath);
+            if (fileStat.isFile()) {
+                const content = await readFile(fullPath, 'utf-8');
+                results.push({ relativePath: pattern, content });
+            }
+            else if (fileStat.isDirectory()) {
+                const files = await collectFiles(fullPath);
+                for (const absPath of files) {
+                    const content = await readFile(absPath, 'utf-8');
+                    results.push({
+                        relativePath: relative(targetRepoPath, absPath),
+                        content,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ENOENT')
+                continue;
+            throw err;
+        }
+    }
+    return results;
+}
+async function collectFiles(dirPath) {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = join(dirPath, entry.name);
+        if (entry.name.startsWith('.') || entry.name === 'node_modules')
+            continue;
+        if (entry.isFile()) {
+            files.push(fullPath);
+        }
+        else if (entry.isDirectory()) {
+            files.push(...(await collectFiles(fullPath)));
+        }
+    }
+    return files;
+}

package/dist/context/context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.test.d.ts.map

package/dist/context/context.test.d.ts.map

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