@syntesseraai/opencode-feature-factory 0.2.13 → 0.2.15

package/dist/agent-management-tools.js

@@ -0,0 +1,117 @@
+import { tool } from '@opencode-ai/plugin/tool';
+import { listActiveAgents, findAgentFiles, findAgentFilesById, findAllAgentFiles, readAgentContextById, } from './agent-context.js';
+/**
+ * Create agent management tools for the plugin
+ */
+export function createAgentManagementTools(input) {
+    const { $ } = input;
+    return {
+        tool: {
+            'ff-agents-current': tool({
+                description: 'List all currently active Feature Factory agents with their UUIDs and status',
+                args: {
+                    sessionID: tool.schema.string().optional().describe('Filter by specific session ID'),
+                    agent: tool.schema
+                        .string()
+                        .optional()
+                        .describe('Filter by agent type (e.g., planning, research)'),
+                },
+                execute: async (args) => {
+                    try {
+                        const agents = await listActiveAgents(input, args.sessionID, args.agent);
+                        if (agents.length === 0) {
+                            return JSON.stringify({
+                                count: 0,
+                                message: 'No active agents found',
+                                agents: [],
+                            }, null, 2);
+                        }
+                        return JSON.stringify({
+                            count: agents.length,
+                            agents: agents.map((a) => ({
+                                id: a.id,
+                                agent: a.agent,
+                                title: a.title,
+                                folder: a.folder,
+                                status: a.status,
+                                started: a.started,
+                                session: a.session,
+                                parent: a.parent || null,
+                                delegated_to: a.delegated_to || [],
+                            })),
+                        }, null, 2);
+                    }
+                    catch (error) {
+                        return JSON.stringify({
+                            error: `Failed to list agents: ${error}`,
+                        }, null, 2);
+                    }
+                },
+            }),
+            'ff-agents-clear': tool({
+                description: 'Clear agent context files. Can clear all, or filter by session, agent type, or specific UUID',
+                args: {
+                    sessionID: tool.schema
+                        .string()
+                        .optional()
+                        .describe('Clear only agents for specific session'),
+                    agent: tool.schema.string().optional().describe('Clear only specific agent type'),
+                    id: tool.schema.string().optional().describe('Clear specific agent by UUID'),
+                },
+                execute: async (args) => {
+                    try {
+                        let files = [];
+                        if (args.id) {
+                            files = await findAgentFilesById(input, args.id);
+                        }
+                        else if (args.agent && args.sessionID) {
+                            files = await findAgentFiles(input, args.agent, args.sessionID);
+                        }
+                        else if (args.sessionID) {
+                            files = await findAgentFiles(input, undefined, args.sessionID);
+                        }
+                        else if (args.agent) {
+                            files = await findAgentFiles(input, args.agent);
+                        }
+                        else {
+                            files = await findAllAgentFiles(input);
+                        }
+                        if (files.length === 0) {
+                            return 'No agent context files found to clear.';
+                        }
+                        for (const file of files) {
+                            try {
+                                await $ `rm ${file}`.quiet();
+                            }
+                            catch {
+                                // Continue even if one file fails
+                            }
+                        }
+                        return `Cleared ${files.length} agent context file(s)`;
+                    }
+                    catch (error) {
+                        return `Error clearing agents: ${error}`;
+                    }
+                },
+            }),
+            'ff-agents-show': tool({
+                description: 'Show detailed context for a specific agent by UUID',
+                args: {
+                    id: tool.schema.string().describe('Agent UUID to show details for'),
+                },
+                execute: async (args) => {
+                    try {
+                        const agentContext = await readAgentContextById(input, args.id);
+                        if (!agentContext) {
+                            return `Agent with ID "${args.id}" not found`;
+                        }
+                        return JSON.stringify(agentContext, null, 2);
+                    }
+                    catch (error) {
+                        return `Error reading agent: ${error}`;
+                    }
+                },
+            }),
+        },
+    };
+}

package/dist/feature-factory-setup.d.ts

@@ -0,0 +1,9 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+type BunShell = any;
+/**
+ * Initialize the Feature Factory directory structure.
+ * Creates .feature-factory/ and .feature-factory/agents/ directories.
+ * Migrates management/ci.sh to .feature-factory/ci.sh if it exists.
+ */
+export declare function initializeFeatureFactory(input: PluginInput, $: BunShell): Promise<void>;
+export {};

package/dist/feature-factory-setup.js

