@helmiq/crew 0.1.0

package/dist/publication/publication.test.js

@@ -0,0 +1,235 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtemp, readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+import { parse as yamlParse } from 'yaml';
+import { addFrontmatter, parseFrontmatter } from './frontmatter.js';
+import { writeProvenance, writeManifest } from './provenance-writer.js';
+import { scanForSecrets } from './secret-scanner.js';
+import { SecretDetectedError } from '../common/errors.js';
+import { publish } from './publisher.js';
+function makeProvenance() {
+    return {
+        run_id: 'run-test-001',
+        persona: 'engineer',
+        task: 'implement-story',
+        versions: {
+            persona_spec_hash: 'sha256:abc',
+            prompt_hashes: { planner: 'sha256:def' },
+            model: 'claude-sonnet-4',
+            rubric_hash: 'sha256:ghi',
+            runtime_version: '0.0.0',
+        },
+        timestamp: new Date().toISOString(),
+        duration_ms: 5000,
+        trigger: 'manual',
+        inputs: {
+            artifacts_read: [{ type: 'requirements', path: 'work/TEST-01/requirements.md' }],
+            context_tokens: 1000,
+        },
+        outputs: { artifact_produced: { type: 'review', id: 'review-001' } },
+        evaluation: { self_eval_score: 8.5, self_eval_pass: true },
+        cost: { llm_calls: 3, total_tokens: 5000, estimated_cost_usd: 0.05 },
+        run_state: 'published',
+    };
+}
+function makeRunRecord() {
+    return {
+        run_id: 'run-test-001',
+        persona: 'engineer',
+        task: 'implement-story',
+        scope: 'TEST-01-001',
+        status: 'publishing',
+        started_at: new Date().toISOString(),
+    };
+}
+describe('T-01-006a: markdown artifact with frontmatter', () => {
+    it('adds YAML frontmatter to content', () => {
+        const result = addFrontmatter('# My Artifact\n\nContent here.', {
+            author: 'engineer',
+            run_id: 'run-test-001',
+            status: 'published',
+            timestamp: '2026-03-22T09:00:00Z',
+            eval_score: 8.5,
+            eval_pass: true,
+        });
+        expect(result).toContain('---');
+        expect(result).toContain('author: engineer');
+        expect(result).toContain('run_id: run-test-001');
+        expect(result).toContain('status: published');
+        expect(result).toContain('eval_score: 8.5');
+        expect(result).toContain('# My Artifact');
+    });
+    it('roundtrips through parse', () => {
+        const original = addFrontmatter('Body content', {
+            author: 'reviewer',
+            run_id: 'run-002',
+            status: 'awaiting_review',
+            timestamp: '2026-03-22T10:00:00Z',
+        });
+        const { content, data } = parseFrontmatter(original);
+        expect(content.trim()).toBe('Body content');
+        expect(data['author']).toBe('reviewer');
+        expect(data['status']).toBe('awaiting_review');
+    });
+});
+describe('T-01-006c: provenance record completeness', () => {
+    let runDir;
+    beforeEach(async () => {
+        runDir = await mkdtemp(join(tmpdir(), 'crew-prov-test-'));
+    });
+    it('writes provenance.yaml with all required fields', async () => {
+        const provenance = makeProvenance();
+        const path = await writeProvenance(runDir, provenance);
+        const raw = await readFile(path, 'utf-8');
+        const parsed = yamlParse(raw);
+        expect(parsed['run_id']).toBe('run-test-001');
+        expect(parsed['persona']).toBe('engineer');
+        expect(parsed['task']).toBe('implement-story');
+        expect(parsed['versions']).toBeDefined();
+        expect(parsed['inputs']).toBeDefined();
+        expect(parsed['outputs']).toBeDefined();
+        expect(parsed['evaluation']).toBeDefined();
+        expect(parsed['cost']).toBeDefined();
+        expect(parsed['run_state']).toBe('published');
+    });
+});
+describe('T-01-006d: run manifest cross-repo linkage', () => {
+    let runDir;
+    beforeEach(async () => {
+        runDir = await mkdtemp(join(tmpdir(), 'crew-manifest-test-'));
+    });
+    it('writes manifest.yaml linking workspace and target repos', async () => {
+        const path = await writeManifest(runDir, {
+            run_id: 'run-test-001',
+            artifacts_repo: {
+                commit_sha: 'abc123',
+                artifacts_referenced: [
+                    { type: 'requirements', path: 'work/TEST-01/requirements.md', status: 'approved' },
+                ],
+            },
+            target_repo: {
+                branch: 'feat/TEST-01-001-implement',
+                commit_sha: 'def456',
+            },
+            story_id: 'TEST-01-001',
+        });
+        const raw = await readFile(path, 'utf-8');
+        const parsed = yamlParse(raw);
+        expect(parsed.manifest['run_id']).toBe('run-test-001');
+        expect(parsed.manifest['artifacts_repo']).toBeDefined();
+        expect(parsed.manifest['target_repo']).toBeDefined();
+        expect(parsed.manifest['story_id']).toBe('TEST-01-001');
+    });
+});
+describe('T-01-006e: rollback on publication failure', () => {
+    it('blocks publication when secrets are detected', () => {
+        expect(() => scanForSecrets('API key: sk-ant-abc123456789012345678901234567890', 'test.md')).toThrow(SecretDetectedError);
+    });
+    it('does not throw for clean content', () => {
+        expect(() => scanForSecrets('# Normal artifact\n\nNo secrets here.', 'test.md')).not.toThrow();
+    });
+    it('blocks publish when artifact contains secrets', async () => {
+        const tmpBase = await mkdtemp(join(tmpdir(), 'crew-secret-test-'));
+        const ws = join(tmpBase, 'ws');
+        await mkdir(ws, { recursive: true });
+        await expect(publish({
+            artifact: 'secret: sk-ant-abc123456789012345678901234567890',
+            artifactPath: 'bad.md',
+            metadata: {
+                author: 'engineer',
+                run_id: 'run-test-001',
+                status: 'published',
+                timestamp: new Date().toISOString(),
+            },
+            provenance: makeProvenance(),
+            config: {
+                project: { name: 'T', key: 'T' },
+                workspace: { path: ws, work: 'work/', runs: 'runs/' },
+                source: { repo: 'github:test/repo', path: ws },
+                llm: {
+                    default_model: 'x',
+                    providers: { a: { api_key_env: 'X', models: { x: 'x' } } },
+                },
+            },
+            runRecord: makeRunRecord(),
+            runDir: join(tmpBase, 'run'),
+            push: false,
+        })).rejects.toThrow(SecretDetectedError);
+    });
+});
+describe('T-01-006b: code artifact on branch (git integration)', () => {
+    let tmpBase;
+    let workspacePath;
+    let runDir;
+    function canRunGit() {
+        try {
+            execSync('git --version', { stdio: 'ignore' });
+            const testDir = join(tmpdir(), `crew-git-check-${Date.now()}`);
+            execSync(`mkdir -p ${testDir} && cd ${testDir} && git init`, { stdio: 'ignore' });
+            execSync(`rm -rf ${testDir}`, { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    beforeEach(async () => {
+        tmpBase = await mkdtemp(join(tmpdir(), 'crew-git-pub-'));
+        workspacePath = join(tmpBase, 'workspace');
+        runDir = join(tmpBase, 'runs', 'run-test-001');
+        await mkdir(workspacePath, { recursive: true });
+        await mkdir(runDir, { recursive: true });
+        if (canRunGit()) {
+            execSync('git init', { cwd: workspacePath, stdio: 'ignore' });
+            execSync('git config user.email "test@test.com"', { cwd: workspacePath, stdio: 'ignore' });
+            execSync('git config user.name "Test"', { cwd: workspacePath, stdio: 'ignore' });
+            execSync('git commit --allow-empty -m "init"', { cwd: workspacePath, stdio: 'ignore' });
+        }
+    });
+    it('publishes a workspace artifact and commits', async () => {
+        if (!canRunGit())
+            return;
+        const artifactDir = join(workspacePath, 'work', 'TEST-01');
+        await mkdir(artifactDir, { recursive: true });
+        const config = {
+            project: {
+                name: 'Test',
+                key: 'TEST',
+            },
+            workspace: { path: workspacePath, work: 'work/', runs: 'runs/' },
+            source: { repo: 'github:test/repo', path: workspacePath },
+            llm: {
+                default_model: 'claude-sonnet',
+                providers: {
+                    anthropic: {
+                        api_key_env: 'ANTHROPIC_API_KEY',
+                        models: { 'claude-sonnet': 'claude-sonnet-4' },
+                    },
+                },
+            },
+        };
+        const result = await publish({
+            artifact: '# Review\n\nLooks good.',
+            artifactPath: 'work/TEST-01/review.md',
+            metadata: {
+                author: 'engineer',
+                run_id: 'run-test-001',
+                status: 'published',
+                timestamp: new Date().toISOString(),
+            },
+            provenance: makeProvenance(),
+            config,
+            runRecord: makeRunRecord(),
+            runDir,
+            push: false,
+        });
+        expect(result.artifactPath).toContain('review.md');
+        expect(result.commitSha).toBeTruthy();
+        expect(result.provenancePath).toContain('provenance.yaml');
+        const written = await readFile(result.artifactPath, 'utf-8');
+        expect(written).toContain('author: engineer');
+        expect(written).toContain('# Review');
+    });
+});

package/dist/publication/publisher.d.ts

@@ -0,0 +1,32 @@
+import type { Provenance, ProjectConfig, RunRecord } from '../types/index.js';
+import type { ArtifactMetadata } from './frontmatter.js';
+export interface PublicationOptions {
+    artifact: string;
+    artifactPath: string;
+    metadata: ArtifactMetadata;
+    provenance: Provenance;
+    config: ProjectConfig;
+    runRecord: RunRecord;
+    runDir: string;
+    push?: boolean;
+    targetRepoBranch?: string;
+    targetRepoFiles?: {
+        path: string;
+        content: string;
+    }[];
+}
+export interface PublicationResult {
+    artifactPath: string;
+    commitSha: string;
+    provenancePath: string;
+    manifestPath?: string;
+}
+/**
+ * Publish an artifact to the workspace repo (and optionally code to the target repo),
+ * record provenance, and produce a cross-repo manifest.
+ *
+ * Follows the ordered publication sequence with compensating rollback
+ * for local, unpushed state per ADR-0007.
+ */
+export declare function publish(options: PublicationOptions): Promise<PublicationResult>;
+//# sourceMappingURL=publisher.d.ts.map

package/dist/publication/publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.d.ts","sourceRoot":"","sources":["../../src/publication/publisher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACvD;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuIrF"}

package/dist/publication/publisher.js

@@ -0,0 +1,113 @@
+import { writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { PublicationError } from '../common/errors.js';
+import { addFrontmatter } from './frontmatter.js';
+import { commitAndPush, resetLastCommit, createBranch } from './git-ops.js';
+import { writeProvenance, writeManifest } from './provenance-writer.js';
+import { scanForSecrets } from './secret-scanner.js';
+/**
+ * Publish an artifact to the workspace repo (and optionally code to the target repo),
+ * record provenance, and produce a cross-repo manifest.
+ *
+ * Follows the ordered publication sequence with compensating rollback
+ * for local, unpushed state per ADR-0007.
+ */
+export async function publish(options) {
+    const { artifact, artifactPath, metadata, provenance, config, runRecord, runDir, push = false, targetRepoBranch, targetRepoFiles, } = options;
+    const workspacePath = config.workspace.path;
+    const compensations = [];
+    scanForSecrets(artifact, artifactPath);
+    const fullArtifactPath = join(workspacePath, artifactPath);
+    try {
+        // Step 1: Write artifact with frontmatter
+        const artifactWithFrontmatter = addFrontmatter(artifact, metadata);
+        const dir = join(fullArtifactPath, '..');
+        await mkdir(dir, { recursive: true });
+        await writeFile(fullArtifactPath, artifactWithFrontmatter, 'utf-8');
+        compensations.push(async () => {
+            try {
+                await unlink(fullArtifactPath);
+            }
+            catch {
+                /* best-effort */
+            }
+        });
+        // Step 2: Commit to workspace repo
+        const relPath = relative(workspacePath, fullArtifactPath);
+        const workspaceCommitSha = await commitAndPush(workspacePath, [relPath], `publish: ${runRecord.persona}/${runRecord.task} [${runRecord.run_id}]`, false);
+        compensations.push(async () => {
+            await resetLastCommit(workspacePath);
+        });
+        // Step 3: Push workspace repo (if enabled)
+        if (push) {
+            await commitAndPush(workspacePath, [], '', true);
+            // After push: no automatic rollback for remote state
+        }
+        // Step 4-5: Target repo operations (code artifacts)
+        let targetCommitSha;
+        if (targetRepoBranch && targetRepoFiles && targetRepoFiles.length > 0) {
+            const targetPath = config.source.path;
+            for (const file of targetRepoFiles) {
+                scanForSecrets(file.content, file.path);
+            }
+            await createBranch(targetPath, targetRepoBranch);
+            for (const file of targetRepoFiles) {
+                const fullPath = join(targetPath, file.path);
+                const fileDir = join(fullPath, '..');
+                await mkdir(fileDir, { recursive: true });
+                await writeFile(fullPath, file.content, 'utf-8');
+            }
+            const filePaths = targetRepoFiles.map((f) => f.path);
+            targetCommitSha = await commitAndPush(targetPath, filePaths, `feat: ${runRecord.task} [${runRecord.run_id}]`, false);
+            compensations.push(async () => {
+                await resetLastCommit(targetPath);
+            });
+            if (push) {
+                await commitAndPush(targetPath, [], '', true, targetRepoBranch);
+            }
+        }
+        // Step 6: Write provenance
+        const provenancePath = await writeProvenance(runDir, provenance);
+        // Step 7: Write manifest (cross-repo linkage)
+        let manifestPath;
+        if (targetCommitSha) {
+            const manifestData = {
+                run_id: runRecord.run_id,
+                artifacts_repo: {
+                    commit_sha: workspaceCommitSha,
+                    artifacts_referenced: provenance.inputs.artifacts_read.map((a) => ({
+                        type: a.type,
+                        path: a.path,
+                        status: a.status ?? 'unknown',
+                    })),
+                },
+                target_repo: {
+                    branch: targetRepoBranch,
+                    commit_sha: targetCommitSha,
+                },
+                story_id: runRecord.scope,
+            };
+            manifestPath = await writeManifest(runDir, manifestData);
+        }
+        return {
+            artifactPath: fullArtifactPath,
+            commitSha: workspaceCommitSha,
+            provenancePath,
+            manifestPath,
+        };
+    }
+    catch (err) {
+        // Execute compensations in reverse order
+        for (let i = compensations.length - 1; i >= 0; i--) {
+            try {
+                await compensations[i]();
+            }
+            catch {
+                /* compensation best-effort */
+            }
+        }
+        if (err instanceof PublicationError)
+            throw err;
+        throw new PublicationError(`Publication failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err, runId: runRecord.run_id, stage: 'publish' });
+    }
+}

package/dist/publication/secret-scanner.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Scan content for patterns that look like secrets.
+ * Throws SecretDetectedError if any match is found.
+ */
+export declare function scanForSecrets(content: string, context: string): void;
+//# sourceMappingURL=secret-scanner.d.ts.map

package/dist/publication/secret-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-scanner.d.ts","sourceRoot":"","sources":["../../src/publication/secret-scanner.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQrE"}

package/dist/publication/secret-scanner.js

@@ -0,0 +1,19 @@
+import { SecretDetectedError } from '../common/errors.js';
+const SECRET_PATTERNS = [
+    /(?:sk-|sk_)[a-zA-Z0-9_-]{20,}/,
+    /(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{30,}/,
+    /(?:AKIA|ABIA|ACCA|ASIA)[A-Z0-9]{16}/,
+    /-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----/,
+    /(?:bearer|token|api[_-]?key|secret|password)\s*[:=]\s*['"]?[A-Za-z0-9_/+=-]{20,}/i,
+];
+/**
+ * Scan content for patterns that look like secrets.
+ * Throws SecretDetectedError if any match is found.
+ */
+export function scanForSecrets(content, context) {
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.test(content)) {
+            throw new SecretDetectedError(`Potential secret detected in ${context}. Publication blocked. Pattern: ${pattern.source.slice(0, 30)}...`);
+        }
+    }
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { createToolRegistry } from './registry.js';
+export type { ToolRegistryOptions } from './registry.js';
+export { TOOL_GROUPS, expandToolNames } from './tool-groups.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,2 @@
+export { createToolRegistry } from './registry.js';
+export { TOOL_GROUPS, expandToolNames } from './tool-groups.js';

package/dist/tools/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CrewTool registry -- maps logical tool names used in persona specs
+ * to executable CrewTool implementations backed by the tool packages.
+ *
+ * Each tool's `execute` function adapts the tool package's API,
+ * injecting ToolExecutionContext values (repo paths, protected paths, etc.)
+ * so the LLM only needs to provide the operation-specific parameters.
+ */
+import type { CrewToolSet } from '../types/tool-runtime.js';
+import type { ArtifactStore } from '../types/artifact-store.js';
+export interface ToolRegistryOptions {
+    artifactStore?: ArtifactStore;
+}
+export declare function createToolRegistry(options?: ToolRegistryOptions): CrewToolSet;
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,WAAW,CA0T7E"}