@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/cli/commands/export.d.ts

@@ -1,5 +1,7 @@
 /**
- * Export command - generate serverless function handlers for deployment
+ * Export command - run a workflow through an export target provided by an
+ * installed pack. Flow Weaver core ships no target; each comes from a pack's
+ * `exportTargets` manifest, resolved from node_modules per call.
  */
 export interface ExportOptions {
     /** Target platform (provided by installed packs) */
@@ -8,9 +10,9 @@ export interface ExportOptions {
     output: string;
     /** Specific workflow name to export */
     workflow?: string;
-    /** Production mode (default: true) */
+    /** Production mode (default: false) */
     production?: boolean;
-    /** Bundle into single file (future feature) */
+    /** Bundle into a single file, when the target supports it */
     bundle?: boolean;
     /** Dry run - preview without writing files */
     dryRun?: boolean;
@@ -24,7 +26,7 @@ export interface ExportOptions {
     durableSteps?: boolean;
 }
 /**
- * Export a workflow as a serverless function.
+ * Export a workflow through an installed pack's export target.
  *
  * @param input - Path to the workflow file
  * @param options - Export options

package/dist/cli/commands/grammar.d.ts

@@ -1,6 +1,3 @@
-/**
- * Grammar command - output JSDoc grammar as HTML railroad diagrams or EBNF text
- */
 export interface GrammarOptions {
     format?: 'html' | 'ebnf';
     output?: string;

package/dist/cli/commands/implement.d.ts

@@ -1,5 +1,5 @@
 /**
- * Implement command — replaces a stub node with a real function skeleton
+ * Implement command: replaces a stub node with a real function skeleton
  */
 export interface ImplementOptions {
     workflowName?: string;

package/dist/cli/commands/init/agent-handoff.d.ts

@@ -0,0 +1,28 @@
+import type { McpSetupFromInitResult, ToolId } from '../mcp-setup.js';
+import type { PersonaId } from '../init-personas.js';
+import type { InitConfig, InitOptions } from './types.js';
+interface AgentHandoffOptions {
+    projectName: string;
+    persona: PersonaId;
+    template: string;
+    targetDir: string;
+    cliTools: ToolId[];
+    guiTools: ToolId[];
+    filesCreated: string[];
+    useCaseDescription?: string;
+}
+/**
+ * Offers the handoff when it applies. Decoupled from MCP: even if MCP
+ * wasn't run, it checks for CLI tools on the PATH. Returns true when init
+ * should print nothing more: an agent was launched and takes over, or the
+ * user pressed Ctrl+C at a handoff prompt. Any other failure only skips the
+ * handoff.
+ */
+export declare function offerAgentHandoff(config: InitConfig, options: InitOptions, filesCreated: string[], mcpResult: McpSetupFromInitResult | undefined): Promise<boolean>;
+/**
+ * After init + MCP setup, offer to launch a CLI agent or generate a prompt for GUI editors.
+ * Returns true if a CLI agent was spawned (init should exit and let the agent take over).
+ */
+export declare function handleAgentHandoff(opts: AgentHandoffOptions): Promise<boolean>;
+export {};
+//# sourceMappingURL=agent-handoff.d.ts.map

package/dist/cli/commands/init/config.d.ts

@@ -0,0 +1,3 @@
+import type { InitConfig, InitOptions } from './types.js';
+export declare function resolveInitConfig(dirArg: string | undefined, options: InitOptions): Promise<InitConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/cli/commands/init/files.d.ts

@@ -0,0 +1,12 @@
+import type { TModuleFormat } from '../../../ast/types.js';
+import type { PersonaId } from '../init-personas.js';
+export declare function generateProjectFiles(projectName: string, template: string, format?: TModuleFormat, persona?: PersonaId): Record<string, string>;
+/** Refuses a target directory that already holds a package.json, unless forced. */
+export declare function assertNoExistingProject(targetDir: string, force: boolean): void;
+export declare function scaffoldProject(targetDir: string, files: Record<string, string>, options: {
+    force: boolean;
+}): {
+    filesCreated: string[];
+    filesSkipped: string[];
+};
+//# sourceMappingURL=files.d.ts.map

package/dist/cli/commands/init/naming.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Project and workflow names.
+ *
+ * Decides which project names init accepts (npm-safe: at most 214
+ * characters, starting with a letter or digit, then letters, digits, hyphens,
+ * dots and underscores) and derives the workflow function name and the
+ * workflow file name from the project name.
+ */
+export declare function validateProjectName(name: string): string | true;
+export declare function toWorkflowName(projectName: string): string;
+/** The scaffolded workflow's file name under src/, e.g. `my-app-workflow.ts`. */
+export declare function workflowFileName(projectName: string): string;
+//# sourceMappingURL=naming.d.ts.map

package/dist/cli/commands/init/output.d.ts

@@ -0,0 +1,12 @@
+import type { InitConfig, StepResult } from './types.js';
+interface SetupOutcome {
+    filesSkipped: string[];
+    installResult?: StepResult;
+    gitResult?: StepResult;
+    compileResult?: StepResult;
+}
+export declare function printStatusLines(config: InitConfig, outcome: SetupOutcome): void;
+/** The project directory as the next steps show it, or null when it is the current directory. */
+export declare function displayDirFor(targetDir: string): string | null;
+export {};
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/commands/init/setup.d.ts

@@ -0,0 +1,21 @@
+import type { McpSetupFromInitResult } from '../mcp-setup.js';
+import type { TModuleFormat } from '../../../ast/types.js';
+import type { StepResult } from './types.js';
+export declare function runNpmInstall(targetDir: string): {
+    success: boolean;
+    error?: string;
+};
+export declare function runGitInit(targetDir: string): {
+    success: boolean;
+    error?: string;
+};
+/** npm install, behind a spinner when showProgress is set. */
+export declare function installDependencies(targetDir: string, showProgress: boolean): StepResult;
+/** Compiles the scaffolded workflow in place; undefined when the file is not there. */
+export declare function compileWorkflow(workflowPath: string, format: TModuleFormat): Promise<StepResult | undefined>;
+/**
+ * Detects and configures AI editors, printing a line per configured or
+ * failed editor. Undefined when setup itself failed.
+ */
+export declare function setUpEditors(): Promise<McpSetupFromInitResult | undefined>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/cli/commands/init/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The shapes init passes between its steps: the options from the command
+ * line, the config every later step reads once flags, defaults and prompts
+ * are settled, and the report printed with --json.
+ */
+import type { TModuleFormat } from '../../../ast/types.js';
+import type { PersonaId } from '../init-personas.js';
+export interface InitOptions {
+    name?: string;
+    template?: string;
+    format?: TModuleFormat;
+    yes?: boolean;
+    install?: boolean;
+    git?: boolean;
+    force?: boolean;
+    json?: boolean;
+    preset?: string;
+    useCase?: string;
+    mcp?: boolean;
+    agent?: boolean;
+}
+export interface InitConfig {
+    projectName: string;
+    targetDir: string;
+    template: string;
+    format: TModuleFormat;
+    install: boolean;
+    git: boolean;
+    force: boolean;
+    persona: PersonaId;
+    useCase?: string;
+    /** Free-text description when user picked "Something else" */
+    useCaseDescription?: string;
+    mcp: boolean;
+}
+/** How a step that reports instead of throwing went (npm install, git init, compile). */
+export interface StepResult {
+    success: boolean;
+    error?: string;
+}
+export interface InitReport {
+    projectDir: string;
+    filesCreated: string[];
+    filesSkipped: string[];
+    template: string;
+    format: TModuleFormat;
+    persona: PersonaId;
+    installResult?: StepResult;
+    gitResult?: StepResult;
+    mcpConfigured?: string[];
+    agentLaunched?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/commands/init-personas.d.ts

@@ -71,7 +71,15 @@ export interface PrintNextStepsOptions {
     compiled?: boolean;
 }
 export declare function printNextSteps(opts: PrintNextStepsOptions): void;
-/** Maps each persona to the fw_context preset used for agent knowledge bootstrap. */
+/**
+ * Maps each persona to the fw_context preset used for agent knowledge bootstrap.
+ *
+ * Every persona starts from `core`. It is a short map (the model, the tool
+ * loop, and which topic answers which task), and the assistant loads further
+ * topics with fw_docs as the work calls for them. The `authoring` preset the
+ * coding personas used to load is ~70 KB, most of it never needed in a given
+ * session.
+ */
 export declare const AGENT_CONTEXT_PRESETS: Record<PersonaId, string>;
 /**
  * Generate the initial prompt for a CLI agent (Claude Code, Codex).

package/dist/cli/commands/init.d.ts

@@ -1,93 +1,29 @@
 /**
- * Init command — scaffolds a new flow-weaver project interactively.
+ * Init command: scaffolds a new flow-weaver project interactively.
  * Supports persona-aware onboarding for nocode, low-code, vibe-coder, and expert users.
+ *
+ * initCommand decides the order of the steps. Each lives in ./init/:
+ *
+ * - config: flags, defaults and prompts into an InitConfig
+ * - naming: accepted project names and the workflow names derived from them
+ * - files: the files a project starts with, and writing them
+ * - setup: npm install, git init, compiling the workflow, editor (MCP) setup
+ * - output: the human status lines and how the project directory is shown
+ * - agent-handoff: launching a CLI agent or writing an editor setup prompt
+ *
+ * The persona texts (choices, READMEs, prompts, next steps) are in
+ * ./init-personas.ts.
  */
-import type { ToolId } from './mcp-setup.js';
-import type { TModuleFormat } from '../../ast/types.js';
-import type { PersonaId } from './init-personas.js';
-export interface InitOptions {
-    name?: string;
-    template?: string;
-    format?: TModuleFormat;
-    yes?: boolean;
-    install?: boolean;
-    git?: boolean;
-    force?: boolean;
-    json?: boolean;
-    preset?: string;
-    useCase?: string;
-    mcp?: boolean;
-    agent?: boolean;
-    withWeaver?: boolean;
-    weaver?: boolean;
-}
-export interface InitConfig {
-    projectName: string;
-    targetDir: string;
-    template: string;
-    format: TModuleFormat;
-    install: boolean;
-    git: boolean;
-    force: boolean;
-    persona: PersonaId;
-    useCase?: string;
-    /** Free-text description when user picked "Something else" */
-    useCaseDescription?: string;
-    mcp: boolean;
-    installWeaver: boolean;
-}
-export interface InitReport {
-    projectDir: string;
-    filesCreated: string[];
-    filesSkipped: string[];
-    template: string;
-    format: TModuleFormat;
-    persona: PersonaId;
-    installResult?: {
-        success: boolean;
-        error?: string;
-    };
-    gitResult?: {
-        success: boolean;
-        error?: string;
-    };
-    mcpConfigured?: string[];
-    agentLaunched?: boolean;
-}
-export declare function validateProjectName(name: string): string | true;
-export declare function toWorkflowName(projectName: string): string;
-export declare function isNonInteractive(): boolean;
-export declare function resolveInitConfig(dirArg: string | undefined, options: InitOptions): Promise<InitConfig>;
-export declare function generateProjectFiles(projectName: string, template: string, format?: TModuleFormat, persona?: PersonaId, installWeaver?: boolean): Record<string, string>;
-export declare function scaffoldProject(targetDir: string, files: Record<string, string>, options: {
-    force: boolean;
-}): {
-    filesCreated: string[];
-    filesSkipped: string[];
-};
-export declare function runNpmInstall(targetDir: string): {
-    success: boolean;
-    error?: string;
-};
-export declare function runGitInit(targetDir: string): {
-    success: boolean;
-    error?: string;
-};
-interface AgentHandoffOptions {
-    projectName: string;
-    persona: PersonaId;
-    template: string;
-    targetDir: string;
-    cliTools: ToolId[];
-    guiTools: ToolId[];
-    filesCreated: string[];
-    useCaseDescription?: string;
-}
-/**
- * After init + MCP setup, offer to launch a CLI agent or generate a prompt for GUI editors.
- * Returns true if a CLI agent was spawned (init should exit and let the agent take over).
- */
-export declare function handleAgentHandoff(opts: AgentHandoffOptions): Promise<boolean>;
+import { isNonInteractive } from '../utils/interactive.js';
+import { resolveInitConfig } from './init/config.js';
+import { generateProjectFiles, scaffoldProject } from './init/files.js';
+import { runGitInit } from './init/setup.js';
+import type { InitOptions } from './init/types.js';
+export type { InitOptions, InitConfig, InitReport } from './init/types.js';
+export { validateProjectName, toWorkflowName } from './init/naming.js';
+export { resolveInitConfig, generateProjectFiles, scaffoldProject, runGitInit };
+export { runNpmInstall } from './init/setup.js';
+export { handleAgentHandoff } from './init/agent-handoff.js';
+export { isNonInteractive };
 export declare function initCommand(dirArg: string | undefined, options: InitOptions): Promise<void>;
-export {};
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/market.d.ts

@@ -1,5 +1,5 @@
 /**
- * Marketplace commands — init, pack, publish, install, search, list
+ * Marketplace commands: init, pack, publish, install, search, list
  */
 export interface MarketInitOptions {
     description?: string;

package/dist/cli/commands/mcp-setup.d.ts

@@ -1,9 +1,7 @@
 /**
- * mcp-setup command — detect AI coding tools and configure the Flow Weaver MCP server.
+ * mcp-setup command: detect AI coding tools and configure the Flow Weaver MCP server.
  */
 export type ToolId = 'claude' | 'cursor' | 'vscode' | 'windsurf' | 'codex' | 'openclaw';
-/** Tools that can be spawned as interactive CLI sessions */
-export declare const CLI_TOOL_IDS: ReadonlySet<ToolId>;
 /** Binary name to spawn for each CLI tool */
 export declare const CLI_TOOL_BINARY: Partial<Record<ToolId, string>>;
 export interface McpSetupDeps {
@@ -37,7 +35,6 @@ interface DetectedTool {
     detected: boolean;
     configured: boolean;
 }
-export declare function defaultDeps(): McpSetupDeps;
 export declare function mergeJsonConfig(deps: McpSetupDeps, filePath: string, rootKey: string): Promise<{
     action: 'created' | 'added' | 'already-configured';
     detail: string;

package/dist/cli/commands/modify.d.ts

@@ -17,11 +17,6 @@ export declare function modifyRenameNodeCommand(file: string, opts: {
     oldId: string;
     newId: string;
 }): Promise<void>;
-export declare function modifySetPositionCommand(file: string, opts: {
-    nodeId: string;
-    x: string;
-    y: string;
-}): Promise<void>;
 export declare function modifySetLabelCommand(file: string, opts: {
     nodeId: string;
     label: string;

package/dist/cli/commands/openapi.d.ts

@@ -1,5 +1,7 @@
 /**
- * OpenAPI command - generate OpenAPI specification from workflow files
+ * OpenAPI command - the document `fw serve` publishes at /openapi.json,
+ * written to a file: the declared `@http` routes, the run resource of every
+ * workflow, and the run endpoints.
  */
 export interface OpenAPIOptions {
     /** Output file path */
@@ -14,23 +16,19 @@ export interface OpenAPIOptions {
     format?: 'json' | 'yaml';
     /** Server URL */
     server?: string;
+    /** Describe the bearer scheme, as a server with a token has. Default true. */
+    auth?: boolean;
+    /** Include `POST /workflows/<name>` for every workflow. Default true. */
+    legacy?: boolean;
 }
 /**
- * Generate OpenAPI specification from workflows in a directory.
- *
- * @param dir - Directory containing workflow files
- * @param options - Generation options
+ * Generate the OpenAPI specification for the workflows in a directory.
  *
  * @example
  * ```bash
- * # Generate JSON spec to stdout
  * fw openapi ./workflows
- *
- * # Generate YAML spec to file
  * fw openapi ./workflows --format yaml --output api-spec.yaml
- *
- * # With custom title and version
- * fw openapi ./workflows --title "My API" --version "2.0.0"
+ * fw openapi ./workflows --server https://api.example.com/api --title "Orders API"
  * ```
  */
 export declare function openapiCommand(dir: string, options: OpenAPIOptions): Promise<void>;

package/dist/cli/commands/run.d.ts

@@ -25,10 +25,6 @@ export interface RunOptions {
     mocksFile?: string;
     /** Start in step-through debug mode */
     debug?: boolean;
-    /** Enable checkpointing to disk after each node */
-    checkpoint?: boolean;
-    /** Resume from a checkpoint file (true for auto-detect, or a file path) */
-    resume?: boolean | string;
     /** Initial breakpoint node IDs */
     breakpoint?: string[];
 }

package/dist/cli/commands/serve.d.ts

@@ -1,44 +1,42 @@
 /**
- * Serve command - start HTTP server exposing workflows as endpoints
+ * Serve command - the project's workflows as HTTP endpoints, runs as resources.
  */
 export interface ServeOptions {
-    /** Server port */
+    /** Server port. Default 3000. */
     port?: number;
-    /** Server host */
+    /** Server host. Default 127.0.0.1. Anything else needs a token or --insecure. */
     host?: string;
-    /** Enable file watching for hot reload */
+    /** Re-discover workflows when files change. Default true. */
     watch?: boolean;
-    /** Production mode (no trace events) */
+    /** Deprecated alias for `trace: false`. */
     production?: boolean;
-    /** Precompile all workflows on startup */
+    /** Accepted for compatibility. Has no effect. */
     precompile?: boolean;
-    /** CORS origin */
+    /** CORS origin. Unset sends no CORS headers. */
     cors?: string;
-    /** Enable Swagger UI at /docs */
+    /** Swagger UI at /docs. */
     swagger?: boolean;
+    /** Bearer token. Also read from FW_SERVE_TOKEN. */
+    token?: string;
+    /** Answer agent gates from .flowweaver/agents.yaml. Default true. */
+    agents?: boolean;
+    /** Keep and stream a step trace per run. */
+    trace?: boolean;
+    /** Error stacks in responses. Mocks accepted in a start body. */
+    dev?: boolean;
+    /** Listen beyond loopback without a token. */
+    insecure?: boolean;
 }
 /**
- * Start a webhook server exposing workflows as HTTP endpoints.
- *
- * @param dir - Directory containing workflow files (defaults to current directory)
- * @param options - Server options
+ * Start the HTTP server.
  *
  * @example
  * ```bash
- * # Start server with current directory
- * fw serve
- *
- * # Specify workflow directory
- * fw serve ./workflows
- *
- * # Custom port
- * fw serve --port 8080
- *
- * # Production mode
- * fw serve --production --precompile
- *
- * # Disable hot reload
- * fw serve --no-watch
+ * fw serve                              # this directory, on 127.0.0.1:3000
+ * fw serve ./workflows --port 8080
+ * fw serve --host 0.0.0.0 --token $FW_SERVE_TOKEN   # reachable, guarded
+ * fw serve --trace --dev                # streams every step, stacks in errors
+ * fw serve --no-agents                  # agent gates wait for a person
  * ```
  */
 export declare function serveCommand(dir: string | undefined, options: ServeOptions): Promise<void>;

package/dist/cli/commands/status.d.ts

@@ -1,5 +1,5 @@
 /**
- * Status command — reports implementation progress for stub workflows
+ * Status command: reports implementation progress for stub workflows
  */
 export interface StatusOptions {
     workflowName?: string;

package/dist/cli/exports.d.ts

@@ -1,9 +1,8 @@
 /**
- * CLI utilities — public barrel for export target packs.
+ * CLI utilities: public barrel for export target packs.
  *
  * Exposes CLI internals that marketplace packs need: template types,
- * provider code generators, LLM type snippets, compileCustomTarget,
- * and the logger.
+ * provider code generators, LLM type snippets, and the logger.
  */
 export type { WorkflowTemplate, WorkflowTemplateOptions, NodeTemplate, ConfigSchema, ConfigField, ConfigFieldType, } from './templates/index.js';
 export { registerWorkflowTemplates, getAllWorkflowTemplates, getWorkflowTemplate, } from './templates/index.js';
@@ -11,7 +10,7 @@ export { getProviderCode, generateOpenAIProvider, generateAnthropicProvider, gen
 export { LLM_CORE_TYPES, LLM_SIMPLE_TYPES, LLM_MOCK_PROVIDER, LLM_MOCK_PROVIDER_WITH_TOOLS, } from './templates/shared/llm-types.js';
 export { aiConfigSchema } from './templates/workflows/ai-agent.js';
 export { registerPackUseCase } from './commands/init-personas.js';
-export { compileCustomTarget } from './commands/compile.js';
 export { logger } from './utils/logger.js';
 export { getErrorMessage, wrapError } from '../utils/error-utils.js';
+export type { TManifestCliArgument, TPackCliCommandContext, TPackCliOptionValue, } from '../marketplace/types.js';
 //# sourceMappingURL=exports.d.ts.map