@syntesseraai/opencode-feature-factory 0.4.3 → 0.4.5

package/agents/building.md

@@ -72,9 +72,29 @@ At the start of EVERY building task:
 9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/building-{UUID}.md`
 10. **Check for existing plans** - Use `ff-plans-list` and `ff-plans-get` to find implementation plans
 
-## Git Worktrees (Mandatory)
+## Git Workflow
 
-To prevent conflicts and ensure a clean state, you MUST use git worktrees for your implementation:
+Choose the appropriate git workflow based on the repository's working agreements. Check `AGENTS.md` (or equivalent) in the repository root for explicit guidance.
+
+### How to Detect the Development Model
+
+1. Check for `AGENTS.md` in the repository root for explicit working agreements
+2. Look for keywords: "trunk-based", "mainline", "direct to main" → use **Trunk-Based**
+3. Look for keywords: "pull request", "feature branch", "branch protection" → use **Branch-Based**
+4. **Default:** If no guidance is found, use **trunk-based development** (simpler, less overhead)
+
+### Trunk-Based Development (Direct to Main)
+
+If the repository specifies **trunk-based / mainline development** (e.g., "commit directly to the main branch, do not create branches or PRs"):
+
+1. **Work in the existing checkout** — Do NOT create worktrees or feature branches
+2. **Commit directly to `main`** — Make atomic, well-described commits
+3. **Run quality checks before committing** — Ensure lint, typecheck, and tests pass
+4. **Keep commits small and focused** — Each commit should be a logical unit of work
+
+### Branch-Based Development (Worktrees)
+
+If the repository uses **branch-based / PR workflows**, use git worktrees to prevent conflicts and ensure a clean state:
 
 1. **Create Worktree:** Before starting code modifications, create a dedicated worktree in a writable root (avoid `../` paths that may resolve outside CI workspace mounts):
    ```bash
@@ -434,6 +454,7 @@ Use ff-severity-classification when making changes:
 
 ## Important Notes
 
+- **GitHub Interactions** - ALWAYS prefer using the `gh` CLI tool via bash for interacting with GitHub (e.g., `gh pr create`, `gh issue view`, etc.) rather than making direct `curl` requests or calling the REST API. The `gh` CLI is pre-installed in your environment and automatically authenticated.
 - **You can make code changes** - This is the only agent that can edit files
 - **Always create todos** - Track progress visibly for the user
 - **Validate frequently** - Don't wait until the end to check quality

package/package.json

