@synergenius/flow-weaver 0.20.1 → 0.20.3

package/docs/reference/cli-reference.md

@@ -1,7 +1,7 @@
 ---
 name: CLI Reference
 description: Complete reference for all Flow Weaver CLI commands, flags, and options
-keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates, context]
+keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates, context, modify, implement, status]
 ---
 
 # CLI Reference
@@ -34,6 +34,9 @@ Complete reference for all `flow-weaver` CLI commands.
 | `changelog` | Generate changelog from git |
 | `market` | Marketplace packages |
 | `plugin` | External plugins |
+| `modify` | Add/remove/rename nodes, connections, positions, and labels |
+| `implement` | Replace stub node with function skeleton |
+| `status` | Report implementation progress |
 | `context` | Generate LLM context bundle |
 | `docs` | Browse reference documentation |
 | `ui` | Send commands to the editor |
@@ -475,6 +478,120 @@ flow-weaver create node checker my-workflow.ts --template validator
 
 ---
 
+### modify
+
+Modify workflow structure programmatically. Parses the file, applies the operation, and regenerates the JSDoc annotations in place. Useful for scripting, CI pipelines, and the genesis self-evolution system.
+
+#### modify addNode
+
+```bash
+flow-weaver modify addNode --file <path> --nodeId <id> --nodeType <type>
+```
+
+Adds a new node instance to the workflow. Auto-positions to the right of the rightmost existing node. Warns if the node type isn't defined in the file.
+
+#### modify removeNode
+
+```bash
+flow-weaver modify removeNode --file <path> --nodeId <id>
+```
+
+Removes a node instance and all connections attached to it.
+
+#### modify addConnection
+
+```bash
+flow-weaver modify addConnection --file <path> --from <node.port> --to <node.port>
+```
+
+Adds a connection between two ports. Both nodes must exist. Port names are validated against the node type definition when available.
+
+#### modify removeConnection
+
+```bash
+flow-weaver modify removeConnection --file <path> --from <node.port> --to <node.port>
+```
+
+Removes an existing connection.
+
+#### modify renameNode
+
+```bash
+flow-weaver modify renameNode --file <path> --oldId <id> --newId <id>
+```
+
+Renames a node instance and updates all connections that reference it.
+
+#### modify setPosition
+
+```bash
+flow-weaver modify setPosition --file <path> --nodeId <id> --x <number> --y <number>
+```
+
+Sets the canvas position of a node instance.
+
+#### modify setLabel
+
+```bash
+flow-weaver modify setLabel --file <path> --nodeId <id> --label <text>
+```
+
+Sets the display label for a node instance.
+
+**Examples:**
+```bash
+flow-weaver modify addNode --file workflow.ts --nodeId validator --nodeType validateInput
+flow-weaver modify addConnection --file workflow.ts --from Start.data --to validator.input
+flow-weaver modify removeNode --file workflow.ts --nodeId oldStep
+flow-weaver modify removeConnection --file workflow.ts --from a.output --to b.input
+flow-weaver modify renameNode --file workflow.ts --oldId step1 --newId validateStep
+flow-weaver modify setPosition --file workflow.ts --nodeId step1 --x 200 --y 100
+flow-weaver modify setLabel --file workflow.ts --nodeId step1 --label "Validate Input"
+```
+
+---
+
+### implement
+
+Replace a stub node (`declare function`) with a real function skeleton containing the correct signature, JSDoc annotations, and return type.
+
+```bash
+flow-weaver implement <input> <node> [options]
+flow-weaver implement <input> --nodeId <id> [options]
+```
+
+The node can be specified as a positional argument or with the `--nodeId` flag.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-w, --workflow <name>` | Specific workflow name | — |
+| `--nodeId <id>` | Node to implement (alternative to positional arg) | — |
+| `-p, --preview` | Preview without writing | `false` |
+
+**Examples:**
+```bash
+flow-weaver implement workflow.ts validateInput
+flow-weaver implement workflow.ts --nodeId validateInput
+flow-weaver implement workflow.ts myNode --preview
+```
+
+---
+
+### status
+
+Report implementation progress for stub workflows. Shows which nodes are implemented vs still declared as stubs.
+
+```bash
+flow-weaver status <input> [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-w, --workflow <name>` | Specific workflow name | — |
+| `--json` | Output as JSON | `false` |
+
+---
+
 ### templates
 
 List available workflow and node templates.

package/docs/reference/error-codes.md

@@ -540,7 +540,7 @@ const fetchData = (execute: boolean, url: string, apiKey: string) => { ... };
 | Severity      | Warning                                                                                                                                                                                                                                 |
 | Meaning       | A node's data output port is never connected to anything. The data produced by this port is discarded.                                                                                                                                  |
 | Common Causes | The node produces an output that is not needed by the current workflow. A connection from this port was removed but the port still exists. Control flow ports (`onSuccess`, `onFailure`) and scoped ports are excluded from this check. |
-| Fix           | If the output is needed, connect it to a downstream node or to `Exit`. If not needed, the warning can be ignored, but it may indicate an incomplete workflow.                                                                           |
+| Fix           | If the output is needed, connect it to a downstream node or to `Exit`. If the output is intentionally discarded, add `[suppress: "UNUSED_OUTPUT_PORT"]` to the `@node` annotation to silence this warning for that instance. |
 
 #### UNREACHABLE_EXIT_PORT (warning)
 

package/docs/reference/jsdoc-grammar.md

@@ -212,8 +212,8 @@ attributeBracket ::= "[" nodeAttr { "," nodeAttr } "]"
 
 nodeAttr       ::= labelAttr | exprAttr | portOrderAttr | portLabelAttr
                  | minimizedAttr | pullExecutionAttr | sizeAttr
-                 | colorAttr | iconAttr | tagsAttr | positionAttr
-                 | jobAttr | environmentAttr
+                 | colorAttr | iconAttr | tagsAttr | suppressAttr
+                 | positionAttr | jobAttr | environmentAttr
 
 labelAttr      ::= "label:" STRING
 exprAttr       ::= "expr:" IDENTIFIER "=" STRING { "," IDENTIFIER "=" STRING }
@@ -229,6 +229,7 @@ tagEntry       ::= STRING [ STRING ]
 positionAttr   ::= "position:" INTEGER INTEGER
 jobAttr        ::= "job:" STRING
 environmentAttr ::= "environment:" STRING
+suppressAttr   ::= "suppress:" STRING { "," STRING }
 ```
 
 Multiple attribute brackets are allowed (zero or more). Attributes can be split across brackets or combined in one.
@@ -250,6 +251,7 @@ Multiple attribute brackets are allowed (zero or more). Attributes can be split
 @node myAdd Add [label: "hi"] [color: "#f00"] [position: 360 0]
 @node build npmBuild [job: "build"]
 @node deploy deploySsh [job: "deploy"] [environment: "production"]
+@node fetch fetchData [suppress: "UNUSED_OUTPUT_PORT"]
 ```
 
 ## @connect

package/docs/reference/marketplace.md

@@ -159,6 +159,80 @@ The `market pack` command validates packages against additional rules beyond sta
 
 ---
 
+## Custom Tag Handlers
+
+Tag handlers let packs extend the parser with custom JSDoc annotations. When the parser encounters a tag it doesn't recognize natively, it delegates to registered pack handlers before emitting "Unknown annotation" warnings.
+
+The CI/CD pack (`flowweaver-pack-cicd`) is the primary example: it registers handlers for `@secret`, `@runner`, `@cache`, `@artifact`, and other CI/CD tags.
+
+### Writing a handler
+
+A tag handler is a function matching the `TTagHandlerFn` signature:
+
+```typescript
+import type { TTagHandlerFn } from '@synergenius/flow-weaver/api';
+
+export const myHandler: TTagHandlerFn = (tagName, comment, ctx) => {
+  // tagName: the tag without '@', e.g. "secret"
+  // comment: everything after the tag on that line
+  // ctx.deploy: the deploy map for your namespace (mutate it directly)
+  // ctx.warnings: push parser warnings here
+
+  const value = comment.trim();
+  if (!value) {
+    ctx.warnings.push(`Empty @${tagName} tag`);
+    return;
+  }
+
+  const items = (ctx.deploy['items'] as string[]) ?? [];
+  items.push(value);
+  ctx.deploy['items'] = items;
+};
+```
+
+The handler receives one call per tag occurrence. Parsed data goes into `ctx.deploy`, which maps to `workflow.deploy[namespace]` or `nodeType.deploy[namespace]` in the final AST.
+
+### Declaring handlers in the manifest
+
+Add a `tagHandlers` entry to your `flowweaver.manifest.json`:
+
+```json
+{
+  "manifestVersion": 2,
+  "tagHandlers": [
+    {
+      "tags": ["secret", "runner", "cache"],
+      "namespace": "cicd",
+      "scope": "both",
+      "file": "dist/tag-handler.js",
+      "exportName": "cicdTagHandler"
+    }
+  ]
+}
+```
+
+Fields:
+
+| Field | Description |
+|-------|-------------|
+| `tags` | Tag names this handler processes (without the `@` prefix) |
+| `namespace` | Key in the deploy map where parsed data is stored |
+| `scope` | `workflow` for workflow-level tags, `nodeType` for node type tags, `both` for either |
+| `file` | Relative path to the compiled JS file exporting the handler |
+| `exportName` | Named export from the file (omit for `default` export) |
+
+### Handler scope
+
+A handler scoped to `workflow` only runs for tags inside `@flowWeaver workflow` blocks. A handler scoped to `nodeType` only runs inside `@flowWeaver nodeType` blocks. Use `both` when your tags are valid in either context.
+
+If a tag appears in the wrong scope, the parser emits a warning and skips the handler call.
+
+### How discovery works
+
+When `parseWorkflow()` is called with a `projectDir` option (or when the CLI runs from a project directory), the parser scans `node_modules` for installed packs with a `flowweaver.manifest.json`. It reads the `tagHandlers` array from each manifest, dynamically imports the handler files, and registers them in the `TagHandlerRegistry`. This scan runs once per project directory and is cached for subsequent parse calls.
+
+---
+
 ## External Plugins
 
 Plugins extend the Flow Weaver Studio IDE with custom UI components, system logic, and integrations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",