@fractary/faber 2.4.0 → 2.4.2

package/dist/workflows/registry.js

@@ -0,0 +1,232 @@
+/**
+ * @fractary/faber - Workflow Registry
+ *
+ * Manages workflow discovery and loading from the workflows manifest.
+ * Provides a unified interface for finding and loading workflow definitions.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { z } from 'zod';
+import { FABER_DEFAULTS } from '../defaults.js';
+import { findProjectRoot } from '../config.js';
+// ============================================================================
+// Schema Validation
+// ============================================================================
+const WorkflowEntrySchema = z.object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z][a-z0-9-]*$/, 'Workflow ID must be lowercase alphanumeric with hyphens'),
+    file: z
+        .string()
+        .min(1)
+        .max(255)
+        .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.(yaml|yml|json)$/, 'File must be a .yaml, .yml, or .json file'),
+    description: z.string().max(500).optional(),
+});
+const WorkflowRegistrySchema = z.object({
+    workflows: z.array(WorkflowEntrySchema).min(1),
+});
+// ============================================================================
+// Registry Errors
+// ============================================================================
+export class WorkflowRegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkflowRegistryError';
+    }
+}
+export class RegistryWorkflowNotFoundError extends WorkflowRegistryError {
+    workflowId;
+    availableWorkflows;
+    constructor(workflowId, availableWorkflows) {
+        super(`Workflow '${workflowId}' not found. Available workflows: ${availableWorkflows.join(', ') || 'none'}`);
+        this.workflowId = workflowId;
+        this.availableWorkflows = availableWorkflows;
+        this.name = 'RegistryWorkflowNotFoundError';
+    }
+}
+/**
+ * Load the workflow registry from the manifest file or auto-discover workflows.
+ *
+ * @param options Loading options
+ * @returns Workflow registry
+ * @throws WorkflowRegistryError if registry cannot be loaded
+ */
+export function loadWorkflowRegistry(options = {}) {
+    const projectRoot = options.projectRoot || findProjectRoot();
+    const workflowsPath = options.config?.workflows?.path || FABER_DEFAULTS.paths.workflows;
+    const workflowsDir = path.isAbsolute(workflowsPath)
+        ? workflowsPath
+        : path.join(projectRoot, workflowsPath);
+    const manifestPath = path.join(workflowsDir, FABER_DEFAULTS.manifestFilename);
+    // Try to load manifest file
+    if (fs.existsSync(manifestPath)) {
+        return loadManifestFile(manifestPath);
+    }
+    // Auto-discover if enabled
+    if (options.autoDiscover !== false) {
+        return autoDiscoverWorkflows(workflowsDir);
+    }
+    // Return empty registry
+    return { workflows: [] };
+}
+/**
+ * Load registry from manifest file (workflows.yaml)
+ */
+function loadManifestFile(manifestPath) {
+    try {
+        const content = fs.readFileSync(manifestPath, 'utf-8');
+        const data = yaml.load(content);
+        const result = WorkflowRegistrySchema.safeParse(data);
+        if (!result.success) {
+            const errors = result.error.errors
+                .map((e) => `${e.path.join('.')}: ${e.message}`)
+                .join(', ');
+            throw new WorkflowRegistryError(`Invalid workflow manifest at ${manifestPath}: ${errors}`);
+        }
+        return result.data;
+    }
+    catch (error) {
+        if (error instanceof WorkflowRegistryError)
+            throw error;
+        throw new WorkflowRegistryError(`Failed to load workflow manifest: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Auto-discover workflows by scanning the workflows directory
+ */
+function autoDiscoverWorkflows(workflowsDir) {
+    if (!fs.existsSync(workflowsDir)) {
+        return { workflows: [] };
+    }
+    const files = fs.readdirSync(workflowsDir);
+    const workflows = [];
+    for (const file of files) {
+        // Skip manifest file and non-workflow files
+        if (file === FABER_DEFAULTS.manifestFilename)
+            continue;
+        if (!/\.(yaml|yml|json)$/.test(file))
+            continue;
+        // Skip files starting with underscore (templates, partials)
+        if (file.startsWith('_'))
+            continue;
+        // Extract ID from filename
+        const id = file.replace(/\.(yaml|yml|json)$/, '');
+        // Validate ID format
+        if (!/^[a-z][a-z0-9-]*$/.test(id)) {
+            console.warn(`Skipping workflow file ${file}: invalid ID format`);
+            continue;
+        }
+        workflows.push({
+            id,
+            file,
+        });
+    }
+    // Sort by ID for consistent ordering
+    workflows.sort((a, b) => a.id.localeCompare(b.id));
+    return { workflows };
+}
+/**
+ * Get a specific workflow entry by ID
+ *
+ * @param options Options including workflowId
+ * @returns Workflow entry
+ * @throws WorkflowNotFoundError if workflow doesn't exist
+ */
+export function getWorkflow(options) {
+    const registry = loadWorkflowRegistry(options);
+    const workflow = registry.workflows.find((w) => w.id === options.workflowId);
+    if (!workflow) {
+        throw new RegistryWorkflowNotFoundError(options.workflowId, registry.workflows.map((w) => w.id));
+    }
+    return workflow;
+}
+/**
+ * Get the file path for a workflow
+ *
+ * @param options Options including workflowId
+ * @returns Absolute path to the workflow file
+ * @throws WorkflowNotFoundError if workflow doesn't exist
+ */
+export function getWorkflowPath(options) {
+    const projectRoot = options.projectRoot || findProjectRoot();
+    const workflowsPath = options.config?.workflows?.path || FABER_DEFAULTS.paths.workflows;
+    const workflowsDir = path.isAbsolute(workflowsPath)
+        ? workflowsPath
+        : path.join(projectRoot, workflowsPath);
+    const workflow = getWorkflow(options);
+    return path.join(workflowsDir, workflow.file);
+}
+/**
+ * List all available workflows
+ *
+ * @param options Loading options
+ * @returns Array of workflow entries
+ */
+export function listWorkflows(options = {}) {
+    const registry = loadWorkflowRegistry(options);
+    return registry.workflows;
+}
+/**
+ * Check if a workflow exists
+ *
+ * @param workflowId Workflow ID to check
+ * @param options Loading options
+ * @returns true if workflow exists
+ */
+export function workflowExists(workflowId, options = {}) {
+    const registry = loadWorkflowRegistry(options);
+    return registry.workflows.some((w) => w.id === workflowId);
+}
+/**
+ * Get the default workflow ID from config or fallback
+ *
+ * @param options Loading options
+ * @returns Default workflow ID
+ */
+export function getDefaultWorkflowId(options = {}) {
+    return options.config?.workflows?.default || FABER_DEFAULTS.workflow.defaultWorkflow;
+}
+/**
+ * Create a new workflow manifest file
+ *
+ * @param options Creation options
+ * @returns Path to created manifest
+ */
+export function createWorkflowManifest(options = {}) {
+    const projectRoot = options.projectRoot || findProjectRoot();
+    const workflowsPath = options.workflowsPath || FABER_DEFAULTS.paths.workflows;
+    const workflowsDir = path.isAbsolute(workflowsPath)
+        ? workflowsPath
+        : path.join(projectRoot, workflowsPath);
+    // Ensure directory exists
+    fs.mkdirSync(workflowsDir, { recursive: true });
+    const manifestPath = path.join(workflowsDir, FABER_DEFAULTS.manifestFilename);
+    // Use provided workflows or create default entry
+    const workflows = options.workflows || [
+        {
+            id: 'default',
+            file: 'default.yaml',
+            description: 'Default FABER workflow for software development',
+        },
+    ];
+    const registry = { workflows };
+    const content = yaml.dump(registry, {
+        indent: 2,
+        lineWidth: 100,
+        noRefs: true,
+        sortKeys: false,
+    });
+    // Add header comment
+    const fileContent = `# Workflow Registry - Lists available FABER workflows
+# Each workflow is defined in a separate file in this directory
+# Schema: https://fractary.dev/schemas/workflow-registry.schema.json
+
+${content}`;
+    fs.writeFileSync(manifestPath, fileContent, 'utf-8');
+    return manifestPath;
+}
+//# sourceMappingURL=registry.js.map

package/dist/workflows/registry.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fractary/faber",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "FABER SDK - Development toolkit for AI-assisted workflows",
   "type": "module",
   "main": "dist/index.js",