@@ -1,14 +1,14 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "ff-deploy": "./bin/ff-deploy.js"
+    "ff-deploy": "bin/ff-deploy.js"
   },
   "files": [
     "dist",

package/dist/discovery.test.d.ts

@@ -1,10 +0,0 @@
-/**
- * Unit tests for discovery module
- *
- * Tests focus on the pure function:
- * - buildRunCommand: builds package manager-specific run commands
- *
- * Note: Most functions in discovery.ts require shell access ($) so they're
- * integration-tested elsewhere. This file tests the pure utility functions.
- */
-export {};

package/dist/discovery.test.js

@@ -1,97 +0,0 @@
-/**
- * Unit tests for discovery module
- *
- * Tests focus on the pure function:
- * - buildRunCommand: builds package manager-specific run commands
- *
- * Note: Most functions in discovery.ts require shell access ($) so they're
- * integration-tested elsewhere. This file tests the pure utility functions.
- */
-// Re-implement buildRunCommand for testing since it's not exported
-function buildRunCommand(pm, script) {
-    switch (pm) {
-        case 'pnpm':
-            return `pnpm -s run ${script}`;
-        case 'bun':
-            return `bun run ${script}`;
-        case 'yarn':
-            return `yarn -s ${script}`;
-        case 'npm':
-            return `npm run -s ${script}`;
-        default:
-            return `npm run -s ${script}`;
-    }
-}
-describe('buildRunCommand', () => {
-    describe('pnpm', () => {
-        it('should build correct pnpm command', () => {
-            expect(buildRunCommand('pnpm', 'lint')).toBe('pnpm -s run lint');
-        });
-        it('should build correct pnpm command for build script', () => {
-            expect(buildRunCommand('pnpm', 'build')).toBe('pnpm -s run build');
-        });
-        it('should build correct pnpm command for test script', () => {
-            expect(buildRunCommand('pnpm', 'test')).toBe('pnpm -s run test');
-        });
-        it('should handle scripts with colons', () => {
-            expect(buildRunCommand('pnpm', 'lint:ci')).toBe('pnpm -s run lint:ci');
-        });
-    });
-    describe('bun', () => {
-        it('should build correct bun command', () => {
-            expect(buildRunCommand('bun', 'lint')).toBe('bun run lint');
-        });
-        it('should build correct bun command for build script', () => {
-            expect(buildRunCommand('bun', 'build')).toBe('bun run build');
-        });
-        it('should build correct bun command for test script', () => {
-            expect(buildRunCommand('bun', 'test')).toBe('bun run test');
-        });
-    });
-    describe('yarn', () => {
-        it('should build correct yarn command', () => {
-            expect(buildRunCommand('yarn', 'lint')).toBe('yarn -s lint');
-        });
-        it('should build correct yarn command for build script', () => {
-            expect(buildRunCommand('yarn', 'build')).toBe('yarn -s build');
-        });
-        it('should build correct yarn command for test script', () => {
-            expect(buildRunCommand('yarn', 'test')).toBe('yarn -s test');
-        });
-    });
-    describe('npm', () => {
-        it('should build correct npm command', () => {
-            expect(buildRunCommand('npm', 'lint')).toBe('npm run -s lint');
-        });
-        it('should build correct npm command for build script', () => {
-            expect(buildRunCommand('npm', 'build')).toBe('npm run -s build');
-        });
-        it('should build correct npm command for test script', () => {
-            expect(buildRunCommand('npm', 'test')).toBe('npm run -s test');
-        });
-    });
-    describe('edge cases', () => {
-        it('should handle script names with hyphens', () => {
-            expect(buildRunCommand('npm', 'type-check')).toBe('npm run -s type-check');
-        });
-        it('should handle script names with underscores', () => {
-            expect(buildRunCommand('pnpm', 'lint_fix')).toBe('pnpm -s run lint_fix');
-        });
-        it('should handle long script names', () => {
-            expect(buildRunCommand('yarn', 'test:unit:coverage')).toBe('yarn -s test:unit:coverage');
-        });
-    });
-});
-/**
- * PackageManager type validation tests
- * These ensure the type constraints are working correctly
- */
-describe('PackageManager type', () => {
-    it('should accept valid package manager values', () => {
-        const validManagers = ['pnpm', 'bun', 'yarn', 'npm'];
-        validManagers.forEach((pm) => {
-            expect(['pnpm', 'bun', 'yarn', 'npm']).toContain(pm);
-        });
-    });
-});
-export {};

package/dist/local-recall/daemon-controller.d.ts

@@ -1,51 +0,0 @@
-import { type ExtractionStats } from './daemon.js';
-import { OramaMemoryIndex } from './vector/orama-index.js';
-export interface DaemonRunReport {
-    fullRebuild: boolean;
-    extraction: ExtractionStats | null;
-    upserted: number;
-    removed: number;
-    documents: number;
-    durationMs: number;
-    completedAt: string;
-}
-export interface DaemonStatus {
-    running: boolean;
-    processing: boolean;
-    intervalMs: number;
-    pending: boolean;
-    pendingReason: string | null;
-    lastRun: DaemonRunReport | null;
-    lastError: string | null;
-}
-interface ControllerOptions {
-    directory: string;
-    index: OramaMemoryIndex;
-    intervalMs?: number;
-    extractionEnabled?: boolean;
-}
-export declare class LocalRecallDaemonController {
-    private readonly directory;
-    private readonly index;
-    private readonly extractionEnabled;
-    private intervalMs;
-    private timer;
-    private running;
-    private processing;
-    private pending;
-    private pendingFullRebuild;
-    private pendingReason;
-    private lastRun;
-    private lastError;
-    constructor(options: ControllerOptions);
-    start(intervalMs?: number): DaemonStatus;
-    stop(): DaemonStatus;
-    requestRun(reason?: string, fullRebuild?: boolean): void;
-    runNow(reason?: string, fullRebuild?: boolean): Promise<DaemonStatus>;
-    rebuild(): Promise<DaemonStatus>;
-    getStatus(): DaemonStatus;
-    private runLoop;
-    private runCycle;
-    private waitForIdle;
-}
-export {};

package/dist/local-recall/daemon-controller.js

@@ -1,166 +0,0 @@
-import { runExtraction } from './daemon.js';
-import { computeMemoryHash, readIndexState, writeIndexState } from './index-state.js';
-import { listAllMemories } from './memory-service.js';
-const DEFAULT_INTERVAL_MS = 15_000;
-export class LocalRecallDaemonController {
-    directory;
-    index;
-    extractionEnabled;
-    intervalMs;
-    timer = null;
-    running = false;
-    processing = false;
-    pending = false;
-    pendingFullRebuild = false;
-    pendingReason = null;
-    lastRun = null;
-    lastError = null;
-    constructor(options) {
-        this.directory = options.directory;
-        this.index = options.index;
-        this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
-        this.extractionEnabled = options.extractionEnabled ?? true;
-    }
-    start(intervalMs) {
-        if (intervalMs && intervalMs > 0) {
-            this.intervalMs = intervalMs;
-        }
-        if (this.running) {
-            return this.getStatus();
-        }
-        this.running = true;
-        this.timer = setInterval(() => {
-            this.requestRun('interval');
-        }, this.intervalMs);
-        this.requestRun('startup');
-        return this.getStatus();
-    }
-    stop() {
-        this.running = false;
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = null;
-        }
-        return this.getStatus();
-    }
-    requestRun(reason = 'manual', fullRebuild = false) {
-        this.pending = true;
-        this.pendingReason = reason;
-        if (fullRebuild) {
-            this.pendingFullRebuild = true;
-        }
-        void this.runLoop();
-    }
-    async runNow(reason = 'manual', fullRebuild = false) {
-        this.requestRun(reason, fullRebuild);
-        await this.waitForIdle();
-        return this.getStatus();
-    }
-    async rebuild() {
-        return this.runNow('rebuild', true);
-    }
-    getStatus() {
-        return {
-            running: this.running,
-            processing: this.processing,
-            intervalMs: this.intervalMs,
-            pending: this.pending,
-            pendingReason: this.pendingReason,
-            lastRun: this.lastRun,
-            lastError: this.lastError,
-        };
-    }
-    async runLoop() {
-        if (this.processing) {
-            return;
-        }
-        this.processing = true;
-        try {
-            while (this.pending) {
-                const fullRebuild = this.pendingFullRebuild;
-                this.pending = false;
-                this.pendingFullRebuild = false;
-                this.pendingReason = null;
-                await this.runCycle(fullRebuild);
-            }
-        }
-        finally {
-            this.processing = false;
-        }
-    }
-    async runCycle(fullRebuild) {
-        const startedAt = Date.now();
-        this.lastError = null;
-        try {
-            const extraction = this.extractionEnabled ? await runExtraction(this.directory) : null;
-            const allMemories = await listAllMemories(this.directory);
-            const now = Date.now();
-            let upserted = 0;
-            let removed = 0;
-            if (fullRebuild) {
-                upserted = await this.index.rebuild(allMemories);
-            }
-            else {
-                const previousState = await readIndexState(this.directory);
-                const nextEntries = {};
-                const changed = [];
-                for (const memory of allMemories) {
-                    const hash = computeMemoryHash(memory);
-                    nextEntries[memory.id] = {
-                        hash,
-                        updatedAt: now,
-                    };
-                    const previous = previousState.entries[memory.id];
-                    if (!previous || previous.hash !== hash) {
-                        changed.push(memory);
-                    }
-                }
-                const removedIDs = Object.keys(previousState.entries).filter((id) => !nextEntries[id]);
-                if (changed.length > 0) {
-                    upserted = await this.index.upsertMemories(changed);
-                }
-                if (removedIDs.length > 0) {
-                    removed = await this.index.removeMemories(removedIDs);
-                }
-            }
-            await writeIndexState(this.directory, {
-                version: 1,
-                entries: Object.fromEntries(allMemories.map((memory) => [
-                    memory.id,
-                    {
-                        hash: computeMemoryHash(memory),
-                        updatedAt: now,
-                    },
-                ])),
-                updatedAt: now,
-            });
-            const documents = this.index.getStatus().documents;
-            this.lastRun = {
-                fullRebuild,
-                extraction,
-                upserted,
-                removed,
-                documents,
-                durationMs: Date.now() - startedAt,
-                completedAt: new Date().toISOString(),
-            };
-        }
-        catch (error) {
-            this.lastError = error instanceof Error ? error.message : String(error);
-            this.lastRun = {
-                fullRebuild,
-                extraction: null,
-                upserted: 0,
-                removed: 0,
-                documents: this.index.getStatus().documents,
-                durationMs: Date.now() - startedAt,
-                completedAt: new Date().toISOString(),
-            };
-        }
-    }
-    async waitForIdle() {
-        while (this.processing || this.pending) {
-            await new Promise((resolve) => setTimeout(resolve, 25));
-        }
-    }
-}

