@ansible-flow/node 0.0.0-stage → 0.85.0

package/dist/env/userSettings.d.ts

@@ -0,0 +1,33 @@
+/** The settings keys that choose the environment (package.json's restrictedConfigurations). */
+export declare const ENVIRONMENT_KEYS: readonly ['afd.environment.kind', 'afd.environment.image', 'afd.environment.containerEngine', 'afd.environment.containerOptions', 'afd.environment.python', 'afd.environment.wslDistro', 'afd.environment.sshHost', 'afd.environment.sshDir', 'afd.environment.sshImage', 'ansible.executionEnvironment.enabled', 'ansible.executionEnvironment.image', 'ansible.executionEnvironment.containerEngine', 'ansible.executionEnvironment.containerOptions', 'ansible.executionEnvironment.volumeMounts', 'ansible.python.interpreterPath'];
+export interface SettingsHost {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+}
+/** User settings.json files to try; AFD_USER_SETTINGS names one explicitly. */
+export declare function userSettingsCandidates(host: SettingsHost): string[];
+export declare const workspaceEnvironmentAllowed: (env: NodeJS.ProcessEnv) => boolean;
+export interface EnvironmentSettings {
+    /** The environment keys, the workspace's over the user's when the workspace is allowed. */
+    json: Record<string, unknown>;
+    /** The settings files the keys came from. */
+    sources: string[];
+    /** The workspace sets environment keys that were not used (no opt-in). */
+    ignoredWorkspace: boolean;
+}
+/** The environment settings for a root: the first user settings.json found, then the workspace's. */
+export declare function environmentSettings(root: string, host?: SettingsHost): Promise<EnvironmentSettings>;
+/**
+ * `afd.canvas.direction` for a root (AFD-192), so the MCP tools lay out unplaced nodes as the
+ * canvas does: the workspace's .vscode/settings.json, else the first user settings.json found
+ * (VS Code's order). Not a restricted key: it only places boxes. TB when neither sets it.
+ */
+export declare function canvasDirection(root: string, host?: SettingsHost): Promise<'TB' | 'LR'>;
+/**
+ * `afd.run.inventory` for a root (AFD-261), so the agents' inventory tool works on the inventory
+ * the runs use: the workspace's .vscode/settings.json, else the first user settings.json found.
+ * Not a restricted key: it names a file of the repository, which the tool reads inside the root
+ * only. Empty when neither sets it (the default of ansible.cfg).
+ */
+export declare function runInventory(root: string, host?: SettingsHost): Promise<string>;

package/dist/env/userSettings.js

