yaml-flow 6.0.0 → 7.1.0

package/dist/storage-refs.cjs

@@ -1,4 +1,4 @@
-'use strict';var i=require('fs'),c=require('path'),child_process=require('child_process');function _interopNamespace(e){if(e&&e.__esModule)return e;var n=Object.create(null);if(e){Object.keys(e).forEach(function(k){if(k!=='default'){var d=Object.getOwnPropertyDescriptor(e,k);Object.defineProperty(n,k,d.get?d:{enumerable:true,get:function(){return e[k]}});}})}n.default=e;return Object.freeze(n)}var i__namespace=/*#__PURE__*/_interopNamespace(i);var c__namespace=/*#__PURE__*/_interopNamespace(c);function x(t){if(!t.startsWith("::"))throw new Error(`Invalid ref format (expected ::kind::value): ${t}`);let n=t.slice(2),r=n.indexOf("::");if(r===-1)throw new Error(`Invalid ref format (expected ::kind::value): ${t}`);return {kind:n.slice(0,r),value:n.slice(r+2)}}function h(t){return `::${t.kind}::${t.value}`}function R(){return {read(t){if(!i__namespace.existsSync(t))return null;try{return i__namespace.readFileSync(t,"utf-8")}catch{return null}},write(t,n){i__namespace.mkdirSync(c__namespace.dirname(t),{recursive:true}),i__namespace.writeFileSync(t,n,"utf-8");}}}function k(t){if(t.kind==="fs-path")return R();throw new Error(`Unsupported storage kind: "${t.kind}". Supported kinds: fs-path`)}function d(t){try{return x(t).value}catch{return t}}function g(t){let n=t.extra?.notifyChannel;return typeof n=="string"&&n.length>0?n:void 0}function w(t){if(!t.endsWith(".ts"))return {cmd:process.execPath,args:[t]};let n=c__namespace.dirname(t),r=[];for(let o=1;o<=5;o++){let s=c__namespace.join(n,...Array(o).fill(".."),"node_modules");r.push(c__namespace.join(s,"tsx","dist","cli.mjs")),r.push(c__namespace.join(s,".bin","tsx"));}let e=r.find(o=>i__namespace.existsSync(o));return e?{cmd:process.execPath,args:[e,t]}:{cmd:"npx",args:["tsx",t]}}function v(t,n){let{token:r,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let o=d(e.whatToRun),{cmd:s,args:l}=w(o),u=g(e),f=[...l,"source-data-fetched","--ref",h(n),"--token",r,...u?["--notify-channel",u]:[]],a=child_process.spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportComplete: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let o=d(e.whatToRun),s=JSON.stringify({status:"complete",ref:h(n),token:r});m(o,s);return}throw new Error(`reportComplete: unsupported via.howToRun "${e.howToRun}"`)}function T(t,n){let{token:r,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let o=d(e.whatToRun),{cmd:s,args:l}=w(o),u=g(e),f=[...l,"source-data-fetch-failure","--token",r,"--reason",n,...u?["--notify-channel",u]:[]],a=child_process.spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportFailed: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let o=d(e.whatToRun),s=JSON.stringify({status:"failed",reason:n,token:r});m(o,s);return}throw new Error(`reportFailed: unsupported via.howToRun "${e.howToRun}"`)}function m(t,n){let r=`
+'use strict';var i=require('fs'),c=require('path'),child_process=require('child_process');function _interopNamespace(e){if(e&&e.__esModule)return e;var n=Object.create(null);if(e){Object.keys(e).forEach(function(k){if(k!=='default'){var d=Object.getOwnPropertyDescriptor(e,k);Object.defineProperty(n,k,d.get?d:{enumerable:true,get:function(){return e[k]}});}})}n.default=e;return Object.freeze(n)}var i__namespace=/*#__PURE__*/_interopNamespace(i);var c__namespace=/*#__PURE__*/_interopNamespace(c);function y(t){if(!t.startsWith("b64:"))throw new Error(`Invalid ref format (expected b64:<base64url(json)>): ${t}`);let n=t.slice(4),o=n.replace(/-/g,"+").replace(/_/g,"/")+"=".repeat((4-n.length%4)%4),e;try{e=JSON.parse(Buffer.from(o,"base64").toString("utf8"));}catch{throw new Error(`Invalid ref format (malformed base64url/json): ${t}`)}if(!e||typeof e!="object")throw new Error(`Invalid ref format (expected object payload): ${t}`);let r=e;if(typeof r.kind!="string"||typeof r.value!="string")throw new Error(`Invalid ref format (payload must contain string kind/value): ${t}`);return {kind:r.kind,value:r.value}}function h(t){return `b64:${Buffer.from(JSON.stringify(t),"utf8").toString("base64").replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}`}function R(){return {read(t){if(!i__namespace.existsSync(t))return null;try{return i__namespace.readFileSync(t,"utf-8")}catch{return null}},write(t,n){i__namespace.mkdirSync(c__namespace.dirname(t),{recursive:true}),i__namespace.writeFileSync(t,n,"utf-8");}}}function k(t){if(t.kind==="fs-path")return R();throw new Error(`Unsupported storage kind: "${t.kind}". Supported kinds: fs-path`)}function d(t){return y(t).value}function g(t){let n=t.extra?.notifyChannel;return typeof n=="string"&&n.length>0?n:void 0}function w(t){if(!t.endsWith(".ts"))return {cmd:process.execPath,args:[t]};let n=c__namespace.dirname(t),o=[];for(let r=1;r<=5;r++){let s=c__namespace.join(n,...Array(r).fill(".."),"node_modules");o.push(c__namespace.join(s,"tsx","dist","cli.mjs")),o.push(c__namespace.join(s,".bin","tsx"));}let e=o.find(r=>i__namespace.existsSync(r));return e?{cmd:process.execPath,args:[e,t]}:{cmd:"npx",args:["tsx",t]}}function b(t,n){let{token:o,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let r=d(e.whatToRun),{cmd:s,args:l}=w(r),u=g(e),f=[...l,"source-data-fetched","--ref",h(n),"--token",o,...u?["--notify-channel",u]:[]],a=child_process.spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportComplete: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let r=d(e.whatToRun),s=JSON.stringify({status:"complete",ref:h(n),token:o});m(r,s);return}throw new Error(`reportComplete: unsupported via.howToRun "${e.howToRun}"`)}function v(t,n){let{token:o,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let r=d(e.whatToRun),{cmd:s,args:l}=w(r),u=g(e),f=[...l,"source-data-fetch-failure","--token",o,"--reason",n,...u?["--notify-channel",u]:[]],a=child_process.spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportFailed: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let r=d(e.whatToRun),s=JSON.stringify({status:"failed",reason:n,token:o});m(r,s);return}throw new Error(`reportFailed: unsupported via.howToRun "${e.howToRun}"`)}function m(t,n){let o=`
     const {request} = require(new URL('${t}').protocol === 'https:' ? 'https' : 'http');
     const h = ${JSON.stringify({"Content-Type":"application/json","Content-Length":Buffer.byteLength(n)})};
     const u = new URL('${t}');
@@ -6,5 +6,5 @@
     req.on('error', e => { process.stderr.write(e.message); process.exit(1); });
     req.write(${JSON.stringify(n)});
     req.end();
-  `,e=child_process.spawnSync(process.execPath,["-e",r],{encoding:"utf-8",windowsHide:true});if(e.status!==0)throw new Error(`http-post failed: ${e.stderr?.trim()}`)}exports.blobStorageForRef=k;exports.parseRef=x;exports.reportComplete=v;exports.reportFailed=T;exports.serializeRef=h;//# sourceMappingURL=storage-refs.cjs.map
+  `,e=child_process.spawnSync(process.execPath,["-e",o],{encoding:"utf-8",windowsHide:true});if(e.status!==0)throw new Error(`http-post failed: ${e.stderr?.trim()}`)}exports.blobStorageForRef=k;exports.parseRef=y;exports.reportComplete=b;exports.reportFailed=v;exports.serializeRef=h;//# sourceMappingURL=storage-refs.cjs.map
 //# sourceMappingURL=storage-refs.cjs.map