package/dist/local-recall/daemon.d.ts

@@ -1,35 +0,0 @@
-/**
- * daemon.ts — Background extraction daemon for local-recall.
- *
- * Scans OpenCode session storage for unprocessed assistant and thinking messages,
- * runs the extraction pipeline (session + thinking extractors),
- * and stores resulting memories with logical IDs and content-hash
- * idempotency.
- *
- * Logical ID conventions:
- *   session memories → session-<sessionID>-<messageID>-<index>
- *   thinking memories → thinking-<sessionID>-<messageID>-<index>
- *
- * Idempotency is dual-layer:
- *   1. Message-ID check (fast skip for already-processed messages)
- *   2. Content-hash check (skips duplicate content across edits/replays)
- */
-export interface ExtractionStats {
-    sessionsScanned: number;
-    messagesScanned: number;
-    messagesSkipped: number;
-    newMemories: number;
-    errors: string[];
-}
-/**
- * Run a full extraction pass for the project rooted at `directory`.
- *
- * 1. Find the OpenCode project matching `directory`
- * 2. Load existing processed log for fast membership checks
- * 3. Iterate sessions → messages (assistant + thinking)
- * 4. Skip by message-ID *and* content-hash (dual idempotency)
- * 5. Run session + thinking extractors
- * 6. Assign logical IDs (session-<sid>-<msgid>-N / thinking-<sid>-<msgid>-N)
- * 7. Store new memories & update processed log
- */
-export declare function runExtraction(directory: string): Promise<ExtractionStats>;

