@ansible-flow/core 0.0.0-stage → 0.85.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei Chistokhin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @ansible-flow/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ansible Flow Designer core: the flow model, commands, validation and playbook generation, for any JavaScript host.
+
+Built from [Ansible Flow Designer](https://github.com/ChistokhinSV/ansible-flow-designer) 0.85.0
+and released with it. Modules are imported by their path in the source tree, for example
+`@ansible-flow/core/ai/contributions`.
+
+What is in the package, which entry points are documented and what may change:
+[docs/packages.md](https://github.com/ChistokhinSV/ansible-flow-designer/blob/main/docs/packages.md).

package/dist/ai/contributions.d.ts

@@ -0,0 +1,29 @@
+import { type ToolSpec } from './specs';
+/** Copilot tool names carry the extension prefix (VS Code naming guideline). */
+export declare const COPILOT_PREFIX = "afd_";
+export declare function languageModelTool(spec: ToolSpec): {
+    name: string;
+    displayName: string;
+    toolReferenceName: string;
+    canBeReferencedInPrompt: boolean;
+    icon: string;
+    tags: string[];
+    userDescription: string;
+    modelDescription: string;
+    inputSchema: {
+        [x: string]: unknown;
+    };
+};
+export declare function languageModelTools(): {
+    name: string;
+    displayName: string;
+    toolReferenceName: string;
+    canBeReferencedInPrompt: boolean;
+    icon: string;
+    tags: string[];
+    userDescription: string;
+    modelDescription: string;
+    inputSchema: {
+        [x: string]: unknown;
+    };
+}[];

package/dist/ai/contributions.js

@@ -0,0 +1,33 @@
+import {
+  TOOL_SPECS
+} from "../chunks/chunk-SELZNC6A.js";
+import "../chunks/chunk-A2VWJAFE.js";
+import "../chunks/chunk-3DHWUD35.js";
+import "../chunks/chunk-ZP5LQ4XC.js";
+import "../chunks/chunk-AGWQ3ANE.js";
+
+// src/core/ai/contributions.ts
+var COPILOT_PREFIX = "afd_";
+var camel = (name) => name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+function languageModelTool(spec) {
+  return {
+    name: `${COPILOT_PREFIX}${spec.name}`,
+    displayName: spec.title,
+    toolReferenceName: camel(spec.name),
+    canBeReferencedInPrompt: true,
+    icon: "$(type-hierarchy)",
+    tags: ["ansible-flow"],
+    userDescription: spec.description,
+    modelDescription: `${spec.description} Ansible Flow Designer flows (*.flow.yaml); see the ansible-flow skill.`,
+    inputSchema: spec.inputSchema
+  };
+}
+function languageModelTools() {
+  return TOOL_SPECS.map(languageModelTool);
+}
+export {
+  COPILOT_PREFIX,
+  languageModelTool,
+  languageModelTools
+};
+//# sourceMappingURL=contributions.js.map

package/dist/ai/contributions.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/core/ai/contributions.ts"],
+  "sourcesContent": ["// package.json entries derived from the tool specs (AFD-19): `just gen-ai` writes them and a test\n// keeps package.json equal to them, so Copilot sees the same tools as MCP clients.\nimport { TOOL_SPECS, type ToolSpec } from './specs';\n\n/** Copilot tool names carry the extension prefix (VS Code naming guideline). */\nexport const COPILOT_PREFIX = 'afd_';\n\nconst camel = (name: string) => name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());\n\nexport function languageModelTool(spec: ToolSpec) {\n  return {\n    name: `${COPILOT_PREFIX}${spec.name}`,\n    displayName: spec.title,\n    toolReferenceName: camel(spec.name),\n    canBeReferencedInPrompt: true,\n    icon: '$(type-hierarchy)',\n    tags: ['ansible-flow'],\n    userDescription: spec.description,\n    modelDescription: `${spec.description} Ansible Flow Designer flows (*.flow.yaml); see the ansible-flow skill.`,\n    inputSchema: spec.inputSchema,\n  };\n}\n\nexport function languageModelTools() {\n  return TOOL_SPECS.map(languageModelTool);\n}\n"],
+  "mappings": ";;;;;;;;;AAKO,IAAM,iBAAiB;AAE9B,IAAM,QAAQ,CAAC,SAAiB,KAAK,QAAQ,aAAa,CAAC,GAAG,MAAc,EAAE,YAAY,CAAC;AAEpF,SAAS,kBAAkB,MAAgB;AAChD,SAAO;AAAA,IACL,MAAM,GAAG,cAAc,GAAG,KAAK,IAAI;AAAA,IACnC,aAAa,KAAK;AAAA,IAClB,mBAAmB,MAAM,KAAK,IAAI;AAAA,IAClC,yBAAyB;AAAA,IACzB,MAAM;AAAA,IACN,MAAM,CAAC,cAAc;AAAA,IACrB,iBAAiB,KAAK;AAAA,IACtB,kBAAkB,GAAG,KAAK,WAAW;AAAA,IACrC,aAAa,KAAK;AAAA,EACpB;AACF;AAEO,SAAS,qBAAqB;AACnC,SAAO,WAAW,IAAI,iBAAiB;AACzC;",
+  "names": []
+}

package/dist/ai/describe.d.ts

@@ -0,0 +1,29 @@
+import { type LayoutProblem } from '../export/layoutCheck';
+import { type FlowModel } from '../flow/model';
+import type { Position } from '../flow/types';
+import { type Finding } from '../flow/validate';
+/** Where the canvas shows nodes (AFD-24): stored positions and auto ones. */
+export interface ShownLayout {
+    stored: Partial<Record<string, Position>>;
+    auto: Partial<Record<string, Position>>;
+}
+/** AFD-189: how much of a flow describeFlow shows. */
+export interface DescribeView {
+    /** One short line per node. */
+    brief?: boolean;
+    /** Only nodes whose key path starts with one of these, and the wires touching them. */
+    nodes?: string[];
+    /** With layout: only the layout check, no nodes or wires. */
+    onlyProblems?: boolean;
+}
+/**
+ * AFD-189: problems grouped by code (count, the nodes with most of them, the fix once), so a flow
+ * with hundreds of warnings fits in one answer.
+ */
+export declare function summarizeFindings(model: FlowModel, findings: readonly Finding[]): string;
+/** Problems by key, with the fix for each code. */
+export declare function formatFindings(model: FlowModel, findings: readonly Finding[], max?: number): string;
+export declare function countFindings(findings: readonly Finding[]): string;
+export declare function describeFlow(model: FlowModel, findings: readonly Finding[], revision: string, level?: string, layout?: ShownLayout, 
+/** AFD-69: the layout check per level, with layout. */
+layoutIssues?: ReadonlyMap<string, readonly LayoutProblem[]>, view?: DescribeView): string;

package/dist/ai/describe.js

@@ -0,0 +1,62 @@
+import {
+  countFindings,
+  describeFlow,
+  formatFindings,
+  summarizeFindings
+} from "../chunks/chunk-MZ6IJWB2.js";
+import "../chunks/chunk-Z6Y6M2ZK.js";
+import "../chunks/chunk-XOVPLQDM.js";
+import "../chunks/chunk-X3DEH47B.js";
+import "../chunks/chunk-BXJOUAXV.js";
+import "../chunks/chunk-SD6TCN3P.js";
+import "../chunks/chunk-72LO6GQE.js";
+import "../chunks/chunk-4RMWFRWG.js";
+import "../chunks/chunk-X4UNEUME.js";
+import "../chunks/chunk-RLCV7OFW.js";
+import "../chunks/chunk-2QQC4IZ7.js";
+import "../chunks/chunk-OREXQ4IZ.js";
+import "../chunks/chunk-KSM4O2XL.js";
+import "../chunks/chunk-T6SZLRDM.js";
+import "../chunks/chunk-7D55CRGU.js";
+import "../chunks/chunk-GK3SD3WE.js";
+import "../chunks/chunk-H6ARLMMI.js";
+import "../chunks/chunk-TG3C3GIL.js";
+import "../chunks/chunk-WISXIO3I.js";
+import "../chunks/chunk-WG7O3OBV.js";
+import "../chunks/chunk-NUGJSYSP.js";
+import "../chunks/chunk-XRGZNPPO.js";
+import "../chunks/chunk-VG3RKETK.js";
+import "../chunks/chunk-4IZNAB7J.js";
+import "../chunks/chunk-OY4PP6RF.js";
+import "../chunks/chunk-TS4N2EIO.js";
+import "../chunks/chunk-BCX7P6SV.js";
+import "../chunks/chunk-HFHXHOBC.js";
+import "../chunks/chunk-RKLF3DLT.js";
+import "../chunks/chunk-GTHXWNCC.js";
+import "../chunks/chunk-OEQXGULI.js";
+import "../chunks/chunk-AJRIS5VY.js";
+import "../chunks/chunk-GQ2W4RTY.js";
+import "../chunks/chunk-BVEW6MKL.js";
+import "../chunks/chunk-BUPWGYNF.js";
+import "../chunks/chunk-WKETMTKT.js";
+import "../chunks/chunk-VHCA4A7K.js";
+import "../chunks/chunk-3Z2U3LN7.js";
+import "../chunks/chunk-GHG3VINX.js";
+import "../chunks/chunk-5TUAMVIV.js";
+import "../chunks/chunk-45CE2RUH.js";
+import "../chunks/chunk-E2YZJWO7.js";
+import "../chunks/chunk-76T45V37.js";
+import "../chunks/chunk-SELZNC6A.js";
+import "../chunks/chunk-A2VWJAFE.js";
+import "../chunks/chunk-3DHWUD35.js";
+import "../chunks/chunk-ZP5LQ4XC.js";
+import "../chunks/chunk-VY4PCEDN.js";
+import "../chunks/chunk-2OD7UZ7V.js";
+import "../chunks/chunk-AGWQ3ANE.js";
+export {
+  countFindings,
+  describeFlow,
+  formatFindings,
+  summarizeFindings
+};
+//# sourceMappingURL=describe.js.map

package/dist/ai/describe.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/ai/handlers.d.ts

@@ -0,0 +1,144 @@
+import type { SchemaValidator } from '../flow/schema';
+import type { SourceIO } from '../import/read';
+import type { ScenarioResult } from '../scenario/scenarios';
+import { type InventoryIO } from './inventory';
+import { type OpsContext } from './ops';
+import { type ReferenceTopic } from './reference';
+export interface FlowIO {
+    /** Flow files the tools may see, as the paths tools take. */
+    list(): Promise<string[]>;
+    /** The flow a call without path means: the one open in the designer, if any. */
+    current?(): string | undefined;
+    /** Throws an Error with a message for the model when the path is not an allowed flow. */
+    read(path: string): Promise<string>;
+    /** Writes the new text of a flow; returns its final text (e.g. version bumped) and notes. */
+    write(path: string, before: string, after: string): Promise<{
+        text: string;
+        notes: string[];
+    }>;
+    /** Creates a new flow file; throws when it exists or is not allowed. */
+    create(path: string, text: string): Promise<{
+        text: string;
+        notes: string[];
+    }>;
+    /** How ops run for a flow: IDs, the author of decisions, the layout for tidy_up. */
+    ops(path: string): OpsContext;
+    schema: SchemaValidator;
+    /**
+     * AFD-25: writes an export (.drawio or .svg) inside the roots, creating folders; returns its path
+     * as the tools show it. Throws for anything else.
+     */
+    writeExport?(path: string, text: string): Promise<string>;
+    /**
+     * AFD-27: Ansible files inside the roots (playbooks, task files, roles, ansible.cfg, AWX export
+     * JSON), read-only: the reader of the root that holds `path`, the path within it, and the prefix
+     * tools show for that root (its name when there are several, else ''). Absent where the host
+     * cannot read them.
+     */
+    source?(path: string): {
+        io: SourceIO;
+        path: string;
+        prefix: string;
+    } | undefined;
+    /** Short module name + the play's collections → FQCN, where a catalog is loaded. */
+    resolveModule?(name: string, collections: string[]): string | undefined;
+    /** AFD-261: the repository's inventory files, for the inventory tool. Absent where the host has none. */
+    inventory?: InventoryIO;
+    /** AFD-117: the scenarios file next to a flow (`<key>.scenarios.yaml`); undefined if none. */
+    readScenarios?(flowPath: string, flowKey: string): Promise<string | undefined>;
+    /** AFD-117: writes that file (creating it when `before` is undefined); notes for the answer. */
+    writeScenarios?(flowPath: string, flowKey: string, before: string | undefined, after: string): Promise<string[]>;
+    /**
+     * AFD-117: runs scenarios in Ansible (every step its stub) in the configured environment; all
+     * when `names` is absent. Absent where the host cannot run them.
+     */
+    verifyScenarios?(flowPath: string, names?: string[]): Promise<ScenarioResult[] | string>;
+    /**
+     * AFD-191: generates the flow's code (generated/) from the file as it is now, as a save does;
+     * notes for the answer. Absent where the host cannot.
+     */
+    generate?(path: string): Promise<string[]>;
+    /** AFD-191: whether generated/ matches the flow ("current", "out of date: …"); undefined if unknown. */
+    codeState?(path: string): Promise<string | undefined>;
+}
+export interface ToolResult {
+    text: string;
+    isError?: boolean;
+}
+/** A short fingerprint of the file text: flow_edit refuses when the file changed since. */
+export declare function revisionOf(text: string): string;
+export declare function flowList(io: FlowIO): Promise<ToolResult>;
+export declare function flowDescribe(io: FlowIO, input: {
+    path?: string;
+    level?: string;
+    layout?: boolean;
+    nodes?: string[] | string;
+    detail?: string;
+    only_problems?: boolean;
+    page?: number;
+}): Promise<ToolResult>;
+export declare function flowValidate(io: FlowIO, input: {
+    path?: string;
+    code?: string | string[];
+    node?: string;
+    severity?: string;
+    summary?: boolean;
+    page?: number;
+}): Promise<ToolResult>;
+export declare function flowReference(input: {
+    topic?: ReferenceTopic;
+}): ToolResult;
+export declare function flowEdit(io: FlowIO, input: {
+    path?: string;
+    ops?: unknown;
+    revision?: string;
+    dry_run?: boolean;
+}): Promise<ToolResult>;
+export declare function flowNew(io: FlowIO, input: {
+    path?: string;
+    name?: string;
+    key?: string;
+    goal?: string;
+}): Promise<ToolResult>;
+export declare function flowCompleteIds(io: FlowIO, input: {
+    path?: string;
+}): Promise<ToolResult>;
+/**
+ * AFD-25: the flow as a draw.io file (a page per level) or SVG images of its levels, which embed
+ * the draw.io file. Positions are what the canvas shows; PNG needs the designer, so not here.
+ */
+export declare function flowExport(io: FlowIO, input: {
+    path?: string;
+    format?: string;
+    level?: string;
+    out?: string;
+}): Promise<ToolResult>;
+/**
+ * AFD-27: existing automation (a playbook, a folder, a role, an AWX export) as text an agent designs
+ * from: structure, and per task the exact binding an import writes. Secrets by name only.
+ */
+export declare function sourceOutlineTool(io: FlowIO, input: {
+    path?: string;
+    focus?: string;
+    flow?: string;
+    page?: number;
+    full?: boolean;
+}): Promise<ToolResult>;
+/**
+ * AFD-27: the as-is import (AFD-26) as a tool: a playbook, or a template of an AWX export, becomes a
+ * new flow, one step per task. For an exact copy; an intent-based design is built with flow_new and
+ * flow_edit from source_outline instead.
+ */
+export declare function flowImport(io: FlowIO, input: {
+    source?: string;
+    path?: string;
+    template?: string;
+    name?: string;
+}): Promise<ToolResult>;
+/**
+ * AFD-189: the largest answer a tool gives. Agents take about 25k tokens per tool result; a
+ * larger one is saved to a file they read in pieces.
+ */
+export declare const MAX_TOOL_TEXT = 40000;
+/** Runs a tool by name: the adapters' single entry point. */
+export declare function runTool(io: FlowIO, name: string, input: unknown): Promise<ToolResult>;