@lumenflow/core 1.0.0

package/dist/core/tool.schemas.d.ts

@@ -0,0 +1,226 @@
+/**
+ * @file tool.schemas.ts
+ * @description Zod schemas for tool abstraction layer (WU-1394)
+ *
+ * Provides runtime validation and TypeScript type inference for tool inputs,
+ * outputs, and metadata. Supports JSON Schema export for provider adapters
+ * (MCP, OpenAI, Gemini).
+ *
+ * Reference: tools/lib/arg-parser.mjs for current argument handling patterns
+ */
+import { z, type ZodTypeAny } from 'zod';
+/**
+ * Schema for tool input
+ *
+ * Represents the standardized input format for all tools in the system.
+ * Maps command names to their arguments and optional context.
+ */
+export declare const ToolInputSchema: z.ZodObject<{
+    command: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ToolInput = z.infer<typeof ToolInputSchema>;
+/**
+ * Schema for tool error details
+ */
+export declare const ToolErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stack: z.ZodOptional<z.ZodString>;
+    tryNext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ToolError = z.infer<typeof ToolErrorSchema>;
+/**
+ * Schema for tool output
+ *
+ * Standardized response format for all tools. Success/failure indicated by
+ * the `success` field, with data/error fields providing details.
+ */
+export declare const ToolOutputSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    data: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        stack: z.ZodOptional<z.ZodString>;
+        tryNext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ToolOutput = z.infer<typeof ToolOutputSchema>;
+/**
+ * Schema for tool metadata
+ *
+ * Describes a tool's capabilities, domain, permissions, and usage examples.
+ */
+export declare const ToolMetadataSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    domain: z.ZodEnum<{
+        git: "git";
+        test: "test";
+        file: "file";
+        wu: "wu";
+        initiative: "initiative";
+        docs: "docs";
+        security: "security";
+        explore: "explore";
+        db: "db";
+        metrics: "metrics";
+        orchestration: "orchestration";
+        util: "util";
+    }>;
+    permission: z.ZodEnum<{
+        read: "read";
+        write: "write";
+        admin: "admin";
+    }>;
+    version: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+    replacedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ToolMetadata = z.infer<typeof ToolMetadataSchema>;
+/**
+ * Schema for tool definition
+ *
+ * Complete tool specification including metadata, schemas, and execution function.
+ */
+export declare const ToolDefinitionSchema: z.ZodObject<{
+    metadata: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        domain: z.ZodEnum<{
+            git: "git";
+            test: "test";
+            file: "file";
+            wu: "wu";
+            initiative: "initiative";
+            docs: "docs";
+            security: "security";
+            explore: "explore";
+            db: "db";
+            metrics: "metrics";
+            orchestration: "orchestration";
+            util: "util";
+        }>;
+        permission: z.ZodEnum<{
+            read: "read";
+            write: "write";
+            admin: "admin";
+        }>;
+        version: z.ZodString;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            description: z.ZodString;
+            input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+        replacedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    inputSchema: z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    outputSchema: z.ZodOptional<z.ZodCustom<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>>;
+    execute: z.ZodCustom<(input: any, context?: Record<string, unknown>) => Promise<ToolOutput>, (input: any, context?: Record<string, unknown>) => Promise<ToolOutput>>;
+}, z.core.$strip>;
+export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;
+/**
+ * Schema for tool execution result (audit logging)
+ */
+export declare const ToolExecutionResultSchema: z.ZodObject<{
+    tool: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        success: "success";
+        timeout: "timeout";
+        failed: "failed";
+        pending: "pending";
+        running: "running";
+    }>;
+    startedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    output: z.ZodOptional<z.ZodObject<{
+        success: z.ZodBoolean;
+        data: z.ZodOptional<z.ZodUnknown>;
+        error: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+            details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            stack: z.ZodOptional<z.ZodString>;
+            tryNext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        stack: z.ZodOptional<z.ZodString>;
+        tryNext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ToolExecutionResult = z.infer<typeof ToolExecutionResultSchema>;
+/**
+ * Convert Zod schema to JSON Schema for provider adapters
+ *
+ * Uses Zod 4's native z.toJSONSchema() for robust conversion.
+ * Supports MCP, OpenAI Functions, and Gemini Tools formats.
+ *
+ * @param schema - Zod schema to convert
+ * @param options - Conversion options
+ * @returns JSON Schema object
+ *
+ * @example
+ * const inputSchema = z.object({ id: z.string() });
+ * const jsonSchema = toJSONSchema(inputSchema);
+ * // Returns: { type: 'object', properties: { id: { type: 'string' } }, ... }
+ */
+export declare function toJSONSchema(schema: ZodTypeAny, options?: {
+    /** Schema name (for $id field) */
+    name?: string;
+    /** Base URI for schema references */
+    baseUri?: string;
+}): Record<string, unknown>;
+/**
+ * Validate tool input against schema
+ *
+ * @param input - Tool input to validate
+ * @param schema - Zod schema to validate against
+ * @returns Validation result with parsed data or errors
+ */
+export declare function validateToolInput<T>(input: unknown, schema: z.ZodType<T>): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+/**
+ * Create standardized tool output for success case
+ *
+ * @param data - Output data
+ * @param metadata - Optional execution metadata
+ * @returns Standardized ToolOutput
+ */
+export declare function createSuccessOutput(data: unknown, metadata?: Record<string, unknown>): ToolOutput;
+/**
+ * Create standardized tool output for error case
+ *
+ * @param error - Error details
+ * @param metadata - Optional execution metadata
+ * @returns Standardized ToolOutput
+ */
+export declare function createErrorOutput(error: ToolError, metadata?: Record<string, unknown>): ToolOutput;

package/dist/core/tool.schemas.js

@@ -0,0 +1,226 @@
+/**
+ * @file tool.schemas.ts
+ * @description Zod schemas for tool abstraction layer (WU-1394)
+ *
+ * Provides runtime validation and TypeScript type inference for tool inputs,
+ * outputs, and metadata. Supports JSON Schema export for provider adapters
+ * (MCP, OpenAI, Gemini).
+ *
+ * Reference: tools/lib/arg-parser.mjs for current argument handling patterns
+ */
+import { z } from 'zod';
+import { TOOL_DOMAINS, PERMISSION_LEVELS, TOOL_STATUS, } from './tool.constants.js';
+/**
+ * Schema for tool input
+ *
+ * Represents the standardized input format for all tools in the system.
+ * Maps command names to their arguments and optional context.
+ */
+export const ToolInputSchema = z.object({
+    /** Tool command name (e.g., 'wu:claim', 'git:commit') */
+    command: z.string().min(1).describe('Tool command name'),
+    /** Tool-specific arguments (validated by tool's inputSchema) */
+    arguments: z.record(z.string(), z.unknown()).default({}),
+    /** Optional execution context (session ID, user, etc.) */
+    context: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Execution context (session_id, user, etc.)'),
+});
+/**
+ * Schema for tool error details
+ */
+export const ToolErrorSchema = z.object({
+    /** Error code from TOOL_ERROR_CODES or ErrorCodes */
+    code: z.string(),
+    /** Human-readable error message */
+    message: z.string(),
+    /** Optional additional error details */
+    details: z.record(z.string(), z.unknown()).optional(),
+    /** Optional stack trace (for debugging) */
+    stack: z.string().optional(),
+    /** Optional suggestions for resolution (WU-1339: Agent-friendly errors) */
+    tryNext: z.array(z.string()).optional().describe('Suggested next actions'),
+});
+/**
+ * Schema for tool output
+ *
+ * Standardized response format for all tools. Success/failure indicated by
+ * the `success` field, with data/error fields providing details.
+ */
+export const ToolOutputSchema = z.object({
+    /** Operation success status */
+    success: z.boolean(),
+    /** Output data (present when success=true) */
+    data: z.unknown().optional(),
+    /** Error details (present when success=false) */
+    error: ToolErrorSchema.optional(),
+    /** Optional warning messages */
+    warnings: z.array(z.string()).optional(),
+    /** Optional execution metadata (duration, timestamp, etc.) */
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Schema for tool metadata
+ *
+ * Describes a tool's capabilities, domain, permissions, and usage examples.
+ */
+export const ToolMetadataSchema = z.object({
+    /** Tool name (unique identifier) */
+    name: z.string().min(1),
+    /** Human-readable description */
+    description: z.string().min(1),
+    /** Tool domain classification */
+    domain: z.enum([
+        TOOL_DOMAINS.WU,
+        TOOL_DOMAINS.GIT,
+        TOOL_DOMAINS.FILE,
+        TOOL_DOMAINS.EXPLORE,
+        TOOL_DOMAINS.TEST,
+        TOOL_DOMAINS.DB,
+        TOOL_DOMAINS.SECURITY,
+        TOOL_DOMAINS.INITIATIVE,
+        TOOL_DOMAINS.METRICS,
+        TOOL_DOMAINS.ORCHESTRATION,
+        TOOL_DOMAINS.DOCS,
+        TOOL_DOMAINS.UTIL,
+    ]),
+    /** Required permission level */
+    permission: z.enum([
+        PERMISSION_LEVELS.READ,
+        PERMISSION_LEVELS.WRITE,
+        PERMISSION_LEVELS.ADMIN,
+    ]),
+    /** Tool version (semantic versioning) */
+    version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Must be semantic version (x.y.z)'),
+    /** Optional tags for categorization */
+    tags: z.array(z.string()).optional(),
+    /** Optional usage examples */
+    examples: z
+        .array(z.object({
+        description: z.string(),
+        input: z.record(z.string(), z.unknown()),
+        output: z.record(z.string(), z.unknown()).optional(),
+    }))
+        .optional(),
+    /** Optional deprecation notice */
+    deprecated: z.boolean().optional(),
+    /** Optional replacement tool (if deprecated) */
+    replacedBy: z.string().optional(),
+});
+/**
+ * Schema for tool definition
+ *
+ * Complete tool specification including metadata, schemas, and execution function.
+ */
+export const ToolDefinitionSchema = z.object({
+    /** Tool metadata */
+    metadata: ToolMetadataSchema,
+    /** Input schema (Zod schema for argument validation) */
+    inputSchema: z.custom((val) => val instanceof z.ZodType),
+    /** Optional output schema (Zod schema for response validation) */
+    outputSchema: z.custom((val) => val instanceof z.ZodType).optional(),
+    /** Tool execution function */
+    execute: z.custom((val) => typeof val === 'function'),
+});
+/**
+ * Schema for tool execution result (audit logging)
+ */
+export const ToolExecutionResultSchema = z.object({
+    /** Tool name */
+    tool: z.string(),
+    /** Execution status */
+    status: z.enum([
+        TOOL_STATUS.PENDING,
+        TOOL_STATUS.RUNNING,
+        TOOL_STATUS.SUCCESS,
+        TOOL_STATUS.FAILED,
+        TOOL_STATUS.TIMEOUT,
+        TOOL_STATUS.CANCELLED,
+    ]),
+    /** Start timestamp */
+    startedAt: z.string().datetime(),
+    /** End timestamp */
+    completedAt: z.string().datetime().optional(),
+    /** Execution duration in milliseconds */
+    durationMs: z.number().int().nonnegative().optional(),
+    /** Tool input (sanitized, no sensitive data) */
+    input: z.record(z.string(), z.unknown()),
+    /** Tool output (sanitized) */
+    output: ToolOutputSchema.optional(),
+    /** Error details (if failed) */
+    error: ToolErrorSchema.optional(),
+    /** Execution context (session, user, etc.) */
+    context: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Convert Zod schema to JSON Schema for provider adapters
+ *
+ * Uses Zod 4's native z.toJSONSchema() for robust conversion.
+ * Supports MCP, OpenAI Functions, and Gemini Tools formats.
+ *
+ * @param schema - Zod schema to convert
+ * @param options - Conversion options
+ * @returns JSON Schema object
+ *
+ * @example
+ * const inputSchema = z.object({ id: z.string() });
+ * const jsonSchema = toJSONSchema(inputSchema);
+ * // Returns: { type: 'object', properties: { id: { type: 'string' } }, ... }
+ */
+export function toJSONSchema(schema, options) {
+    // Use Zod 4's native JSON Schema conversion
+    const jsonSchema = z.toJSONSchema(schema);
+    // Add $id if name is provided
+    if (options?.name) {
+        return {
+            ...jsonSchema,
+            $id: `${options.baseUri || ''}#/${options.name}`,
+        };
+    }
+    return jsonSchema;
+}
+/**
+ * Validate tool input against schema
+ *
+ * @param input - Tool input to validate
+ * @param schema - Zod schema to validate against
+ * @returns Validation result with parsed data or errors
+ */
+export function validateToolInput(input, schema) {
+    const result = schema.safeParse(input);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    else {
+        return { success: false, error: result.error };
+    }
+}
+/**
+ * Create standardized tool output for success case
+ *
+ * @param data - Output data
+ * @param metadata - Optional execution metadata
+ * @returns Standardized ToolOutput
+ */
+export function createSuccessOutput(data, metadata) {
+    return {
+        success: true,
+        data,
+        metadata,
+    };
+}
+/**
+ * Create standardized tool output for error case
+ *
+ * @param error - Error details
+ * @param metadata - Optional execution metadata
+ * @returns Standardized ToolOutput
+ */
+export function createErrorOutput(error, metadata) {
+    return {
+        success: false,
+        error,
+        metadata,
+    };
+}

package/dist/core/worktree-guard.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @file worktree-guard.mjs
+ * @description WU context validation and main branch protection (WU-1396)
+ *
+ * Provides runtime guards to enforce worktree discipline:
+ * - Detect if current directory is inside a worktree
+ * - Extract WU ID and lane from worktree path or git branch
+ * - Throw descriptive error when write operations attempted outside worktree
+ * - Check if on main/master branch
+ *
+ * Used by wu- scripts to prevent writes to main checkout when worktrees exist.
+ * Complements .claude/hooks/user-prompt-submit-hook (human agent protection).
+ *
+ * @see {@link .claude/hooks/user-prompt-submit-hook} - Agent blocking hook
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - Worktree discipline
+ */
+/**
+ * Git adapter interface for worktree operations
+ */
+interface GitAdapter {
+    getCurrentBranch(): Promise<string>;
+}
+/**
+ * Options with git adapter
+ */
+interface GitOptions {
+    /** GitAdapter instance (for testing) */
+    git?: GitAdapter;
+}
+/**
+ * Options for isInWorktree
+ */
+interface CwdOptions {
+    /** Current working directory (defaults to process.cwd()) */
+    cwd?: string;
+}
+/**
+ * Combined options for context functions
+ */
+interface WorktreeContextOptions extends GitOptions, CwdOptions {
+    /** Operation name for error message */
+    operation?: string;
+}
+/**
+ * Check if on main or master branch
+ *
+ * @param {GitOptions} [options] - Options
+ * @returns {Promise<boolean>} True if on main/master branch
+ *
+ * @example
+ * if (await isMainBranch()) {
+ *   console.log('On main branch');
+ * }
+ */
+export declare function isMainBranch(options?: GitOptions): Promise<boolean>;
+/**
+ * Check if current directory is inside a worktree
+ *
+ * Detects worktree by checking if path contains worktrees/<lane>-wu-<id> pattern.
+ * Works correctly from nested directories within worktree.
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {boolean} True if inside a worktree directory
+ *
+ * @example
+ * if (isInWorktree()) {
+ *   console.log('Working in a worktree');
+ * }
+ *
+ * // From nested directory
+ * isInWorktree({ cwd: '/project/worktrees/operations-wu-123/tools/lib' }); // true
+ */
+export declare function isInWorktree(options?: CwdOptions): boolean;
+/**
+ * Get WU context from current directory or git branch
+ *
+ * Extracts WU ID, lane, and worktree path from:
+ * 1. Worktree directory path (priority) - works from nested directories
+ * 2. Git branch name (fallback) - lane/operations-tooling/wu-1396
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @param {Object} [options.git] - GitAdapter instance (for testing)
+ * @returns {Promise<Object|null>} WU context or null if not in WU workspace
+ *
+ * @example
+ * // From worktree
+ * const ctx = await getWUContext();
+ * // { wuId: 'WU-1396', lane: 'operations-tooling', worktreePath: 'worktrees/operations-tooling-wu-1396' }
+ *
+ * // From lane branch (not in worktree)
+ * const ctx = await getWUContext();
+ * // { wuId: 'WU-1396', lane: 'operations-tooling', worktreePath: null }
+ *
+ * // From main checkout on main branch
+ * const ctx = await getWUContext();
+ * // null
+ */
+export declare function getWUContext(options?: WorktreeContextOptions): Promise<{
+    wuId: string;
+    lane: any;
+    worktreePath: any;
+}>;
+/**
+ * Assert that current context is inside a worktree or on a lane branch
+ *
+ * Throws descriptive error if:
+ * - On main/master branch AND
+ * - Not in a worktree directory
+ *
+ * Used by write operations to prevent modifications to main checkout.
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @param {Object} [options.git] - GitAdapter instance (for testing)
+ * @param {string} [options.operation] - Operation name for error message
+ * @throws {Error} If not in worktree and on main branch
+ *
+ * @example
+ * // In a wu- script write operation
+ * await assertWorktreeRequired({ operation: 'wu:claim' });
+ *
+ * // Will throw if on main in main checkout:
+ * // Error: BLOCKED: Operation 'wu:claim' requires a worktree.
+ * //        You are on 'main' branch in main checkout.
+ * //        ...
+ */
+export declare function assertWorktreeRequired(options?: WorktreeContextOptions): Promise<void>;
+export {};