@ansible-flow/node 0.85.0 → 0.86.0

package/README.md

@@ -2,7 +2,7 @@
 
 Ansible Flow Designer for Node hosts: layout, the probe client, runs, the AWX client, the module catalog and SSH.
 
-Built from [Ansible Flow Designer](https://github.com/ChistokhinSV/ansible-flow-designer) 0.85.0
+Built from [Ansible Flow Designer](https://github.com/ChistokhinSV/ansible-flow-designer) 0.86.0
 and released with it. Modules are imported by their path in the source tree, for example
 `@ansible-flow/node/ai/agents`.
 

package/dist/flowMerge.d.ts

@@ -0,0 +1,35 @@
+import { type FlowMerge, type MergeSide } from '@ansible-flow/core/flow/merge';
+/** A merge waiting for choices: the three versions, the file, and what was chosen so far. */
+export interface MergeState {
+    /** The file's path in the repository, as git names it. */
+    file: string;
+    base: string;
+    ours: string;
+    theirs: string;
+    choices: Record<string, MergeSide>;
+    at: string;
+}
+export declare const MERGE_FOLDER = "afd-merge";
+/** Where the merge of `file` waits, in the repository's git folder. */
+export declare function mergeStatePath(gitDir: string, file: string): string;
+export declare function readMergeState(gitDir: string, file: string): MergeState | undefined;
+export declare function writeMergeState(gitDir: string, state: MergeState): void;
+export declare function removeMergeState(gitDir: string, file: string): void;
+export type Merged = 
+/** Not three flows this can read: the caller merges the text instead. */
+{
+    kind: 'not-flows';
+    why: string;
+} | {
+    kind: 'merged';
+    text: string;
+    merge: FlowMerge;
+    /** Errors in the merged flow that neither side had: a person looks before it is taken. */
+    broken: string[];
+};
+/** Merges three versions of a flow file's text, with `choices` made so far. */
+export declare function mergeFlowTexts(base: string, ours: string, theirs: string, choices?: Record<string, MergeSide>): Merged;
+export declare const MERGE_ATTRIBUTES: string[];
+export declare const MERGE_DRIVER = "node .afd/afd-merge.js %O %A %B %P";
+/** `.gitattributes` with the flow lines it lacks, or undefined when it has them all. */
+export declare function withMergeAttributes(text: string): string | undefined;

package/dist/flowMerge.js

@@ -0,0 +1,74 @@
+// src/node/flowMerge.ts
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseFlow } from "@ansible-flow/core/flow/document";
+import { mergeFlows } from "@ansible-flow/core/flow/merge";
+import { writeMergedFlow } from "@ansible-flow/core/flow/mergeText";
+import { validateFlow } from "@ansible-flow/core/flow/validate";
+var MERGE_FOLDER = "afd-merge";
+function mergeStatePath(gitDir, file) {
+  return join(gitDir, MERGE_FOLDER, `${encodeURIComponent(file.replaceAll("\\", "/"))}.json`);
+}
+function readMergeState(gitDir, file) {
+  const path = mergeStatePath(gitDir, file);
+  if (!existsSync(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function writeMergeState(gitDir, state) {
+  const path = mergeStatePath(gitDir, state.file);
+  mkdirSync(join(gitDir, MERGE_FOLDER), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 1)}
+`);
+}
+function removeMergeState(gitDir, file) {
+  rmSync(mergeStatePath(gitDir, file), { force: true });
+}
+var errorsOf = (doc) => new Set(
+  validateFlow(doc).findings.filter((f) => f.severity === "error").map((f) => f.message)
+);
+function mergeFlowTexts(base, ours, theirs, choices = {}) {
+  const docs = [base, ours, theirs].map((t2) => parseFlow(t2));
+  const names = ["the common version", "ours", "theirs"];
+  for (const [i, d] of docs.entries())
+    if (!d.doc) return { kind: "not-flows", why: `${names[i]} is not a flow this can read` };
+  const [b, o, t] = docs.map((d) => d.doc);
+  const merge = mergeFlows(b, o, t, choices);
+  let text;
+  try {
+    text = writeMergedFlow(ours, merge.doc);
+  } catch (e) {
+    return {
+      kind: "not-flows",
+      why: `the merged flow could not be written: ${e.message}`
+    };
+  }
+  const had = /* @__PURE__ */ new Set([...errorsOf(o), ...errorsOf(t)]);
+  const broken = [...errorsOf(merge.doc)].filter((m) => !had.has(m));
+  return { kind: "merged", text, merge, broken };
+}
+var MERGE_ATTRIBUTES = ["*.flow.yaml merge=ansible-flow", "*.flow.yml merge=ansible-flow"];
+var MERGE_DRIVER = "node .afd/afd-merge.js %O %A %B %P";
+function withMergeAttributes(text) {
+  const have = new Set(text.split(/\r?\n/).map((l) => l.trim().replace(/\s+/g, " ")));
+  const missing = MERGE_ATTRIBUTES.filter((l) => !have.has(l));
+  if (!missing.length) return void 0;
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const head = text === "" || text.endsWith("\n") ? text : `${text}${eol}`;
+  return `${head}# Flows merge by their steps, not their lines (Ansible Flow Designer)${eol}${missing.join(eol)}${eol}`;
+}
+export {
+  MERGE_ATTRIBUTES,
+  MERGE_DRIVER,
+  MERGE_FOLDER,
+  mergeFlowTexts,
+  mergeStatePath,
+  readMergeState,
+  removeMergeState,
+  withMergeAttributes,
+  writeMergeState
+};
+//# sourceMappingURL=flowMerge.js.map

package/dist/flowMerge.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/node/flowMerge.ts"],
+  "sourcesContent": ["// AFD-283: merging a flow file the way git asks a merge driver to, and the merge left for a person\n// to finish. The driver writes the merged flow over \"ours\"; when the two sides changed the same\n// place, it writes the flow with \"ours\" for each such place, keeps the three versions beside the\n// repository's git folder (never in the work tree), and tells git the file is not merged. The\n// designer reads that state, lets the person choose, and writes the file again.\nimport { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { parseFlow } from '../core/flow/document';\nimport { type FlowMerge, type MergeSide, mergeFlows } from '../core/flow/merge';\nimport { writeMergedFlow } from '../core/flow/mergeText';\nimport type { FlowDocument } from '../core/flow/types';\nimport { validateFlow } from '../core/flow/validate';\n\n/** A merge waiting for choices: the three versions, the file, and what was chosen so far. */\nexport interface MergeState {\n  /** The file's path in the repository, as git names it. */\n  file: string;\n  base: string;\n  ours: string;\n  theirs: string;\n  choices: Record<string, MergeSide>;\n  at: string;\n}\n\nexport const MERGE_FOLDER = 'afd-merge';\n\n/** Where the merge of `file` waits, in the repository's git folder. */\nexport function mergeStatePath(gitDir: string, file: string): string {\n  return join(gitDir, MERGE_FOLDER, `${encodeURIComponent(file.replaceAll('\\\\', '/'))}.json`);\n}\n\nexport function readMergeState(gitDir: string, file: string): MergeState | undefined {\n  const path = mergeStatePath(gitDir, file);\n  if (!existsSync(path)) return undefined;\n  try {\n    return JSON.parse(readFileSync(path, 'utf8')) as MergeState;\n  } catch {\n    return undefined;\n  }\n}\n\nexport function writeMergeState(gitDir: string, state: MergeState): void {\n  const path = mergeStatePath(gitDir, state.file);\n  mkdirSync(join(gitDir, MERGE_FOLDER), { recursive: true });\n  writeFileSync(path, `${JSON.stringify(state, null, 1)}\\n`);\n}\n\nexport function removeMergeState(gitDir: string, file: string): void {\n  rmSync(mergeStatePath(gitDir, file), { force: true });\n}\n\nexport type Merged =\n  /** Not three flows this can read: the caller merges the text instead. */\n  | { kind: 'not-flows'; why: string }\n  | {\n      kind: 'merged';\n      text: string;\n      merge: FlowMerge;\n      /** Errors in the merged flow that neither side had: a person looks before it is taken. */\n      broken: string[];\n    };\n\nconst errorsOf = (doc: FlowDocument) =>\n  new Set(\n    validateFlow(doc)\n      .findings.filter((f) => f.severity === 'error')\n      .map((f) => f.message),\n  );\n\n/** Merges three versions of a flow file's text, with `choices` made so far. */\nexport function mergeFlowTexts(\n  base: string,\n  ours: string,\n  theirs: string,\n  choices: Record<string, MergeSide> = {},\n): Merged {\n  const docs = [base, ours, theirs].map((t) => parseFlow(t));\n  const names = ['the common version', 'ours', 'theirs'];\n  for (const [i, d] of docs.entries())\n    if (!d.doc) return { kind: 'not-flows', why: `${names[i]} is not a flow this can read` };\n  const [b, o, t] = docs.map((d) => d.doc as FlowDocument) as [\n    FlowDocument,\n    FlowDocument,\n    FlowDocument,\n  ];\n  const merge = mergeFlows(b, o, t, choices);\n  let text: string;\n  try {\n    text = writeMergedFlow(ours, merge.doc);\n  } catch (e) {\n    return {\n      kind: 'not-flows',\n      why: `the merged flow could not be written: ${(e as Error).message}`,\n    };\n  }\n  const had = new Set([...errorsOf(o), ...errorsOf(t)]);\n  const broken = [...errorsOf(merge.doc)].filter((m) => !had.has(m));\n  return { kind: 'merged', text, merge, broken };\n}\n\n// --- setting a repository up (Set Up Flow Merging in Repository)\n\nexport const MERGE_ATTRIBUTES = ['*.flow.yaml merge=ansible-flow', '*.flow.yml merge=ansible-flow'];\nexport const MERGE_DRIVER = 'node .afd/afd-merge.js %O %A %B %P';\n\n/** `.gitattributes` with the flow lines it lacks, or undefined when it has them all. */\nexport function withMergeAttributes(text: string): string | undefined {\n  const have = new Set(text.split(/\\r?\\n/).map((l) => l.trim().replace(/\\s+/g, ' ')));\n  const missing = MERGE_ATTRIBUTES.filter((l) => !have.has(l));\n  if (!missing.length) return undefined;\n  const eol = text.includes('\\r\\n') ? '\\r\\n' : '\\n';\n  const head = text === '' || text.endsWith('\\n') ? text : `${text}${eol}`;\n  return `${head}# Flows merge by their steps, not their lines (Ansible Flow Designer)${eol}${missing.join(eol)}${eol}`;\n}\n"],
+  "mappings": ";AAKA,SAAS,YAAY,WAAW,cAAc,QAAQ,qBAAqB;AAC3E,SAAS,YAAY;AACrB,SAAS,iBAAiB;AAC1B,SAAyC,kBAAkB;AAC3D,SAAS,uBAAuB;AAEhC,SAAS,oBAAoB;AAatB,IAAM,eAAe;AAGrB,SAAS,eAAe,QAAgB,MAAsB;AACnE,SAAO,KAAK,QAAQ,cAAc,GAAG,mBAAmB,KAAK,WAAW,MAAM,GAAG,CAAC,CAAC,OAAO;AAC5F;AAEO,SAAS,eAAe,QAAgB,MAAsC;AACnF,QAAM,OAAO,eAAe,QAAQ,IAAI;AACxC,MAAI,CAAC,WAAW,IAAI,EAAG,QAAO;AAC9B,MAAI;AACF,WAAO,KAAK,MAAM,aAAa,MAAM,MAAM,CAAC;AAAA,EAC9C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,gBAAgB,QAAgB,OAAyB;AACvE,QAAM,OAAO,eAAe,QAAQ,MAAM,IAAI;AAC9C,YAAU,KAAK,QAAQ,YAAY,GAAG,EAAE,WAAW,KAAK,CAAC;AACzD,gBAAc,MAAM,GAAG,KAAK,UAAU,OAAO,MAAM,CAAC,CAAC;AAAA,CAAI;AAC3D;AAEO,SAAS,iBAAiB,QAAgB,MAAoB;AACnE,SAAO,eAAe,QAAQ,IAAI,GAAG,EAAE,OAAO,KAAK,CAAC;AACtD;AAaA,IAAM,WAAW,CAAC,QAChB,IAAI;AAAA,EACF,aAAa,GAAG,EACb,SAAS,OAAO,CAAC,MAAM,EAAE,aAAa,OAAO,EAC7C,IAAI,CAAC,MAAM,EAAE,OAAO;AACzB;AAGK,SAAS,eACd,MACA,MACA,QACA,UAAqC,CAAC,GAC9B;AACR,QAAM,OAAO,CAAC,MAAM,MAAM,MAAM,EAAE,IAAI,CAACA,OAAM,UAAUA,EAAC,CAAC;AACzD,QAAM,QAAQ,CAAC,sBAAsB,QAAQ,QAAQ;AACrD,aAAW,CAAC,GAAG,CAAC,KAAK,KAAK,QAAQ;AAChC,QAAI,CAAC,EAAE,IAAK,QAAO,EAAE,MAAM,aAAa,KAAK,GAAG,MAAM,CAAC,CAAC,+BAA+B;AACzF,QAAM,CAAC,GAAG,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,GAAmB;AAKvD,QAAM,QAAQ,WAAW,GAAG,GAAG,GAAG,OAAO;AACzC,MAAI;AACJ,MAAI;AACF,WAAO,gBAAgB,MAAM,MAAM,GAAG;AAAA,EACxC,SAAS,GAAG;AACV,WAAO;AAAA,MACL,MAAM;AAAA,MACN,KAAK,yCAA0C,EAAY,OAAO;AAAA,IACpE;AAAA,EACF;AACA,QAAM,MAAM,oBAAI,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC;AACpD,QAAM,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;AACjE,SAAO,EAAE,MAAM,UAAU,MAAM,OAAO,OAAO;AAC/C;AAIO,IAAM,mBAAmB,CAAC,kCAAkC,+BAA+B;AAC3F,IAAM,eAAe;AAGrB,SAAS,oBAAoB,MAAkC;AACpE,QAAM,OAAO,IAAI,IAAI,KAAK,MAAM,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,QAAQ,GAAG,CAAC,CAAC;AAClF,QAAM,UAAU,iBAAiB,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;AAC3D,MAAI,CAAC,QAAQ,OAAQ,QAAO;AAC5B,QAAM,MAAM,KAAK,SAAS,MAAM,IAAI,SAAS;AAC7C,QAAM,OAAO,SAAS,MAAM,KAAK,SAAS,IAAI,IAAI,OAAO,GAAG,IAAI,GAAG,GAAG;AACtE,SAAO,GAAG,IAAI,wEAAwE,GAAG,GAAG,QAAQ,KAAK,GAAG,CAAC,GAAG,GAAG;AACrH;",
+  "names": ["t"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ansible-flow/node",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "Ansible Flow Designer for Node hosts: layout, the probe client, runs, the AWX client, the module catalog and SSH.",
   "license": "MIT",
   "homepage": "https://github.com/ChistokhinSV/ansible-flow-designer/blob/main/docs/packages.md",
@@ -26,7 +26,7 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "@ansible-flow/core": "0.85.0",
+    "@ansible-flow/core": "0.86.0",
     "elkjs": "0.12.0",
     "jsonc-parser": "3.3.1",
     "yaml": "2.9.1"