package/dist/storage-refs.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli/node/public-storage-adapter.ts"],"names":["parseRef","s","inner","idx","serializeRef","ref","createFsPathBlobStorage","key","i","content","c","blobStorageForRef","_parseWhatToRun","whatToRun","_notifyChannelFromVia","via","candidate","_resolveLocalNodeInvocation","scriptPath","dir","candidates","up","base","tsx","p","reportComplete","callback","outRef","token","cmd","args","notifyChannel","callbackArgs","result","spawnSync","url","body","_httpPostSync","reportFailed","reason","script"],"mappings":"mfA8CO,SAASA,CAAAA,CAASC,CAAAA,CAAyB,CAChD,GAAI,CAACA,CAAAA,CAAE,UAAA,CAAW,IAAI,CAAA,CAAG,MAAM,IAAI,KAAA,CAAM,CAAA,6CAAA,EAAgDA,CAAC,CAAA,CAAE,CAAA,CAC5F,IAAMC,CAAAA,CAAQD,CAAAA,CAAE,MAAM,CAAC,CAAA,CACjBE,CAAAA,CAAMD,CAAAA,CAAM,OAAA,CAAQ,IAAI,CAAA,CAC9B,GAAIC,CAAAA,GAAQ,EAAA,CAAI,MAAM,IAAI,KAAA,CAAM,CAAA,6CAAA,EAAgDF,CAAC,CAAA,CAAE,EACnF,OAAO,CAAE,IAAA,CAAMC,CAAAA,CAAM,KAAA,CAAM,CAAA,CAAGC,CAAG,CAAA,CAAG,KAAA,CAAOD,CAAAA,CAAM,KAAA,CAAMC,CAAAA,CAAM,CAAC,CAAE,CAClE,CAGO,SAASC,CAAAA,CAAaC,CAAAA,CAA2B,CACtD,OAAO,CAAA,EAAA,EAAKA,CAAAA,CAAI,IAAI,CAAA,EAAA,EAAKA,CAAAA,CAAI,KAAK,CAAA,CACpC,CAiBA,SAASC,CAAAA,EAAuC,CAC9C,OAAO,CACL,IAAA,CAAKC,CAAAA,CAA4B,CAC/B,GAAI,CAAIC,YAAA,CAAA,UAAA,CAAWD,CAAG,CAAA,CAAG,OAAO,IAAA,CAChC,GAAI,CAAE,OAAUC,YAAA,CAAA,YAAA,CAAaD,CAAAA,CAAK,OAAO,CAAG,CAAA,KAAQ,CAAE,OAAO,IAAM,CACrE,CAAA,CACA,KAAA,CAAMA,CAAAA,CAAaE,CAAAA,CAAuB,CACrCD,YAAA,CAAA,SAAA,CAAeE,YAAA,CAAA,OAAA,CAAQH,CAAG,CAAA,CAAG,CAAE,SAAA,CAAW,IAAK,CAAC,CAAA,CAChDC,YAAA,CAAA,aAAA,CAAcD,CAAAA,CAAKE,CAAAA,CAAS,OAAO,EACxC,CACF,CACF,CAUO,SAASE,CAAAA,CAAkBN,CAAAA,CAAgC,CAChE,GAAQA,CAAAA,CAAI,OACL,SAAA,CAAW,OAAOC,CAAAA,EAAwB,CACtC,MAAM,IAAI,KAAA,CAAM,CAAA,2BAAA,EAA8BD,CAAAA,CAAI,IAAI,CAAA,2BAAA,CAA6B,CAEhG,CA0CA,SAASO,CAAAA,CAAgBC,CAAAA,CAA2B,CAClD,GAAI,CAAE,OAAOb,CAAAA,CAASa,CAAS,CAAA,CAAE,KAAO,CAAA,KAAQ,CAAE,OAAOA,CAAW,CACtE,CAEA,SAASC,CAAAA,CAAsBC,CAAAA,CAAuC,CACpE,IAAMC,CAAAA,CAAYD,CAAAA,CAAI,KAAA,EAAQ,aAAA,CAC9B,OAAO,OAAOC,CAAAA,EAAc,QAAA,EAAYA,CAAAA,CAAU,MAAA,CAAS,CAAA,CAAIA,CAAAA,CAAY,MAC7E,CAOA,SAASC,EAA4BC,CAAAA,CAAqD,CACxF,GAAI,CAACA,CAAAA,CAAW,QAAA,CAAS,KAAK,CAAA,CAC5B,OAAO,CAAE,GAAA,CAAK,OAAA,CAAQ,QAAA,CAAU,IAAA,CAAM,CAACA,CAAU,CAAE,CAAA,CAIrD,IAAMC,CAAAA,CAAWT,YAAA,CAAA,OAAA,CAAQQ,CAAU,CAAA,CAC7BE,CAAAA,CAAuB,EAAC,CAC9B,IAAA,IAASC,CAAAA,CAAK,CAAA,CAAGA,CAAAA,EAAM,CAAA,CAAGA,CAAAA,EAAAA,CAAM,CAC9B,IAAMC,CAAAA,CAAYZ,YAAA,CAAA,IAAA,CAAKS,CAAAA,CAAK,GAAG,KAAA,CAAME,CAAE,CAAA,CAAE,IAAA,CAAK,IAAI,CAAA,CAAG,cAAc,CAAA,CACnED,CAAAA,CAAW,IAAA,CAAUV,YAAA,CAAA,IAAA,CAAKY,CAAAA,CAAM,MAAO,MAAA,CAAQ,SAAS,CAAC,CAAA,CACzDF,CAAAA,CAAW,IAAA,CAAUV,YAAA,CAAA,IAAA,CAAKY,CAAAA,CAAM,MAAA,CAAQ,KAAK,CAAC,EAChD,CACA,IAAMC,CAAAA,CAAMH,CAAAA,CAAW,KAAKI,CAAAA,EAAQhB,YAAA,CAAA,UAAA,CAAWgB,CAAC,CAAC,CAAA,CACjD,OAAID,CAAAA,CAAY,CAAE,GAAA,CAAK,OAAA,CAAQ,QAAA,CAAU,IAAA,CAAM,CAACA,CAAAA,CAAKL,CAAU,CAAE,EAC1D,CAAE,GAAA,CAAK,KAAA,CAAO,IAAA,CAAM,CAAC,KAAA,CAAOA,CAAU,CAAE,CACjD,CAMO,SAASO,CAAAA,CAAeC,CAAAA,CAAwBC,CAAAA,CAA4B,CACjF,GAAM,CAAE,KAAA,CAAAC,CAAAA,CAAO,GAAA,CAAAb,CAAI,CAAA,CAAIW,CAAAA,CACvB,GAAIX,CAAAA,CAAI,QAAA,GAAa,YAAA,EAAgBA,CAAAA,CAAI,QAAA,GAAa,eAAA,CAAiB,CACrE,IAAMG,CAAAA,CAAaN,EAAgBG,CAAAA,CAAI,SAAS,CAAA,CAC1C,CAAE,GAAA,CAAAc,CAAAA,CAAK,IAAA,CAAAC,CAAK,CAAA,CAAIb,CAAAA,CAA4BC,CAAU,CAAA,CACtDa,CAAAA,CAAgBjB,CAAAA,CAAsBC,CAAG,CAAA,CACzCiB,EAAe,CACnB,GAAGF,CAAAA,CACH,qBAAA,CACA,OAAA,CAAS1B,CAAAA,CAAauB,CAAM,CAAA,CAC5B,SAAA,CAAWC,CAAAA,CACX,GAAIG,CAAAA,CAAgB,CAAC,kBAAA,CAAoBA,CAAa,CAAA,CAAI,EAC5D,CAAA,CACME,CAAAA,CAASC,uBAAAA,CAAUL,CAAAA,CAAKG,CAAAA,CAAc,CAAE,QAAA,CAAU,OAAA,CAAS,WAAA,CAAa,IAAK,CAAC,CAAA,CACpF,GAAIC,CAAAA,CAAO,MAAA,GAAW,EACpB,MAAM,IAAI,KAAA,CAAM,CAAA,iCAAA,EAAoCA,CAAAA,CAAO,MAAM,CAAA,EAAA,EAAKA,CAAAA,CAAO,MAAA,EAAQ,IAAA,EAAM,CAAA,CAAE,CAAA,CAE/F,MACF,CACA,GAAIlB,EAAI,QAAA,GAAa,WAAA,CAAa,CAChC,IAAMoB,CAAAA,CAAMvB,CAAAA,CAAgBG,CAAAA,CAAI,SAAS,CAAA,CACnCqB,CAAAA,CAAO,IAAA,CAAK,SAAA,CAAU,CAAE,MAAA,CAAQ,UAAA,CAAY,GAAA,CAAKhC,EAAauB,CAAM,CAAA,CAAG,KAAA,CAAAC,CAAM,CAAC,CAAA,CACpFS,CAAAA,CAAcF,CAAAA,CAAKC,CAAI,CAAA,CACvB,MACF,CACA,MAAM,IAAI,KAAA,CAAM,CAAA,0CAAA,EAA6CrB,EAAI,QAAQ,CAAA,CAAA,CAAG,CAC9E,CAMO,SAASuB,CAAAA,CAAaZ,CAAAA,CAAwBa,CAAAA,CAAsB,CACzE,GAAM,CAAE,KAAA,CAAAX,CAAAA,CAAO,GAAA,CAAAb,CAAI,CAAA,CAAIW,EACvB,GAAIX,CAAAA,CAAI,QAAA,GAAa,YAAA,EAAgBA,CAAAA,CAAI,QAAA,GAAa,eAAA,CAAiB,CACrE,IAAMG,CAAAA,CAAaN,CAAAA,CAAgBG,CAAAA,CAAI,SAAS,CAAA,CAC1C,CAAE,GAAA,CAAAc,EAAK,IAAA,CAAAC,CAAK,CAAA,CAAIb,CAAAA,CAA4BC,CAAU,CAAA,CACtDa,CAAAA,CAAgBjB,CAAAA,CAAsBC,CAAG,CAAA,CACzCiB,CAAAA,CAAe,CACnB,GAAGF,CAAAA,CACH,2BAAA,CACA,SAAA,CAAWF,EACX,UAAA,CAAYW,CAAAA,CACZ,GAAIR,CAAAA,CAAgB,CAAC,kBAAA,CAAoBA,CAAa,CAAA,CAAI,EAC5D,CAAA,CACME,CAAAA,CAASC,uBAAAA,CAAUL,CAAAA,CAAKG,CAAAA,CAAc,CAAE,SAAU,OAAA,CAAS,WAAA,CAAa,IAAK,CAAC,CAAA,CACpF,GAAIC,CAAAA,CAAO,MAAA,GAAW,CAAA,CACpB,MAAM,IAAI,KAAA,CAAM,CAAA,+BAAA,EAAkCA,CAAAA,CAAO,MAAM,CAAA,EAAA,EAAKA,EAAO,MAAA,EAAQ,IAAA,EAAM,CAAA,CAAE,CAAA,CAE7F,MACF,CACA,GAAIlB,CAAAA,CAAI,QAAA,GAAa,WAAA,CAAa,CAChC,IAAMoB,CAAAA,CAAMvB,CAAAA,CAAgBG,CAAAA,CAAI,SAAS,CAAA,CACnCqB,CAAAA,CAAO,IAAA,CAAK,SAAA,CAAU,CAAE,MAAA,CAAQ,QAAA,CAAU,MAAA,CAAAG,CAAAA,CAAQ,KAAA,CAAAX,CAAM,CAAC,CAAA,CAC/DS,CAAAA,CAAcF,CAAAA,CAAKC,CAAI,EACvB,MACF,CACA,MAAM,IAAI,KAAA,CAAM,CAAA,wCAAA,EAA2CrB,CAAAA,CAAI,QAAQ,CAAA,CAAA,CAAG,CAC5E,CAGA,SAASsB,CAAAA,CAAcF,CAAAA,CAAaC,CAAAA,CAAoB,CACtD,IAAMI,CAAAA,CAAS;AAAA,uCAAA,EACwBL,CAAG,CAAA;AAAA,cAAA,EAC5B,IAAA,CAAK,SAAA,CAAU,CAAE,cAAA,CAAgB,kBAAA,CAAoB,gBAAA,CAAkB,MAAA,CAAO,UAAA,CAAWC,CAAI,CAAE,CAAC,CAAC,CAAA;AAAA,uBAAA,EACxFD,CAAG,CAAA;AAAA;AAAA;AAAA,cAAA,EAGZ,IAAA,CAAK,SAAA,CAAUC,CAAI,CAAC,CAAA;AAAA;AAAA,EAAA,CAAA,CAG5BH,CAAAA,CAASC,uBAAAA,CAAU,OAAA,CAAQ,QAAA,CAAU,CAAC,IAAA,CAAMM,CAAM,CAAA,CAAG,CAAE,QAAA,CAAU,OAAA,CAAS,WAAA,CAAa,IAAK,CAAC,CAAA,CACnG,GAAIP,CAAAA,CAAO,MAAA,GAAW,CAAA,CAAG,MAAM,IAAI,KAAA,CAAM,CAAA,kBAAA,EAAqBA,CAAAA,CAAO,MAAA,EAAQ,IAAA,EAAM,CAAA,CAAE,CACvF","file":"storage-refs.cjs","sourcesContent":["/**\n * public-storage-adapter.ts\n *\n * Standalone file — copy this to your task-executor project.\n * Zero dependencies on the rest of yaml-flow.\n *\n * Provides:\n *   - KindValueRef      wire format: ::kind::value\n *   - parseRef()        parse a ::kind::value string\n *   - serializeRef()    produce a ::kind::value string\n *   - BlobStorage       read/write interface\n *   - blobStorageForRef resolve a ref to its BlobStorage backend\n *   - ExecutionRef      portable invocation descriptor (inlined, stays standalone)\n *   - TaskCallback      how to report task completion back to the board\n *   - reportComplete()  call from executor on success\n *   - reportFailed()    call from executor on failure\n *\n * Supported storage kinds:\n *   fs-path   — ref.value is an absolute file path; reads/writes via node:fs\n *\n * Supported callback transports (via ExecutionRef.howToRun):\n *   local-node     — invoke board CLI as a child Node process\n *   http:post      — HTTP POST to a board endpoint\n *\n * Usage:\n *   import { parseRef, blobStorageForRef, reportComplete, reportFailed } from './public-storage-adapter.js';\n *\n *   const { source_def, callback } = JSON.parse(blobStorageForRef(inRef).read(inRef.value));\n *   // ... do work, write to outRef ...\n *   reportComplete(callback, outRef);\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { spawnSync } from 'node:child_process';\n\n// ============================================================================\n// KindValueRef\n// ============================================================================\n\nexport interface KindValueRef {\n  readonly kind: string;\n  readonly value: string;\n}\n\n/** Parse a wire-format ref string (::kind::value) into a KindValueRef. */\nexport function parseRef(s: string): KindValueRef {\n  if (!s.startsWith('::')) throw new Error(`Invalid ref format (expected ::kind::value): ${s}`);\n  const inner = s.slice(2);\n  const idx = inner.indexOf('::');\n  if (idx === -1) throw new Error(`Invalid ref format (expected ::kind::value): ${s}`);\n  return { kind: inner.slice(0, idx), value: inner.slice(idx + 2) };\n}\n\n/** Serialize a KindValueRef to the wire format: ::kind::value */\nexport function serializeRef(ref: KindValueRef): string {\n  return `::${ref.kind}::${ref.value}`;\n}\n\n// ============================================================================\n// BlobStorage\n// ============================================================================\n\nexport interface BlobStorage {\n  /** Returns content string, or null if not found. */\n  read(key: string): string | null;\n  /** Write content at key. */\n  write(key: string, content: string): void;\n}\n\n// ============================================================================\n// fs-path backend — key IS the absolute file path\n// ============================================================================\n\nfunction createFsPathBlobStorage(): BlobStorage {\n  return {\n    read(key: string): string | null {\n      if (!fs.existsSync(key)) return null;\n      try { return fs.readFileSync(key, 'utf-8'); } catch { return null; }\n    },\n    write(key: string, content: string): void {\n      fs.mkdirSync(path.dirname(key), { recursive: true });\n      fs.writeFileSync(key, content, 'utf-8');\n    },\n  };\n}\n\n// ============================================================================\n// blobStorageForRef\n// ============================================================================\n\n/**\n * Resolve a KindValueRef to its BlobStorage backend.\n * Throws a clear error for unrecognised kinds.\n */\nexport function blobStorageForRef(ref: KindValueRef): BlobStorage {\n  switch (ref.kind) {\n    case 'fs-path': return createFsPathBlobStorage();\n    default: throw new Error(`Unsupported storage kind: \"${ref.kind}\". Supported kinds: fs-path`);\n  }\n}\n\n// ============================================================================\n// TaskCallback — how a task-executor reports results back to the board\n// ============================================================================\n\n/**\n * Portable invocation descriptor for the board CLI back-channel.\n * Inlined here so this file stays standalone (zero deps on yaml-flow internals).\n * Shape matches ExecutionRef in execution-interface.ts — keep in sync.\n *\n * Supported howToRun values for TaskCallback.via:\n *   local-node   — invoke board CLI as: node [tsx?] <whatToRun.value> <cmd> [...argv]\n *   http:post    — POST to <whatToRun.value> with a JSON body\n */\nexport interface ExecutionRef {\n  /** Optional human-readable label. Not used for dispatch. */\n  meta?: string;\n  /** Transport / runtime kind. */\n  howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';\n  /** Address of the target in ::kind::value wire form (e.g. ::fs-path::/path/to/cli.js). */\n  whatToRun: string;\n  /** Opaque executor config stored with the ref. */\n  extra?: Record<string, unknown>;\n}\n\n/**\n * Describes how the board wants to receive task completion callbacks.\n * Baked into the inRef payload as { source_def, callback }.\n * The executor treats `token` as opaque and passes it back unchanged.\n */\nexport interface TaskCallback {\n  /** Opaque routing token — generated by the board, passed back unchanged. */\n  token: string;\n  /** Delivery mechanism — an ExecutionRef pointing at the board CLI or endpoint. */\n  via: ExecutionRef;\n}\n\n/**\n * Extract the path/url value from a whatToRun ::kind::value wire string.\n * Falls back to the raw string if it isn’t in ::kind::value form.\n */\nfunction _parseWhatToRun(whatToRun: string): string {\n  try { return parseRef(whatToRun).value; } catch { return whatToRun; }\n}\n\nfunction _notifyChannelFromVia(via: ExecutionRef): string | undefined {\n  const candidate = via.extra?.['notifyChannel'];\n  return typeof candidate === 'string' && candidate.length > 0 ? candidate : undefined;\n}\n\n/**\n * Resolve the Node invocation for a local board CLI script.\n * If the path ends in .ts (dev mode), attempts to locate tsx alongside it;\n * otherwise assumes it’s a compiled .js and invokes directly with node.\n */\nfunction _resolveLocalNodeInvocation(scriptPath: string): { cmd: string; args: string[] } {\n  if (!scriptPath.endsWith('.ts')) {\n    return { cmd: process.execPath, args: [scriptPath] };\n  }\n  // Dev path: look for tsx in node_modules relative to the script's package root.\n  // The .ts file may be at src/cli/node/<file>.ts — walk up until we find node_modules/tsx.\n  const dir = path.dirname(scriptPath);\n  const candidates: string[] = [];\n  for (let up = 1; up <= 5; up++) {\n    const base = path.join(dir, ...Array(up).fill('..'), 'node_modules');\n    candidates.push(path.join(base, 'tsx', 'dist', 'cli.mjs'));\n    candidates.push(path.join(base, '.bin', 'tsx'));\n  }\n  const tsx = candidates.find(p => fs.existsSync(p));\n  if (tsx) return { cmd: process.execPath, args: [tsx, scriptPath] };\n  return { cmd: 'npx', args: ['tsx', scriptPath] };\n}\n\n/**\n * Report successful task completion back to the board.\n * Call this from a task-executor after writing the result to outRef.\n */\nexport function reportComplete(callback: TaskCallback, outRef: KindValueRef): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetched',\n      '--ref', serializeRef(outRef),\n      '--token', token,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportComplete: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'complete', ref: serializeRef(outRef), token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportComplete: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/**\n * Report task failure back to the board.\n * Call this from a task-executor instead of writing to outRef.\n */\nexport function reportFailed(callback: TaskCallback, reason: string): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetch-failure',\n      '--token', token,\n      '--reason', reason,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportFailed: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'failed', reason, token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportFailed: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/** Synchronous HTTP POST using a child node process (keeps this file free of async). */\nfunction _httpPostSync(url: string, body: string): void {\n  const script = `\n    const {request} = require(new URL('${url}').protocol === 'https:' ? 'https' : 'http');\n    const h = ${JSON.stringify({ 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) })};\n    const u = new URL('${url}');\n    const req = request({hostname:u.hostname,port:u.port,path:u.pathname+u.search,method:'POST',headers:h});\n    req.on('error', e => { process.stderr.write(e.message); process.exit(1); });\n    req.write(${JSON.stringify(body)});\n    req.end();\n  `;\n  const result = spawnSync(process.execPath, ['-e', script], { encoding: 'utf-8', windowsHide: true });\n  if (result.status !== 0) throw new Error(`http-post failed: ${result.stderr?.trim()}`);\n}\n"]}
+{"version":3,"sources":["../src/cli/node/public-storage-adapter.ts"],"names":["parseRef","s","payload","padded","decoded","candidate","serializeRef","ref","createFsPathBlobStorage","key","i","content","c","blobStorageForRef","_parseWhatToRun","whatToRun","_notifyChannelFromVia","via","_resolveLocalNodeInvocation","scriptPath","dir","candidates","up","base","tsx","p","reportComplete","callback","outRef","token","cmd","args","notifyChannel","callbackArgs","result","spawnSync","url","body","_httpPostSync","reportFailed","reason","script"],"mappings":"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","file":"storage-refs.cjs","sourcesContent":["/**\n * public-storage-adapter.ts\n *\n * Standalone file — copy this to your task-executor project.\n * Zero dependencies on the rest of yaml-flow.\n *\n * Provides:\n *   - KindValueRef      wire format: b64:<base64url(json)>\n *   - parseRef()        parse a b64:<base64url(json)> string\n *   - serializeRef()    produce a b64:<base64url(json)> string\n *   - BlobStorage       read/write interface\n *   - blobStorageForRef resolve a ref to its BlobStorage backend\n *   - ExecutionRef      portable invocation descriptor (inlined, stays standalone)\n *   - TaskCallback      how to report task completion back to the board\n *   - reportComplete()  call from executor on success\n *   - reportFailed()    call from executor on failure\n *\n * Supported storage kinds:\n *   fs-path   — ref.value is an absolute file path; reads/writes via node:fs\n *\n * Supported callback transports (via ExecutionRef.howToRun):\n *   local-node     — invoke board CLI as a child Node process\n *   http:post      — HTTP POST to a board endpoint\n *\n * Usage:\n *   import { parseRef, blobStorageForRef, reportComplete, reportFailed } from './public-storage-adapter.js';\n *\n *   const { source_def, callback } = JSON.parse(blobStorageForRef(inRef).read(inRef.value));\n *   // ... do work, write to outRef ...\n *   reportComplete(callback, outRef);\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { spawnSync } from 'node:child_process';\n\n// ============================================================================\n// KindValueRef\n// ============================================================================\n\nexport interface KindValueRef {\n  readonly kind: string;\n  readonly value: string;\n}\n\n/** Parse a wire-format ref string (b64:<base64url(json)>) into a KindValueRef. */\nexport function parseRef(s: string): KindValueRef {\n  if (!s.startsWith('b64:')) throw new Error(`Invalid ref format (expected b64:<base64url(json)>): ${s}`);\n  const payload = s.slice(4);\n  const padded = payload.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (payload.length % 4)) % 4);\n  let decoded: unknown;\n  try {\n    decoded = JSON.parse(Buffer.from(padded, 'base64').toString('utf8'));\n  } catch {\n    throw new Error(`Invalid ref format (malformed base64url/json): ${s}`);\n  }\n  if (!decoded || typeof decoded !== 'object') {\n    throw new Error(`Invalid ref format (expected object payload): ${s}`);\n  }\n  const candidate = decoded as { kind?: unknown; value?: unknown };\n  if (typeof candidate.kind !== 'string' || typeof candidate.value !== 'string') {\n    throw new Error(`Invalid ref format (payload must contain string kind/value): ${s}`);\n  }\n  return { kind: candidate.kind, value: candidate.value };\n}\n\n/** Serialize a KindValueRef to the wire format: b64:<base64url(json)> */\nexport function serializeRef(ref: KindValueRef): string {\n  return `b64:${Buffer.from(JSON.stringify(ref), 'utf8').toString('base64').replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/g, '')}`;\n}\n\n// ============================================================================\n// BlobStorage\n// ============================================================================\n\nexport interface BlobStorage {\n  /** Returns content string, or null if not found. */\n  read(key: string): string | null;\n  /** Write content at key. */\n  write(key: string, content: string): void;\n}\n\n// ============================================================================\n// fs-path backend — key IS the absolute file path\n// ============================================================================\n\nfunction createFsPathBlobStorage(): BlobStorage {\n  return {\n    read(key: string): string | null {\n      if (!fs.existsSync(key)) return null;\n      try { return fs.readFileSync(key, 'utf-8'); } catch { return null; }\n    },\n    write(key: string, content: string): void {\n      fs.mkdirSync(path.dirname(key), { recursive: true });\n      fs.writeFileSync(key, content, 'utf-8');\n    },\n  };\n}\n\n// ============================================================================\n// blobStorageForRef\n// ============================================================================\n\n/**\n * Resolve a KindValueRef to its BlobStorage backend.\n * Throws a clear error for unrecognised kinds.\n */\nexport function blobStorageForRef(ref: KindValueRef): BlobStorage {\n  switch (ref.kind) {\n    case 'fs-path': return createFsPathBlobStorage();\n    default: throw new Error(`Unsupported storage kind: \"${ref.kind}\". Supported kinds: fs-path`);\n  }\n}\n\n// ============================================================================\n// TaskCallback — how a task-executor reports results back to the board\n// ============================================================================\n\n/**\n * Portable invocation descriptor for the board CLI back-channel.\n * Inlined here so this file stays standalone (zero deps on yaml-flow internals).\n * Shape matches ExecutionRef in execution-interface.ts — keep in sync.\n *\n * Supported howToRun values for TaskCallback.via:\n *   local-node   — invoke board CLI as: node [tsx?] <whatToRun.value> <cmd> [...argv]\n *   http:post    — POST to <whatToRun.value> with a JSON body\n */\nexport interface ExecutionRef {\n  /** Optional human-readable label. Not used for dispatch. */\n  meta?: string;\n  /** Transport / runtime kind. */\n  howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';\n  /** Address of the target in b64:<base64url(json)> wire form. */\n  whatToRun: string;\n  /** Opaque executor config stored with the ref. */\n  extra?: Record<string, unknown>;\n}\n\n/**\n * Describes how the board wants to receive task completion callbacks.\n * Baked into the inRef payload as { source_def, callback }.\n * The executor treats `token` as opaque and passes it back unchanged.\n */\nexport interface TaskCallback {\n  /** Opaque routing token — generated by the board, passed back unchanged. */\n  token: string;\n  /** Delivery mechanism — an ExecutionRef pointing at the board CLI or endpoint. */\n  via: ExecutionRef;\n}\n\n/**\n * Extract the path/url value from a whatToRun b64:<base64url(json)> wire string.\n */\nfunction _parseWhatToRun(whatToRun: string): string {\n  return parseRef(whatToRun).value;\n}\n\nfunction _notifyChannelFromVia(via: ExecutionRef): string | undefined {\n  const candidate = via.extra?.['notifyChannel'];\n  return typeof candidate === 'string' && candidate.length > 0 ? candidate : undefined;\n}\n\n/**\n * Resolve the Node invocation for a local board CLI script.\n * If the path ends in .ts (dev mode), attempts to locate tsx alongside it;\n * otherwise assumes it’s a compiled .js and invokes directly with node.\n */\nfunction _resolveLocalNodeInvocation(scriptPath: string): { cmd: string; args: string[] } {\n  if (!scriptPath.endsWith('.ts')) {\n    return { cmd: process.execPath, args: [scriptPath] };\n  }\n  // Dev path: look for tsx in node_modules relative to the script's package root.\n  // The .ts file may be at src/cli/node/<file>.ts — walk up until we find node_modules/tsx.\n  const dir = path.dirname(scriptPath);\n  const candidates: string[] = [];\n  for (let up = 1; up <= 5; up++) {\n    const base = path.join(dir, ...Array(up).fill('..'), 'node_modules');\n    candidates.push(path.join(base, 'tsx', 'dist', 'cli.mjs'));\n    candidates.push(path.join(base, '.bin', 'tsx'));\n  }\n  const tsx = candidates.find(p => fs.existsSync(p));\n  if (tsx) return { cmd: process.execPath, args: [tsx, scriptPath] };\n  return { cmd: 'npx', args: ['tsx', scriptPath] };\n}\n\n/**\n * Report successful task completion back to the board.\n * Call this from a task-executor after writing the result to outRef.\n */\nexport function reportComplete(callback: TaskCallback, outRef: KindValueRef): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetched',\n      '--ref', serializeRef(outRef),\n      '--token', token,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportComplete: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'complete', ref: serializeRef(outRef), token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportComplete: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/**\n * Report task failure back to the board.\n * Call this from a task-executor instead of writing to outRef.\n */\nexport function reportFailed(callback: TaskCallback, reason: string): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetch-failure',\n      '--token', token,\n      '--reason', reason,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportFailed: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'failed', reason, token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportFailed: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/** Synchronous HTTP POST using a child node process (keeps this file free of async). */\nfunction _httpPostSync(url: string, body: string): void {\n  const script = `\n    const {request} = require(new URL('${url}').protocol === 'https:' ? 'https' : 'http');\n    const h = ${JSON.stringify({ 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) })};\n    const u = new URL('${url}');\n    const req = request({hostname:u.hostname,port:u.port,path:u.pathname+u.search,method:'POST',headers:h});\n    req.on('error', e => { process.stderr.write(e.message); process.exit(1); });\n    req.write(${JSON.stringify(body)});\n    req.end();\n  `;\n  const result = spawnSync(process.execPath, ['-e', script], { encoding: 'utf-8', windowsHide: true });\n  if (result.status !== 0) throw new Error(`http-post failed: ${result.stderr?.trim()}`);\n}\n"]}

