@potential-guide/check-environment 0.0.0-stage → 0.1.0

package/dist/bundles/network/schemas/1.json

@@ -0,0 +1,78 @@
+{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "pass"
+      ],
+      "properties": {
+        "pass": {
+          "const": true,
+          "type": "boolean"
+        }
+      }
+    },
+    {
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "pass",
+        "problems"
+      ],
+      "properties": {
+        "pass": {
+          "const": false,
+          "type": "boolean"
+        },
+        "problems": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "additionalProperties": false,
+            "type": "object",
+            "required": [
+              "target",
+              "code",
+              "actual"
+            ],
+            "properties": {
+              "target": {
+                "minLength": 1,
+                "maxLength": 4096,
+                "type": "string"
+              },
+              "code": {
+                "anyOf": [
+                  {
+                    "const": "dns-unavailable",
+                    "type": "string"
+                  },
+                  {
+                    "const": "http-status",
+                    "type": "string"
+                  },
+                  {
+                    "const": "http-unavailable",
+                    "type": "string"
+                  }
+                ]
+              },
+              "actual": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$id": "https://task.invalid/schema/result"
+}

package/dist/bundles/network/schemas/2.json

@@ -0,0 +1,4 @@
+{
+  "not": {},
+  "$id": "https://task.invalid/schema/message"
+}

package/dist/bundles/network/task.yaml

@@ -0,0 +1,23 @@
+$schema: https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json
+name: Environment network check
+runtime:
+  type: node
+  minVersion: 22.13.0
+entry: worker.cjs
+inputSchema:
+  $ref: schemas/0.json
+resultSchema:
+  $ref: schemas/1.json
+messageSchema:
+  $ref: schemas/2.json
+include:
+  - resources/check.json
+  - resources/references/en/check.md
+  - resources/references/en/problems/dns-unavailable.md
+  - resources/references/en/problems/http-status.md
+  - resources/references/en/problems/http-unavailable.md
+  - schemas/0.json
+  - schemas/1.json
+  - schemas/2.json
+  - task.yaml
+  - worker.cjs

package/dist/bundles/network/worker.cjs

@@ -0,0 +1,2 @@
+const __artifactURL = require("node:url").pathToFileURL(__filename).href;
+"use strict";function Q(o){if(new Set(o).size!==o.length||o.some(n=>!/^[a-z][a-z0-9-]*$/.test(n)||n.length>4096))throw new Error("Check problem codes must be unique stable names of at most 4096 characters.")}function ce(o,n){Q(o);let i=new Set(o),r=n.map(a=>{if(!i.has(a.code))throw new Error(`Undeclared Check problem code: ${a.code}`);if(typeof a.target!="string"||!a.target.length||[...a.target].length>4096||a.actual!==null&&typeof a.actual!="string"||Object.keys(a).some(u=>!["target","code","actual"].includes(u)))throw new Error("Invalid Check problem.");return{target:a.target,code:a.code,actual:a.actual}});return r.length?{pass:!1,problems:r}:{pass:!0}}function Y(o,n){return async(i,r)=>{r.signal.throwIfAborted();let a=await n(i,r);return r.signal.throwIfAborted(),ce(o,a)}}var D=require("node:worker_threads");var g=class extends Error{code;details;constructor(n,i,r){super(i),this.code=n,this.details=r,this.name="TaskError"}};function T(o,n){throw new g(o,n)}function R(o,n=65536){let i=new Set,r=0;function a(s,c){if((++r>n||c>64)&&T("invalid_payload","JSON structure exceeds limit."),s===null||typeof s=="string"||typeof s=="boolean"||typeof s=="number"&&Number.isFinite(s))return s;(typeof s!="object"||s===null)&&T("invalid_payload","Only finite JSON values are accepted."),i.has(s)&&T("invalid_payload","Cyclic JSON is not accepted.");let b=Array.isArray(s);Object.getPrototypeOf(s)!==(b?Array.prototype:Object.prototype)&&T("invalid_payload","Custom prototypes are not accepted."),i.add(s);let f=Object.getOwnPropertyDescriptors(s),m=Reflect.ownKeys(f),x={},S=[];b&&m.length!==s.length+1&&T("invalid_payload","Sparse or decorated arrays are not accepted.");for(let w of m){typeof w!="string"&&T("invalid_payload","Symbol keys are not accepted.");let y=f[w];(!y||!("value"in y))&&T("invalid_payload","Accessors are not accepted."),!(b&&w==="length")&&(y.enumerable||T("invalid_payload","Hidden properties are not accepted."),b?(w!==String(S.length)&&T("invalid_payload","Invalid array keys."),S.push(a(y.value,c+1))):Object.defineProperty(x,w,{value:a(y.value,c+1),enumerable:!0,writable:!0,configurable:!0}))}return i.delete(s),b?S:x}let u=a(o,0);return new TextEncoder().encode(JSON.stringify(u)).byteLength>n&&T("payload_too_large","JSON payload exceeds byte limit."),u}function q(o){return Array.isArray(o)?`[${o.map(q).join(",")}]`:o&&typeof o=="object"?`{${Object.keys(o).sort().map(n=>`${JSON.stringify(n)}:${q(o[n]??null)}`).join(",")}}`:JSON.stringify(o)}var v=class extends g{result;constructor(n,i,r){super(n,i),this.result=r}};var B="https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json";var H={declaration:JSON.parse('{"$schema":"https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json","name":"Environment network check","runtime":{"type":"node","minVersion":"22.13.0"},"entry":"worker.cjs","inputSchema":{"additionalProperties":false,"anyOf":[{"properties":{"dns":{"type":"array","minItems":1}}},{"properties":{"http":{"type":"array","minItems":1}}}],"type":"object","required":["dns","http"],"properties":{"checkTimeoutMs":{"minimum":100,"maximum":300000,"type":"integer"},"dns":{"maxItems":100,"type":"array","items":{"maxLength":253,"pattern":"^[A-Za-z0-9][A-Za-z0-9.-]*$","type":"string"}},"http":{"maxItems":100,"type":"array","items":{"additionalProperties":false,"type":"object","required":["url","expectedStatus","followRedirects"],"properties":{"url":{"minLength":1,"maxLength":4096,"type":"string"},"expectedStatus":{"minItems":1,"uniqueItems":true,"type":"array","items":{"minimum":100,"maximum":599,"type":"integer"}},"followRedirects":{"type":"boolean"}}}}}},"resultSchema":{"anyOf":[{"additionalProperties":false,"type":"object","required":["pass"],"properties":{"pass":{"const":true,"type":"boolean"}}},{"additionalProperties":false,"type":"object","required":["pass","problems"],"properties":{"pass":{"const":false,"type":"boolean"},"problems":{"minItems":1,"type":"array","items":{"additionalProperties":false,"type":"object","required":["target","code","actual"],"properties":{"target":{"minLength":1,"maxLength":4096,"type":"string"},"code":{"anyOf":[{"const":"dns-unavailable","type":"string"},{"const":"http-status","type":"string"},{"const":"http-unavailable","type":"string"}]},"actual":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}}]},"messageSchema":{"not":{}},"include":["resources/check.json","resources/references/en/check.md","resources/references/en/problems/dns-unavailable.md","resources/references/en/problems/http-status.md","resources/references/en/problems/http-unavailable.md","schemas/0.json","schemas/1.json","schemas/2.json","task.yaml","worker.cjs"]}')};var Z=class{capacity;queue=[];waiter;closed=!1;constructor(n){this.capacity=n}push(n){if(this.closed||this.queue.length>=this.capacity)throw new Error("Task inbox unavailable.");this.waiter?(this.waiter({done:!1,value:n}),this.waiter=void 0):this.queue.push(n)}close(){this.closed=!0,this.queue=[],this.waiter?.({done:!0,value:void 0}),this.waiter=void 0}[Symbol.asyncIterator](){return{next:()=>{let n=this.queue.shift();return n?Promise.resolve({done:!1,value:n}):this.closed?Promise.resolve({done:!0,value:void 0}):this.waiter?Promise.reject(new Error("Task inbox has one consumer.")):new Promise(i=>{this.waiter=i})}}}};function ee(o){if(!H)throw new Error("Task SDK requires a build-locked Bundle binding.");let{declaration:n}=H,i=D.parentPort;if(!i||n.$schema!==B)throw new Error("Unsupported Task Worker.");let r=D.workerData;if(typeof r.generation!="string"||!r.generation||!Number.isSafeInteger(r.maxInFlight)||r.maxInFlight<=0||!Number.isSafeInteger(r.maxPayloadBytes)||r.maxPayloadBytes<=0||typeof r.bundle?.cid!="string"||!r.bundle.cid||r.bundle.cid.length>256)throw new Error("Invalid trusted Task Worker configuration.");if(!r.bundle||q(R(r.bundle.declaration,1048576))!==q(R(n,1048576)))throw new Error("Task Worker declaration differs from verified Bundle.");let a=new AbortController,u=new Z(r.maxInFlight),s=new Map,c=new Map,b=0,f,m=!1,x=0,S=!1,w=Promise.resolve(),y,j=0,E=new Map;function N(t,h={}){let l=++j,e=h.signal?AbortSignal.any([a.signal,h.signal]):a.signal,d=()=>{},k=()=>{d(),E.get(l)?.reject(new DOMException("Bundle read canceled.","AbortError")),E.delete(l),i.postMessage({generation:r.generation,runId:f,kind:"bundle-cancel",readId:l})};return new ReadableStream({start(I){let p=()=>{k(),I.error(e.reason)};if(d=()=>e.removeEventListener("abort",p),e.aborted){I.error(e.reason);return}e.addEventListener("abort",p,{once:!0})},async pull(I){try{if(m)throw new g("run_finished","Bundle stream is closed.");e.throwIfAborted();let p=await new Promise((A,ie)=>{E.set(l,{resolve:A,reject:ie}),i.postMessage({generation:r.generation,runId:f,kind:"bundle-pull",readId:l,path:t})});if(p.done)d(),I.close();else if(p.chunk instanceof Uint8Array)I.enqueue(p.chunk);else throw new g("invalid_bundle","Invalid Bundle stream chunk.")}catch(p){k(),I.error(p)}},cancel:k},{highWaterMark:0})}let M=0,_=new Map,O=0,$=0,F=!1,P=!1,W=!1,C;function ae(){if(C||P||m||a.signal.aborted||O<=$)return;let t=++M,h=O,l=setTimeout(()=>{P=!0},1e3);C={id:t,count:h,timer:l};try{i.postMessage({generation:r.generation,runId:f,kind:"log-drop",logId:t,count:h})}catch{clearTimeout(l),C=void 0,P=!0}}function G(){F||C||P||m||a.signal.aborted||(F=!0,queueMicrotask(()=>{F=!1,ae()}))}function X(){if(!(W||O<=$)){W=!0;try{i.postMessage({generation:r.generation,runId:f,kind:"log-drop",logId:++M,count:O,final:!0})}catch{}}}function U(){C&&clearTimeout(C.timer),C=void 0,P=!0;for(let t of _.values())clearTimeout(t.timer),t.resolve({state:"unavailable",reason:"channel"});_.clear()}async function se(t){if(m||a.signal.aborted)return{state:"unavailable",reason:"channel"};if(_.size>=Math.min(r.maxInFlight,16))return O=Math.min(Number.MAX_SAFE_INTEGER,O+1),G(),{state:"dropped",reason:"capacity"};let h=M+1;return new Promise((l,e)=>{let d=setTimeout(()=>{_.delete(h),l({state:"unavailable",reason:"timeout"})},1e3);_.set(h,{resolve:l,reject:e,timer:d});try{i.postMessage({generation:r.generation,runId:f,kind:"log",logId:h,value:t}),M=h}catch(k){clearTimeout(d),_.delete(h),k instanceof Error&&k.name==="DataCloneError"?e(new g("invalid_payload","Task payload cannot be cloned for IPC.")):l({state:"unavailable",reason:"channel"})}})}function L(t,h){if(c.size>=r.maxInFlight)return Promise.reject(new Error("Task channel capacity exceeded."));let l=b+1,e=new Promise((d,k)=>{c.set(l,{resolve:d,reject:k})});try{i.postMessage({generation:r.generation,runId:f,id:l,kind:t,value:h}),b=l}catch(d){c.get(l)?.reject(d instanceof Error&&d.name==="DataCloneError"?new g("invalid_payload","Task payload cannot be cloned for IPC."):d instanceof Error?d:new Error("Task send failed.")),c.delete(l)}return e}function J(t,h){if(m)return Promise.reject(new g("run_finished","Task is finishing."));if(x>=r.maxInFlight)return Promise.reject(new Error("Task channel capacity exceeded."));x++;let l=w.then(()=>L(t,h)).catch(e=>{throw y??=e,e}).finally(()=>{x--});return w=l,l.catch(()=>{}),l}i.postMessage({generation:r.generation,kind:"ready",value:{$schema:n.$schema,cid:r.bundle.cid,inputSchema:n.inputSchema,resultSchema:n.resultSchema,messageSchema:n.messageSchema}}),i.on("message",t=>{if(!t||t.generation!==r.generation)return;if(t.kind==="bundle-data"){let e=E.get(t.readId);if(!e)return;E.delete(t.readId),t.error?e.reject(new g(t.error.code,t.error.message)):e.resolve(t);return}if(t.kind==="log-drop-ack"){if(t.runId!==f||!C||t.logId!==C.id)return;let e=C;clearTimeout(e.timer),C=void 0,t.error||t.value?.state==="unavailable"?P=!0:($=e.count,P=!1,G());return}if(t.kind==="log-ack"){if(t.runId!==f)return;let e=_.get(t.logId);if(!e)return;_.delete(t.logId),clearTimeout(e.timer),t.error?e.reject(new g(t.error.code,t.error.message)):e.resolve(t.value);return}if(t.kind==="ack"){let e=c.get(t.id);if(!e)return;c.delete(t.id),t.error?e.reject(new g(t.error.code,t.error.message)):e.resolve();return}if(t.kind==="ping"){i.postMessage({generation:r.generation,kind:"pong"});return}if(t.runId!==f&&t.kind!=="run")return;if(t.kind==="cancel"){i.postMessage({generation:r.generation,runId:f,kind:"stopping"}),a.abort(),U(),u.close();for(let e of s.values())e.abort();return}if(t.kind==="withdraw"){let e=s.get(t.taskId)??new AbortController;s.set(t.taskId,e),e.abort();return}if(t.kind==="message"){let e=t.value,d=s.get(e.taskId)??new AbortController;s.set(e.taskId,d);let k=!1,I=(p,A)=>k||d.signal.aborted?Promise.reject(new Error("Message unavailable.")):(k=!0,J("message-confirm",{taskId:e.taskId,messageId:e.messageId,state:p,...A===void 0?{}:{reason:A}}));u.push(Object.freeze({messageId:e.messageId,taskId:e.taskId,caller:Object.freeze(e.caller),signal:d.signal,payload:e.payload,accept:()=>I("accepted"),reject:p=>I("rejected",p)}));return}if(t.kind!=="run"||f!==void 0)return;f=t.runId;let h=Object.freeze({runId:t.runId,...t.identity?{generation:t.identity.generation,startedAt:t.identity.startedAt}:{},scope:t.scope,signal:a.signal,messages:u,bundle:Object.freeze({read:N}),progress:e=>J("progress",e),checkpoint:e=>J("checkpoint",e),log:se}),l=async e=>{let d=e;S||=d instanceof g&&["reclamation_failed","reclamation_unknown"].includes(d.code);let k=d instanceof v?d.result:void 0,I=(p,A)=>({code:p instanceof g?p.code.slice(0,128):"run_failed",message:p instanceof Error?p.message.slice(0,512):"Task callback failed.",...A===void 0?{}:{result:A}});try{await L("failed",I(d,k))}catch(p){await L("failed",I(p))}};(async()=>{try{let e=await o(t.input,h);if(m=!0,X(),await w,y!==void 0)throw y;await L("complete",e)}catch(e){m=!0,X(),await w.catch(()=>{}),S||=e instanceof g&&["reclamation_failed","reclamation_unknown"].includes(e.code);let d=y??e;if(a.signal.aborted&&d instanceof Error&&(d.name==="AbortError"||d instanceof g&&["ABORT_ERR","run_canceled"].includes(d.code)))return;await l(d)}})().then(()=>{u.close(),a.abort(),U();for(let e of s.values())e.abort();i.postMessage({generation:r.generation,runId:f,kind:S?"uncertain":"released"}),i.close()},()=>{u.close(),a.abort(),U();for(let e of s.values())e.abort();i.postMessage({generation:r.generation,runId:f,kind:"uncertain"}),i.close()})})}var K=Object.freeze(["dns-unavailable","http-status","http-unavailable"]);var z=require("node:child_process");function te(o){return o.filter(n=>!n.ok).map(({target:n,code:i,actual:r})=>{if(i==="pass")throw new Error("A failing check requires a problem code.");return{target:n,code:i,actual:r}})}function V(o){return o instanceof Error&&"code"in o&&typeof o.code=="string"?o.code:void 0}function re(o){let n=o??5e3;if(!Number.isSafeInteger(n)||n<100||n>3e5)throw new Error("checkTimeoutMs must be an integer between 100 and 300000.");return n}async function de(o){if(process.platform!=="win32"){try{process.kill(-o,"SIGKILL")}catch(n){if(V(n)!=="ESRCH")throw n}return}await new Promise((n,i)=>{(0,z.execFile)("taskkill",["/PID",String(o),"/T","/F"],{timeout:5e3},r=>{r?i(r):n()})})}async function ne(o,n,i,r){if(r?.throwIfAborted(),!o||o.includes("\0")||/[\r\n]/.test(o)||n.some(a=>a.includes("\0")))throw new Error("Invalid command or arguments.");if(process.platform==="win32"&&/\.(cmd|bat)$/i.test(o))throw new Error("Use a native executable or node with an absolute CLI JavaScript entry.");return new Promise((a,u)=>{let s=(0,z.spawn)(o,n,{shell:!1,detached:process.platform!=="win32",windowsHide:!0,stdio:["ignore","pipe","pipe"]}),c="",b="",f=0,m,x,S=j=>{m||(m=j,s.pid!==void 0&&(x=de(s.pid),x.catch(E=>{m=new Error("Command process tree cleanup failed.",{cause:E})})))},w=setTimeout(()=>S(new Error("Command timed out.")),i),y=()=>S(new Error("Command cancelled.",{cause:r?.reason}));r?.addEventListener("abort",y,{once:!0}),r?.aborted&&y();for(let[j,E]of[[s.stdout,"stdout"],[s.stderr,"stderr"]])j.on("data",N=>{if(f+=N.length,f>262144){S(new Error("Command output exceeded 262144 bytes."));return}E==="stdout"?c+=N.toString():b+=N.toString()});s.once("error",j=>{clearTimeout(w),r?.removeEventListener("abort",y),m?u(m):V(j)==="ENOENT"?a({code:127,stdout:"",stderr:"",missing:!0}):u(j)}),s.once("close",async j=>{if(clearTimeout(w),r?.removeEventListener("abort",y),x)try{await x}catch(E){u(new Error("Command process tree cleanup failed.",{cause:E}));return}m?u(m):a({code:j,stdout:c,stderr:b,missing:!1})})})}async function oe(o,n={}){if(!o.dns.length&&!o.http.length||o.dns.length>100||o.http.length>100)throw new Error("Specify DNS or HTTP checks, with at most 100 of each.");let i=re(o.checkTimeoutMs);for(let a of o.dns)if(!/^[A-Za-z0-9][A-Za-z0-9.-]{0,252}$/.test(a))throw new Error("Invalid DNS name.");for(let a of o.http){let u=new URL(a.url);if(!["http:","https:"].includes(u.protocol)||u.username||u.password||!a.expectedStatus.length||a.expectedStatus.some(s=>!Number.isInteger(s)||s<100||s>599))throw new Error("HTTP checks require HTTP(S) URLs without credentials and valid status codes.")}let r=[];for(let a of o.dns){let s=await ne(process.execPath,["--input-type=module","-e","import{lookup}from'node:dns/promises';try{const r=await lookup(process.argv[1]);console.log(JSON.stringify({ok:true,actual:r.address}));}catch(e){if(!['ENOTFOUND','EAI_AGAIN','EAI_FAIL','ETIMEOUT'].includes(e.code))throw e;console.log(JSON.stringify({ok:false,actual:e.code}));}",a],i,n.signal);if(s.code!==0)throw new Error(`DNS check process failed: ${s.stderr}`);let c=JSON.parse(s.stdout);r.push({target:a,ok:c.ok,code:c.ok?"pass":"dns-unavailable",actual:c.actual})}for(let a of o.http){n.signal?.throwIfAborted();let u=AbortSignal.any([AbortSignal.timeout(i),...n.signal?[n.signal]:[]]),s;try{let c=await fetch(a.url,{redirect:a.followRedirects?"follow":"manual",signal:u});try{let b=a.expectedStatus.includes(c.status)&&(a.followRedirects||c.status<300||c.status>=400);s={target:a.url,ok:b,code:b?"pass":"http-status",actual:String(c.status)}}finally{await c.body?.cancel()}}catch(c){if(n.signal?.throwIfAborted(),c instanceof Error&&c.name==="TimeoutError")throw new Error("HTTP check timed out.",{cause:c});if(!(c instanceof TypeError))throw c;s={target:a.url,ok:!1,code:"http-unavailable",actual:c.message}}r.push(s)}return te(r)}var le=Y(K,oe);ee(le);

package/dist/bundles/references.json

@@ -0,0 +1,17 @@
+{
+  "tools": {
+    "directory": "tools",
+    "car": "tools.car",
+    "cid": "bafybeieqcbsrb4xfnstoc5fmlhhjefyylpgruk4nfgk36kcuxf2mj6xota"
+  },
+  "directories": {
+    "directory": "directories",
+    "car": "directories.car",
+    "cid": "bafybeihyo3ujmjh7jgtlfwmi6inowbcub4xdi2amj2m23rbv7ik3mzhdbi"
+  },
+  "network": {
+    "directory": "network",
+    "car": "network.car",
+    "cid": "bafybeigpnzao2lgpmx2ajfdu4w6uzzd3ovo7rf6gfrdv4dyuwwwepr6oca"
+  }
+}

package/dist/bundles/tools/resources/check.json

@@ -0,0 +1,23 @@
+{
+  "kind": "tools",
+  "languages": [
+    "en"
+  ],
+  "problemCodes": [
+    "tool-missing",
+    "tool-unusable",
+    "version-unparseable",
+    "tool-version"
+  ],
+  "references": {
+    "en": {
+      "check": "resources/references/en/check.md",
+      "problems": {
+        "tool-missing": "resources/references/en/problems/tool-missing.md",
+        "tool-unusable": "resources/references/en/problems/tool-unusable.md",
+        "version-unparseable": "resources/references/en/problems/version-unparseable.md",
+        "tool-version": "resources/references/en/problems/tool-version.md"
+      }
+    }
+  }
+}

package/dist/bundles/tools/resources/references/en/check.md

@@ -0,0 +1,21 @@
+---
+title: Tool versions
+description: Check explicit commands and minimum numeric versions without installing or repairing tools.
+---
+
+# Tool versions
+
+Input `tools` lists `command`, `args` and `minimumVersion`; optional
+`checkTimeoutMs` defaults to 5000 (100–300000). Commands run without a shell.
+The host must allow subprocess creation. Versions are dot-separated decimal
+numbers, compared numerically; the first recognizable output version is used.
+The result is `{pass:true}` or only failing `target`, `code`, `actual` entries.
+`target` is the command and `actual` is the parsed version or null.
+
+Problems: [missing](problems/tool-missing.md),
+[unusable](problems/tool-unusable.md),
+[unparseable](problems/version-unparseable.md),
+[too old](problems/tool-version.md).
+Timeout, output overflow, unexpected launch errors and cleanup failures are
+execution faults, not problems. Cancellation propagates after physical process
+cleanup. No installation or repair is performed.

package/dist/bundles/tools/resources/references/en/problems/tool-missing.md

@@ -0,0 +1,8 @@
+---
+title: Tool missing
+description: The explicitly requested command could not be found.
+---
+
+`target` is the command; `actual` is a parsed version if any, otherwise null.
+Check the executable path and PATH in the Engine host. Install or configure the
+tool separately; this check does not repair it. See [tool checks](../check.md).

package/dist/bundles/tools/resources/references/en/problems/tool-unusable.md

@@ -0,0 +1,9 @@
+---
+title: Tool unusable
+description: The command ran but exited unsuccessfully.
+---
+
+`target` is the command; `actual` is a parsed version if output contained one,
+otherwise null. Run the same arguments on the host and inspect its permissions
+and configuration. This differs from an execution fault such as a timeout.
+See [tool checks](../check.md).

package/dist/bundles/tools/resources/references/en/problems/tool-version.md

@@ -0,0 +1,8 @@
+---
+title: Tool version too old
+description: The parsed tool version is below the requested minimum version.
+---
+
+`target` is the command; `actual` is its parsed numeric version. Compare the
+requested minimum, select a suitable executable or upgrade separately.
+The check performs no upgrade. See [tool checks](../check.md).

package/dist/bundles/tools/resources/references/en/problems/version-unparseable.md

@@ -0,0 +1,8 @@
+---
+title: Version unparseable
+description: Successful command output did not contain a recognizable dotted numeric version.
+---
+
+`target` is the command; `actual` is null. Check the version arguments and output
+format. This parser recognizes a dotted numeric version, optionally prefixed by
+`v`, not arbitrary vendor version formats. See [tool checks](../check.md).

package/dist/bundles/tools/schemas/0.json

@@ -0,0 +1,50 @@
+{
+  "additionalProperties": false,
+  "type": "object",
+  "required": [
+    "tools"
+  ],
+  "properties": {
+    "checkTimeoutMs": {
+      "minimum": 100,
+      "maximum": 300000,
+      "type": "integer"
+    },
+    "tools": {
+      "minItems": 1,
+      "maxItems": 100,
+      "type": "array",
+      "items": {
+        "additionalProperties": false,
+        "type": "object",
+        "required": [
+          "command",
+          "args",
+          "minimumVersion"
+        ],
+        "properties": {
+          "command": {
+            "minLength": 1,
+            "maxLength": 4096,
+            "type": "string"
+          },
+          "args": {
+            "maxItems": 100,
+            "type": "array",
+            "items": {
+              "minLength": 1,
+              "maxLength": 4096,
+              "type": "string"
+            }
+          },
+          "minimumVersion": {
+            "maxLength": 128,
+            "pattern": "^\\d+(?:\\.\\d+)*$",
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "$id": "https://task.invalid/schema/input"
+}

package/dist/bundles/tools/schemas/1.json

@@ -0,0 +1,82 @@
+{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "pass"
+      ],
+      "properties": {
+        "pass": {
+          "const": true,
+          "type": "boolean"
+        }
+      }
+    },
+    {
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "pass",
+        "problems"
+      ],
+      "properties": {
+        "pass": {
+          "const": false,
+          "type": "boolean"
+        },
+        "problems": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "additionalProperties": false,
+            "type": "object",
+            "required": [
+              "target",
+              "code",
+              "actual"
+            ],
+            "properties": {
+              "target": {
+                "minLength": 1,
+                "maxLength": 4096,
+                "type": "string"
+              },
+              "code": {
+                "anyOf": [
+                  {
+                    "const": "tool-missing",
+                    "type": "string"
+                  },
+                  {
+                    "const": "tool-unusable",
+                    "type": "string"
+                  },
+                  {
+                    "const": "version-unparseable",
+                    "type": "string"
+                  },
+                  {
+                    "const": "tool-version",
+                    "type": "string"
+                  }
+                ]
+              },
+              "actual": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$id": "https://task.invalid/schema/result"
+}

package/dist/bundles/tools/schemas/2.json

@@ -0,0 +1,4 @@
+{
+  "not": {},
+  "$id": "https://task.invalid/schema/message"
+}

package/dist/bundles/tools/task.yaml

@@ -0,0 +1,24 @@
+$schema: https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json
+name: Environment tools check
+runtime:
+  type: node
+  minVersion: 22.13.0
+entry: worker.cjs
+inputSchema:
+  $ref: schemas/0.json
+resultSchema:
+  $ref: schemas/1.json
+messageSchema:
+  $ref: schemas/2.json
+include:
+  - resources/check.json
+  - resources/references/en/check.md
+  - resources/references/en/problems/tool-missing.md
+  - resources/references/en/problems/tool-unusable.md
+  - resources/references/en/problems/tool-version.md
+  - resources/references/en/problems/version-unparseable.md
+  - schemas/0.json
+  - schemas/1.json
+  - schemas/2.json
+  - task.yaml
+  - worker.cjs

package/dist/bundles/tools/worker.cjs

@@ -0,0 +1,2 @@
+const __artifactURL = require("node:url").pathToFileURL(__filename).href;
+"use strict";function Q(o){if(new Set(o).size!==o.length||o.some(n=>!/^[a-z][a-z0-9-]*$/.test(n)||n.length>4096))throw new Error("Check problem codes must be unique stable names of at most 4096 characters.")}function de(o,n){Q(o);let i=new Set(o),t=n.map(s=>{if(!i.has(s.code))throw new Error(`Undeclared Check problem code: ${s.code}`);if(typeof s.target!="string"||!s.target.length||[...s.target].length>4096||s.actual!==null&&typeof s.actual!="string"||Object.keys(s).some(d=>!["target","code","actual"].includes(d)))throw new Error("Invalid Check problem.");return{target:s.target,code:s.code,actual:s.actual}});return t.length?{pass:!1,problems:t}:{pass:!0}}function Y(o,n){return async(i,t)=>{t.signal.throwIfAborted();let s=await n(i,t);return t.signal.throwIfAborted(),de(o,s)}}var $=require("node:worker_threads");var p=class extends Error{code;details;constructor(n,i,t){super(i),this.code=n,this.details=t,this.name="TaskError"}};function T(o,n){throw new p(o,n)}function v(o,n=65536){let i=new Set,t=0;function s(a,h){if((++t>n||h>64)&&T("invalid_payload","JSON structure exceeds limit."),a===null||typeof a=="string"||typeof a=="boolean"||typeof a=="number"&&Number.isFinite(a))return a;(typeof a!="object"||a===null)&&T("invalid_payload","Only finite JSON values are accepted."),i.has(a)&&T("invalid_payload","Cyclic JSON is not accepted.");let x=Array.isArray(a);Object.getPrototypeOf(a)!==(x?Array.prototype:Object.prototype)&&T("invalid_payload","Custom prototypes are not accepted."),i.add(a);let u=Object.getOwnPropertyDescriptors(a),m=Reflect.ownKeys(u),I={},C=[];x&&m.length!==a.length+1&&T("invalid_payload","Sparse or decorated arrays are not accepted.");for(let y of m){typeof y!="string"&&T("invalid_payload","Symbol keys are not accepted.");let b=u[y];(!b||!("value"in b))&&T("invalid_payload","Accessors are not accepted."),!(x&&y==="length")&&(b.enumerable||T("invalid_payload","Hidden properties are not accepted."),x?(y!==String(C.length)&&T("invalid_payload","Invalid array keys."),C.push(s(b.value,h+1))):Object.defineProperty(I,y,{value:s(b.value,h+1),enumerable:!0,writable:!0,configurable:!0}))}return i.delete(a),x?C:I}let d=s(o,0);return new TextEncoder().encode(JSON.stringify(d)).byteLength>n&&T("payload_too_large","JSON payload exceeds byte limit."),d}function q(o){return Array.isArray(o)?`[${o.map(q).join(",")}]`:o&&typeof o=="object"?`{${Object.keys(o).sort().map(n=>`${JSON.stringify(n)}:${q(o[n]??null)}`).join(",")}}`:JSON.stringify(o)}var R=class extends p{result;constructor(n,i,t){super(n,i),this.result=t}};var U="https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json";var B={declaration:JSON.parse('{"$schema":"https://shazhou-ww.github.io/potential-guide/schemas/artifacts/task/v1.json","name":"Environment tools check","runtime":{"type":"node","minVersion":"22.13.0"},"entry":"worker.cjs","inputSchema":{"additionalProperties":false,"type":"object","required":["tools"],"properties":{"checkTimeoutMs":{"minimum":100,"maximum":300000,"type":"integer"},"tools":{"minItems":1,"maxItems":100,"type":"array","items":{"additionalProperties":false,"type":"object","required":["command","args","minimumVersion"],"properties":{"command":{"minLength":1,"maxLength":4096,"type":"string"},"args":{"maxItems":100,"type":"array","items":{"minLength":1,"maxLength":4096,"type":"string"}},"minimumVersion":{"maxLength":128,"pattern":"^\\\\d+(?:\\\\.\\\\d+)*$","type":"string"}}}}}},"resultSchema":{"anyOf":[{"additionalProperties":false,"type":"object","required":["pass"],"properties":{"pass":{"const":true,"type":"boolean"}}},{"additionalProperties":false,"type":"object","required":["pass","problems"],"properties":{"pass":{"const":false,"type":"boolean"},"problems":{"minItems":1,"type":"array","items":{"additionalProperties":false,"type":"object","required":["target","code","actual"],"properties":{"target":{"minLength":1,"maxLength":4096,"type":"string"},"code":{"anyOf":[{"const":"tool-missing","type":"string"},{"const":"tool-unusable","type":"string"},{"const":"version-unparseable","type":"string"},{"const":"tool-version","type":"string"}]},"actual":{"anyOf":[{"type":"string"},{"type":"null"}]}}}}}}]},"messageSchema":{"not":{}},"include":["resources/check.json","resources/references/en/check.md","resources/references/en/problems/tool-missing.md","resources/references/en/problems/tool-unusable.md","resources/references/en/problems/tool-version.md","resources/references/en/problems/version-unparseable.md","schemas/0.json","schemas/1.json","schemas/2.json","task.yaml","worker.cjs"]}')};var H=class{capacity;queue=[];waiter;closed=!1;constructor(n){this.capacity=n}push(n){if(this.closed||this.queue.length>=this.capacity)throw new Error("Task inbox unavailable.");this.waiter?(this.waiter({done:!1,value:n}),this.waiter=void 0):this.queue.push(n)}close(){this.closed=!0,this.queue=[],this.waiter?.({done:!0,value:void 0}),this.waiter=void 0}[Symbol.asyncIterator](){return{next:()=>{let n=this.queue.shift();return n?Promise.resolve({done:!1,value:n}):this.closed?Promise.resolve({done:!0,value:void 0}):this.waiter?Promise.reject(new Error("Task inbox has one consumer.")):new Promise(i=>{this.waiter=i})}}}};function ee(o){if(!B)throw new Error("Task SDK requires a build-locked Bundle binding.");let{declaration:n}=B,i=$.parentPort;if(!i||n.$schema!==U)throw new Error("Unsupported Task Worker.");let t=$.workerData;if(typeof t.generation!="string"||!t.generation||!Number.isSafeInteger(t.maxInFlight)||t.maxInFlight<=0||!Number.isSafeInteger(t.maxPayloadBytes)||t.maxPayloadBytes<=0||typeof t.bundle?.cid!="string"||!t.bundle.cid||t.bundle.cid.length>256)throw new Error("Invalid trusted Task Worker configuration.");if(!t.bundle||q(v(t.bundle.declaration,1048576))!==q(v(n,1048576)))throw new Error("Task Worker declaration differs from verified Bundle.");let s=new AbortController,d=new H(t.maxInFlight),a=new Map,h=new Map,x=0,u,m=!1,I=0,C=!1,y=Promise.resolve(),b,j=0,E=new Map;function M(r,g={}){let l=++j,e=g.signal?AbortSignal.any([s.signal,g.signal]):s.signal,c=()=>{},w=()=>{c(),E.get(l)?.reject(new DOMException("Bundle read canceled.","AbortError")),E.delete(l),i.postMessage({generation:t.generation,runId:u,kind:"bundle-cancel",readId:l})};return new ReadableStream({start(k){let f=()=>{w(),k.error(e.reason)};if(c=()=>e.removeEventListener("abort",f),e.aborted){k.error(e.reason);return}e.addEventListener("abort",f,{once:!0})},async pull(k){try{if(m)throw new p("run_finished","Bundle stream is closed.");e.throwIfAborted();let f=await new Promise((O,ce)=>{E.set(l,{resolve:O,reject:ce}),i.postMessage({generation:t.generation,runId:u,kind:"bundle-pull",readId:l,path:r})});if(f.done)c(),k.close();else if(f.chunk instanceof Uint8Array)k.enqueue(f.chunk);else throw new p("invalid_bundle","Invalid Bundle stream chunk.")}catch(f){w(),k.error(f)}},cancel:w},{highWaterMark:0})}let L=0,_=new Map,A=0,z=0,F=!1,P=!1,G=!1,S;function ie(){if(S||P||m||s.signal.aborted||A<=z)return;let r=++L,g=A,l=setTimeout(()=>{P=!0},1e3);S={id:r,count:g,timer:l};try{i.postMessage({generation:t.generation,runId:u,kind:"log-drop",logId:r,count:g})}catch{clearTimeout(l),S=void 0,P=!0}}function Z(){F||S||P||m||s.signal.aborted||(F=!0,queueMicrotask(()=>{F=!1,ie()}))}function X(){if(!(G||A<=z)){G=!0;try{i.postMessage({generation:t.generation,runId:u,kind:"log-drop",logId:++L,count:A,final:!0})}catch{}}}function V(){S&&clearTimeout(S.timer),S=void 0,P=!0;for(let r of _.values())clearTimeout(r.timer),r.resolve({state:"unavailable",reason:"channel"});_.clear()}async function ae(r){if(m||s.signal.aborted)return{state:"unavailable",reason:"channel"};if(_.size>=Math.min(t.maxInFlight,16))return A=Math.min(Number.MAX_SAFE_INTEGER,A+1),Z(),{state:"dropped",reason:"capacity"};let g=L+1;return new Promise((l,e)=>{let c=setTimeout(()=>{_.delete(g),l({state:"unavailable",reason:"timeout"})},1e3);_.set(g,{resolve:l,reject:e,timer:c});try{i.postMessage({generation:t.generation,runId:u,kind:"log",logId:g,value:r}),L=g}catch(w){clearTimeout(c),_.delete(g),w instanceof Error&&w.name==="DataCloneError"?e(new p("invalid_payload","Task payload cannot be cloned for IPC.")):l({state:"unavailable",reason:"channel"})}})}function N(r,g){if(h.size>=t.maxInFlight)return Promise.reject(new Error("Task channel capacity exceeded."));let l=x+1,e=new Promise((c,w)=>{h.set(l,{resolve:c,reject:w})});try{i.postMessage({generation:t.generation,runId:u,id:l,kind:r,value:g}),x=l}catch(c){h.get(l)?.reject(c instanceof Error&&c.name==="DataCloneError"?new p("invalid_payload","Task payload cannot be cloned for IPC."):c instanceof Error?c:new Error("Task send failed.")),h.delete(l)}return e}function J(r,g){if(m)return Promise.reject(new p("run_finished","Task is finishing."));if(I>=t.maxInFlight)return Promise.reject(new Error("Task channel capacity exceeded."));I++;let l=y.then(()=>N(r,g)).catch(e=>{throw b??=e,e}).finally(()=>{I--});return y=l,l.catch(()=>{}),l}i.postMessage({generation:t.generation,kind:"ready",value:{$schema:n.$schema,cid:t.bundle.cid,inputSchema:n.inputSchema,resultSchema:n.resultSchema,messageSchema:n.messageSchema}}),i.on("message",r=>{if(!r||r.generation!==t.generation)return;if(r.kind==="bundle-data"){let e=E.get(r.readId);if(!e)return;E.delete(r.readId),r.error?e.reject(new p(r.error.code,r.error.message)):e.resolve(r);return}if(r.kind==="log-drop-ack"){if(r.runId!==u||!S||r.logId!==S.id)return;let e=S;clearTimeout(e.timer),S=void 0,r.error||r.value?.state==="unavailable"?P=!0:(z=e.count,P=!1,Z());return}if(r.kind==="log-ack"){if(r.runId!==u)return;let e=_.get(r.logId);if(!e)return;_.delete(r.logId),clearTimeout(e.timer),r.error?e.reject(new p(r.error.code,r.error.message)):e.resolve(r.value);return}if(r.kind==="ack"){let e=h.get(r.id);if(!e)return;h.delete(r.id),r.error?e.reject(new p(r.error.code,r.error.message)):e.resolve();return}if(r.kind==="ping"){i.postMessage({generation:t.generation,kind:"pong"});return}if(r.runId!==u&&r.kind!=="run")return;if(r.kind==="cancel"){i.postMessage({generation:t.generation,runId:u,kind:"stopping"}),s.abort(),V(),d.close();for(let e of a.values())e.abort();return}if(r.kind==="withdraw"){let e=a.get(r.taskId)??new AbortController;a.set(r.taskId,e),e.abort();return}if(r.kind==="message"){let e=r.value,c=a.get(e.taskId)??new AbortController;a.set(e.taskId,c);let w=!1,k=(f,O)=>w||c.signal.aborted?Promise.reject(new Error("Message unavailable.")):(w=!0,J("message-confirm",{taskId:e.taskId,messageId:e.messageId,state:f,...O===void 0?{}:{reason:O}}));d.push(Object.freeze({messageId:e.messageId,taskId:e.taskId,caller:Object.freeze(e.caller),signal:c.signal,payload:e.payload,accept:()=>k("accepted"),reject:f=>k("rejected",f)}));return}if(r.kind!=="run"||u!==void 0)return;u=r.runId;let g=Object.freeze({runId:r.runId,...r.identity?{generation:r.identity.generation,startedAt:r.identity.startedAt}:{},scope:r.scope,signal:s.signal,messages:d,bundle:Object.freeze({read:M}),progress:e=>J("progress",e),checkpoint:e=>J("checkpoint",e),log:ae}),l=async e=>{let c=e;C||=c instanceof p&&["reclamation_failed","reclamation_unknown"].includes(c.code);let w=c instanceof R?c.result:void 0,k=(f,O)=>({code:f instanceof p?f.code.slice(0,128):"run_failed",message:f instanceof Error?f.message.slice(0,512):"Task callback failed.",...O===void 0?{}:{result:O}});try{await N("failed",k(c,w))}catch(f){await N("failed",k(f))}};(async()=>{try{let e=await o(r.input,g);if(m=!0,X(),await y,b!==void 0)throw b;await N("complete",e)}catch(e){m=!0,X(),await y.catch(()=>{}),C||=e instanceof p&&["reclamation_failed","reclamation_unknown"].includes(e.code);let c=b??e;if(s.signal.aborted&&c instanceof Error&&(c.name==="AbortError"||c instanceof p&&["ABORT_ERR","run_canceled"].includes(c.code)))return;await l(c)}})().then(()=>{d.close(),s.abort(),V();for(let e of a.values())e.abort();i.postMessage({generation:t.generation,runId:u,kind:C?"uncertain":"released"}),i.close()},()=>{d.close(),s.abort(),V();for(let e of a.values())e.abort();i.postMessage({generation:t.generation,runId:u,kind:"uncertain"}),i.close()})})}var K=Object.freeze(["tool-missing","tool-unusable","version-unparseable","tool-version"]);var D=require("node:child_process");function te(o){return o.filter(n=>!n.ok).map(({target:n,code:i,actual:t})=>{if(i==="pass")throw new Error("A failing check requires a problem code.");return{target:n,code:i,actual:t}})}function W(o){return o instanceof Error&&"code"in o&&typeof o.code=="string"?o.code:void 0}function re(o){let n=o??5e3;if(!Number.isSafeInteger(n)||n<100||n>3e5)throw new Error("checkTimeoutMs must be an integer between 100 and 300000.");return n}async function le(o){if(process.platform!=="win32"){try{process.kill(-o,"SIGKILL")}catch(n){if(W(n)!=="ESRCH")throw n}return}await new Promise((n,i)=>{(0,D.execFile)("taskkill",["/PID",String(o),"/T","/F"],{timeout:5e3},t=>{t?i(t):n()})})}async function ne(o,n,i,t){if(t?.throwIfAborted(),!o||o.includes("\0")||/[\r\n]/.test(o)||n.some(s=>s.includes("\0")))throw new Error("Invalid command or arguments.");if(process.platform==="win32"&&/\.(cmd|bat)$/i.test(o))throw new Error("Use a native executable or node with an absolute CLI JavaScript entry.");return new Promise((s,d)=>{let a=(0,D.spawn)(o,n,{shell:!1,detached:process.platform!=="win32",windowsHide:!0,stdio:["ignore","pipe","pipe"]}),h="",x="",u=0,m,I,C=j=>{m||(m=j,a.pid!==void 0&&(I=le(a.pid),I.catch(E=>{m=new Error("Command process tree cleanup failed.",{cause:E})})))},y=setTimeout(()=>C(new Error("Command timed out.")),i),b=()=>C(new Error("Command cancelled.",{cause:t?.reason}));t?.addEventListener("abort",b,{once:!0}),t?.aborted&&b();for(let[j,E]of[[a.stdout,"stdout"],[a.stderr,"stderr"]])j.on("data",M=>{if(u+=M.length,u>262144){C(new Error("Command output exceeded 262144 bytes."));return}E==="stdout"?h+=M.toString():x+=M.toString()});a.once("error",j=>{clearTimeout(y),t?.removeEventListener("abort",b),m?d(m):W(j)==="ENOENT"?s({code:127,stdout:"",stderr:"",missing:!0}):d(j)}),a.once("close",async j=>{if(clearTimeout(y),t?.removeEventListener("abort",b),I)try{await I}catch(E){d(new Error("Command process tree cleanup failed.",{cause:E}));return}m?d(m):s({code:j,stdout:h,stderr:x,missing:!1})})})}function ue(o){return/(?:^|\s)v?(\d+\.\d+(?:\.\d+)*)(?:\b|$)/m.exec(o)?.[1]}function oe(o,n){if(![o,n].every(s=>/^\d+(?:\.\d+)*$/.test(s)))throw new Error("Versions must contain only dot-separated decimal numbers.");let i=o.split(".").map(s=>s.replace(/^0+(?=\d)/,"")),t=n.split(".").map(s=>s.replace(/^0+(?=\d)/,""));for(let s=0;s<Math.max(i.length,t.length);s++){let d=i[s]??"0",a=t[s]??"0";if(d.length!==a.length)return Math.sign(d.length-a.length);if(d!==a)return d>a?1:-1}return 0}async function se(o,n={}){if(!o.tools.length||o.tools.length>100)throw new Error("Specify between 1 and 100 tools.");let i=re(o.checkTimeoutMs);for(let s of o.tools)oe(s.minimumVersion,s.minimumVersion);let t=[];for(let s of o.tools){let d=await ne(s.command,s.args,i,n.signal),a=ue(d.stdout+d.stderr),h=d.missing?"tool-missing":d.code!==0?"tool-unusable":a===void 0?"version-unparseable":oe(a,s.minimumVersion)<0?"tool-version":"pass";t.push({target:s.command,ok:h==="pass",code:h,actual:a??null})}return te(t)}var fe=Y(K,se);ee(fe);

package/dist/command.d.ts

@@ -0,0 +1,8 @@
+export interface CommandResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    missing: boolean;
+}
+export declare function executeCommand(command: string, args: string[], timeoutMs: number, signal?: AbortSignal): Promise<CommandResult>;
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAmBD,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA0ExB"}

package/dist/command.js

@@ -0,0 +1,105 @@
+import { execFile, spawn } from "node:child_process";
+import { errorCode } from "./result.js";
+async function stop(pid) {
+    if (process.platform !== "win32") {
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch (error) {
+            if (errorCode(error) !== "ESRCH")
+                throw error;
+        }
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        execFile("taskkill", ["/PID", String(pid), "/T", "/F"], { timeout: 5000 }, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+export async function executeCommand(command, args, timeoutMs, signal) {
+    signal?.throwIfAborted();
+    if (!command ||
+        command.includes("\0") ||
+        /[\r\n]/.test(command) ||
+        args.some((arg) => arg.includes("\0")))
+        throw new Error("Invalid command or arguments.");
+    if (process.platform === "win32" && /\.(cmd|bat)$/i.test(command))
+        throw new Error("Use a native executable or node with an absolute CLI JavaScript entry.");
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            shell: false,
+            detached: process.platform !== "win32",
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let bytes = 0;
+        let failure;
+        let cleanup;
+        const terminate = (error) => {
+            if (failure)
+                return;
+            failure = error;
+            if (child.pid !== undefined) {
+                cleanup = stop(child.pid);
+                cleanup.catch((error) => {
+                    failure = new Error("Command process tree cleanup failed.", { cause: error });
+                });
+            }
+        };
+        const timer = setTimeout(() => terminate(new Error("Command timed out.")), timeoutMs);
+        const abort = () => terminate(new Error("Command cancelled.", { cause: signal?.reason }));
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        for (const [stream, name] of [
+            [child.stdout, "stdout"],
+            [child.stderr, "stderr"],
+        ]) {
+            stream.on("data", (chunk) => {
+                bytes += chunk.length;
+                if (bytes > 262144) {
+                    terminate(new Error("Command output exceeded 262144 bytes."));
+                    return;
+                }
+                if (name === "stdout")
+                    stdout += chunk.toString();
+                else
+                    stderr += chunk.toString();
+            });
+        }
+        child.once("error", (error) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            if (failure)
+                reject(failure);
+            else if (errorCode(error) === "ENOENT")
+                resolve({ code: 127, stdout: "", stderr: "", missing: true });
+            else
+                reject(error);
+        });
+        child.once("close", async (code) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            if (cleanup) {
+                try {
+                    await cleanup;
+                }
+                catch (error) {
+                    reject(new Error("Command process tree cleanup failed.", { cause: error }));
+                    return;
+                }
+            }
+            if (failure)
+                reject(failure);
+            else
+                resolve({ code, stdout, stderr, missing: false });
+        });
+    });
+}
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"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"}

package/dist/contracts.d.ts

@@ -0,0 +1,36 @@
+export declare const inputSchemas: {
+    tools: import("@sinclair/typebox").TObject<{
+        checkTimeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        tools: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            command: import("@sinclair/typebox").TString;
+            args: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+            minimumVersion: import("@sinclair/typebox").TString;
+        }>>;
+    }>;
+    directories: import("@sinclair/typebox").TObject<{
+        directories: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            path: import("@sinclair/typebox").TString;
+            requirements: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"exists">, import("@sinclair/typebox").TLiteral<"read">, import("@sinclair/typebox").TLiteral<"write">]>>;
+        }>>;
+    }>;
+    network: import("@sinclair/typebox").TObject<{
+        checkTimeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        dns: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+        http: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            url: import("@sinclair/typebox").TString;
+            expectedStatus: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TInteger>;
+            followRedirects: import("@sinclair/typebox").TBoolean;
+        }>>;
+    }>;
+};
+export declare const resultSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+    pass: import("@sinclair/typebox").TLiteral<true>;
+}>, import("@sinclair/typebox").TObject<{
+    pass: import("@sinclair/typebox").TLiteral<false>;
+    problems: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        target: import("@sinclair/typebox").TString;
+        code: import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"not-directory" | "directory-unusable" | "dns-unavailable" | "http-status" | "http-unavailable" | "tool-missing" | "tool-unusable" | "version-unparseable" | "tool-version">[]>;
+        actual: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNull]>;
+    }>>;
+}>]>;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;CAIxB,CAAC;AACF,eAAO,MAAM,YAAY;;;;;;;;;IAAkE,CAAC"}