@lumenflow/core 3.1.3 → 3.2.1

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

@@ -0,0 +1,227 @@
+/**
+ * @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.ts 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";
+        file: "file";
+        test: "test";
+        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";
+            file: "file";
+            test: "test";
+            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: UnsafeAny, context?: Record<string, unknown>) => Promise<ToolOutput>, (input: UnsafeAny, 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";
+        pending: "pending";
+        failed: "failed";
+        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;
+//# sourceMappingURL=tool.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool.schemas.d.ts","sourceRoot":"","sources":["../../src/core/tool.schemas.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,KAAK,UAAU,EAAE,MAAM,KAAK,CAAC;AAGzC;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;iBAY1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;iBAe1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAe3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoD7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAarB,SAAS,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,UAApE,SAAS,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC;iBAE9E,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkCpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE;IACR,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACnB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAA;CAAE,CAQpE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAMjG;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,UAAU,CAMZ"}

package/dist/core/tool.schemas.js

@@ -0,0 +1,229 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @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.ts 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,
+    };
+}
+//# sourceMappingURL=tool.schemas.js.map

package/dist/core/tool.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.schemas.js","sourceRoot":"","sources":["../../src/core/tool.schemas.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAmB,MAAM,KAAK,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEnF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,yDAAyD;IACzD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAExD,gEAAgE;IAChE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAExD,0DAA0D;IAC1D,OAAO,EAAE,CAAC;SACP,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CAAC,4CAA4C,CAAC;CAC1D,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,qDAAqD;IACrD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAEhB,mCAAmC;IACnC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IAEnB,wCAAwC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAErD,2CAA2C;IAC3C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE5B,2EAA2E;IAC3E,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;CAC3E,CAAC,CAAC;AAIH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,+BAA+B;IAC/B,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IAEpB,8CAA8C;IAC9C,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAE5B,iDAAiD;IACjD,KAAK,EAAE,eAAe,CAAC,QAAQ,EAAE;IAEjC,gCAAgC;IAChC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAExC,8DAA8D;IAC9D,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,oCAAoC;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEvB,iCAAiC;IACjC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE9B,iCAAiC;IACjC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC;QACb,YAAY,CAAC,EAAE;QACf,YAAY,CAAC,GAAG;QAChB,YAAY,CAAC,IAAI;QACjB,YAAY,CAAC,OAAO;QACpB,YAAY,CAAC,IAAI;QACjB,YAAY,CAAC,EAAE;QACf,YAAY,CAAC,QAAQ;QACrB,YAAY,CAAC,UAAU;QACvB,YAAY,CAAC,OAAO;QACpB,YAAY,CAAC,aAAa;QAC1B,YAAY,CAAC,IAAI;QACjB,YAAY,CAAC,IAAI;KACT,CAAC;IAEX,gCAAgC;IAChC,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC;QACjB,iBAAiB,CAAC,IAAI;QACtB,iBAAiB,CAAC,KAAK;QACvB,iBAAiB,CAAC,KAAK;KACf,CAAC;IAEX,yCAAyC;IACzC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,iBAAiB,EAAE,kCAAkC,CAAC;IAEhF,uCAAuC;IACvC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAEpC,8BAA8B;IAC9B,QAAQ,EAAE,CAAC;SACR,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;QACvB,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACxC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;KACrD,CAAC,CACH;SACA,QAAQ,EAAE;IAEb,kCAAkC;IAClC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAElC,gDAAgD;IAChD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,oBAAoB;IACpB,QAAQ,EAAE,kBAAkB;IAE5B,wDAAwD;IACxD,WAAW,EAAE,CAAC,CAAC,MAAM,CAAa,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,OAAO,CAAC;IAEpE,kEAAkE;IAClE,YAAY,EAAE,CAAC,CAAC,MAAM,CAAa,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE;IAEhF,8BAA8B;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,CAGf,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,UAAU,CAAC;CACtC,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,gBAAgB;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAEhB,uBAAuB;IACvB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC;QACb,WAAW,CAAC,OAAO;QACnB,WAAW,CAAC,OAAO;QACnB,WAAW,CAAC,OAAO;QACnB,WAAW,CAAC,MAAM;QAClB,WAAW,CAAC,OAAO;QACnB,WAAW,CAAC,SAAS;KACb,CAAC;IAEX,sBAAsB;IACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEhC,oBAAoB;IACpB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAE7C,yCAAyC;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAErD,gDAAgD;IAChD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAExC,8BAA8B;IAC9B,MAAM,EAAE,gBAAgB,CAAC,QAAQ,EAAE;IAEnC,gCAAgC;IAChC,KAAK,EAAE,eAAe,CAAC,QAAQ,EAAE;IAEjC,8CAA8C;IAC9C,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACtD,CAAC,CAAC;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAkB,EAClB,OAKC;IAED,4CAA4C;IAC5C,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,MAAM,CAA4B,CAAC;IAErE,8BAA8B;IAC9B,IAAI,OAAO,EAAE,IAAI,EAAE,CAAC;QAClB,OAAO;YACL,GAAG,UAAU;YACb,GAAG,EAAE,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,EAAE;SACjD,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,MAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAEvC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa,EAAE,QAAkC;IACnF,OAAO;QACL,OAAO,EAAE,IAAI;QACb,IAAI;QACJ,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAgB,EAChB,QAAkC;IAElC,OAAO;QACL,OAAO,EAAE,KAAK;QACd,KAAK;QACL,QAAQ;KACT,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,115 @@
+/**
+ * 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;
+} | null>;
+/**
+ * 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 {};
+//# sourceMappingURL=worktree-guard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-guard.d.ts","sourceRoot":"","sources":["../../src/core/worktree-guard.ts"],"names":[],"mappings":"AA8CA;;GAEG;AACH,UAAU,UAAU;IAClB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,UAAU,UAAU;IAClB,wCAAwC;IACxC,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED;;GAEG;AACH,UAAU,UAAU;IAClB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,UAAU,sBAAuB,SAAQ,UAAU,EAAE,UAAU;IAC7D,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,UAAe,oBAK1D;AAiBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,UAAe,WAOpD;AAwDD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,sBAA2B;;;;UAkBtE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,iBA6ChF"}