package/dist/storage-refs.d.cts

@@ -5,9 +5,9 @@
  * Zero dependencies on the rest of yaml-flow.
  *
  * Provides:
- *   - KindValueRef      wire format: ::kind::value
- *   - parseRef()        parse a ::kind::value string
- *   - serializeRef()    produce a ::kind::value string
+ *   - KindValueRef      wire format: b64:<base64url(json)>
+ *   - parseRef()        parse a b64:<base64url(json)> string
+ *   - serializeRef()    produce a b64:<base64url(json)> string
  *   - BlobStorage       read/write interface
  *   - blobStorageForRef resolve a ref to its BlobStorage backend
  *   - ExecutionRef      portable invocation descriptor (inlined, stays standalone)
@@ -33,9 +33,9 @@ interface KindValueRef {
     readonly kind: string;
     readonly value: string;
 }
-/** Parse a wire-format ref string (::kind::value) into a KindValueRef. */
+/** Parse a wire-format ref string (b64:<base64url(json)>) into a KindValueRef. */
 declare function parseRef(s: string): KindValueRef;
-/** Serialize a KindValueRef to the wire format: ::kind::value */
+/** Serialize a KindValueRef to the wire format: b64:<base64url(json)> */
 declare function serializeRef(ref: KindValueRef): string;
 interface BlobStorage {
     /** Returns content string, or null if not found. */
@@ -62,7 +62,7 @@ interface ExecutionRef {
     meta?: string;
     /** Transport / runtime kind. */
     howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';
-    /** Address of the target in ::kind::value wire form (e.g. ::fs-path::/path/to/cli.js). */
+    /** Address of the target in b64:<base64url(json)> wire form. */
     whatToRun: string;
     /** Opaque executor config stored with the ref. */
     extra?: Record<string, unknown>;

package/dist/storage-refs.d.ts

@@ -5,9 +5,9 @@
  * Zero dependencies on the rest of yaml-flow.
  *
  * Provides:
- *   - KindValueRef      wire format: ::kind::value
- *   - parseRef()        parse a ::kind::value string
- *   - serializeRef()    produce a ::kind::value string
+ *   - KindValueRef      wire format: b64:<base64url(json)>
+ *   - parseRef()        parse a b64:<base64url(json)> string
+ *   - serializeRef()    produce a b64:<base64url(json)> string
  *   - BlobStorage       read/write interface
  *   - blobStorageForRef resolve a ref to its BlobStorage backend
  *   - ExecutionRef      portable invocation descriptor (inlined, stays standalone)
@@ -33,9 +33,9 @@ interface KindValueRef {
     readonly kind: string;
     readonly value: string;
 }
-/** Parse a wire-format ref string (::kind::value) into a KindValueRef. */
+/** Parse a wire-format ref string (b64:<base64url(json)>) into a KindValueRef. */
 declare function parseRef(s: string): KindValueRef;
-/** Serialize a KindValueRef to the wire format: ::kind::value */
+/** Serialize a KindValueRef to the wire format: b64:<base64url(json)> */
 declare function serializeRef(ref: KindValueRef): string;
 interface BlobStorage {
     /** Returns content string, or null if not found. */
@@ -62,7 +62,7 @@ interface ExecutionRef {
     meta?: string;
     /** Transport / runtime kind. */
     howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';
-    /** Address of the target in ::kind::value wire form (e.g. ::fs-path::/path/to/cli.js). */
+    /** Address of the target in b64:<base64url(json)> wire form. */
     whatToRun: string;
     /** Opaque executor config stored with the ref. */
     extra?: Record<string, unknown>;

package/dist/storage-refs.js

@@ -1,4 +1,4 @@
-import*as i from'fs';import*as c from'path';import {spawnSync}from'child_process';function x(t){if(!t.startsWith("::"))throw new Error(`Invalid ref format (expected ::kind::value): ${t}`);let n=t.slice(2),r=n.indexOf("::");if(r===-1)throw new Error(`Invalid ref format (expected ::kind::value): ${t}`);return {kind:n.slice(0,r),value:n.slice(r+2)}}function h(t){return `::${t.kind}::${t.value}`}function R(){return {read(t){if(!i.existsSync(t))return null;try{return i.readFileSync(t,"utf-8")}catch{return null}},write(t,n){i.mkdirSync(c.dirname(t),{recursive:true}),i.writeFileSync(t,n,"utf-8");}}}function k(t){if(t.kind==="fs-path")return R();throw new Error(`Unsupported storage kind: "${t.kind}". Supported kinds: fs-path`)}function d(t){try{return x(t).value}catch{return t}}function g(t){let n=t.extra?.notifyChannel;return typeof n=="string"&&n.length>0?n:void 0}function w(t){if(!t.endsWith(".ts"))return {cmd:process.execPath,args:[t]};let n=c.dirname(t),r=[];for(let o=1;o<=5;o++){let s=c.join(n,...Array(o).fill(".."),"node_modules");r.push(c.join(s,"tsx","dist","cli.mjs")),r.push(c.join(s,".bin","tsx"));}let e=r.find(o=>i.existsSync(o));return e?{cmd:process.execPath,args:[e,t]}:{cmd:"npx",args:["tsx",t]}}function v(t,n){let{token:r,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let o=d(e.whatToRun),{cmd:s,args:l}=w(o),u=g(e),f=[...l,"source-data-fetched","--ref",h(n),"--token",r,...u?["--notify-channel",u]:[]],a=spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportComplete: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let o=d(e.whatToRun),s=JSON.stringify({status:"complete",ref:h(n),token:r});m(o,s);return}throw new Error(`reportComplete: unsupported via.howToRun "${e.howToRun}"`)}function T(t,n){let{token:r,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let o=d(e.whatToRun),{cmd:s,args:l}=w(o),u=g(e),f=[...l,"source-data-fetch-failure","--token",r,"--reason",n,...u?["--notify-channel",u]:[]],a=spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportFailed: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let o=d(e.whatToRun),s=JSON.stringify({status:"failed",reason:n,token:r});m(o,s);return}throw new Error(`reportFailed: unsupported via.howToRun "${e.howToRun}"`)}function m(t,n){let r=`
+import*as i from'fs';import*as c from'path';import {spawnSync}from'child_process';function y(t){if(!t.startsWith("b64:"))throw new Error(`Invalid ref format (expected b64:<base64url(json)>): ${t}`);let n=t.slice(4),o=n.replace(/-/g,"+").replace(/_/g,"/")+"=".repeat((4-n.length%4)%4),e;try{e=JSON.parse(Buffer.from(o,"base64").toString("utf8"));}catch{throw new Error(`Invalid ref format (malformed base64url/json): ${t}`)}if(!e||typeof e!="object")throw new Error(`Invalid ref format (expected object payload): ${t}`);let r=e;if(typeof r.kind!="string"||typeof r.value!="string")throw new Error(`Invalid ref format (payload must contain string kind/value): ${t}`);return {kind:r.kind,value:r.value}}function h(t){return `b64:${Buffer.from(JSON.stringify(t),"utf8").toString("base64").replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}`}function R(){return {read(t){if(!i.existsSync(t))return null;try{return i.readFileSync(t,"utf-8")}catch{return null}},write(t,n){i.mkdirSync(c.dirname(t),{recursive:true}),i.writeFileSync(t,n,"utf-8");}}}function k(t){if(t.kind==="fs-path")return R();throw new Error(`Unsupported storage kind: "${t.kind}". Supported kinds: fs-path`)}function d(t){return y(t).value}function g(t){let n=t.extra?.notifyChannel;return typeof n=="string"&&n.length>0?n:void 0}function w(t){if(!t.endsWith(".ts"))return {cmd:process.execPath,args:[t]};let n=c.dirname(t),o=[];for(let r=1;r<=5;r++){let s=c.join(n,...Array(r).fill(".."),"node_modules");o.push(c.join(s,"tsx","dist","cli.mjs")),o.push(c.join(s,".bin","tsx"));}let e=o.find(r=>i.existsSync(r));return e?{cmd:process.execPath,args:[e,t]}:{cmd:"npx",args:["tsx",t]}}function b(t,n){let{token:o,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let r=d(e.whatToRun),{cmd:s,args:l}=w(r),u=g(e),f=[...l,"source-data-fetched","--ref",h(n),"--token",o,...u?["--notify-channel",u]:[]],a=spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportComplete: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let r=d(e.whatToRun),s=JSON.stringify({status:"complete",ref:h(n),token:o});m(r,s);return}throw new Error(`reportComplete: unsupported via.howToRun "${e.howToRun}"`)}function v(t,n){let{token:o,via:e}=t;if(e.howToRun==="local-node"||e.howToRun==="local-process"){let r=d(e.whatToRun),{cmd:s,args:l}=w(r),u=g(e),f=[...l,"source-data-fetch-failure","--token",o,"--reason",n,...u?["--notify-channel",u]:[]],a=spawnSync(s,f,{encoding:"utf-8",windowsHide:true});if(a.status!==0)throw new Error(`reportFailed: board CLI exited ${a.status}: ${a.stderr?.trim()}`);return}if(e.howToRun==="http:post"){let r=d(e.whatToRun),s=JSON.stringify({status:"failed",reason:n,token:o});m(r,s);return}throw new Error(`reportFailed: unsupported via.howToRun "${e.howToRun}"`)}function m(t,n){let o=`
     const {request} = require(new URL('${t}').protocol === 'https:' ? 'https' : 'http');
     const h = ${JSON.stringify({"Content-Type":"application/json","Content-Length":Buffer.byteLength(n)})};
     const u = new URL('${t}');
@@ -6,5 +6,5 @@ import*as i from'fs';import*as c from'path';import {spawnSync}from'child_process
     req.on('error', e => { process.stderr.write(e.message); process.exit(1); });
     req.write(${JSON.stringify(n)});
     req.end();
-  `,e=spawnSync(process.execPath,["-e",r],{encoding:"utf-8",windowsHide:true});if(e.status!==0)throw new Error(`http-post failed: ${e.stderr?.trim()}`)}export{k as blobStorageForRef,x as parseRef,v as reportComplete,T as reportFailed,h as serializeRef};//# sourceMappingURL=storage-refs.js.map
+  `,e=spawnSync(process.execPath,["-e",o],{encoding:"utf-8",windowsHide:true});if(e.status!==0)throw new Error(`http-post failed: ${e.stderr?.trim()}`)}export{k as blobStorageForRef,y as parseRef,b as reportComplete,v as reportFailed,h as serializeRef};//# sourceMappingURL=storage-refs.js.map
 //# sourceMappingURL=storage-refs.js.map

package/dist/storage-refs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli/node/public-storage-adapter.ts"],"names":["parseRef","s","inner","idx","serializeRef","ref","createFsPathBlobStorage","key","content","blobStorageForRef","_parseWhatToRun","whatToRun","_notifyChannelFromVia","via","candidate","_resolveLocalNodeInvocation","scriptPath","dir","candidates","up","base","tsx","p","reportComplete","callback","outRef","token","cmd","args","notifyChannel","callbackArgs","result","spawnSync","url","body","_httpPostSync","reportFailed","reason","script"],"mappings":"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","file":"storage-refs.js","sourcesContent":["/**\n * public-storage-adapter.ts\n *\n * Standalone file — copy this to your task-executor project.\n * Zero dependencies on the rest of yaml-flow.\n *\n * Provides:\n *   - KindValueRef      wire format: ::kind::value\n *   - parseRef()        parse a ::kind::value string\n *   - serializeRef()    produce a ::kind::value string\n *   - BlobStorage       read/write interface\n *   - blobStorageForRef resolve a ref to its BlobStorage backend\n *   - ExecutionRef      portable invocation descriptor (inlined, stays standalone)\n *   - TaskCallback      how to report task completion back to the board\n *   - reportComplete()  call from executor on success\n *   - reportFailed()    call from executor on failure\n *\n * Supported storage kinds:\n *   fs-path   — ref.value is an absolute file path; reads/writes via node:fs\n *\n * Supported callback transports (via ExecutionRef.howToRun):\n *   local-node     — invoke board CLI as a child Node process\n *   http:post      — HTTP POST to a board endpoint\n *\n * Usage:\n *   import { parseRef, blobStorageForRef, reportComplete, reportFailed } from './public-storage-adapter.js';\n *\n *   const { source_def, callback } = JSON.parse(blobStorageForRef(inRef).read(inRef.value));\n *   // ... do work, write to outRef ...\n *   reportComplete(callback, outRef);\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { spawnSync } from 'node:child_process';\n\n// ============================================================================\n// KindValueRef\n// ============================================================================\n\nexport interface KindValueRef {\n  readonly kind: string;\n  readonly value: string;\n}\n\n/** Parse a wire-format ref string (::kind::value) into a KindValueRef. */\nexport function parseRef(s: string): KindValueRef {\n  if (!s.startsWith('::')) throw new Error(`Invalid ref format (expected ::kind::value): ${s}`);\n  const inner = s.slice(2);\n  const idx = inner.indexOf('::');\n  if (idx === -1) throw new Error(`Invalid ref format (expected ::kind::value): ${s}`);\n  return { kind: inner.slice(0, idx), value: inner.slice(idx + 2) };\n}\n\n/** Serialize a KindValueRef to the wire format: ::kind::value */\nexport function serializeRef(ref: KindValueRef): string {\n  return `::${ref.kind}::${ref.value}`;\n}\n\n// ============================================================================\n// BlobStorage\n// ============================================================================\n\nexport interface BlobStorage {\n  /** Returns content string, or null if not found. */\n  read(key: string): string | null;\n  /** Write content at key. */\n  write(key: string, content: string): void;\n}\n\n// ============================================================================\n// fs-path backend — key IS the absolute file path\n// ============================================================================\n\nfunction createFsPathBlobStorage(): BlobStorage {\n  return {\n    read(key: string): string | null {\n      if (!fs.existsSync(key)) return null;\n      try { return fs.readFileSync(key, 'utf-8'); } catch { return null; }\n    },\n    write(key: string, content: string): void {\n      fs.mkdirSync(path.dirname(key), { recursive: true });\n      fs.writeFileSync(key, content, 'utf-8');\n    },\n  };\n}\n\n// ============================================================================\n// blobStorageForRef\n// ============================================================================\n\n/**\n * Resolve a KindValueRef to its BlobStorage backend.\n * Throws a clear error for unrecognised kinds.\n */\nexport function blobStorageForRef(ref: KindValueRef): BlobStorage {\n  switch (ref.kind) {\n    case 'fs-path': return createFsPathBlobStorage();\n    default: throw new Error(`Unsupported storage kind: \"${ref.kind}\". Supported kinds: fs-path`);\n  }\n}\n\n// ============================================================================\n// TaskCallback — how a task-executor reports results back to the board\n// ============================================================================\n\n/**\n * Portable invocation descriptor for the board CLI back-channel.\n * Inlined here so this file stays standalone (zero deps on yaml-flow internals).\n * Shape matches ExecutionRef in execution-interface.ts — keep in sync.\n *\n * Supported howToRun values for TaskCallback.via:\n *   local-node   — invoke board CLI as: node [tsx?] <whatToRun.value> <cmd> [...argv]\n *   http:post    — POST to <whatToRun.value> with a JSON body\n */\nexport interface ExecutionRef {\n  /** Optional human-readable label. Not used for dispatch. */\n  meta?: string;\n  /** Transport / runtime kind. */\n  howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';\n  /** Address of the target in ::kind::value wire form (e.g. ::fs-path::/path/to/cli.js). */\n  whatToRun: string;\n  /** Opaque executor config stored with the ref. */\n  extra?: Record<string, unknown>;\n}\n\n/**\n * Describes how the board wants to receive task completion callbacks.\n * Baked into the inRef payload as { source_def, callback }.\n * The executor treats `token` as opaque and passes it back unchanged.\n */\nexport interface TaskCallback {\n  /** Opaque routing token — generated by the board, passed back unchanged. */\n  token: string;\n  /** Delivery mechanism — an ExecutionRef pointing at the board CLI or endpoint. */\n  via: ExecutionRef;\n}\n\n/**\n * Extract the path/url value from a whatToRun ::kind::value wire string.\n * Falls back to the raw string if it isn’t in ::kind::value form.\n */\nfunction _parseWhatToRun(whatToRun: string): string {\n  try { return parseRef(whatToRun).value; } catch { return whatToRun; }\n}\n\nfunction _notifyChannelFromVia(via: ExecutionRef): string | undefined {\n  const candidate = via.extra?.['notifyChannel'];\n  return typeof candidate === 'string' && candidate.length > 0 ? candidate : undefined;\n}\n\n/**\n * Resolve the Node invocation for a local board CLI script.\n * If the path ends in .ts (dev mode), attempts to locate tsx alongside it;\n * otherwise assumes it’s a compiled .js and invokes directly with node.\n */\nfunction _resolveLocalNodeInvocation(scriptPath: string): { cmd: string; args: string[] } {\n  if (!scriptPath.endsWith('.ts')) {\n    return { cmd: process.execPath, args: [scriptPath] };\n  }\n  // Dev path: look for tsx in node_modules relative to the script's package root.\n  // The .ts file may be at src/cli/node/<file>.ts — walk up until we find node_modules/tsx.\n  const dir = path.dirname(scriptPath);\n  const candidates: string[] = [];\n  for (let up = 1; up <= 5; up++) {\n    const base = path.join(dir, ...Array(up).fill('..'), 'node_modules');\n    candidates.push(path.join(base, 'tsx', 'dist', 'cli.mjs'));\n    candidates.push(path.join(base, '.bin', 'tsx'));\n  }\n  const tsx = candidates.find(p => fs.existsSync(p));\n  if (tsx) return { cmd: process.execPath, args: [tsx, scriptPath] };\n  return { cmd: 'npx', args: ['tsx', scriptPath] };\n}\n\n/**\n * Report successful task completion back to the board.\n * Call this from a task-executor after writing the result to outRef.\n */\nexport function reportComplete(callback: TaskCallback, outRef: KindValueRef): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetched',\n      '--ref', serializeRef(outRef),\n      '--token', token,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportComplete: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'complete', ref: serializeRef(outRef), token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportComplete: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/**\n * Report task failure back to the board.\n * Call this from a task-executor instead of writing to outRef.\n */\nexport function reportFailed(callback: TaskCallback, reason: string): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetch-failure',\n      '--token', token,\n      '--reason', reason,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportFailed: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'failed', reason, token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportFailed: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/** Synchronous HTTP POST using a child node process (keeps this file free of async). */\nfunction _httpPostSync(url: string, body: string): void {\n  const script = `\n    const {request} = require(new URL('${url}').protocol === 'https:' ? 'https' : 'http');\n    const h = ${JSON.stringify({ 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) })};\n    const u = new URL('${url}');\n    const req = request({hostname:u.hostname,port:u.port,path:u.pathname+u.search,method:'POST',headers:h});\n    req.on('error', e => { process.stderr.write(e.message); process.exit(1); });\n    req.write(${JSON.stringify(body)});\n    req.end();\n  `;\n  const result = spawnSync(process.execPath, ['-e', script], { encoding: 'utf-8', windowsHide: true });\n  if (result.status !== 0) throw new Error(`http-post failed: ${result.stderr?.trim()}`);\n}\n"]}
+{"version":3,"sources":["../src/cli/node/public-storage-adapter.ts"],"names":["parseRef","s","payload","padded","decoded","candidate","serializeRef","ref","createFsPathBlobStorage","key","content","blobStorageForRef","_parseWhatToRun","whatToRun","_notifyChannelFromVia","via","_resolveLocalNodeInvocation","scriptPath","dir","candidates","up","base","tsx","p","reportComplete","callback","outRef","token","cmd","args","notifyChannel","callbackArgs","result","spawnSync","url","body","_httpPostSync","reportFailed","reason","script"],"mappings":"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","file":"storage-refs.js","sourcesContent":["/**\n * public-storage-adapter.ts\n *\n * Standalone file — copy this to your task-executor project.\n * Zero dependencies on the rest of yaml-flow.\n *\n * Provides:\n *   - KindValueRef      wire format: b64:<base64url(json)>\n *   - parseRef()        parse a b64:<base64url(json)> string\n *   - serializeRef()    produce a b64:<base64url(json)> string\n *   - BlobStorage       read/write interface\n *   - blobStorageForRef resolve a ref to its BlobStorage backend\n *   - ExecutionRef      portable invocation descriptor (inlined, stays standalone)\n *   - TaskCallback      how to report task completion back to the board\n *   - reportComplete()  call from executor on success\n *   - reportFailed()    call from executor on failure\n *\n * Supported storage kinds:\n *   fs-path   — ref.value is an absolute file path; reads/writes via node:fs\n *\n * Supported callback transports (via ExecutionRef.howToRun):\n *   local-node     — invoke board CLI as a child Node process\n *   http:post      — HTTP POST to a board endpoint\n *\n * Usage:\n *   import { parseRef, blobStorageForRef, reportComplete, reportFailed } from './public-storage-adapter.js';\n *\n *   const { source_def, callback } = JSON.parse(blobStorageForRef(inRef).read(inRef.value));\n *   // ... do work, write to outRef ...\n *   reportComplete(callback, outRef);\n */\n\nimport * as fs from 'node:fs';\nimport * as path from 'node:path';\nimport { spawnSync } from 'node:child_process';\n\n// ============================================================================\n// KindValueRef\n// ============================================================================\n\nexport interface KindValueRef {\n  readonly kind: string;\n  readonly value: string;\n}\n\n/** Parse a wire-format ref string (b64:<base64url(json)>) into a KindValueRef. */\nexport function parseRef(s: string): KindValueRef {\n  if (!s.startsWith('b64:')) throw new Error(`Invalid ref format (expected b64:<base64url(json)>): ${s}`);\n  const payload = s.slice(4);\n  const padded = payload.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (payload.length % 4)) % 4);\n  let decoded: unknown;\n  try {\n    decoded = JSON.parse(Buffer.from(padded, 'base64').toString('utf8'));\n  } catch {\n    throw new Error(`Invalid ref format (malformed base64url/json): ${s}`);\n  }\n  if (!decoded || typeof decoded !== 'object') {\n    throw new Error(`Invalid ref format (expected object payload): ${s}`);\n  }\n  const candidate = decoded as { kind?: unknown; value?: unknown };\n  if (typeof candidate.kind !== 'string' || typeof candidate.value !== 'string') {\n    throw new Error(`Invalid ref format (payload must contain string kind/value): ${s}`);\n  }\n  return { kind: candidate.kind, value: candidate.value };\n}\n\n/** Serialize a KindValueRef to the wire format: b64:<base64url(json)> */\nexport function serializeRef(ref: KindValueRef): string {\n  return `b64:${Buffer.from(JSON.stringify(ref), 'utf8').toString('base64').replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/g, '')}`;\n}\n\n// ============================================================================\n// BlobStorage\n// ============================================================================\n\nexport interface BlobStorage {\n  /** Returns content string, or null if not found. */\n  read(key: string): string | null;\n  /** Write content at key. */\n  write(key: string, content: string): void;\n}\n\n// ============================================================================\n// fs-path backend — key IS the absolute file path\n// ============================================================================\n\nfunction createFsPathBlobStorage(): BlobStorage {\n  return {\n    read(key: string): string | null {\n      if (!fs.existsSync(key)) return null;\n      try { return fs.readFileSync(key, 'utf-8'); } catch { return null; }\n    },\n    write(key: string, content: string): void {\n      fs.mkdirSync(path.dirname(key), { recursive: true });\n      fs.writeFileSync(key, content, 'utf-8');\n    },\n  };\n}\n\n// ============================================================================\n// blobStorageForRef\n// ============================================================================\n\n/**\n * Resolve a KindValueRef to its BlobStorage backend.\n * Throws a clear error for unrecognised kinds.\n */\nexport function blobStorageForRef(ref: KindValueRef): BlobStorage {\n  switch (ref.kind) {\n    case 'fs-path': return createFsPathBlobStorage();\n    default: throw new Error(`Unsupported storage kind: \"${ref.kind}\". Supported kinds: fs-path`);\n  }\n}\n\n// ============================================================================\n// TaskCallback — how a task-executor reports results back to the board\n// ============================================================================\n\n/**\n * Portable invocation descriptor for the board CLI back-channel.\n * Inlined here so this file stays standalone (zero deps on yaml-flow internals).\n * Shape matches ExecutionRef in execution-interface.ts — keep in sync.\n *\n * Supported howToRun values for TaskCallback.via:\n *   local-node   — invoke board CLI as: node [tsx?] <whatToRun.value> <cmd> [...argv]\n *   http:post    — POST to <whatToRun.value> with a JSON body\n */\nexport interface ExecutionRef {\n  /** Optional human-readable label. Not used for dispatch. */\n  meta?: string;\n  /** Transport / runtime kind. */\n  howToRun: 'local-node' | 'local-python' | 'local-process' | 'http:post' | 'http:get' | 'built-in';\n  /** Address of the target in b64:<base64url(json)> wire form. */\n  whatToRun: string;\n  /** Opaque executor config stored with the ref. */\n  extra?: Record<string, unknown>;\n}\n\n/**\n * Describes how the board wants to receive task completion callbacks.\n * Baked into the inRef payload as { source_def, callback }.\n * The executor treats `token` as opaque and passes it back unchanged.\n */\nexport interface TaskCallback {\n  /** Opaque routing token — generated by the board, passed back unchanged. */\n  token: string;\n  /** Delivery mechanism — an ExecutionRef pointing at the board CLI or endpoint. */\n  via: ExecutionRef;\n}\n\n/**\n * Extract the path/url value from a whatToRun b64:<base64url(json)> wire string.\n */\nfunction _parseWhatToRun(whatToRun: string): string {\n  return parseRef(whatToRun).value;\n}\n\nfunction _notifyChannelFromVia(via: ExecutionRef): string | undefined {\n  const candidate = via.extra?.['notifyChannel'];\n  return typeof candidate === 'string' && candidate.length > 0 ? candidate : undefined;\n}\n\n/**\n * Resolve the Node invocation for a local board CLI script.\n * If the path ends in .ts (dev mode), attempts to locate tsx alongside it;\n * otherwise assumes it’s a compiled .js and invokes directly with node.\n */\nfunction _resolveLocalNodeInvocation(scriptPath: string): { cmd: string; args: string[] } {\n  if (!scriptPath.endsWith('.ts')) {\n    return { cmd: process.execPath, args: [scriptPath] };\n  }\n  // Dev path: look for tsx in node_modules relative to the script's package root.\n  // The .ts file may be at src/cli/node/<file>.ts — walk up until we find node_modules/tsx.\n  const dir = path.dirname(scriptPath);\n  const candidates: string[] = [];\n  for (let up = 1; up <= 5; up++) {\n    const base = path.join(dir, ...Array(up).fill('..'), 'node_modules');\n    candidates.push(path.join(base, 'tsx', 'dist', 'cli.mjs'));\n    candidates.push(path.join(base, '.bin', 'tsx'));\n  }\n  const tsx = candidates.find(p => fs.existsSync(p));\n  if (tsx) return { cmd: process.execPath, args: [tsx, scriptPath] };\n  return { cmd: 'npx', args: ['tsx', scriptPath] };\n}\n\n/**\n * Report successful task completion back to the board.\n * Call this from a task-executor after writing the result to outRef.\n */\nexport function reportComplete(callback: TaskCallback, outRef: KindValueRef): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetched',\n      '--ref', serializeRef(outRef),\n      '--token', token,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportComplete: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'complete', ref: serializeRef(outRef), token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportComplete: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/**\n * Report task failure back to the board.\n * Call this from a task-executor instead of writing to outRef.\n */\nexport function reportFailed(callback: TaskCallback, reason: string): void {\n  const { token, via } = callback;\n  if (via.howToRun === 'local-node' || via.howToRun === 'local-process') {\n    const scriptPath = _parseWhatToRun(via.whatToRun);\n    const { cmd, args } = _resolveLocalNodeInvocation(scriptPath);\n    const notifyChannel = _notifyChannelFromVia(via);\n    const callbackArgs = [\n      ...args,\n      'source-data-fetch-failure',\n      '--token', token,\n      '--reason', reason,\n      ...(notifyChannel ? ['--notify-channel', notifyChannel] : []),\n    ];\n    const result = spawnSync(cmd, callbackArgs, { encoding: 'utf-8', windowsHide: true });\n    if (result.status !== 0) {\n      throw new Error(`reportFailed: board CLI exited ${result.status}: ${result.stderr?.trim()}`);\n    }\n    return;\n  }\n  if (via.howToRun === 'http:post') {\n    const url = _parseWhatToRun(via.whatToRun);\n    const body = JSON.stringify({ status: 'failed', reason, token });\n    _httpPostSync(url, body);\n    return;\n  }\n  throw new Error(`reportFailed: unsupported via.howToRun \"${via.howToRun}\"`);\n}\n\n/** Synchronous HTTP POST using a child node process (keeps this file free of async). */\nfunction _httpPostSync(url: string, body: string): void {\n  const script = `\n    const {request} = require(new URL('${url}').protocol === 'https:' ? 'https' : 'http');\n    const h = ${JSON.stringify({ 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) })};\n    const u = new URL('${url}');\n    const req = request({hostname:u.hostname,port:u.port,path:u.pathname+u.search,method:'POST',headers:h});\n    req.on('error', e => { process.stderr.write(e.message); process.exit(1); });\n    req.write(${JSON.stringify(body)});\n    req.end();\n  `;\n  const result = spawnSync(process.execPath, ['-e', script], { encoding: 'utf-8', windowsHide: true });\n  if (result.status !== 0) throw new Error(`http-post failed: ${result.stderr?.trim()}`);\n}\n"]}

package/dist/types-CU3DjTKL.d.cts

@@ -0,0 +1,147 @@
+import { e as KindValueRef, B as BoardPlatformAdapter, d as CommandResult } from './board-live-cards-public-5n1-syA3.cjs';
+import { ExecutionRef } from './execution-refs.cjs';
+
+/**
+ * server-runtime/types.ts
+ *
+ * Platform-free adapter interfaces for the board server runtime.
+ *
+ * The runtime (index.ts) imports ONLY this file and board-live-cards-public
+ * for its dependencies — no node:fs, node:net, node:child_process, etc.
+ *
+ * Hosts (demo-server, Azure Function, Firebase Function) provide implementations
+ * of these interfaces when constructing the runtime.
+ */
+
+interface InvocationAdapter {
+    /**
+     * Fire-and-forget invocation of an ExecutionRef with args.
+     * Used for chat-handler dispatch, and potentially task-executor / inference-adapter.
+     * Returns a promise that resolves when the invocation is dispatched (not completed).
+     */
+    invoke(ref: ExecutionRef, args: Record<string, unknown>): Promise<{
+        dispatched: boolean;
+        error?: string;
+    }>;
+    /**
+     * Optional synchronous describe call — asks the target to identify itself.
+     * Used for pre-init validation (e.g. confirming a chat-handler reports kind='chat-handler').
+     * Hosts that pre-register capabilities at deploy time may omit this.
+     */
+    describe?(ref: ExecutionRef): Promise<DescribeEnvelope | null>;
+}
+interface NotificationTransport {
+    /**
+     * Start listening for events on a notification endpoint identified by a kind-ref.
+     * The ref kind determines the transport mechanism:
+     *   ::named-pipe::/tmp/board-x.sock
+     *   ::firestore-watch::collections/board-x/notifications
+     *   ::signalr::https://x.service.signalr.net/hub/board-x
+     * onEvent is called with parsed JSON notification objects.
+     * Returns a teardown function.
+     */
+    subscribe(ref: KindValueRef, onEvent: (event: unknown) => void): Promise<() => void>;
+}
+interface DescribeEnvelope {
+    name: string;
+    kind: 'task-executor' | 'chat-handler' | 'inference-adapter';
+    protocolVersion: string;
+    supports?: string[];
+}
+interface RuntimeLogger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+interface BoardContextConfig {
+    label: string;
+    boardAdapter: BoardPlatformAdapter;
+    /** Optional separate adapter for file/chat blob storage (defaults to boardAdapter) */
+    artifactsAdapter?: BoardPlatformAdapter;
+    baseRef: KindValueRef;
+    cardStoreRef: string;
+    outputsStoreRef: string;
+    /** Notification endpoint ref — e.g. ::named-pipe::<path> or ::firestore-watch::<path> */
+    notifyRef?: KindValueRef;
+    taskExecutorRef?: ExecutionRef;
+    chatHandlerRef?: ExecutionRef;
+    inferenceAdapterRef?: ExecutionRef;
+}
+interface SingleBoardRuntimeOptions {
+    apiBasePath?: string;
+    corsHeaders?: Record<string, string>;
+    boardId?: string;
+    /** One or more board layers composing this board surface (e.g. base cards + admin cards). */
+    boards: BoardContextConfig[];
+    invocationAdapter: InvocationAdapter;
+    notificationTransport?: NotificationTransport;
+    logger?: RuntimeLogger;
+    serverUrl?: string;
+    /** Extra host-specific fields baked into execution ref extras */
+    executionExtra?: Record<string, unknown>;
+}
+interface MultiBoardRuntimeOptions {
+    apiBasePath?: string;
+    corsHeaders?: Record<string, string>;
+    /** Artifacts store for multi-board registry metadata */
+    serverMetaStore: {
+        getText(key: string): string | null;
+        putText(key: string, text: string): void;
+    };
+    /** Factory that creates a single-board runtime for a given board config */
+    boardRuntimeFactory: (boardId: string, entry: Record<string, unknown>) => SingleBoardRuntime;
+    logger?: RuntimeLogger;
+}
+interface SingleBoardRuntime {
+    readonly apiBasePath: string;
+    readonly corsHeaders: Record<string, string>;
+    handleRuntimeApi(req: RuntimeRequest, res: RuntimeResponse, parsedUrl: URL): Promise<boolean>;
+    buildPublishedRuntimePayload(): unknown;
+    clearChatRecords(cardId: string): void;
+    /** Report that a source fetch completed. Token is the source callback token; ref is the blob ref (b64:<base64url(json)>). */
+    reportSourceFetched(token: string, ref: string): CommandResult;
+    /** Report that a source fetch failed. Token is the source callback token. */
+    reportSourceFetchFailure(token: string, reason: string): CommandResult;
+    /** Exposed card store — host calls cardStore.set({body: cards}) to seed definitions. */
+    readonly cardStore: {
+        get(input: {
+            params?: {
+                id?: string;
+            };
+        }): {
+            status: string;
+            data?: {
+                cards?: Array<Record<string, unknown>>;
+            };
+            error?: string;
+        };
+        set(input: {
+            body: unknown;
+        }): {
+            status: string;
+            error?: string;
+        };
+    };
+}
+interface MultiBoardRuntime {
+    readonly apiBasePath: string;
+    readonly corsHeaders: Record<string, string>;
+    handleApi(req: RuntimeRequest, res: RuntimeResponse, parsedUrl: URL): Promise<boolean>;
+    requireBoardService(boardId: string): {
+        service: SingleBoardRuntime;
+    };
+}
+interface RuntimeRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Buffer | Uint8Array>;
+}
+interface RuntimeResponse {
+    writeHead(statusCode: number, headers?: Record<string, string | number>): void;
+    write(data: string | Buffer): boolean;
+    end(data?: string | Buffer): void;
+}
+
+export type { BoardContextConfig as B, DescribeEnvelope as D, InvocationAdapter as I, MultiBoardRuntimeOptions as M, NotificationTransport as N, RuntimeLogger as R, SingleBoardRuntimeOptions as S, MultiBoardRuntime as a, SingleBoardRuntime as b, RuntimeRequest as c, RuntimeResponse as d };

package/dist/types-HGDTWIun.d.ts

@@ -0,0 +1,147 @@
+import { e as KindValueRef, B as BoardPlatformAdapter, d as CommandResult } from './board-live-cards-public-CK_J8uv0.js';
+import { ExecutionRef } from './execution-refs.js';
+
+/**
+ * server-runtime/types.ts
+ *
+ * Platform-free adapter interfaces for the board server runtime.
+ *
+ * The runtime (index.ts) imports ONLY this file and board-live-cards-public
+ * for its dependencies — no node:fs, node:net, node:child_process, etc.
+ *
+ * Hosts (demo-server, Azure Function, Firebase Function) provide implementations
+ * of these interfaces when constructing the runtime.
+ */
+
+interface InvocationAdapter {
+    /**
+     * Fire-and-forget invocation of an ExecutionRef with args.
+     * Used for chat-handler dispatch, and potentially task-executor / inference-adapter.
+     * Returns a promise that resolves when the invocation is dispatched (not completed).
+     */
+    invoke(ref: ExecutionRef, args: Record<string, unknown>): Promise<{
+        dispatched: boolean;
+        error?: string;
+    }>;
+    /**
+     * Optional synchronous describe call — asks the target to identify itself.
+     * Used for pre-init validation (e.g. confirming a chat-handler reports kind='chat-handler').
+     * Hosts that pre-register capabilities at deploy time may omit this.
+     */
+    describe?(ref: ExecutionRef): Promise<DescribeEnvelope | null>;
+}
+interface NotificationTransport {
+    /**
+     * Start listening for events on a notification endpoint identified by a kind-ref.
+     * The ref kind determines the transport mechanism:
+     *   ::named-pipe::/tmp/board-x.sock
+     *   ::firestore-watch::collections/board-x/notifications
+     *   ::signalr::https://x.service.signalr.net/hub/board-x
+     * onEvent is called with parsed JSON notification objects.
+     * Returns a teardown function.
+     */
+    subscribe(ref: KindValueRef, onEvent: (event: unknown) => void): Promise<() => void>;
+}
+interface DescribeEnvelope {
+    name: string;
+    kind: 'task-executor' | 'chat-handler' | 'inference-adapter';
+    protocolVersion: string;
+    supports?: string[];
+}
+interface RuntimeLogger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+interface BoardContextConfig {
+    label: string;
+    boardAdapter: BoardPlatformAdapter;
+    /** Optional separate adapter for file/chat blob storage (defaults to boardAdapter) */
+    artifactsAdapter?: BoardPlatformAdapter;
+    baseRef: KindValueRef;
+    cardStoreRef: string;
+    outputsStoreRef: string;
+    /** Notification endpoint ref — e.g. ::named-pipe::<path> or ::firestore-watch::<path> */
+    notifyRef?: KindValueRef;
+    taskExecutorRef?: ExecutionRef;
+    chatHandlerRef?: ExecutionRef;
+    inferenceAdapterRef?: ExecutionRef;
+}
+interface SingleBoardRuntimeOptions {
+    apiBasePath?: string;
+    corsHeaders?: Record<string, string>;
+    boardId?: string;
+    /** One or more board layers composing this board surface (e.g. base cards + admin cards). */
+    boards: BoardContextConfig[];
+    invocationAdapter: InvocationAdapter;
+    notificationTransport?: NotificationTransport;
+    logger?: RuntimeLogger;
+    serverUrl?: string;
+    /** Extra host-specific fields baked into execution ref extras */
+    executionExtra?: Record<string, unknown>;
+}
+interface MultiBoardRuntimeOptions {
+    apiBasePath?: string;
+    corsHeaders?: Record<string, string>;
+    /** Artifacts store for multi-board registry metadata */
+    serverMetaStore: {
+        getText(key: string): string | null;
+        putText(key: string, text: string): void;
+    };
+    /** Factory that creates a single-board runtime for a given board config */
+    boardRuntimeFactory: (boardId: string, entry: Record<string, unknown>) => SingleBoardRuntime;
+    logger?: RuntimeLogger;
+}
+interface SingleBoardRuntime {
+    readonly apiBasePath: string;
+    readonly corsHeaders: Record<string, string>;
+    handleRuntimeApi(req: RuntimeRequest, res: RuntimeResponse, parsedUrl: URL): Promise<boolean>;
+    buildPublishedRuntimePayload(): unknown;
+    clearChatRecords(cardId: string): void;
+    /** Report that a source fetch completed. Token is the source callback token; ref is the blob ref (b64:<base64url(json)>). */
+    reportSourceFetched(token: string, ref: string): CommandResult;
+    /** Report that a source fetch failed. Token is the source callback token. */
+    reportSourceFetchFailure(token: string, reason: string): CommandResult;
+    /** Exposed card store — host calls cardStore.set({body: cards}) to seed definitions. */
+    readonly cardStore: {
+        get(input: {
+            params?: {
+                id?: string;
+            };
+        }): {
+            status: string;
+            data?: {
+                cards?: Array<Record<string, unknown>>;
+            };
+            error?: string;
+        };
+        set(input: {
+            body: unknown;
+        }): {
+            status: string;
+            error?: string;
+        };
+    };
+}
+interface MultiBoardRuntime {
+    readonly apiBasePath: string;
+    readonly corsHeaders: Record<string, string>;
+    handleApi(req: RuntimeRequest, res: RuntimeResponse, parsedUrl: URL): Promise<boolean>;
+    requireBoardService(boardId: string): {
+        service: SingleBoardRuntime;
+    };
+}
+interface RuntimeRequest {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Buffer | Uint8Array>;
+}
+interface RuntimeResponse {
+    writeHead(statusCode: number, headers?: Record<string, string | number>): void;
+    write(data: string | Buffer): boolean;
+    end(data?: string | Buffer): void;
+}
+
+export type { BoardContextConfig as B, DescribeEnvelope as D, InvocationAdapter as I, MultiBoardRuntimeOptions as M, NotificationTransport as N, RuntimeLogger as R, SingleBoardRuntimeOptions as S, MultiBoardRuntime as a, SingleBoardRuntime as b, RuntimeRequest as c, RuntimeResponse as d };