@synergenius/flow-weaver 0.2.0

package/dist/doc-metadata/extractors/plugin-api.js

@@ -0,0 +1,279 @@
+/**
+ * Description layer for external plugin API schemas.
+ *
+ * These arrays provide human-readable descriptions for fields that are
+ * extracted dynamically from Zod schemas at documentation build time.
+ * Field names come from the live schemas (code-tied), descriptions from here.
+ */
+/** Field descriptions for pluginDefinitionSchema (plugin-artifact.yaml) */
+export const PLUGIN_DEFINITION_FIELDS = [
+    {
+        name: 'name',
+        type: 'string',
+        required: true,
+        description: 'Unique plugin identifier (e.g., "my-analytics-plugin")',
+    },
+    {
+        name: 'version',
+        type: 'string',
+        required: true,
+        description: 'Semantic version (e.g., "1.0.0")',
+    },
+    {
+        name: 'description',
+        type: 'string',
+        required: true,
+        description: 'Human-readable plugin description',
+    },
+    {
+        name: 'entry',
+        type: 'object',
+        required: true,
+        description: 'Entry point paths for client and system modules',
+        children: [
+            {
+                name: 'client',
+                type: 'string',
+                required: true,
+                description: 'Client-side entry (e.g., "src/client.tsx")',
+            },
+            {
+                name: 'system',
+                type: 'string',
+                required: false,
+                description: 'Server-side entry (e.g., "src/system.ts")',
+            },
+        ],
+    },
+    {
+        name: 'dependencies',
+        type: 'object',
+        required: false,
+        description: 'Plugin and system dependencies',
+        children: [
+            {
+                name: 'plugins',
+                type: 'string[]',
+                required: false,
+                description: 'Required plugin IDs',
+            },
+            {
+                name: 'system',
+                type: 'string[]',
+                required: false,
+                description: 'Required system modules',
+            },
+        ],
+    },
+    {
+        name: 'capabilities',
+        type: 'object',
+        required: true,
+        description: 'Security capability declarations (see Capabilities section)',
+    },
+];
+/** Field descriptions for pluginCapabilitiesSchema */
+export const PLUGIN_CAPABILITIES = [
+    {
+        name: 'filesystem',
+        type: 'object',
+        required: false,
+        description: 'File system access',
+        children: [
+            {
+                name: 'allowed',
+                type: 'boolean',
+                required: true,
+                description: 'Enable filesystem access',
+            },
+            {
+                name: 'paths',
+                type: 'string[]',
+                required: false,
+                description: 'Allowed path patterns',
+            },
+            {
+                name: 'operations',
+                type: 'enum[]',
+                required: false,
+                description: 'Allowed operations',
+                enum: ['read', 'write', 'delete'],
+            },
+        ],
+    },
+    {
+        name: 'network',
+        type: 'object',
+        required: false,
+        description: 'Network access',
+        children: [
+            {
+                name: 'allowed',
+                type: 'boolean',
+                required: true,
+                description: 'Enable network access',
+            },
+            {
+                name: 'domains',
+                type: 'string[]',
+                required: false,
+                description: 'Allowed domains',
+            },
+            {
+                name: 'protocols',
+                type: 'enum[]',
+                required: false,
+                description: 'Allowed protocols',
+                enum: ['http', 'https', 'ws', 'wss'],
+            },
+        ],
+    },
+    {
+        name: 'process',
+        type: 'object',
+        required: false,
+        description: 'Process control',
+        children: [
+            {
+                name: 'allowed',
+                type: 'boolean',
+                required: true,
+                description: 'Enable process access',
+            },
+            {
+                name: 'maxMemory',
+                type: 'number',
+                required: false,
+                description: 'Memory limit in bytes',
+            },
+            {
+                name: 'timeout',
+                type: 'number',
+                required: false,
+                description: 'Execution timeout in ms',
+            },
+        ],
+    },
+    {
+        name: 'interop',
+        type: 'object',
+        required: false,
+        description: 'Inter-plugin communication',
+        children: [
+            {
+                name: 'allowed',
+                type: 'boolean',
+                required: true,
+                description: 'Enable inter-plugin calls',
+            },
+            {
+                name: 'plugins',
+                type: 'string[]',
+                required: false,
+                description: 'Allowed plugin IDs',
+            },
+        ],
+    },
+];
+/** Field descriptions for pluginComponentConfigSchema */
+export const PLUGIN_COMPONENT_CONFIG_FIELDS = [
+    {
+        name: 'name',
+        type: 'string',
+        required: true,
+        description: 'Component identifier (unique within plugin)',
+    },
+    {
+        name: 'displayName',
+        type: 'string',
+        required: true,
+        description: 'Label shown in UI headers and tabs',
+    },
+    {
+        name: 'description',
+        type: 'string',
+        required: false,
+        description: 'Tooltip or summary text',
+    },
+    {
+        name: 'icon',
+        type: 'string',
+        required: false,
+        description: 'Icon name from the icon catalog (camelCase)',
+    },
+    {
+        name: 'area',
+        type: 'enum',
+        required: true,
+        description: 'Placement area for the component',
+    },
+];
+/** Description map for pluginComponentAreaSchema enum values */
+export const PLUGIN_COMPONENT_AREAS = {
+    sidebar: 'Left dock zone (alongside project, documentation)',
+    main: 'Center content area',
+    toolbar: 'Rendered inline in toolbar — not window-compatible',
+    modal: 'Overlay dialog — not window-compatible',
+    panel: 'Right dock zone (alongside history, deployment)',
+};
+/** Categorized UI Kit components available to external plugins */
+export const PLUGIN_UI_KIT_COMPONENTS = {
+    Display: [
+        'Chip',
+        'WorkflowDiagram',
+        'NodeDiagram',
+        'CodeBlock',
+        'CodeSnippet',
+        'CountBadge',
+        'EmptyState',
+        'Header',
+        'Icon',
+        'InfoSection',
+        'JsonViewer',
+        'KeyValueRow',
+        'PanelHeader',
+        'PanelTitle',
+        'PortTag',
+        'ProfileBadge',
+        'StatusCard',
+        'StatusDot',
+        'StatusIndicator',
+        'Table',
+        'Tag',
+        'TruncateText',
+        'Typography',
+    ],
+    Feedback: ['Banner', 'ErrorBoundary', 'LoadingContainer', 'LoadingSpinner', 'Tooltip'],
+    Input: [
+        'Button',
+        'ButtonGroup',
+        'IconButton',
+        'Calendar',
+        'Checkbox',
+        'CodeEditor',
+        'Input',
+        'Slider',
+        'StatusChip',
+        'Switch',
+        'ToggleGroup',
+        'Tree',
+        'ExpressionControl',
+        'SelectableCard',
+        'NodeIconPicker',
+    ],
+    Layout: [
+        'CollapsibleSection',
+        'Divider',
+        'Draggable',
+        'Flex',
+        'Menu',
+        'MenuItem',
+        'Modal',
+        'ResponsiveContainer',
+        'Tabs',
+        'Window',
+    ],
+    Navigation: ['Breadcrumbs', 'Stepper'],
+    Hooks: ['useVerticalResize', 'useStableCallback', 'useDebouncedLoading'],
+};
+//# sourceMappingURL=plugin-api.js.map

