sqlew 3.7.3 → 3.8.0

package/dist/tools/help/actions/batch-guide.js

@@ -0,0 +1,59 @@
+/**
+ * Help Tool - batch_guide Action
+ * Get guidance for batch operations
+ */
+import { getAdapter } from '../../../database.js';
+/**
+ * Get batch operation guide
+ * Queries database for batch-specific examples and adds best practices
+ */
+export async function batchGuide(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    const db = actualAdapter.getKnex();
+    try {
+        // Parse operation (e.g., "task.create_batch" → tool=task, action=create_batch)
+        const parts = params.operation.split('.');
+        if (parts.length !== 2) {
+            return {
+                error: 'Operation must be in format "tool.action" (e.g., "task.create_batch")'
+            };
+        }
+        const [tool, action] = parts;
+        // Query for batch-specific examples
+        const examples = await db('t_help_action_examples')
+            .join('m_help_actions', 't_help_action_examples.action_id', 'm_help_actions.action_id')
+            .where('m_help_actions.tool_name', tool)
+            .where('m_help_actions.action_name', action)
+            .select('t_help_action_examples.example_title as title', 't_help_action_examples.example_code as code', 't_help_action_examples.explanation');
+        if (examples.length === 0) {
+            return {
+                error: `No examples found for operation "${params.operation}". Check tool and action names.`
+            };
+        }
+        // Curated best practices for batch operations
+        const bestPractices = [
+            'Limit batch size to 20 items for optimal performance',
+            'Use consistent metadata (layer, priority, tags) across batch',
+            'Validate all items before submitting batch to avoid partial failures',
+            'Consider transaction boundaries for data integrity',
+            'Use atomic: true flag if all items must succeed or none'
+        ];
+        const helpExamples = examples.map((ex) => ({
+            title: ex.title,
+            code: ex.code,
+            explanation: ex.explanation
+        }));
+        return {
+            operation: params.operation,
+            description: `Batch operation guide for ${tool}.${action}`,
+            syntax: examples[0]?.code || '',
+            best_practices: bestPractices,
+            examples: helpExamples
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { error: `Failed to query batch guide: ${message}` };
+    }
+}
+//# sourceMappingURL=batch-guide.js.map

package/dist/tools/help/actions/batch-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-guide.js","sourceRoot":"","sources":["../../../../src/tools/help/actions/batch-guide.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAA4B,EAC5B,OAAyB;IAEzB,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,EAAE,CAAC;IAC9C,MAAM,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC;IAEnC,IAAI,CAAC;QACH,+EAA+E;QAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,KAAK,EAAE,uEAAuE;aAC/E,CAAC;QACJ,CAAC;QAED,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;QAE7B,oCAAoC;QACpC,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,wBAAwB,CAAC;aAChD,IAAI,CAAC,gBAAgB,EAAE,kCAAkC,EAAE,0BAA0B,CAAC;aACtF,KAAK,CAAC,0BAA0B,EAAE,IAAI,CAAC;aACvC,KAAK,CAAC,4BAA4B,EAAE,MAAM,CAAC;aAC3C,MAAM,CACL,+CAA+C,EAC/C,6CAA6C,EAC7C,oCAAoC,CACrC,CAAC;QAEJ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACL,KAAK,EAAE,oCAAoC,MAAM,CAAC,SAAS,iCAAiC;aAC7F,CAAC;QACJ,CAAC;QAED,8CAA8C;QAC9C,MAAM,aAAa,GAAG;YACpB,sDAAsD;YACtD,8DAA8D;YAC9D,sEAAsE;YACtE,oDAAoD;YACpD,yDAAyD;SAC1D,CAAC;QAEF,MAAM,YAAY,GAAkB,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAO,EAAE,EAAE,CAAC,CAAC;YAC7D,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,WAAW,EAAE,EAAE,CAAC,WAAW;SAC5B,CAAC,CAAC,CAAC;QAEJ,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,WAAW,EAAE,6BAA6B,IAAI,IAAI,MAAM,EAAE;YAC1D,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE;YAC/B,cAAc,EAAE,aAAa;YAC7B,QAAQ,EAAE,YAAY;SACvB,CAAC;IAEJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,EAAE,KAAK,EAAE,gCAAgC,OAAO,EAAE,EAAE,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/dist/tools/help/actions/error-recovery.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Help Tool - error_recovery Action
+ * Analyze errors and suggest fixes
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import { HelpErrorRecoveryParams, HelpErrorRecoveryResult } from '../types.js';
+/**
+ * Get error recovery suggestions
+ * Pattern matches common errors and provides solutions
+ */
+export declare function errorRecovery(params: HelpErrorRecoveryParams, adapter?: DatabaseAdapter): Promise<HelpErrorRecoveryResult>;
+//# sourceMappingURL=error-recovery.d.ts.map

package/dist/tools/help/actions/error-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-recovery.d.ts","sourceRoot":"","sources":["../../../../src/tools/help/actions/error-recovery.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAsF/E;;;GAGG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,uBAAuB,CAAC,CA4BlC"}

package/dist/tools/help/actions/error-recovery.js

@@ -0,0 +1,107 @@
+/**
+ * Help Tool - error_recovery Action
+ * Analyze errors and suggest fixes
+ */
+import { getAdapter } from '../../../database.js';
+const ERROR_PATTERNS = [
+    {
+        pattern: /action.*required|missing.*action/i,
+        cause: 'Missing "action" parameter in tool call',
+        solution: 'Every sqlew tool call must include action parameter',
+        example: 'decision({ action: "set", key: "...", value: "..." })',
+        prevention: 'Always use help({ action: "query_action", ... }) to verify syntax before calling'
+    },
+    {
+        pattern: /tags.*must.*array/i,
+        cause: 'Tags parameter passed as string instead of array',
+        solution: 'Use array syntax for tags',
+        example: 'tags: ["security", "api"]  // Not "security,api"',
+        prevention: 'Check help({ action: "query_params", ... }) for correct parameter types'
+    },
+    {
+        pattern: /constraint.*key.*not found|decision.*not found/i,
+        cause: 'Referenced decision key does not exist',
+        solution: 'Create decision first, then reference it in constraint',
+        example: 'decision({ action: "set", key: "my-decision", ... })\nconstraint({ action: "add", ..., related_context_key: "my-decision" })',
+        prevention: 'Use decision({ action: "list" }) to verify key exists before referencing'
+    },
+    {
+        pattern: /file_actions.*required/i,
+        cause: 'FILE_REQUIRED layer task missing file_actions parameter',
+        solution: 'Include file_actions array for presentation, business, data, infrastructure, cross-cutting, documentation layers',
+        example: 'task({ action: "create", layer: "business", file_actions: [{ action: "create", path: "src/file.ts" }] })',
+        prevention: 'Use file_actions: [] for planning tasks, or use planning/coordination/review layers for non-file work'
+    },
+    {
+        pattern: /layer.*invalid|layer.*not found/i,
+        cause: 'Invalid layer name specified',
+        solution: 'Use one of the 9 valid layers',
+        example: 'Valid layers: presentation, business, data, infrastructure, cross-cutting, documentation, planning, coordination, review',
+        prevention: 'Check help({ action: "query_tool", tool: "task" }) for layer descriptions'
+    },
+    {
+        pattern: /task.*not found|task_id.*invalid/i,
+        cause: 'Referenced task does not exist',
+        solution: 'Verify task exists before linking or updating',
+        example: 'task({ action: "list" })  // Find valid task IDs first',
+        prevention: 'Use task({ action: "get", task_id: ... }) to verify task exists'
+    },
+    {
+        pattern: /circular.*dependency|dependency.*cycle/i,
+        cause: 'Task dependency creates a circular reference',
+        solution: 'Remove dependency that creates the cycle',
+        example: 'task({ action: "remove_dependency", task_id: ..., depends_on: ... })',
+        prevention: 'Plan task dependencies in a directed acyclic graph (DAG)'
+    },
+    {
+        pattern: /agent.*not found/i,
+        cause: 'Referenced agent does not exist',
+        solution: 'Agent will be auto-created on first use, or verify agent name',
+        example: 'task({ action: "create", assigned_agent: "my-agent", ... })',
+        prevention: 'Agent names are auto-registered; use consistent naming'
+    },
+    {
+        pattern: /priority.*invalid/i,
+        cause: 'Invalid priority value specified',
+        solution: 'Use one of: low, medium, high, critical',
+        example: 'task({ action: "create", priority: "high", ... })',
+        prevention: 'Check help({ action: "query_params", tool: "task", target_action: "create" }) for valid enum values'
+    },
+    {
+        pattern: /database.*locked|SQLITE_BUSY/i,
+        cause: 'Database is locked by another process or transaction',
+        solution: 'Wait briefly and retry, or check for long-running transactions',
+        example: 'Retry after 100-500ms, or use stats({ action: "flush" }) to checkpoint WAL',
+        prevention: 'Avoid long-running transactions, use batch operations for bulk inserts'
+    }
+];
+/**
+ * Get error recovery suggestions
+ * Pattern matches common errors and provides solutions
+ */
+export async function errorRecovery(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    // Find matching error pattern
+    const match = ERROR_PATTERNS.find(p => p.pattern.test(params.error_message));
+    if (match) {
+        return {
+            error: params.error_message,
+            cause: match.cause,
+            solution: match.solution,
+            example: match.example,
+            prevention: match.prevention
+        };
+    }
+    // Generic fallback for unknown errors
+    const toolHint = params.tool
+        ? `help({ action: "query_tool", tool: "${params.tool}" })`
+        : 'help({ action: "query_tool", tool: "..." })';
+    return {
+        error: params.error_message,
+        cause: 'Unknown error - pattern not recognized',
+        solution: `Check tool documentation: ${toolHint}`,
+        example: 'help({ action: "query_action", tool: "decision", target_action: "set" })',
+        prevention: 'Always verify syntax with help tool before calling unfamiliar actions'
+    };
+}
+//# sourceMappingURL=error-recovery.js.map

package/dist/tools/help/actions/error-recovery.js.map

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

package/dist/tools/help/actions/query-action.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - query_action Action
+ * Get action documentation with parameters and examples
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import { HelpQueryActionParams, HelpActionResult } from '../types.js';
+/**
+ * Query single action with parameters and examples
+ * Reuses existing queryHelpAction from help-queries.ts
+ */
+export declare function queryAction(params: HelpQueryActionParams, adapter?: DatabaseAdapter): Promise<HelpActionResult | {
+    error: string;
+    available_actions?: string[];
+}>;
+//# sourceMappingURL=query-action.d.ts.map

package/dist/tools/help/actions/query-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-action.d.ts","sourceRoot":"","sources":["../../../../src/tools/help/actions/query-action.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEtE;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,gBAAgB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAG7E"}

package/dist/tools/help/actions/query-action.js

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - query_action Action
+ * Get action documentation with parameters and examples
+ */
+import { getAdapter } from '../../../database.js';
+import { queryHelpAction } from '../../help-queries.js';
+/**
+ * Query single action with parameters and examples
+ * Reuses existing queryHelpAction from help-queries.ts
+ */
+export async function queryAction(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    return queryHelpAction(actualAdapter, params.tool, params.target_action);
+}
+//# sourceMappingURL=query-action.js.map

package/dist/tools/help/actions/query-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-action.js","sourceRoot":"","sources":["../../../../src/tools/help/actions/query-action.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAA6B,EAC7B,OAAyB;IAEzB,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,EAAE,CAAC;IAC9C,OAAO,eAAe,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;AAC3E,CAAC"}

package/dist/tools/help/actions/query-params.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - query_params Action
+ * Get parameter list only (quick reference)
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import { HelpQueryParamsParams, HelpParamsResult } from '../types.js';
+/**
+ * Query parameter list only for quick reference
+ * Reuses existing queryHelpParams from help-queries.ts
+ */
+export declare function queryParams(params: HelpQueryParamsParams, adapter?: DatabaseAdapter): Promise<HelpParamsResult | {
+    error: string;
+    available_actions?: string[];
+}>;
+//# sourceMappingURL=query-params.d.ts.map

package/dist/tools/help/actions/query-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-params.d.ts","sourceRoot":"","sources":["../../../../src/tools/help/actions/query-params.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEtE;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,gBAAgB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAG7E"}

package/dist/tools/help/actions/query-params.js

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - query_params Action
+ * Get parameter list only (quick reference)
+ */
+import { getAdapter } from '../../../database.js';
+import { queryHelpParams } from '../../help-queries.js';
+/**
+ * Query parameter list only for quick reference
+ * Reuses existing queryHelpParams from help-queries.ts
+ */
+export async function queryParams(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    return queryHelpParams(actualAdapter, params.tool, params.target_action);
+}
+//# sourceMappingURL=query-params.js.map

package/dist/tools/help/actions/query-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-params.js","sourceRoot":"","sources":["../../../../src/tools/help/actions/query-params.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAA6B,EAC7B,OAAyB;IAEzB,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,EAAE,CAAC;IAC9C,OAAO,eAAe,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;AAC3E,CAAC"}

package/dist/tools/help/actions/query-tool.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - query_tool Action
+ * Get tool overview and all actions
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import { HelpQueryToolParams, HelpToolResult } from '../types.js';
+/**
+ * Query tool overview and all actions
+ * Reuses existing queryHelpTool from help-queries.ts
+ */
+export declare function queryTool(params: HelpQueryToolParams, adapter?: DatabaseAdapter): Promise<HelpToolResult | {
+    error: string;
+    available_tools?: string[];
+}>;
+//# sourceMappingURL=query-tool.d.ts.map

package/dist/tools/help/actions/query-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-tool.d.ts","sourceRoot":"","sources":["../../../../src/tools/help/actions/query-tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElE;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,mBAAmB,EAC3B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAGzE"}

package/dist/tools/help/actions/query-tool.js

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - query_tool Action
+ * Get tool overview and all actions
+ */
+import { getAdapter } from '../../../database.js';
+import { queryHelpTool } from '../../help-queries.js';
+/**
+ * Query tool overview and all actions
+ * Reuses existing queryHelpTool from help-queries.ts
+ */
+export async function queryTool(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    return queryHelpTool(actualAdapter, params.tool);
+}
+//# sourceMappingURL=query-tool.js.map

package/dist/tools/help/actions/query-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-tool.js","sourceRoot":"","sources":["../../../../src/tools/help/actions/query-tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGtD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAA2B,EAC3B,OAAyB;IAEzB,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,EAAE,CAAC;IAC9C,OAAO,aAAa,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC"}

package/dist/tools/help/actions/workflow-hints.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Help Tool - workflow_hints Action
+ * Get common next actions after current action
+ */
+import { DatabaseAdapter } from '../../../adapters/index.js';
+import { HelpWorkflowHintsParams, HelpNextActionsResult } from '../types.js';
+/**
+ * Get workflow hints (common next actions)
+ * Reuses existing queryHelpNextActions from help-queries.ts
+ */
+export declare function workflowHints(params: HelpWorkflowHintsParams, adapter?: DatabaseAdapter): Promise<HelpNextActionsResult | {
+    error: string;
+}>;
+//# sourceMappingURL=workflow-hints.d.ts.map

package/dist/tools/help/actions/workflow-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-hints.d.ts","sourceRoot":"","sources":["../../../../src/tools/help/actions/workflow-hints.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE7E;;;GAGG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,qBAAqB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAGpD"}

package/dist/tools/help/actions/workflow-hints.js

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - workflow_hints Action
+ * Get common next actions after current action
+ */
+import { getAdapter } from '../../../database.js';
+import { queryHelpNextActions } from '../../help-queries.js';
+/**
+ * Get workflow hints (common next actions)
+ * Reuses existing queryHelpNextActions from help-queries.ts
+ */
+export async function workflowHints(params, adapter) {
+    const actualAdapter = adapter ?? getAdapter();
+    return queryHelpNextActions(actualAdapter, params.tool, params.current_action);
+}
+//# sourceMappingURL=workflow-hints.js.map

package/dist/tools/help/actions/workflow-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-hints.js","sourceRoot":"","sources":["../../../../src/tools/help/actions/workflow-hints.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAG7D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAA+B,EAC/B,OAAyB;IAEzB,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,EAAE,CAAC;IAC9C,OAAO,oBAAoB,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;AACjF,CAAC"}

package/dist/tools/help/help/example.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Help Tool - example Action
+ * Provides usage examples for the help tool
+ */
+export declare function helpExample(): any;
+//# sourceMappingURL=example.d.ts.map

package/dist/tools/help/help/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../../../src/tools/help/help/example.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,WAAW,IAAI,GAAG,CAgEjC"}

package/dist/tools/help/help/example.js

@@ -0,0 +1,70 @@
+/**
+ * Help Tool - example Action
+ * Provides usage examples for the help tool
+ */
+export function helpExample() {
+    return {
+        tool: 'help',
+        examples: [
+            {
+                title: 'Get detailed help for decision.set action',
+                code: 'help({ action: "query_action", tool: "decision", target_action: "set" })',
+                explanation: 'Returns full documentation including parameters, types, and code examples for the set action',
+                complexity: 'basic',
+                expected_output: 'Action description, parameter list with types and requirements, code examples'
+            },
+            {
+                title: 'Quick parameter reference for task.create',
+                code: 'help({ action: "query_params", tool: "task", target_action: "create" })',
+                explanation: 'Returns just the parameter list without examples - useful for quick lookup',
+                complexity: 'basic',
+                expected_output: 'Parameter list with names, types, required flags, and descriptions'
+            },
+            {
+                title: 'Get overview of constraint tool',
+                code: 'help({ action: "query_tool", tool: "constraint" })',
+                explanation: 'Returns tool description and list of all available actions',
+                complexity: 'basic',
+                expected_output: 'Tool description and action list with brief descriptions'
+            },
+            {
+                title: 'Find what to do after creating a task',
+                code: 'help({ action: "workflow_hints", tool: "task", current_action: "create" })',
+                explanation: 'Suggests common next actions based on typical workflows (e.g., link, add_dependency)',
+                complexity: 'intermediate',
+                expected_output: 'List of suggested next actions with frequency and context'
+            },
+            {
+                title: 'Get guidance for batch task creation',
+                code: 'help({ action: "batch_guide", operation: "task.create_batch" })',
+                explanation: 'Returns best practices and examples for creating multiple tasks at once',
+                complexity: 'intermediate',
+                expected_output: 'Batch operation syntax, best practices, and code examples'
+            },
+            {
+                title: 'Troubleshoot missing action parameter error',
+                code: 'help({ action: "error_recovery", error_message: "action parameter is required", tool: "decision" })',
+                explanation: 'Analyzes error message and provides cause, solution, example, and prevention tips',
+                complexity: 'intermediate',
+                expected_output: 'Error analysis with cause, solution, working example, and prevention strategy'
+            },
+            {
+                title: 'Recover from file_actions validation error',
+                code: 'help({ action: "error_recovery", error_message: "file_actions required for FILE_REQUIRED layer" })',
+                explanation: 'Explains FILE_REQUIRED vs FILE_OPTIONAL layers and how to fix the error',
+                complexity: 'advanced',
+                expected_output: 'Layer system explanation, solution with file_actions example, layer selection guidance'
+            }
+        ],
+        tips: [
+            'Use query_action when you need full details including examples',
+            'Use query_params when you just need a quick parameter lookup',
+            'Use query_tool to discover all actions available for a tool',
+            'Use workflow_hints to learn typical action sequences',
+            'Use batch_guide before performing batch operations',
+            'Use error_recovery to troubleshoot errors instead of guessing'
+        ],
+        token_savings: 'Help tool returns 80-95% less tokens than legacy help actions by only returning requested information'
+    };
+}
+//# sourceMappingURL=example.js.map

package/dist/tools/help/help/example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.js","sourceRoot":"","sources":["../../../../src/tools/help/help/example.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE;YACR;gBACE,KAAK,EAAE,2CAA2C;gBAClD,IAAI,EAAE,0EAA0E;gBAChF,WAAW,EAAE,8FAA8F;gBAC3G,UAAU,EAAE,OAAO;gBACnB,eAAe,EAAE,+EAA+E;aACjG;YACD;gBACE,KAAK,EAAE,2CAA2C;gBAClD,IAAI,EAAE,yEAAyE;gBAC/E,WAAW,EAAE,4EAA4E;gBACzF,UAAU,EAAE,OAAO;gBACnB,eAAe,EAAE,oEAAoE;aACtF;YACD;gBACE,KAAK,EAAE,iCAAiC;gBACxC,IAAI,EAAE,oDAAoD;gBAC1D,WAAW,EAAE,4DAA4D;gBACzE,UAAU,EAAE,OAAO;gBACnB,eAAe,EAAE,0DAA0D;aAC5E;YACD;gBACE,KAAK,EAAE,uCAAuC;gBAC9C,IAAI,EAAE,4EAA4E;gBAClF,WAAW,EAAE,sFAAsF;gBACnG,UAAU,EAAE,cAAc;gBAC1B,eAAe,EAAE,2DAA2D;aAC7E;YACD;gBACE,KAAK,EAAE,sCAAsC;gBAC7C,IAAI,EAAE,iEAAiE;gBACvE,WAAW,EAAE,yEAAyE;gBACtF,UAAU,EAAE,cAAc;gBAC1B,eAAe,EAAE,2DAA2D;aAC7E;YACD;gBACE,KAAK,EAAE,6CAA6C;gBACpD,IAAI,EAAE,qGAAqG;gBAC3G,WAAW,EAAE,mFAAmF;gBAChG,UAAU,EAAE,cAAc;gBAC1B,eAAe,EAAE,+EAA+E;aACjG;YACD;gBACE,KAAK,EAAE,4CAA4C;gBACnD,IAAI,EAAE,oGAAoG;gBAC1G,WAAW,EAAE,yEAAyE;gBACtF,UAAU,EAAE,UAAU;gBACtB,eAAe,EAAE,wFAAwF;aAC1G;SACF;QACD,IAAI,EAAE;YACJ,gEAAgE;YAChE,8DAA8D;YAC9D,6DAA6D;YAC7D,sDAAsD;YACtD,oDAAoD;YACpD,+DAA+D;SAChE;QACD,aAAa,EAAE,uGAAuG;KACvH,CAAC;AACJ,CAAC"}

package/dist/tools/help/help/help.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Help Tool - help Action
+ * Provides help documentation for the help tool itself
+ */
+export declare function helpHelp(): any;
+//# sourceMappingURL=help.d.ts.map

package/dist/tools/help/help/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../../src/tools/help/help/help.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,QAAQ,IAAI,GAAG,CA6D9B"}

package/dist/tools/help/help/help.js

@@ -0,0 +1,67 @@
+/**
+ * Help Tool - help Action
+ * Provides help documentation for the help tool itself
+ */
+export function helpHelp() {
+    return {
+        tool: 'help',
+        description: 'Query action documentation, parameters, and workflow guidance',
+        actions: [
+            {
+                name: 'query_action',
+                description: 'Get action documentation with parameters and examples',
+                parameters: [
+                    { name: 'tool', type: 'string', required: true, description: 'Target tool name' },
+                    { name: 'target_action', type: 'string', required: true, description: 'Target action name' }
+                ],
+                example: 'help({ action: "query_action", tool: "decision", target_action: "set" })'
+            },
+            {
+                name: 'query_params',
+                description: 'Get parameter list only (quick reference)',
+                parameters: [
+                    { name: 'tool', type: 'string', required: true, description: 'Target tool name' },
+                    { name: 'target_action', type: 'string', required: true, description: 'Target action name' }
+                ],
+                example: 'help({ action: "query_params", tool: "task", target_action: "create" })'
+            },
+            {
+                name: 'query_tool',
+                description: 'Get tool overview and all actions',
+                parameters: [
+                    { name: 'tool', type: 'string', required: true, description: 'Target tool name' }
+                ],
+                example: 'help({ action: "query_tool", tool: "constraint" })'
+            },
+            {
+                name: 'workflow_hints',
+                description: 'Get common next actions after current action',
+                parameters: [
+                    { name: 'tool', type: 'string', required: true, description: 'Target tool name' },
+                    { name: 'current_action', type: 'string', required: true, description: 'Current action name' }
+                ],
+                example: 'help({ action: "workflow_hints", tool: "task", current_action: "create" })'
+            },
+            {
+                name: 'batch_guide',
+                description: 'Get guidance for batch operations',
+                parameters: [
+                    { name: 'operation', type: 'string', required: true, description: 'Batch operation name (e.g., "task.create_batch")' }
+                ],
+                example: 'help({ action: "batch_guide", operation: "task.create_batch" })'
+            },
+            {
+                name: 'error_recovery',
+                description: 'Get suggestions for common errors',
+                parameters: [
+                    { name: 'error_message', type: 'string', required: true, description: 'Error message to analyze' },
+                    { name: 'tool', type: 'string', required: false, description: 'Optional tool context' }
+                ],
+                example: 'help({ action: "error_recovery", error_message: "action parameter is required" })'
+            }
+        ],
+        usage_note: 'This tool provides help for all sqlew tools. Use query_action for detailed action help, query_params for quick parameter reference, query_tool for tool overview.',
+        token_efficiency: 'Returns only requested information (80-95% token reduction vs legacy help)'
+    };
+}
+//# sourceMappingURL=help.js.map

package/dist/tools/help/help/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../../../src/tools/help/help/help.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,QAAQ;IACtB,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,+DAA+D;QAC5E,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,cAAc;gBACpB,WAAW,EAAE,uDAAuD;gBACpE,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE;oBACjF,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE;iBAC7F;gBACD,OAAO,EAAE,0EAA0E;aACpF;YACD;gBACE,IAAI,EAAE,cAAc;gBACpB,WAAW,EAAE,2CAA2C;gBACxD,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE;oBACjF,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE;iBAC7F;gBACD,OAAO,EAAE,yEAAyE;aACnF;YACD;gBACE,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,mCAAmC;gBAChD,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE;iBAClF;gBACD,OAAO,EAAE,oDAAoD;aAC9D;YACD;gBACE,IAAI,EAAE,gBAAgB;gBACtB,WAAW,EAAE,8CAA8C;gBAC3D,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE;oBACjF,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,qBAAqB,EAAE;iBAC/F;gBACD,OAAO,EAAE,4EAA4E;aACtF;YACD;gBACE,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,mCAAmC;gBAChD,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,kDAAkD,EAAE;iBACvH;gBACD,OAAO,EAAE,iEAAiE;aAC3E;YACD;gBACE,IAAI,EAAE,gBAAgB;gBACtB,WAAW,EAAE,mCAAmC;gBAChD,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,0BAA0B,EAAE;oBAClG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAE;iBACxF;gBACD,OAAO,EAAE,mFAAmF;aAC7F;SACF;QACD,UAAU,EAAE,mKAAmK;QAC/K,gBAAgB,EAAE,4EAA4E;KAC/F,CAAC;AACJ,CAAC"}

package/dist/tools/help/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Help Tool - Barrel Export
+ * Exports all help tool actions and utilities
+ */
+export { queryAction } from './actions/query-action.js';
+export { queryParams } from './actions/query-params.js';
+export { queryTool } from './actions/query-tool.js';
+export { workflowHints } from './actions/workflow-hints.js';
+export { batchGuide } from './actions/batch-guide.js';
+export { errorRecovery } from './actions/error-recovery.js';
+export { helpHelp } from './help/help.js';
+export { helpExample } from './help/example.js';
+export type { HelpAction, HelpParams, HelpQueryActionParams, HelpQueryParamsParams, HelpQueryToolParams, HelpWorkflowHintsParams, HelpBatchGuideParams, HelpErrorRecoveryParams, HelpActionResult, HelpParamsResult, HelpToolResult, HelpNextActionsResult, HelpBatchGuideResult, HelpErrorRecoveryResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/help/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/help/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,YAAY,EACV,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACxB,MAAM,YAAY,CAAC"}

package/dist/tools/help/index.js

@@ -0,0 +1,15 @@
+/**
+ * Help Tool - Barrel Export
+ * Exports all help tool actions and utilities
+ */
+// Action exports
+export { queryAction } from './actions/query-action.js';
+export { queryParams } from './actions/query-params.js';
+export { queryTool } from './actions/query-tool.js';
+export { workflowHints } from './actions/workflow-hints.js';
+export { batchGuide } from './actions/batch-guide.js';
+export { errorRecovery } from './actions/error-recovery.js';
+// Help/Example exports
+export { helpHelp } from './help/help.js';
+export { helpExample } from './help/example.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/help/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/help/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,uBAAuB;AACvB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}