package/dist/local-recall/daemon.js

@@ -1,262 +0,0 @@
-/**
- * daemon.ts — Background extraction daemon for local-recall.
- *
- * Scans OpenCode session storage for unprocessed assistant and thinking messages,
- * runs the extraction pipeline (session + thinking extractors),
- * and stores resulting memories with logical IDs and content-hash
- * idempotency.
- *
- * Logical ID conventions:
- *   session memories → session-<sessionID>-<messageID>-<index>
- *   thinking memories → thinking-<sessionID>-<messageID>-<index>
- *
- * Idempotency is dual-layer:
- *   1. Message-ID check (fast skip for already-processed messages)
- *   2. Content-hash check (skips duplicate content across edits/replays)
- */
-import * as fs from 'node:fs/promises';
-import { findProject, listSessions, listMessages, listParts } from './storage-reader.js';
-import { extractFromMessage } from './session-extractor.js';
-import { extractThinkingFromMessage } from './thinking-extractor.js';
-import { readProcessedLog, getProcessedMessageIDs, getProcessedHashes, markProcessed, contentHash, } from './processed-log.js';
-import { getMemoriesDir, storeMemories } from './memory-service.js';
-function getErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function toProcessedFailureEntry(failure, failureMessage) {
-    switch (failure.scope) {
-        case 'project':
-            return {
-                kind: 'failure',
-                scope: 'project',
-                processedAt: Date.now(),
-                failure: failureMessage,
-                directory: failure.directory,
-            };
-        case 'session':
-            return {
-                kind: 'failure',
-                scope: 'session',
-                processedAt: Date.now(),
-                failure: failureMessage,
-                sessionID: failure.sessionID,
-            };
-        case 'extraction':
-            return {
-                kind: 'failure',
-                scope: 'extraction',
-                processedAt: Date.now(),
-                failure: failureMessage,
-            };
-    }
-}
-function recordFailure(stats, failure) {
-    let message;
-    switch (failure.scope) {
-        case 'project':
-            message = `No OpenCode project found for directory: ${failure.directory}`;
-            break;
-        case 'message':
-            message = `Error processing message ${failure.messageID}: ${getErrorMessage(failure.error)}`;
-            break;
-        case 'session':
-            message = `Error processing session ${failure.sessionID}: ${getErrorMessage(failure.error)}`;
-            break;
-        case 'extraction':
-            message = `Extraction failed: ${getErrorMessage(failure.error)}`;
-            break;
-    }
-    stats.errors.push(message);
-    return message;
-}
-// ────────────────────────────────────────────────────────────
-// Helpers
-// ────────────────────────────────────────────────────────────
-/**
- * Build a deterministic content hash for a message based on its
- * concatenated part text.  This allows us to detect duplicate
- * processing even when message IDs change.
- */
-async function buildMessageContentHash(messageID) {
-    try {
-        const parts = await listParts(messageID);
-        const textParts = parts
-            .filter((p) => p.type === 'text' || p.type === 'reasoning' || p.type === 'thinking')
-            .map((p) => p.text ?? '')
-            .join('\n');
-        // Hash content only (no messageID) so dedupe works across ID changes
-        return contentHash(textParts);
-    }
-    catch {
-        // Fallback: hash the message ID itself (best effort)
-        return contentHash(messageID);
-    }
-}
-// ────────────────────────────────────────────────────────────
-// Main extraction loop
-// ────────────────────────────────────────────────────────────
-/**
- * Run a full extraction pass for the project rooted at `directory`.
- *
- * 1. Find the OpenCode project matching `directory`
- * 2. Load existing processed log for fast membership checks
- * 3. Iterate sessions → messages (assistant + thinking)
- * 4. Skip by message-ID *and* content-hash (dual idempotency)
- * 5. Run session + thinking extractors
- * 6. Assign logical IDs (session-<sid>-<msgid>-N / thinking-<sid>-<msgid>-N)
- * 7. Store new memories & update processed log
- */
-export async function runExtraction(directory) {
-    const stats = {
-        sessionsScanned: 0,
-        messagesScanned: 0,
-        messagesSkipped: 0,
-        newMemories: 0,
-        errors: [],
-    };
-    try {
-        // Find project for this directory
-        const project = await findProject(directory);
-        if (!project) {
-            const failure = { scope: 'project', directory };
-            const failureMessage = recordFailure(stats, failure);
-            try {
-                await markProcessed(directory, [toProcessedFailureEntry(failure, failureMessage)]);
-            }
-            catch (persistErr) {
-                stats.errors.push(`Failed to persist processing failure: ${getErrorMessage(persistErr)}`);
-            }
-            return stats;
-        }
-        // Ensure local-recall directories exist
-        await fs.mkdir(getMemoriesDir(directory), { recursive: true });
-        // Pre-load processed log for fast lookups
-        const existingLog = await readProcessedLog(directory);
-        const processedMsgIDs = getProcessedMessageIDs(existingLog);
-        const processedHashes = getProcessedHashes(existingLog);
-        // Iterate sessions
-        const sessions = await listSessions(project.id);
-        stats.sessionsScanned = sessions.length;
-        const newProcessedEntries = [];
-        const allNewMemories = [];
-        for (const session of sessions) {
-            try {
-                const messages = await listMessages(session.id);
-                for (const message of messages) {
-                    stats.messagesScanned++;
-                    // Only process assistant and thinking messages
-                    if (message.role !== 'assistant' && message.role !== 'thinking') {
-                        stats.messagesSkipped++;
-                        continue;
-                    }
-                    // Layer 1: skip by message ID
-                    if (processedMsgIDs.has(message.id)) {
-                        stats.messagesSkipped++;
-                        continue;
-                    }
-                    // Layer 2: skip by content hash
-                    const msgHash = await buildMessageContentHash(message.id);
-                    if (processedHashes.has(msgHash)) {
-                        stats.messagesSkipped++;
-                        continue;
-                    }
-                    try {
-                        const input = {
-                            sessionID: session.id,
-                            messageID: message.id,
-                        };
-                        // Run both extractors in parallel
-                        const [sessionResults, thinkingResults] = await Promise.all([
-                            extractFromMessage(input),
-                            extractThinkingFromMessage(input),
-                        ]);
-                        // Convert ExtractionResult → Memory with logical IDs
-                        const sessionMemories = sessionResults.map((r, idx) => ({
-                            id: `session-${session.id}-${message.id}-${idx}`,
-                            sessionID: r.sessionID,
-                            messageID: r.messageID,
-                            category: r.category,
-                            title: r.title,
-                            body: r.body,
-                            tags: r.tags,
-                            importance: r.importance,
-                            createdAt: message.time?.created ?? Date.now(),
-                            extractedBy: 'local-recall-daemon',
-                        }));
-                        const thinkingMemories = thinkingResults.map((r, idx) => ({
-                            id: `thinking-${session.id}-${message.id}-${idx}`,
-                            sessionID: r.sessionID,
-                            messageID: r.messageID,
-                            category: r.category,
-                            title: r.title,
-                            body: r.body,
-                            tags: r.tags,
-                            importance: r.importance,
-                            createdAt: message.time?.created ?? Date.now(),
-                            extractedBy: 'local-recall-daemon',
-                        }));
-                        const memories = [...sessionMemories, ...thinkingMemories];
-                        allNewMemories.push(...memories);
-                        // Add to fast-lookup sets so subsequent messages in this
-                        // pass are also deduplicated
-                        processedMsgIDs.add(message.id);
-                        processedHashes.add(msgHash);
-                        // Mark as processed with content hash
-                        newProcessedEntries.push({
-                            status: 'success',
-                            messageID: message.id,
-                            contentHash: msgHash,
-                            processedAt: Date.now(),
-                            memoriesCreated: memories.length,
-                        });
-                    }
-                    catch (err) {
-                        recordFailure(stats, {
-                            scope: 'message',
-                            messageID: message.id,
-                            error: err,
-                        });
-                        // Still mark as processed to avoid re-trying broken messages
-                        newProcessedEntries.push({
-                            status: 'failed',
-                            messageID: message.id,
-                            contentHash: msgHash,
-                            processedAt: Date.now(),
-                            memoriesCreated: 0,
-                            failure: getErrorMessage(err),
-                        });
-                    }
-                }
-            }
-            catch (err) {
-                const failure = {
-                    scope: 'session',
-                    sessionID: session.id,
-                    error: err,
-                };
-                const failureMessage = recordFailure(stats, failure);
-                newProcessedEntries.push(toProcessedFailureEntry(failure, failureMessage));
-            }
-        }
-        // Batch store all new memories
-        if (allNewMemories.length > 0) {
-            await storeMemories(directory, allNewMemories);
-            stats.newMemories = allNewMemories.length;
-        }
-        // Batch update processed log
-        if (newProcessedEntries.length > 0) {
-            await markProcessed(directory, newProcessedEntries);
-        }
-    }
-    catch (err) {
-        const failure = { scope: 'extraction', error: err };
-        const failureMessage = recordFailure(stats, failure);
-        try {
-            await markProcessed(directory, [toProcessedFailureEntry(failure, failureMessage)]);
-        }
-        catch (persistErr) {
-            stats.errors.push(`Failed to persist processing failure: ${getErrorMessage(persistErr)}`);
-        }
-    }
-    return stats;
-}