@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/console/packs.d.ts

@@ -0,0 +1,100 @@
+import type { TInstalledPackage } from '../marketplace/types.js';
+export interface PackPort {
+    name: string;
+    type: string;
+    optional: boolean;
+    description: string;
+}
+export interface PackView {
+    /** The npm name, as installed. */
+    name: string;
+    /** The words after `fw` its commands live under: `@acme/flow-weaver-pack-audio` → `audio`. */
+    namespace: string;
+    version: string;
+    path: string;
+    description: string;
+    engineVersion: string | null;
+    /** Whether this Flow Weaver satisfies `engineVersion`. Null when it cannot be read. */
+    compatible: boolean | null;
+    nodeTypes: Array<{
+        name: string;
+        functionName: string;
+        description: string;
+        inputs: PackPort[];
+        outputs: PackPort[];
+        color: string | null;
+        icon: string | null;
+    }>;
+    workflows: Array<{
+        name: string;
+        description: string;
+        params: PackPort[];
+        returns: PackPort[];
+        nodes: number;
+    }>;
+    exportTargets: Array<{
+        name: string;
+        description: string;
+    }>;
+    tagHandlers: Array<{
+        tags: string[];
+        namespace: string;
+        scope: string;
+    }>;
+    validationRuleSets: Array<{
+        name: string;
+        namespace: string;
+    }>;
+    docs: Array<{
+        slug: string;
+        name: string;
+        description: string;
+    }>;
+    cliCommands: Array<{
+        name: string;
+        description: string;
+        usage: string;
+        flags: Array<{
+            flag: string;
+            description: string;
+            default: string;
+        }>;
+    }>;
+    mcpTools: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+/** The namespace a pack's CLI commands are registered under. */
+export declare function packNamespace(name: string): string;
+/** What provenance needs of an installed pack: its name and where it sits. */
+export interface InstalledRef {
+    name: string;
+    path: string;
+}
+/**
+ * The installed pack a source file belongs to, or null for the project's
+ * own files and for ordinary dependencies. Decided against the packs that
+ * are actually installed, on either separator, the longest path winning.
+ */
+export declare function packForFile(file: string, packs: InstalledRef[]): string | null;
+/** The package an import specifier names: `@acme/pipelines/dist/x.js` → `@acme/pipelines`. */
+export declare function packageOfSpecifier(specifier: string): string | null;
+/**
+ * The installed pack an import specifier points into, or null. `@fwImport x
+ * fn from "@acme/pipelines/dist/x.js"` is resolved by the parser into a node
+ * type whose source is the importing file, so the specifier is the only
+ * trace of where it came from.
+ */
+export declare function packForSpecifier(specifier: string | undefined, packs: InstalledRef[]): string | null;
+export declare function installedRefs(projectDir: string): Promise<InstalledRef[]>;
+/**
+ * Whether `version` satisfies a simple range: `>=x.y.z`, `^x.y.z`, `~x.y.z`,
+ * `x.y.z` or `*`. Anything more elaborate answers null rather than a guess.
+ */
+export declare function engineCompatible(range: string | undefined, version?: string): boolean | null;
+/** One installed pack, read for a person. */
+export declare function describePack(pkg: TInstalledPackage): PackView;
+/** Every pack installed in the project, by namespace. */
+export declare function describePacks(projectDir: string): Promise<PackView[]>;
+//# sourceMappingURL=packs.d.ts.map

package/dist/console/request-guard.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Why a request must be refused, or undefined to let it through.
+ *
+ * @param bound The address the console listens on, as given to `listen`.
+ */
+export declare function refusal(req: {
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+}, bound: string): string | undefined;
+//# sourceMappingURL=request-guard.d.ts.map

package/dist/console/respond.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Writing the console's answers, and reading its request bodies.
+ */
+import type * as http from 'node:http';
+export type Json = Record<string, unknown>;
+export declare function json(res: http.ServerResponse, status: number, body: unknown): void;
+/** Open an event stream. */
+export declare function sse(res: http.ServerResponse): void;
+/** One event on an open stream. */
+export declare function send(res: http.ServerResponse, msg: unknown): void;
+export declare function sendFile(res: http.ServerResponse, file: string, type: string): void;
+/** A request body that is not a JSON object is the client's mistake, answered with 400 rather than 500. */
+export declare class BadRequest extends Error {
+}
+export declare function readBody(req: http.IncomingMessage): Promise<Json>;
+//# sourceMappingURL=respond.d.ts.map

package/dist/console/router.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The console's routes: a table per area, matched in order, and what every
+ * route is handed.
+ */
+import type * as http from 'node:http';
+import type { Supervisor } from './services.js';
+import type { RunDriver } from './runs.js';
+import type { ProfileCache } from './routes-agents.js';
+import type { Json } from './respond.js';
+/** What the routes share: the project, the pages following it, and the parts of the console. */
+export interface ConsoleContext {
+    /** The project the console is open on. It changes when another is opened. */
+    projectDir(): string;
+    /** Switch to another project: its listing, services, watcher and pack topics. */
+    openProject(dir: string): Promise<void>;
+    /** The absolute path, if it is inside the project; null otherwise. */
+    inProject(p: string): string | null;
+    /** Tell every following page something changed. */
+    broadcast(msg: Json): void;
+    /** The pages following every change, over `/api/events`. */
+    followers: Set<http.ServerResponse>;
+    /** Parse and validate the project's workflows in the background. */
+    queueCheck(): void;
+    /** The project's services. Replaced when the project changes. */
+    supervisor(): Supervisor;
+    profiles: ProfileCache;
+    runs: RunDriver;
+    /** Where the console is and what it watches, for the status page. */
+    status(): {
+        url: string;
+        watching: boolean;
+        runsDir: string;
+    };
+    /** Where the client's files are served from. */
+    client: {
+        pageDir: string;
+        scriptDir: string;
+    };
+}
+/** One request, as a route sees it. */
+export interface Call {
+    req: http.IncomingMessage;
+    res: http.ServerResponse;
+    url: URL;
+    /** A query parameter, or the empty string. */
+    q(name: string): string;
+    /** The body, read as a JSON object. */
+    body(): Promise<Json>;
+    /** The groups of a pattern route's match; empty for a path route. */
+    match: RegExpMatchArray | [];
+}
+export interface Route {
+    /** Any method when omitted. */
+    method?: string;
+    /** An exact path, or a pattern over the whole path. */
+    path: string | RegExp;
+    handle(call: Call): unknown;
+}
+/** The first route for a method and path, with the pattern's match. */
+export declare function findRoute(routes: readonly Route[], method: string, pathname: string): {
+    route: Route;
+    match: RegExpMatchArray | [];
+} | undefined;
+//# sourceMappingURL=router.d.ts.map

package/dist/console/routes-agents.d.ts

@@ -0,0 +1,14 @@
+import { type AgentProfiles } from '../agent/profiles.js';
+import { type Json } from './respond.js';
+import type { ConsoleContext, Route } from './router.js';
+export interface ProfileCache {
+    /** The project's profiles, read again when the file or the project changes. */
+    get(): AgentProfiles;
+    /** Write them, and read them fresh next time. */
+    save(profiles: Pick<AgentProfiles, 'agents' | 'default' | 'gates'>): void;
+    /** The profiles as the Agents view shows them: readiness by environment, never a key. */
+    describe(): Json;
+}
+export declare function createProfileCache(projectDir: () => string): ProfileCache;
+export declare function agentRoutes(ctx: ConsoleContext): Route[];
+//# sourceMappingURL=routes-agents.d.ts.map

package/dist/console/routes-project.d.ts

@@ -0,0 +1,3 @@
+import type { ConsoleContext, Route } from './router.js';
+export declare function projectRoutes(ctx: ConsoleContext): Route[];
+//# sourceMappingURL=routes-project.d.ts.map

package/dist/console/routes-runs.d.ts

@@ -0,0 +1,3 @@
+import type { ConsoleContext, Route } from './router.js';
+export declare function runRoutes(ctx: ConsoleContext): Route[];
+//# sourceMappingURL=routes-runs.d.ts.map

package/dist/console/routes-services.d.ts

@@ -0,0 +1,7 @@
+import type { Supervisor } from './services.js';
+import { type Json } from './respond.js';
+import type { ConsoleContext, Route } from './router.js';
+/** Whether `fw serve` is running for this project: ours, or from a terminal. */
+export declare function describeServe(supervisor: Supervisor): Json;
+export declare function serviceRoutes(ctx: ConsoleContext): Route[];
+//# sourceMappingURL=routes-services.d.ts.map

package/dist/console/routes-tools.d.ts

@@ -0,0 +1,3 @@
+import type { ConsoleContext, Route } from './router.js';
+export declare function toolRoutes(ctx: ConsoleContext): Route[];
+//# sourceMappingURL=routes-tools.d.ts.map

package/dist/console/runs.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The console's runs.
+ *
+ * Runs live in the coordinator's store, the same one `fw_run` and
+ * `fw_resume` write to, so a run started here can be answered by an
+ * assistant over MCP and the other way round. What this process holds is
+ * the segment of execution it is driving at the moment, the step-through
+ * debug sessions, and the pages watching each run.
+ */
+import type * as http from 'node:http';
+import { type LocalCoordinator, type RunRecord } from '../coordinator/index.js';
+import type { AgentProfiles } from '../agent/profiles.js';
+import type { FwMockConfig } from '../built-in-nodes/mock-types.js';
+import { DebugSessions } from './debug.js';
+import { type Json } from './respond.js';
+type Source = {
+    commit?: string;
+    dirty?: boolean;
+};
+/** The mocks a request carried, or nothing: only the four known sections, only objects. */
+export declare function mocksFrom(b: Record<string, unknown>): FwMockConfig | undefined;
+export interface RunDriverOptions {
+    coordinator: LocalCoordinator;
+    /** Tell every page something changed. */
+    broadcast: (msg: Json) => void;
+    /** The project the console is open on, which may change. */
+    projectDir: () => string;
+    /** The project's agent profiles, for answering agent gates. */
+    profiles: () => AgentProfiles;
+}
+export type RunDriver = ReturnType<typeof createRunDriver>;
+export declare function createRunDriver({ coordinator, broadcast, projectDir, profiles }: RunDriverOptions): {
+    debug: DebugSessions;
+    /** The stored record, as the coordinator has it. */
+    record: (id: string) => Promise<RunRecord | undefined>;
+    /** A document kept beside the run. */
+    kept: (id: string, name: string) => Promise<unknown>;
+    snapshot: (id: string) => Promise<Json | undefined>;
+    list: (file: string, name: string) => Promise<Json[]>;
+    start: (file: string, name: string, params: Json, mocks?: FwMockConfig, source?: Source, agents?: "auto" | "manual") => Promise<Json>;
+    startDebug: (file: string, name: string, params: Json, breakpoints: string[], mocks: FwMockConfig | undefined, runTo: "first" | "breakpoint", source?: Source) => Json;
+    resume: (id: string, input: {
+        answer?: unknown;
+        reject?: string;
+    }) => Promise<void>;
+    cancel: (id: string) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+    watch: (id: string, req: http.IncomingMessage, res: http.ServerResponse) => Promise<void>;
+    withEvents: (id: string) => Promise<Json>;
+    askAgent: (id: string) => Promise<string | undefined>;
+    follow: (opts: {
+        watching: boolean;
+        runsDir?: string;
+    }) => Promise<void>;
+    waitingCounts: () => Promise<Map<string, number>>;
+    withWaiting: <W extends {
+        file: string;
+        name: string;
+    }>(w: W, counts?: Map<string, number>) => W & {
+        waiting: number;
+    };
+    /** A value set in a paused session, told to the pages that read values from the trace. */
+    announce: (id: string, msg: Json) => void;
+    /** Keep the run streams open through proxies. */
+    ping(): void;
+    close(): Promise<void>;
+};
+export {};
+//# sourceMappingURL=runs.d.ts.map

package/dist/console/scan.d.ts

@@ -0,0 +1,49 @@
+export interface WorkflowSummary {
+    /** Absolute path, in the platform's own form. */
+    file: string;
+    /**
+     * Path within the project, always `/`-separated.
+     *
+     * The client splits this to build the tree and puts it in the URL hash,
+     * so it is one convention everywhere rather than `\` on Windows and `/`
+     * elsewhere. `file` stays native, because that is what gets opened.
+     */
+    rel: string;
+    name: string;
+    steps: number;
+    gates: number;
+    errors: number;
+    warnings: number;
+    /** False until the full parse has run. The rail shows it as still loading. */
+    checked: boolean;
+    /** Every validation code raised, once each. */
+    codes: string[];
+    /**
+     * What the workflow makes use of, as facets the guide can match a topic
+     * against: `gate:approval`, `builtin:waitForAgent`, `pack:<name>`, `pull`, `expr`,
+     * `scope`, `effect`, `pure`, `expression`.
+     */
+    uses: string[];
+}
+/** A project-relative path the client can split on `/` on any platform. */
+export declare const toPosix: (p: string) => string;
+/** Forget a project's listing, so the next scan re-reads every file. */
+export declare function invalidateListing(projectDir?: string): void;
+/**
+ * Every workflow in the project, with whatever verdicts are already known.
+ *
+ * Returns without parsing: a workflow not yet checked comes back with
+ * `checked: false` and zeroed counts. Call {@link checkWorkflows} to fill
+ * them in.
+ */
+export declare function scanWorkflowNames(projectDir: string): WorkflowSummary[];
+/**
+ * Parse and validate whatever is not yet checked, reporting as each lands.
+ *
+ * @param projectDir - The project being shown.
+ * @param onChecked - Called after each workflow, so the rail can fill in.
+ */
+export declare function checkWorkflows(projectDir: string, onChecked?: (summary: WorkflowSummary) => void): Promise<WorkflowSummary[]>;
+/** Names and verdicts together. Convenient, but as slow as the full check. */
+export declare function scanWorkflows(projectDir: string): Promise<WorkflowSummary[]>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/console/schema.d.ts

@@ -0,0 +1,74 @@
+export type FieldSchema = {
+    type: 'string';
+    optional?: boolean;
+} | {
+    type: 'number';
+    optional?: boolean;
+} | {
+    type: 'boolean';
+    optional?: boolean;
+} | {
+    type: 'enum';
+    values: Array<string | number>;
+    optional?: boolean;
+} | {
+    type: 'array';
+    items: FieldSchema;
+    optional?: boolean;
+    text?: string;
+} | {
+    type: 'object';
+    fields?: Record<string, FieldSchema>;
+    text?: string;
+    optional?: boolean;
+} | {
+    type: 'any';
+    text?: string;
+    optional?: boolean;
+};
+/**
+ * The shape of each data output of a gate node.
+ *
+ * An authored gate declares it in its own return type. A built-in gate
+ * (`waitForEvent`, `waitForAgent`) has no source, so the schema is taken
+ * from the parameter that consumes the output downstream. Without that, the
+ * caller falls back to a free-form value.
+ */
+export declare function gateOutputSchemas(ast: {
+    instances: Array<{
+        id: string;
+        nodeType: string;
+    }>;
+    nodeTypes: Array<{
+        name: string;
+        functionName: string;
+        functionText?: string;
+        sourceLocation?: {
+            file?: string;
+        };
+    }>;
+    connections: Array<{
+        from: {
+            node: string;
+            port: string;
+        };
+        to: {
+            node: string;
+            port: string;
+        };
+    }>;
+}, gateId: string, fallbackFile: string): Record<string, FieldSchema> | null;
+/** The `params` object of a workflow function: one schema per declared Start port. */
+export declare function workflowParamsSchema(file: string, fnName: string): Record<string, FieldSchema> | null;
+/**
+ * The schema of one parameter of a node function.
+ *
+ * A built-in gate (`waitForEvent`, `waitForAgent`) has no source of its own,
+ * so its output shape cannot be read from a return type. Whatever consumes
+ * that output downstream does declare it (`plan.agentResult` flows into
+ * `checkPlan(plan: Plan)`), so the consumer's parameter is the schema.
+ */
+export declare function nodeInputSchema(file: string, fnName: string, paramName: string): FieldSchema | null;
+/** Data outputs of a node function's return type, control ports dropped. */
+export declare function nodeOutputSchema(file: string, fnName: string): Record<string, FieldSchema> | null;
+//# sourceMappingURL=schema.d.ts.map

package/dist/console/server.d.ts

@@ -0,0 +1,34 @@
+import { type RunStore } from '../coordinator/index.js';
+import { type SupervisorOptions } from './services.js';
+export interface ConsoleServerOptions {
+    /** Directory whose workflows the console shows. */
+    projectDir: string;
+    port?: number;
+    host?: string;
+    /** Directory holding the built client (`index.html`, `app.js`, `styles.css`). Resolved automatically when omitted. */
+    assetsDir?: string;
+    /** Re-list and re-validate when files under the project change. Default true. */
+    watch?: boolean;
+    /** Called when the project is switched from the console. */
+    onProject?: (dir: string) => void;
+    /**
+     * The run store to show and drive, in place of the directory under
+     * `~/.fw/runs`: the same store your `createWorkflowApi` instances use, so
+     * a person here answers the gates they reach. Changes made elsewhere are
+     * picked up by polling, since a store of yours has no directory to watch.
+     */
+    store?: RunStore;
+    /** How the project's services are started. A test hands in a fake spawn and its own directories. */
+    services?: Pick<SupervisorOptions, 'spawn' | 'settingsDir' | 'registryDir'>;
+}
+export interface ConsoleServer {
+    url: string;
+    close(): Promise<void>;
+}
+export interface ConsoleServer {
+    url: string;
+    close(): Promise<void>;
+}
+export { stepLabel } from '../diagram/labels.js';
+export declare function createConsoleServer(options: ConsoleServerOptions): Promise<ConsoleServer>;
+//# sourceMappingURL=server.d.ts.map