package/dist/doc-metadata/index.d.ts

@@ -0,0 +1,5 @@
+export { extractMcpTools, MCP_TOOLS } from './extractors/mcp-tools.js';
+export { extractCliCommands, CLI_COMMANDS } from './extractors/cli-commands.js';
+export { PLUGIN_DEFINITION_FIELDS, PLUGIN_CAPABILITIES, PLUGIN_COMPONENT_CONFIG_FIELDS, PLUGIN_COMPONENT_AREAS, PLUGIN_UI_KIT_COMPONENTS, } from './extractors/plugin-api.js';
+export type { TMcpToolDoc, TMcpToolParam, TPluginApiFieldDoc, TCliCommandDoc, TCliOptionDoc } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/doc-metadata/index.js

@@ -0,0 +1,4 @@
+export { extractMcpTools, MCP_TOOLS } from './extractors/mcp-tools.js';
+export { extractCliCommands, CLI_COMMANDS } from './extractors/cli-commands.js';
+export { PLUGIN_DEFINITION_FIELDS, PLUGIN_CAPABILITIES, PLUGIN_COMPONENT_CONFIG_FIELDS, PLUGIN_COMPONENT_AREAS, PLUGIN_UI_KIT_COMPONENTS, } from './extractors/plugin-api.js';
+//# sourceMappingURL=index.js.map