@@ -0,0 +1,101 @@
+// src/node/env/userSettings.ts
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getNodeValue, parseTree } from "jsonc-parser";
+var PRODUCTS = ["Code", "Code - Insiders", "VSCodium", "Cursor", "Windsurf"];
+var ENVIRONMENT_KEYS = [
+  "afd.environment.kind",
+  "afd.environment.image",
+  "afd.environment.containerEngine",
+  "afd.environment.containerOptions",
+  "afd.environment.python",
+  "afd.environment.wslDistro",
+  // AFD-252: without these an SSH environment had a kind and no host.
+  "afd.environment.sshHost",
+  "afd.environment.sshDir",
+  "afd.environment.sshImage",
+  "ansible.executionEnvironment.enabled",
+  "ansible.executionEnvironment.image",
+  "ansible.executionEnvironment.containerEngine",
+  "ansible.executionEnvironment.containerOptions",
+  "ansible.executionEnvironment.volumeMounts",
+  "ansible.python.interpreterPath"
+];
+var thisHost = () => ({
+  platform: process.platform,
+  env: process.env,
+  home: homedir()
+});
+function userSettingsCandidates(host) {
+  if (host.env.AFD_USER_SETTINGS) return [host.env.AFD_USER_SETTINGS];
+  const base = host.platform === "win32" ? host.env.APPDATA ?? join(host.home, "AppData", "Roaming") : host.platform === "darwin" ? join(host.home, "Library", "Application Support") : host.env.XDG_CONFIG_HOME ?? join(host.home, ".config");
+  return PRODUCTS.map((p) => join(base, p, "User", "settings.json"));
+}
+var workspaceEnvironmentAllowed = (env) => /^(1|true|yes)$/i.test(env.AFD_MCP_WORKSPACE_ENVIRONMENT ?? "");
+async function readSettings(path) {
+  try {
+    const tree = parseTree(await fs.readFile(path, "utf8"));
+    const value = tree ? getNodeValue(tree) : void 0;
+    return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var environmentOnly = (json) => Object.fromEntries(ENVIRONMENT_KEYS.filter((k) => k in json).map((k) => [k, json[k]]));
+async function environmentSettings(root, host = thisHost()) {
+  const sources = [];
+  let json = {};
+  for (const path of userSettingsCandidates(host)) {
+    const user = await readSettings(path);
+    if (!user) continue;
+    json = environmentOnly(user);
+    sources.push(path);
+    break;
+  }
+  const workspacePath = join(root, ".vscode", "settings.json");
+  const workspace = environmentOnly(await readSettings(workspacePath) ?? {});
+  const used = Object.keys(workspace).length > 0 && workspaceEnvironmentAllowed(host.env);
+  if (used) {
+    json = { ...json, ...workspace };
+    sources.push(workspacePath);
+  }
+  return {
+    json,
+    sources,
+    ignoredWorkspace: Object.keys(workspace).length > 0 && !used
+  };
+}
+async function canvasDirection(root, host = thisHost()) {
+  const workspace = await readSettings(join(root, ".vscode", "settings.json"));
+  let value = workspace?.["afd.canvas.direction"];
+  if (value === void 0)
+    for (const path of userSettingsCandidates(host)) {
+      const user = await readSettings(path);
+      if (!user) continue;
+      value = user["afd.canvas.direction"];
+      break;
+    }
+  return value === "LR" ? "LR" : "TB";
+}
+async function runInventory(root, host = thisHost()) {
+  const workspace = await readSettings(join(root, ".vscode", "settings.json"));
+  let value = workspace?.["afd.run.inventory"];
+  if (value === void 0)
+    for (const path of userSettingsCandidates(host)) {
+      const user = await readSettings(path);
+      if (!user) continue;
+      value = user["afd.run.inventory"];
+      break;
+    }
+  return typeof value === "string" ? value.trim() : "";
+}
+export {
+  ENVIRONMENT_KEYS,
+  canvasDirection,
+  environmentSettings,
+  runInventory,
+  userSettingsCandidates,
+  workspaceEnvironmentAllowed
+};
+//# sourceMappingURL=userSettings.js.map

package/dist/env/userSettings.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/node/env/userSettings.ts"],
+  "sourcesContent": ["// Where the MCP server takes its Ansible environment from (AFD-126). The image, container options,\n// mounts and interpreter decide what runs on this machine, so they come from the user's own VS Code\n// settings. A workspace's .vscode/settings.json is repository content: VS Code ignores these keys\n// there until the workspace is trusted, and the server has no trust prompt, so it reads them only\n// when the user starts it with AFD_MCP_WORKSPACE_ENVIRONMENT=1.\n\nimport { promises as fs } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport { getNodeValue, parseTree } from 'jsonc-parser';\n\n/** VS Code and the forks the setup registers the server for, in the order they are tried. */\nconst PRODUCTS = ['Code', 'Code - Insiders', 'VSCodium', 'Cursor', 'Windsurf'];\n\n/** The settings keys that choose the environment (package.json's restrictedConfigurations). */\nexport const ENVIRONMENT_KEYS = [\n  'afd.environment.kind',\n  'afd.environment.image',\n  'afd.environment.containerEngine',\n  'afd.environment.containerOptions',\n  'afd.environment.python',\n  'afd.environment.wslDistro',\n  // AFD-252: without these an SSH environment had a kind and no host.\n  'afd.environment.sshHost',\n  'afd.environment.sshDir',\n  'afd.environment.sshImage',\n  'ansible.executionEnvironment.enabled',\n  'ansible.executionEnvironment.image',\n  'ansible.executionEnvironment.containerEngine',\n  'ansible.executionEnvironment.containerOptions',\n  'ansible.executionEnvironment.volumeMounts',\n  'ansible.python.interpreterPath',\n] as const;\n\nexport interface SettingsHost {\n  platform: NodeJS.Platform;\n  env: NodeJS.ProcessEnv;\n  home: string;\n}\n\nconst thisHost = (): SettingsHost => ({\n  platform: process.platform,\n  env: process.env,\n  home: homedir(),\n});\n\n/** User settings.json files to try; AFD_USER_SETTINGS names one explicitly. */\nexport function userSettingsCandidates(host: SettingsHost): string[] {\n  if (host.env.AFD_USER_SETTINGS) return [host.env.AFD_USER_SETTINGS];\n  const base =\n    host.platform === 'win32'\n      ? (host.env.APPDATA ?? join(host.home, 'AppData', 'Roaming'))\n      : host.platform === 'darwin'\n        ? join(host.home, 'Library', 'Application Support')\n        : (host.env.XDG_CONFIG_HOME ?? join(host.home, '.config'));\n  return PRODUCTS.map((p) => join(base, p, 'User', 'settings.json'));\n}\n\nexport const workspaceEnvironmentAllowed = (env: NodeJS.ProcessEnv): boolean =>\n  /^(1|true|yes)$/i.test(env.AFD_MCP_WORKSPACE_ENVIRONMENT ?? '');\n\nasync function readSettings(path: string): Promise<Record<string, unknown> | undefined> {\n  try {\n    const tree = parseTree(await fs.readFile(path, 'utf8'));\n    const value = tree ? getNodeValue(tree) : undefined;\n    return value && typeof value === 'object' && !Array.isArray(value)\n      ? (value as Record<string, unknown>)\n      : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nconst environmentOnly = (json: Record<string, unknown>) =>\n  Object.fromEntries(ENVIRONMENT_KEYS.filter((k) => k in json).map((k) => [k, json[k]]));\n\nexport interface EnvironmentSettings {\n  /** The environment keys, the workspace's over the user's when the workspace is allowed. */\n  json: Record<string, unknown>;\n  /** The settings files the keys came from. */\n  sources: string[];\n  /** The workspace sets environment keys that were not used (no opt-in). */\n  ignoredWorkspace: boolean;\n}\n\n/** The environment settings for a root: the first user settings.json found, then the workspace's. */\nexport async function environmentSettings(\n  root: string,\n  host: SettingsHost = thisHost(),\n): Promise<EnvironmentSettings> {\n  const sources: string[] = [];\n  let json: Record<string, unknown> = {};\n  for (const path of userSettingsCandidates(host)) {\n    const user = await readSettings(path);\n    if (!user) continue;\n    json = environmentOnly(user);\n    sources.push(path);\n    break;\n  }\n  const workspacePath = join(root, '.vscode', 'settings.json');\n  const workspace = environmentOnly((await readSettings(workspacePath)) ?? {});\n  const used = Object.keys(workspace).length > 0 && workspaceEnvironmentAllowed(host.env);\n  if (used) {\n    json = { ...json, ...workspace };\n    sources.push(workspacePath);\n  }\n  return {\n    json,\n    sources,\n    ignoredWorkspace: Object.keys(workspace).length > 0 && !used,\n  };\n}\n\n/**\n * `afd.canvas.direction` for a root (AFD-192), so the MCP tools lay out unplaced nodes as the\n * canvas does: the workspace's .vscode/settings.json, else the first user settings.json found\n * (VS Code's order). Not a restricted key: it only places boxes. TB when neither sets it.\n */\nexport async function canvasDirection(\n  root: string,\n  host: SettingsHost = thisHost(),\n): Promise<'TB' | 'LR'> {\n  const workspace = await readSettings(join(root, '.vscode', 'settings.json'));\n  let value = workspace?.['afd.canvas.direction'];\n  if (value === undefined)\n    for (const path of userSettingsCandidates(host)) {\n      const user = await readSettings(path);\n      if (!user) continue;\n      value = user['afd.canvas.direction'];\n      break;\n    }\n  return value === 'LR' ? 'LR' : 'TB';\n}\n\n/**\n * `afd.run.inventory` for a root (AFD-261), so the agents' inventory tool works on the inventory\n * the runs use: the workspace's .vscode/settings.json, else the first user settings.json found.\n * Not a restricted key: it names a file of the repository, which the tool reads inside the root\n * only. Empty when neither sets it (the default of ansible.cfg).\n */\nexport async function runInventory(root: string, host: SettingsHost = thisHost()): Promise<string> {\n  const workspace = await readSettings(join(root, '.vscode', 'settings.json'));\n  let value = workspace?.['afd.run.inventory'];\n  if (value === undefined)\n    for (const path of userSettingsCandidates(host)) {\n      const user = await readSettings(path);\n      if (!user) continue;\n      value = user['afd.run.inventory'];\n      break;\n    }\n  return typeof value === 'string' ? value.trim() : '';\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/run/audit.d.ts

@@ -0,0 +1,2 @@
+export declare function auditFile(storage: string): string;
+export declare function appendAudit(storage: string, entry: Record<string, unknown>): Promise<void>;

package/dist/run/audit.js

@@ -0,0 +1,10 @@
+import {
+  appendAudit,
+  auditFile
+} from "../chunks/chunk-NTZRNEZM.js";
+import "../chunks/chunk-SUV3VHKR.js";
+export {
+  appendAudit,
+  auditFile
+};
+//# sourceMappingURL=audit.js.map

package/dist/run/audit.js.map

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

package/dist/run/exec.d.ts

@@ -0,0 +1,14 @@
+import type { ProcessSpec } from '@ansible-flow/core/run/command';
+/** A process that was started: how it ended, and how to end it. */
+export interface Execution {
+    /** The exit code; undefined when the process could not start or ended without one. */
+    exit: Promise<number | undefined>;
+    /** Ends the process. What it started beyond itself (a container) is ended with `stopStarted`. */
+    terminate(): void;
+}
+/**
+ * Runs `spec` with `env` on top of this process's environment, feeding its output to `log` line
+ * by line. AFD-247: a spec with `input` names the variables whose values go to the process's
+ * input, one base64 line each, instead of its arguments (what afd-ssh-run does for a terminal).
+ */
+export declare function startProcess(spec: ProcessSpec, env: Record<string, string>, log: (line: string) => void): Execution;

package/dist/run/exec.js

@@ -0,0 +1,7 @@
+import {
+  startProcess
+} from "../chunks/chunk-I6FIOP7G.js";
+export {
+  startProcess
+};
+//# sourceMappingURL=exec.js.map

package/dist/run/exec.js.map

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

package/dist/run/facts.d.ts

@@ -0,0 +1,39 @@
+import type { FlowDocument } from '@ansible-flow/core/flow/types';
+import { type LaunchFacts } from '@ansible-flow/core/run/launch';
+/** The probe of the Ansible environment a run uses, and the name people know it by. */
+export interface RunProbe {
+    client: {
+        call<T>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    };
+    label: string;
+}
+/**
+ * What a run with these inputs would touch: the hosts the targets match in the inventory, the
+ * inventory_targets of the flow's steps, what looks like production.
+ */
+export declare function launchFacts(doc: FlowDocument, inputs: Record<string, unknown>, probe: RunProbe, inventory: string | undefined): Promise<{
+    ok: true;
+    facts: LaunchFacts;
+} | {
+    ok: false;
+    error: string;
+}>;
+/**
+ * The inventory's groups, for the dialog's host list suggestions (AFD-82), with each group's hosts
+ * (AFD-95, from the probe's inventory_tree, one inventory parse as before); none when it fails.
+ */
+export declare function inventoryGroups(probe: RunProbe, inventory: string | undefined): Promise<{
+    groups: string[];
+    hosts: Record<string, {
+        count: number;
+        hosts: string[];
+    }>;
+}>;
+/**
+ * AFD-141: the callbacks the repository's ansible.cfg enables, so they keep running next to the
+ * run's own; undefined when the environment does not answer (the run's callback alone, then).
+ */
+export declare function repositoryCallbacks(probe: RunProbe): Promise<{
+    enabled: string[];
+    paths: string[];
+} | undefined>;

package/dist/run/facts.js

@@ -0,0 +1,96 @@
+import {
+  TIMEOUTS
+} from "../chunks/chunk-IIFP6UQR.js";
+
+// src/node/run/facts.ts
+import { resolvePattern, targetUses } from "@ansible-flow/core/engine/targets";
+import { buildModel } from "@ansible-flow/core/flow/model";
+import { targetsOf } from "@ansible-flow/core/run/launch";
+import { groupHosts } from "@ansible-flow/core/view/inventoryTree";
+async function targetFacts(doc, inputs, count) {
+  return Promise.all(
+    targetUses(buildModel(doc)).map(async (u) => {
+      const pattern = resolvePattern(u.target, inputs);
+      const use = { pattern, declared: u.target, nodes: u.nodes, prod: [] };
+      if (!pattern) return use;
+      try {
+        const f = await count(pattern);
+        use.count = f.count;
+        use.prod = [...f.prod_groups, ...f.prod_hosts];
+      } catch {
+      }
+      return use;
+    })
+  );
+}
+async function launchFacts(doc, inputs, probe, inventory) {
+  const targets = targetsOf(doc, inputs);
+  if (targets.length === 0)
+    return { ok: false, error: "No target hosts: the targets input is empty" };
+  let found;
+  try {
+    found = await probe.client.call(
+      "inventory",
+      { inventory, targets },
+      TIMEOUTS.probeInventory
+    );
+  } catch (e) {
+    return {
+      ok: false,
+      error: `The Ansible environment (${probe.label}) did not answer: ${e.message}`
+    };
+  }
+  if (found.count === 0)
+    return { ok: false, error: `None of the targets (${targets.join(", ")}) is in the inventory` };
+  const uses = await targetFacts(
+    doc,
+    inputs,
+    (pattern) => probe.client.call(
+      "inventory",
+      { inventory, targets: [pattern] },
+      TIMEOUTS.probeInventory
+    )
+  );
+  const prod = [
+    .../* @__PURE__ */ new Set([...found.prod_groups, ...found.prod_hosts, ...uses.flatMap((u) => u.prod)])
+  ];
+  return {
+    ok: true,
+    facts: {
+      sources: found.sources,
+      count: found.count,
+      hosts: found.hosts,
+      unknown: found.unknown,
+      uses,
+      prod,
+      vault: found.vault,
+      environment: probe.label
+    }
+  };
+}
+async function inventoryGroups(probe, inventory) {
+  try {
+    const tree = await probe.client.call(
+      "inventory_tree",
+      { inventory },
+      TIMEOUTS.probeInventory
+    );
+    const hosts = groupHosts(tree);
+    return { groups: Object.keys(hosts).sort((a, b) => a.localeCompare(b)), hosts };
+  } catch {
+    return { groups: [], hosts: {} };
+  }
+}
+async function repositoryCallbacks(probe) {
+  return probe.client.call(
+    "run_config",
+    {},
+    TIMEOUTS.probeInventory
+  ).then((c) => ({ enabled: c.callbacks_enabled ?? [], paths: c.callback_plugins ?? [] })).catch(() => void 0);
+}
+export {
+  inventoryGroups,
+  launchFacts,
+  repositoryCallbacks
+};
+//# sourceMappingURL=facts.js.map

package/dist/run/facts.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/node/run/facts.ts"],
+  "sourcesContent": ["// What a run would touch, asked of the inventory through the probe (the real-run confirmation and\n// the launch dialog, AFD-82). AFD-271: without VS Code, for every host that runs flows.\nimport { resolvePattern, targetUses } from '../../core/engine/targets';\nimport { buildModel } from '../../core/flow/model';\nimport type { FlowDocument } from '../../core/flow/types';\nimport { type LaunchFacts, type TargetUse, targetsOf } from '../../core/run/launch';\nimport { groupHosts, type InventoryTree } from '../../core/view/inventoryTree';\nimport { TIMEOUTS } from '../timeouts';\n\n/** The probe of the Ansible environment a run uses, and the name people know it by. */\nexport interface RunProbe {\n  client: {\n    call<T>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;\n  };\n  label: string;\n}\n\ninterface InventoryFacts {\n  sources: string[];\n  count: number;\n  hosts: string[];\n  unknown: string[];\n  prod_groups: string[];\n  prod_hosts: string[];\n  vault: boolean;\n  /** Per group, how many of the matched hosts it has. */\n  groups?: Record<string, number>;\n}\n\nasync function targetFacts(\n  doc: FlowDocument,\n  inputs: Record<string, unknown>,\n  count: (pattern: string) => Promise<InventoryFacts>,\n): Promise<TargetUse[]> {\n  return Promise.all(\n    targetUses(buildModel(doc)).map(async (u): Promise<TargetUse> => {\n      const pattern = resolvePattern(u.target, inputs);\n      const use: TargetUse = { pattern, declared: u.target, nodes: u.nodes, prod: [] };\n      if (!pattern) return use;\n      try {\n        const f = await count(pattern);\n        use.count = f.count;\n        use.prod = [...f.prod_groups, ...f.prod_hosts];\n      } catch {\n        // Counted at run time only; the confirmation says so.\n      }\n      return use;\n    }),\n  );\n}\n\n/**\n * What a run with these inputs would touch: the hosts the targets match in the inventory, the\n * inventory_targets of the flow's steps, what looks like production.\n */\nexport async function launchFacts(\n  doc: FlowDocument,\n  inputs: Record<string, unknown>,\n  probe: RunProbe,\n  inventory: string | undefined,\n): Promise<{ ok: true; facts: LaunchFacts } | { ok: false; error: string }> {\n  const targets = targetsOf(doc, inputs);\n  if (targets.length === 0)\n    return { ok: false, error: 'No target hosts: the targets input is empty' };\n  let found: InventoryFacts;\n  try {\n    found = await probe.client.call<InventoryFacts>(\n      'inventory',\n      { inventory, targets },\n      TIMEOUTS.probeInventory,\n    );\n  } catch (e) {\n    return {\n      ok: false,\n      error: `The Ansible environment (${probe.label}) did not answer: ${(e as Error).message}`,\n    };\n  }\n  if (found.count === 0)\n    return { ok: false, error: `None of the targets (${targets.join(', ')}) is in the inventory` };\n  const uses = await targetFacts(doc, inputs, (pattern) =>\n    probe.client.call<InventoryFacts>(\n      'inventory',\n      { inventory, targets: [pattern] },\n      TIMEOUTS.probeInventory,\n    ),\n  );\n  const prod = [\n    ...new Set([...found.prod_groups, ...found.prod_hosts, ...uses.flatMap((u) => u.prod)]),\n  ];\n  return {\n    ok: true,\n    facts: {\n      sources: found.sources,\n      count: found.count,\n      hosts: found.hosts,\n      unknown: found.unknown,\n      uses,\n      prod,\n      vault: found.vault,\n      environment: probe.label,\n    },\n  };\n}\n\n/**\n * The inventory's groups, for the dialog's host list suggestions (AFD-82), with each group's hosts\n * (AFD-95, from the probe's inventory_tree, one inventory parse as before); none when it fails.\n */\nexport async function inventoryGroups(\n  probe: RunProbe,\n  inventory: string | undefined,\n): Promise<{ groups: string[]; hosts: Record<string, { count: number; hosts: string[] }> }> {\n  try {\n    const tree = await probe.client.call<InventoryTree>(\n      'inventory_tree',\n      { inventory },\n      TIMEOUTS.probeInventory,\n    );\n    const hosts = groupHosts(tree);\n    return { groups: Object.keys(hosts).sort((a, b) => a.localeCompare(b)), hosts };\n  } catch {\n    return { groups: [], hosts: {} };\n  }\n}\n\n/**\n * AFD-141: the callbacks the repository's ansible.cfg enables, so they keep running next to the\n * run's own; undefined when the environment does not answer (the run's callback alone, then).\n */\nexport async function repositoryCallbacks(\n  probe: RunProbe,\n): Promise<{ enabled: string[]; paths: string[] } | undefined> {\n  return probe.client\n    .call<{ callbacks_enabled: string[]; callback_plugins: string[] }>(\n      'run_config',\n      {},\n      TIMEOUTS.probeInventory,\n    )\n    .then((c) => ({ enabled: c.callbacks_enabled ?? [], paths: c.callback_plugins ?? [] }))\n    .catch(() => undefined);\n}\n"],
+  "mappings": ";;;;;AAEA,SAAS,gBAAgB,kBAAkB;AAC3C,SAAS,kBAAkB;AAE3B,SAA2C,iBAAiB;AAC5D,SAAS,kBAAsC;AAuB/C,eAAe,YACb,KACA,QACA,OACsB;AACtB,SAAO,QAAQ;AAAA,IACb,WAAW,WAAW,GAAG,CAAC,EAAE,IAAI,OAAO,MAA0B;AAC/D,YAAM,UAAU,eAAe,EAAE,QAAQ,MAAM;AAC/C,YAAM,MAAiB,EAAE,SAAS,UAAU,EAAE,QAAQ,OAAO,EAAE,OAAO,MAAM,CAAC,EAAE;AAC/E,UAAI,CAAC,QAAS,QAAO;AACrB,UAAI;AACF,cAAM,IAAI,MAAM,MAAM,OAAO;AAC7B,YAAI,QAAQ,EAAE;AACd,YAAI,OAAO,CAAC,GAAG,EAAE,aAAa,GAAG,EAAE,UAAU;AAAA,MAC/C,QAAQ;AAAA,MAER;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;AAMA,eAAsB,YACpB,KACA,QACA,OACA,WAC0E;AAC1E,QAAM,UAAU,UAAU,KAAK,MAAM;AACrC,MAAI,QAAQ,WAAW;AACrB,WAAO,EAAE,IAAI,OAAO,OAAO,8CAA8C;AAC3E,MAAI;AACJ,MAAI;AACF,YAAQ,MAAM,MAAM,OAAO;AAAA,MACzB;AAAA,MACA,EAAE,WAAW,QAAQ;AAAA,MACrB,SAAS;AAAA,IACX;AAAA,EACF,SAAS,GAAG;AACV,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,OAAO,4BAA4B,MAAM,KAAK,qBAAsB,EAAY,OAAO;AAAA,IACzF;AAAA,EACF;AACA,MAAI,MAAM,UAAU;AAClB,WAAO,EAAE,IAAI,OAAO,OAAO,wBAAwB,QAAQ,KAAK,IAAI,CAAC,wBAAwB;AAC/F,QAAM,OAAO,MAAM;AAAA,IAAY;AAAA,IAAK;AAAA,IAAQ,CAAC,YAC3C,MAAM,OAAO;AAAA,MACX;AAAA,MACA,EAAE,WAAW,SAAS,CAAC,OAAO,EAAE;AAAA,MAChC,SAAS;AAAA,IACX;AAAA,EACF;AACA,QAAM,OAAO;AAAA,IACX,GAAG,oBAAI,IAAI,CAAC,GAAG,MAAM,aAAa,GAAG,MAAM,YAAY,GAAG,KAAK,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAAA,EACxF;AACA,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,OAAO;AAAA,MACL,SAAS,MAAM;AAAA,MACf,OAAO,MAAM;AAAA,MACb,OAAO,MAAM;AAAA,MACb,SAAS,MAAM;AAAA,MACf;AAAA,MACA;AAAA,MACA,OAAO,MAAM;AAAA,MACb,aAAa,MAAM;AAAA,IACrB;AAAA,EACF;AACF;AAMA,eAAsB,gBACpB,OACA,WAC0F;AAC1F,MAAI;AACF,UAAM,OAAO,MAAM,MAAM,OAAO;AAAA,MAC9B;AAAA,MACA,EAAE,UAAU;AAAA,MACZ,SAAS;AAAA,IACX;AACA,UAAM,QAAQ,WAAW,IAAI;AAC7B,WAAO,EAAE,QAAQ,OAAO,KAAK,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,cAAc,CAAC,CAAC,GAAG,MAAM;AAAA,EAChF,QAAQ;AACN,WAAO,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,EAAE;AAAA,EACjC;AACF;AAMA,eAAsB,oBACpB,OAC6D;AAC7D,SAAO,MAAM,OACV;AAAA,IACC;AAAA,IACA,CAAC;AAAA,IACD,SAAS;AAAA,EACX,EACC,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,qBAAqB,CAAC,GAAG,OAAO,EAAE,oBAAoB,CAAC,EAAE,EAAE,EACrF,MAAM,MAAM,MAAS;AAC1B;",
+  "names": []
+}

package/dist/run/ids.d.ts

@@ -0,0 +1,2 @@
+/** A run id: the start time, sortable (run folders are pruned by it, AFD-29). */
+export declare function stamp(d?: Date): string;

package/dist/run/ids.js

@@ -0,0 +1,8 @@
+// src/node/run/ids.ts
+function stamp(d = /* @__PURE__ */ new Date()) {
+  return d.toISOString().replaceAll(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+export {
+  stamp
+};
+//# sourceMappingURL=ids.js.map

package/dist/run/ids.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/node/run/ids.ts"],
+  "sourcesContent": ["/** A run id: the start time, sortable (run folders are pruned by it, AFD-29). */\nexport function stamp(d = new Date()): string {\n  return d\n    .toISOString()\n    .replaceAll(/[-:]/g, '')\n    .replace(/\\.\\d+Z$/, 'Z');\n}\n"],
+  "mappings": ";AACO,SAAS,MAAM,IAAI,oBAAI,KAAK,GAAW;AAC5C,SAAO,EACJ,YAAY,EACZ,WAAW,SAAS,EAAE,EACtB,QAAQ,WAAW,GAAG;AAC3B;",
+  "names": []
+}

package/dist/run/pastRuns.d.ts

@@ -0,0 +1,9 @@
+import type { RunView } from '@ansible-flow/core/protocol';
+import { type PastRun } from '@ansible-flow/core/run/pastRuns';
+/** Where the runs of a flow are kept. */
+export declare function runsDir(storage: string, flowId: string): string;
+/** Keeps a finished run with its events. The view holds host names and results, no input values. */
+export declare function keepRun(runDir: string, run: RunView): Promise<void>;
+/** The kept runs of a flow, the newest first. */
+export declare function listRuns(storage: string, flowId: string): Promise<PastRun[]>;
+export declare function loadRun(storage: string, flowId: string, id: string): Promise<RunView | undefined>;

package/dist/run/pastRuns.js

@@ -0,0 +1,13 @@
+import {
+  keepRun,
+  listRuns,
+  loadRun,
+  runsDir
+} from "../chunks/chunk-4FHPTGI4.js";
+export {
+  keepRun,
+  listRuns,
+  loadRun,
+  runsDir
+};
+//# sourceMappingURL=pastRuns.js.map

package/dist/run/pastRuns.js.map

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

package/dist/run/runFlow.d.ts

@@ -0,0 +1,78 @@
+import type { GenerateResult } from '@ansible-flow/core/engine/types';
+import type { FlowDocument } from '@ansible-flow/core/flow/types';
+import type { RunView } from '@ansible-flow/core/protocol';
+import { type ProcessSpec } from '@ansible-flow/core/run/command';
+import type { Environment } from '@ansible-flow/core/run/environment';
+import { type RunSummary } from '@ansible-flow/core/run/events';
+import { type Execution } from './exec';
+/** How often a live run updates its view, at most (AFD-81). */
+export declare const LIVE_MS = 500;
+/** No new events for this long: the run may wait for input. */
+export declare const STALL_MS = 20000;
+export interface RunFlowRequest {
+    /** The run's id (`stamp()`), which names its folder. */
+    id: string;
+    startedAt: string;
+    mode: 'check' | 'real';
+    doc: FlowDocument;
+    /** The code that runs: its routes map the events back to nodes. */
+    code: GenerateResult;
+    env: Environment;
+    /** The environment's name for people ("afd-ee:2.19 (docker)"). */
+    environment: string;
+    /** Repository root on this machine. */
+    root: string;
+    /** Folder with afd_probe/ and callback_plugins/afd_events.py. */
+    probeDir: string;
+    /** The playbook to run, relative to `root`, with forward slashes. */
+    playbook: string;
+    inventory?: string;
+    /** Where runs are kept: `<storage>/runs/<flow id>/<run id>/`, and the audit log. */
+    storage: string;
+    /** How many runs of the flow to keep (default `KEEP_RUNS`). */
+    keepRuns?: number;
+    /** Flow input values. Secret ones never reach a file. */
+    inputs: Record<string, unknown>;
+    vaultPassword?: string;
+    /** The repository's own callbacks, kept running beside the run's (`repositoryCallbacks`). */
+    callbacks?: {
+        enabled: string[];
+        paths: string[];
+    };
+    /** AFD-244: the run is of a part of the flow; its code is in a folder of its own. */
+    partial?: RunView['partial'];
+    /** AFD-247: paths the SSH copy needs that Git does not list (a partial run's folder). */
+    syncAlso?: string[];
+    /** What the audit log says about the launch, besides the run's id. Never input values. */
+    audit?: Record<string, unknown>;
+    /** Stops the run when it aborts. */
+    signal?: AbortSignal;
+}
+export interface RunFlowHooks {
+    /** The run's view: when it starts, as it goes (at most every `LIVE_MS`), and when it ends. */
+    report(run: RunView): void;
+    /**
+     * Starts the process. Default: a child process whose output goes to `log`. `stopping` says the
+     * run is being stopped, for a host whose process may end without an exit code then.
+     */
+    execute?(spec: ProcessSpec, env: Record<string, string>, stopping: () => boolean): Execution | Promise<Execution>;
+    /** The default process's output, line by line. */
+    log?(line: string): void;
+    /** The run started; `stop` ends it. Returns what to call when the run has ended. */
+    started?(stop: () => Promise<void>): (() => void) | undefined;
+    /** Whether to watch for a run gone quiet (no event for `STALL_MS`). */
+    watchQuiet?: boolean;
+    /** The run went quiet. */
+    quiet?(): void;
+    /** The process ended; before its events are read. */
+    ended?(): Promise<void>;
+    /** How the run ended, before it is kept and reported. */
+    finished?(end: {
+        stopped: boolean;
+        rc: number | undefined;
+        events: boolean;
+        summary: RunSummary;
+    }): void;
+}
+/** Runs the flow's code and resolves with the finished run (also reported). Never rejects. */
+export declare function runFlow(request: RunFlowRequest, hooks: RunFlowHooks): Promise<RunView>;

package/dist/run/runFlow.js

@@ -0,0 +1,20 @@
+import {
+  LIVE_MS,
+  STALL_MS,
+  runFlow
+} from "../chunks/chunk-LGUG2Q7Z.js";
+import "../chunks/chunk-RETJPSKL.js";
+import "../chunks/chunk-THNSGAKN.js";
+import "../chunks/chunk-FG53MLUX.js";
+import "../chunks/chunk-4FHPTGI4.js";
+import "../chunks/chunk-SSZNBJZQ.js";
+import "../chunks/chunk-JDPN3LTT.js";
+import "../chunks/chunk-NTZRNEZM.js";
+import "../chunks/chunk-SUV3VHKR.js";
+import "../chunks/chunk-I6FIOP7G.js";
+export {
+  LIVE_MS,
+  STALL_MS,
+  runFlow
+};
+//# sourceMappingURL=runFlow.js.map

package/dist/run/runFlow.js.map

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

package/dist/run/segments.d.ts

@@ -0,0 +1,43 @@
+import type { SegmentFile } from '@ansible-flow/core/engine/types';
+import type { Ulid } from '@ansible-flow/core/flow/types';
+import type { RunApproval, RunView } from '@ansible-flow/core/protocol';
+import { type RunSummary, summarizeRun } from '@ansible-flow/core/run/events';
+import { type RunFlowHooks, type RunFlowRequest } from './runFlow';
+/** How a gate was decided. `timeout` takes the approval's timeout port (else rejected's). */
+export type GateDecision = 'approved' | 'rejected' | 'timeout';
+/** What a segment's run left for the next one. */
+export interface SegmentOutcome {
+    /** The set_stats data the segment carried (`afd_hostsets`, `afd_gate_empty`); empty if none. */
+    carried: Record<string, unknown>;
+    /** Hosts wait at the segment's gate: a decision is needed. */
+    waiting: boolean;
+    /** The gate had no host: the flow goes on with `finish`. */
+    empty: boolean;
+}
+/** The carried data of a segment's run, from its events (the last stats event's `custom`). */
+export declare function segmentOutcome(segment: SegmentFile, events: string): SegmentOutcome;
+/**
+ * The segment after `from`: its approved or rejected continuation for a decision (a timeout runs
+ * the rejected one, which then takes the timeout port), `finish` when nobody reached its gate.
+ * Undefined when there is none: the run has ended.
+ */
+export declare function nextSegment(segments: SegmentFile[], from: string, decision: GateDecision | 'empty'): SegmentFile | undefined;
+/** The inputs of the segment after a decision: the run's, the carried host sets, the decision. */
+export declare function segmentInputs(inputs: Record<string, unknown>, carried: Record<string, unknown>, decision?: GateDecision): Record<string, unknown>;
+/** The run as one: the events of its segments in order, summarized with the flow's routes. */
+export declare function segmentsSummary(events: string[], routes: Parameters<typeof summarizeRun>[1]): RunSummary;
+export interface SegmentsHooks extends RunFlowHooks {
+    /**
+     * The decision for the approval `gate`, when hosts wait there. Called with the run as it is
+     * then (state `running`, the gate's approval `waiting`). Rejects to stop the run.
+     */
+    decide(gate: Ulid, run: RunView): Promise<{
+        decision: GateDecision;
+    } & Partial<RunApproval>>;
+}
+/**
+ * Runs a flow with approval gates segment by segment in one call: each segment is a `runFlow` of
+ * its playbook (folder `<id>-<n>`), each gate waits for `decide`. Reports the run as one (id
+ * `request.id`), with its approvals; resolves with the finished run. Never rejects.
+ */
+export declare function runSegments(request: RunFlowRequest, segments: SegmentFile[], hooks: SegmentsHooks): Promise<RunView>;