@@ -0,0 +1,151 @@
+const SERVICE_NAME = 'feature-factory';
+/**
+ * Log a message using the OpenCode client's structured logging.
+ * Silently fails if logging is unavailable.
+ */
+async function log(client, level, message, extra) {
+    try {
+        await client.app.log({
+            body: {
+                service: SERVICE_NAME,
+                level,
+                message,
+                extra,
+            },
+        });
+    }
+    catch {
+        // Logging failure should not affect plugin operation
+    }
+}
+/**
+ * Execute a shell command with a timeout to prevent hangs
+ */
+async function executeWithTimeout(operation, timeoutMs = 5000, operationName = 'shell command') {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`${operationName} timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([operation(), timeoutPromise]);
+    }
+    catch (error) {
+        // Return null on timeout or error
+        return null;
+    }
+}
+/**
+ * Validate that a directory path is safe to use
+ */
+function isValidDirectory(directory) {
+    if (!directory || typeof directory !== 'string')
+        return false;
+    if (directory === '' || directory === '/')
+        return false;
+    // Check for common invalid patterns
+    if (directory.includes('\0') || directory.includes('..'))
+        return false;
+    return true;
+}
+/**
+ * Initialize the Feature Factory directory structure.
+ * Creates .feature-factory/ and .feature-factory/agents/ directories.
+ * Migrates management/ci.sh to .feature-factory/ci.sh if it exists.
+ */
+export async function initializeFeatureFactory(input, $) {
+    const { directory, client } = input;
+    // Validate directory before attempting any operations
+    if (!isValidDirectory(directory)) {
+        await log(client, 'debug', 'feature-factory-init-skipped-invalid-directory', {
+            directory: String(directory),
+        });
+        return;
+    }
+    const featureFactoryDir = `${directory}/.feature-factory`;
+    const agentsDir = `${featureFactoryDir}/agents`;
+    // Create directories if they don't exist (with timeout protection)
+    try {
+        const result = await executeWithTimeout(async () => await $ `mkdir -p ${agentsDir}`.quiet(), 3000, 'mkdir -p');
+        if (result === null) {
+            await log(client, 'warn', 'feature-factory-directory-creation-timeout', {
+                agentsDir,
+            });
+            return; // Exit early if we can't create directories
+        }
+        await log(client, 'debug', 'feature-factory-directories-created', {
+            featureFactoryDir,
+            agentsDir,
+        });
+    }
+    catch (error) {
+        await log(client, 'warn', 'feature-factory-directory-creation-failed', {
+            error: String(error),
+        });
+        // Continue even if directory creation fails - it might already exist
+    }
+    // Check for CI script migration (with timeout protection)
+    const oldCiPath = `${directory}/management/ci.sh`;
+    const newCiPath = `${featureFactoryDir}/ci.sh`;
+    try {
+        // Check if old CI exists (with timeout)
+        const oldExists = await executeWithTimeout(async () => {
+            await $ `test -f ${oldCiPath}`.quiet();
+            return true;
+        }, 2000, 'test -f old-ci');
+        if (oldExists !== true) {
+            // Old doesn't exist, nothing to migrate
+            await log(client, 'debug', 'ci-sh-no-migration-needed', {
+                oldPath: oldCiPath,
+            });
+            return;
+        }
+        // Old exists, check if new already exists (with timeout)
+        const newExists = await executeWithTimeout(async () => {
+            await $ `test -f ${newCiPath}`.quiet();
+            return true;
+        }, 2000, 'test -f new-ci');
+        if (newExists === true) {
+            // Both exist - migration already done or user has both
+            await log(client, 'debug', 'ci-sh-both-locations-exist', {
+                oldPath: oldCiPath,
+                newPath: newCiPath,
+            });
+            return;
+        }
+        // Old exists, new doesn't - migrate (with timeout)
+        const copied = await executeWithTimeout(async () => {
+            await $ `cp ${oldCiPath} ${newCiPath}`.quiet();
+            return true;
+        }, 3000, 'cp ci.sh');
+        if (copied === true) {
+            const removed = await executeWithTimeout(async () => {
+                await $ `rm ${oldCiPath}`.quiet();
+                return true;
+            }, 2000, 'rm old-ci');
+            if (removed === true) {
+                await log(client, 'info', 'ci-sh-migrated', {
+                    from: oldCiPath,
+                    to: newCiPath,
+                });
+            }
+            else {
+                await log(client, 'warn', 'ci-sh-migration-partial', {
+                    from: oldCiPath,
+                    to: newCiPath,
+                    reason: 'copied but failed to remove old file',
+                });
+            }
+        }
+        else {
+            await log(client, 'error', 'ci-sh-migration-failed', {
+                from: oldCiPath,
+                to: newCiPath,
+                reason: 'copy operation timed out or failed',
+            });
+        }
+    }
+    catch (error) {
+        await log(client, 'error', 'ci-sh-migration-error', {
+            error: String(error),
+        });
+    }
+}

package/dist/index.d.ts

@@ -6,11 +6,16 @@ import type { Plugin } from '@opencode-ai/plugin';
  *
  * Behavior:
  * - Runs quality gate on session.idle (when agent finishes working)
- * - Executes management/ci.sh directly (no LLM involvement)
+ * - Executes .feature-factory/ci.sh directly (no LLM involvement)
  * - On fast feedback: "Quality gate is running, please stand-by for results ..."
  * - On success: "Quality gate passed"
  * - On failure: passes full CI output to LLM for fix instructions
- * - If management/ci.sh does not exist, quality gate does not run
+ * - If .feature-factory/ci.sh does not exist, quality gate does not run
+ *
+ * Feature Factory Context System:
+ * - Creates .feature-factory/ directory structure on startup
+ * - Migrates management/ci.sh to .feature-factory/ci.sh if present
+ * - Provides tools for agent context tracking (ff-agents-current, ff-agents-clear, ff-agents-show)
  */
 export declare const StopQualityGatePlugin: Plugin;
 export default StopQualityGatePlugin;

package/dist/index.js

@@ -1,5 +1,22 @@
 import { createQualityGateHooks } from './stop-quality-gate.js';
+import { initializeFeatureFactory } from './feature-factory-setup.js';
+import { createAgentManagementTools } from './agent-management-tools.js';
 const SERVICE_NAME = 'feature-factory';
+const PLUGIN_INIT_TIMEOUT_MS = 10000; // 10 seconds max for plugin initialization
+/**
+ * Wrap an async operation with a timeout to prevent hangs
+ */
+async function withTimeout(operation, timeoutMs, _context) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`timeout`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([operation(), timeoutPromise]);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Log a message using the OpenCode client's structured logging.
  * Silently fails if logging is unavailable.
@@ -36,31 +53,69 @@ function resolveRootDir(input) {
  *
  * Behavior:
  * - Runs quality gate on session.idle (when agent finishes working)
- * - Executes management/ci.sh directly (no LLM involvement)
+ * - Executes .feature-factory/ci.sh directly (no LLM involvement)
  * - On fast feedback: "Quality gate is running, please stand-by for results ..."
  * - On success: "Quality gate passed"
  * - On failure: passes full CI output to LLM for fix instructions
- * - If management/ci.sh does not exist, quality gate does not run
+ * - If .feature-factory/ci.sh does not exist, quality gate does not run
+ *
+ * Feature Factory Context System:
+ * - Creates .feature-factory/ directory structure on startup
+ * - Migrates management/ci.sh to .feature-factory/ci.sh if present
+ * - Provides tools for agent context tracking (ff-agents-current, ff-agents-clear, ff-agents-show)
  */
 export const StopQualityGatePlugin = async (input) => {
-    const { worktree, directory, client } = input;
+    const { worktree, directory, client, $ } = input;
     const rootDir = resolveRootDir({ worktree, directory });
-    // Skip quality gate if no valid directory (e.g., global config with no project)
+    // Skip if no valid directory (e.g., global config with no project)
     if (!rootDir || rootDir === '' || rootDir === '/') {
         return {};
     }
-    // Create quality gate hooks
+    // Initialize Feature Factory directory structure (with timeout protection)
+    try {
+        const initResult = await withTimeout(async () => await initializeFeatureFactory(input, $), PLUGIN_INIT_TIMEOUT_MS, 'feature-factory-init');
+        if (initResult === null) {
+            await log(client, 'warn', 'feature-factory-init-timeout', {
+                timeoutMs: PLUGIN_INIT_TIMEOUT_MS,
+            });
+        }
+    }
+    catch (error) {
+        await log(client, 'error', 'feature-factory-init-error', {
+            error: String(error),
+        });
+    }
+    // Create quality gate hooks (with timeout protection)
     let qualityGateHooks = {};
     try {
-        qualityGateHooks = await createQualityGateHooks(input);
+        const hooksResult = await withTimeout(async () => await createQualityGateHooks(input), PLUGIN_INIT_TIMEOUT_MS, 'quality-gate-init');
+        if (hooksResult !== null) {
+            qualityGateHooks = hooksResult;
+        }
+        else {
+            await log(client, 'warn', 'quality-gate-init-timeout', {
+                timeoutMs: PLUGIN_INIT_TIMEOUT_MS,
+            });
+        }
     }
     catch (error) {
         await log(client, 'error', 'quality-gate.init-error', {
             error: String(error),
         });
     }
+    // Create agent management tools (synchronous, minimal timeout for safety)
+    let agentManagementHooks = {};
+    try {
+        agentManagementHooks = createAgentManagementTools(input);
+    }
+    catch (error) {
+        await log(client, 'error', 'agent-management.init-error', {
+            error: String(error),
+        });
+    }
     return {
         ...qualityGateHooks,
+        ...agentManagementHooks,
     };
 };
 // Default export for OpenCode plugin discovery

package/dist/output.test.js

@@ -5,7 +5,7 @@
  * - extractErrorLines: extracts error-like lines from command output
  * - tailLines: returns last N lines with truncation notice
  */
-import { extractErrorLines, tailLines } from './output.js';
+import { extractErrorLines, tailLines } from './output';
 describe('extractErrorLines', () => {
     it('should return empty array for empty input', () => {
         expect(extractErrorLines('', 10)).toEqual([]);

package/dist/quality-gate-config.test.js

@@ -6,7 +6,7 @@
  * - hasConfiguredCommands: checks if explicit commands are configured
  * - DEFAULT_QUALITY_GATE: verify default values
  */
-import { mergeQualityGateConfig, hasConfiguredCommands, DEFAULT_QUALITY_GATE, } from './quality-gate-config.js';
+import { mergeQualityGateConfig, hasConfiguredCommands, DEFAULT_QUALITY_GATE, } from './quality-gate-config';
 describe('DEFAULT_QUALITY_GATE', () => {
     it('should have correct default values', () => {
         expect(DEFAULT_QUALITY_GATE.steps).toEqual(['lint', 'build', 'test']);

package/dist/stop-quality-gate.js

@@ -154,12 +154,30 @@ async function log(client, level, message, extra) {
         return undefined;
     }
 }
+/**
+ * Execute a shell command with a timeout to prevent hangs
+ */
+async function executeWithTimeout(operation, timeoutMs = 5000, _operationName = 'shell command') {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([operation(), timeoutPromise]);
+    }
+    catch {
+        // Return null on timeout or error
+        return null;
+    }
+}
 export async function createQualityGateHooks(input) {
     const { client, $, directory } = input;
     async function ciShExists() {
         try {
-            await $ `test -f ${directory}/management/ci.sh`.quiet();
-            return true;
+            const result = await executeWithTimeout(async () => {
+                await $ `test -f ${directory}/.feature-factory/ci.sh`.quiet();
+                return true;
+            }, 2000, 'test -f ci.sh');
+            return result === true;
         }
         catch {
             return false;
@@ -213,7 +231,7 @@ export async function createQualityGateHooks(input) {
             let ciOutput = '';
             let ciPassed = false;
             let timedOut = false;
-            const ciPath = `${directory}/management/ci.sh`;
+            const ciPath = `${directory}/.feature-factory/ci.sh`;
             // eslint-disable-next-line no-undef
             const proc = Bun.spawn(['bash', ciPath], {
                 cwd: directory,
@@ -274,7 +292,7 @@ export async function createQualityGateHooks(input) {
 
 **Important:** Do not interrupt your current task. Add "Fix quality gate failures" to your todo list and continue with what you were doing. Address the quality gate issues after completing your current task.
 
-If the failure details are missing or truncated, run "management/ci.sh" to get the full output.`;
+If the failure details are missing or truncated, run ".feature-factory/ci.sh" to get the full output.`;
                 const message = timedOut
                     ? `⏱️ Quality gate timed out\n\nThe CI execution exceeded the ${CI_TIMEOUT_MS / 1000} second timeout. The build may be hanging or taking too long.\n\n\`\`\`\n${sanitizedOutput}\n\`\`\`${instructions}`
                     : `❌ Quality gate failed\n\nThe CI checks did not pass. Please review the output below and fix the issues:\n\n\`\`\`\n${sanitizedOutput}\n\`\`\`${instructions}`;

package/dist/stop-quality-gate.test.js

@@ -5,7 +5,7 @@
  * - sanitizeOutput: redacts secrets from CI output
  * - isSessionReadOnly: determines if session has write permissions
  */
-import { sanitizeOutput, truncateOutput } from './stop-quality-gate.js';
+import { sanitizeOutput, truncateOutput } from './stop-quality-gate';
 function isSessionReadOnly(permission) {
     if (!permission)
         return false;

package/dist/uuid.d.ts

@@ -0,0 +1,13 @@
+/**
+ * UUID v4 generator
+ * Generates random UUIDs for agent instance tracking
+ */
+/**
+ * Generate a random UUID v4
+ * Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+export declare function generateUUID(): string;
+/**
+ * Validate if a string is a valid UUID v4
+ */
+export declare function isValidUUID(str: string): boolean;

package/dist/uuid.js

@@ -0,0 +1,22 @@
+/**
+ * UUID v4 generator
+ * Generates random UUIDs for agent instance tracking
+ */
+/**
+ * Generate a random UUID v4
+ * Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+export function generateUUID() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Validate if a string is a valid UUID v4
+ */
+export function isValidUUID(str) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(str);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",