package/dist/doc-metadata/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Types for documentation metadata extraction
+ */
+/**
+ * Documentation for a Flow Weaver JSDoc annotation
+ */
+export interface TAnnotationDoc {
+    /** Annotation name (e.g., '@input', '@connect') */
+    name: string;
+    /** Category for grouping (marker, port, workflow, metadata, pattern, standard) */
+    category: 'marker' | 'port' | 'workflow' | 'metadata' | 'pattern' | 'standard';
+    /** Syntax example */
+    syntax: string;
+    /** Human-readable description */
+    description: string;
+    /** Text to insert (for IDE completions) */
+    insertText: string;
+    /** Insert text format ('plain' or 'snippet') */
+    insertTextFormat: 'plain' | 'snippet';
+}
+/**
+ * Documentation for annotation modifiers (e.g., [order:N], [placement:TOP])
+ */
+export interface TAnnotationModifierDoc {
+    /** Modifier name */
+    name: string;
+    /** Syntax example */
+    syntax: string;
+    /** Human-readable description */
+    description: string;
+    /** Enum values if applicable */
+    enum?: string[];
+}
+/**
+ * Documentation for an MCP tool
+ */
+export interface TMcpToolDoc {
+    /** Tool name (e.g., 'fw_describe') */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Category for grouping */
+    category: 'query' | 'template' | 'pattern' | 'modify' | 'editor' | 'execution';
+    /** Tool parameters */
+    params: TMcpToolParam[];
+}
+/**
+ * Documentation for an MCP tool parameter
+ */
+export interface TMcpToolParam {
+    /** Parameter name */
+    name: string;
+    /** Parameter type */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Human-readable description */
+    description: string;
+    /** Whether the parameter is required */
+    required: boolean;
+    /** Enum values if applicable */
+    enum?: string[];
+}
+/**
+ * Documentation for a plugin API field (schema-tied description layer)
+ */
+export interface TPluginApiFieldDoc {
+    /** Field name as it appears in the Zod schema */
+    name: string;
+    /** Display type string */
+    type: string;
+    /** Whether the field is required */
+    required: boolean;
+    /** Human-readable description */
+    description: string;
+    /** Enum values if applicable */
+    enum?: string[];
+    /** Nested child fields for object types */
+    children?: TPluginApiFieldDoc[];
+}
+/**
+ * Documentation for a CLI command option/flag
+ */
+export interface TCliOptionDoc {
+    /** Flag string, e.g. "-o, --output" */
+    flags: string;
+    /** Argument placeholder, e.g. "<path>" or "esm|cjs|auto" */
+    arg?: string;
+    /** Human-readable description */
+    description: string;
+    /** Default value shown as "(default: value)" */
+    defaultValue?: string;
+    /** Mutual exclusivity group — options sharing the same group become a single select */
+    exclusive?: string;
+    /** Whether this option is required */
+    required?: boolean;
+}
+/**
+ * Documentation for a CLI command
+ */
+export interface TCliCommandDoc {
+    /** Command name, e.g. "compile", "create workflow", "ui focus-node" */
+    name: string;
+    /** Full syntax string, e.g. "flow-weaver compile <input> [options]" */
+    syntax: string;
+    /** Human-readable description */
+    description: string;
+    /** Command options/flags */
+    options: TCliOptionDoc[];
+    /** Pre-computed list items (used verbatim instead of auto-generating from options) */
+    list?: string[];
+    /** Parent group for subcommands: "create", "pattern", "ui", "plugin" */
+    group?: string;
+    /** Override list style (default: 'cli') */
+    listStyle?: string;
+    /** Valid choices for positional arguments — keyed by arg name */
+    positionalChoices?: Record<string, {
+        id: string;
+        label: string;
+    }[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/doc-metadata/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types for documentation metadata extraction
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/editor-completions/annotationValues.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Editor Completions - Annotation Values
+ *
+ * Static value completions for annotations that take specific values.
+ * E.g., @executeWhen CONJUNCTION, @flowWeaver workflow, @color purple
+ */
+import type { FlowWeaverCompletion } from './types.js';
+/**
+ * Get value completions for a specific annotation.
+ */
+export declare function getAnnotationValueCompletions(annotation: string, prefix: string): FlowWeaverCompletion[];
+//# sourceMappingURL=annotationValues.d.ts.map

package/dist/editor-completions/annotationValues.js

@@ -0,0 +1,138 @@
+/**
+ * Editor Completions - Annotation Values
+ *
+ * Static value completions for annotations that take specific values.
+ * E.g., @executeWhen CONJUNCTION, @flowWeaver workflow, @color purple
+ */
+/**
+ * Value maps for annotations that accept specific values.
+ */
+const ANNOTATION_VALUES = {
+    '@executeWhen': [
+        {
+            label: 'CONJUNCTION',
+            detail: 'All inputs required',
+            documentation: 'Node executes when ALL connected input step ports have fired.',
+            insertText: 'CONJUNCTION',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 0,
+        },
+        {
+            label: 'DISJUNCTION',
+            detail: 'Any input triggers',
+            documentation: 'Node executes when ANY connected input step port has fired.',
+            insertText: 'DISJUNCTION',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 1,
+        },
+        {
+            label: 'CUSTOM',
+            detail: 'Custom execution logic',
+            documentation: 'Node uses custom logic to determine when to execute.',
+            insertText: 'CUSTOM',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 2,
+        },
+    ],
+    '@flowWeaver': [
+        {
+            label: 'workflow',
+            detail: 'Visual workflow',
+            documentation: 'Marks this function as a Flow Weaver workflow with a visual node graph.',
+            insertText: 'workflow',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 0,
+        },
+        {
+            label: 'nodeType',
+            detail: 'Reusable node type',
+            documentation: 'Defines a reusable node type that can be instantiated in workflows.',
+            insertText: 'nodeType',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 1,
+        },
+    ],
+    '@color': [
+        {
+            label: 'purple',
+            detail: 'Purple node color',
+            insertText: 'purple',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 0,
+        },
+        {
+            label: 'blue',
+            detail: 'Blue node color',
+            insertText: 'blue',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 1,
+        },
+        {
+            label: 'green',
+            detail: 'Green node color',
+            insertText: 'green',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 2,
+        },
+        {
+            label: 'orange',
+            detail: 'Orange node color',
+            insertText: 'orange',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 3,
+        },
+        {
+            label: 'red',
+            detail: 'Red node color',
+            insertText: 'red',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 4,
+        },
+        {
+            label: 'teal',
+            detail: 'Teal node color',
+            insertText: 'teal',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 5,
+        },
+        {
+            label: 'pink',
+            detail: 'Pink node color',
+            insertText: 'pink',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 6,
+        },
+        {
+            label: 'yellow',
+            detail: 'Yellow node color',
+            insertText: 'yellow',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 7,
+        },
+    ],
+};
+/**
+ * Get value completions for a specific annotation.
+ */
+export function getAnnotationValueCompletions(annotation, prefix) {
+    const values = ANNOTATION_VALUES[annotation];
+    if (!values) {
+        return [];
+    }
+    const lowerPrefix = prefix.toLowerCase();
+    return values.filter((v) => v.label.toLowerCase().startsWith(lowerPrefix));
+}
+//# sourceMappingURL=annotationValues.js.map

package/dist/editor-completions/contextParser.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Editor Completions - Context Parser
+ *
+ * Parses the current line to detect what type of completion is expected.
+ */
+import type { CompletionContext, CompletionContextType } from './types.js';
+/**
+ * Detect whether we're inside a @flowWeaver workflow or nodeType block.
+ * Scans preceding lines in the JSDoc block for the @flowWeaver annotation.
+ */
+export declare function detectBlockType(precedingBlockLines: string[]): 'workflow' | 'nodeType' | null;
+/**
+ * Parse the current line to detect completion context.
+ *
+ * @param lineText - The full text of the current line
+ * @param cursorOffset - Cursor position within the line (0-based)
+ * @param isInJSDoc - Whether the cursor is inside a JSDoc block
+ * @param precedingBlockLines - Optional lines from /** to cursor for block type detection
+ * @returns Completion context or null if no completion should be shown
+ */
+export declare function parseCompletionContext(lineText: string, cursorOffset: number, isInJSDoc: boolean, precedingBlockLines?: string[]): CompletionContext | null;
+/**
+ * Get the word at the given position in the line.
+ * Useful for go-to-definition to find what word was clicked.
+ */
+export declare function getWordAtPosition(lineText: string, offset: number): {
+    word: string;
+    start: number;
+    end: number;
+} | null;
+/**
+ * Detect what kind of symbol is at the given position.
+ * Used for go-to-definition to determine navigation target.
+ */
+export declare function detectSymbolType(lineText: string, offset: number): {
+    type: CompletionContextType;
+    name: string;
+    nodeId?: string;
+} | null;
+//# sourceMappingURL=contextParser.d.ts.map