@pipelex/sdk 0.36.0 → 0.38.0

package/README.md

@@ -216,8 +216,8 @@ These pages ship inside the published package, so a reader who has only installe
 ## Develop
 
 ```bash
-make install    # Install dependencies
-make check      # Lint + format check + typecheck + build + depcruise (alias: make c)
+make install    # Install the dependencies from the lockfile (npm ci, which never rewrites it)
+make check      # Lockfile check + lint + format check + typecheck + build + depcruise (alias: make c)
 make test       # Run the test suite (alias: make t)
 make all        # Clean, check, and test
 ```

package/dist/cli/environment.js

@@ -51,6 +51,7 @@ export function makeClient(io) {
         throw usageError(`${API_KEY_VARIABLE} is not set.`, [
             `Get a key at https://app.pipelex.com and export it: export ${API_KEY_VARIABLE}=<your key>`,
             "This command reads no .env file; to load one into the shell, run: set -a; . ./.env; set +a",
+            'A key saved by pipelex login is in ~/.pipelex/.env, or under PIPELEX_HOME when that is set; to load it, run: set -a; . "${PIPELEX_HOME:-$HOME/.pipelex}/.env"; set +a',
         ]);
     }
     try {

package/dist/cli/environment.js.map

@@ -1 +1 @@
-{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/cli/environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AAErE,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,SAAS,QAAQ,CAAC,EAAa,EAAE,IAAY;IAC3C,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAa;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAC;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,CAAC,GAAG,sBAAsB,0CAA0C,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,EAAa;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAC9C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,UAAU,CAAC,GAAG,gBAAgB,cAAc,EAAE;YAClD,8DAA8D,gBAAgB,aAAa;YAC3F,4FAA4F;SAC7F,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,gBAAgB,CAAC;YAC1B,MAAM;YACN,4FAA4F;YAC5F,0EAA0E;YAC1E,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,oBAAoB;YAC1D,OAAO,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE;SACzD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;YAC1C,MAAM,UAAU,CAAC,GAAG,iBAAiB,cAAc,EAAE,CAAC,WAAW,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACrF,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/cli/environment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AAErE,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,SAAS,QAAQ,CAAC,EAAa,EAAE,IAAY;IAC3C,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAa;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,EAAE,sBAAsB,CAAC,CAAC;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,CAAC,GAAG,sBAAsB,0CAA0C,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,EAAa;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAC9C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,UAAU,CAAC,GAAG,gBAAgB,cAAc,EAAE;YAClD,8DAA8D,gBAAgB,aAAa;YAC3F,4FAA4F;YAC5F,uKAAuK;SACxK,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,gBAAgB,CAAC;YAC1B,MAAM;YACN,4FAA4F;YAC5F,0EAA0E;YAC1E,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,oBAAoB;YAC1D,OAAO,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE;SACzD,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,oBAAoB,EAAE,CAAC;YAC1C,MAAM,UAAU,CAAC,GAAG,iBAAiB,cAAc,EAAE,CAAC,WAAW,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACrF,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/cli/help.d.ts

@@ -1,4 +1,4 @@
 /** The command's help texts, printed on stdout by `--help`. */
-export declare const MAIN_HELP = "pipelex-sdk: run an MTHDS method on the Pipelex API, with nothing to install.\n\nUsage:\n  pipelex-sdk run --method <method> [--pipe <domain.pipe_code>] [--inputs <file> | --inputs-template]\n  pipelex-sdk script --method <address | catalog id> [--pipe <domain.pipe_code>] [--name <name>] [--dir <dir>]\n  pipelex-sdk --version\n  pipelex-sdk <command> --help\n\nCommands:\n  run      Run a method and print its main output as JSON on stdout.\n  script   Write a shell script that runs one method with this SDK's version pinned.\n\nA method is a published address, github.com/<owner>/<repo>[/<package>][@<tag>], a catalog\nid, mt_..., or, for run only, a .mthds file or a bundle directory. A bare catalog id runs the\nmethod's latest published version, mt_...@<version> a fixed version, and mt_...@draft its draft.\n\nThe API key is read from PIPELEX_API_KEY, and the API's address from PIPELEX_BASE_URL\n(https://api.pipelex.com when unset). No .env file is read.\n\nExit codes: 0 done, 1 the run failed or the API refused it, 2 a usage error, 130 interrupted.\n";
+export declare const MAIN_HELP = "pipelex-sdk: run an MTHDS method on the Pipelex API, with nothing to install.\n\nUsage:\n  pipelex-sdk run --method <method> [--pipe <domain.pipe_code>] [--inputs <file> | --inputs-template]\n  pipelex-sdk script --method <address | catalog id> [--pipe <domain.pipe_code>] [--name <name>] [--dir <dir>]\n  pipelex-sdk --version\n  pipelex-sdk <command> --help\n\nCommands:\n  run      Run a method and print its main output as JSON on stdout.\n  script   Write a shell script that runs one method with this SDK's version pinned.\n\nA method is a published address, github.com/<owner>/<repo>[/<package>][@<tag>], a catalog\nid, mt_..., or, for run only, a .mthds file or a bundle directory. A bare catalog id runs the\nmethod's latest published version, mt_...@<version> a fixed version, and mt_...@draft its draft.\n\nThe API key is read from PIPELEX_API_KEY, and the API's address from PIPELEX_BASE_URL\n(https://api.pipelex.com when unset). No .env file is read, not even the one pipelex login\nsaves the key in, ~/.pipelex/.env or the .env under PIPELEX_HOME when that is set. To load it\ninto the shell: set -a; . \"${PIPELEX_HOME:-$HOME/.pipelex}/.env\"; set +a\n\nExit codes: 0 done, 1 the run failed or the API refused it, 2 a usage error, 130 interrupted.\n";
 export declare const RUN_HELP = "Usage: pipelex-sdk run --method <method> [--pipe <domain.pipe_code>] [--inputs <file> | --inputs-template]\n\nRun a method on the Pipelex API, wait for it however long it takes, and print its main\noutput as indented JSON on stdout. The run id, each uploaded file and every error go to\nstderr. Ctrl-C stops waiting; the run keeps going on the server.\n\nOptions:\n  --method <method>          A published address (github.com/<owner>/<repo>[/<package>][@<tag>]),\n                             a catalog id (mt_..., mt_...@<version> or mt_...@draft), or a path\n                             to a .mthds file or a bundle directory.\n  --pipe <domain.pipe_code>  The pipe to run, by its qualified ref. Default: the method's main pipe.\n  --inputs <file>            The inputs, a JSON object with one entry per input; - reads stdin.\n                             A local path or a data: URL at a file input is uploaded first.\n  --inputs-template          Print the inputs template, the object --inputs takes, and run nothing.\n  -h, --help                 Show this help.\n\nNeeds PIPELEX_API_KEY in the environment.\n";
 export declare const SCRIPT_HELP = "Usage: pipelex-sdk script --method <address | catalog id> [--pipe <domain.pipe_code>] [--name <name>] [--dir <dir>]\n\nCheck a method with the API, then write an executable shell script that runs it through\nthis SDK, its version pinned. The script passes its own arguments on to run:\n./<name> --inputs inputs.json, or ./<name> --inputs-template. It never overwrites a file.\n\nOptions:\n  --method <method>          A published address (github.com/<owner>/<repo>[/<package>][@<tag>])\n                             or a catalog id (mt_..., mt_...@<version> or mt_...@draft). A local\n                             bundle is refused.\n  --pipe <domain.pipe_code>  The pipe the script runs. Default: the method's main pipe.\n  --name <name>              The script's file name. Default: the address's last segment, or the\n                             catalog method's name in kebab-case.\n  --dir <dir>                Where to write it. Default: the current directory.\n  -h, --help                 Show this help.\n\nNeeds PIPELEX_API_KEY in the environment. The script needs a POSIX shell.\n";

package/dist/cli/help.js

@@ -16,7 +16,9 @@ id, mt_..., or, for run only, a .mthds file or a bundle directory. A bare catalo
 method's latest published version, mt_...@<version> a fixed version, and mt_...@draft its draft.
 
 The API key is read from PIPELEX_API_KEY, and the API's address from PIPELEX_BASE_URL
-(https://api.pipelex.com when unset). No .env file is read.
+(https://api.pipelex.com when unset). No .env file is read, not even the one pipelex login
+saves the key in, ~/.pipelex/.env or the .env under PIPELEX_HOME when that is set. To load it
+into the shell: set -a; . "\${PIPELEX_HOME:-$HOME/.pipelex}/.env"; set +a
 
 Exit codes: 0 done, 1 the run failed or the API refused it, 2 a usage error, 130 interrupted.
 `;

package/dist/cli/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;CAoBxB,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;CAiBvB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;CAiB1B,CAAC"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBxB,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;CAiBvB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;CAiB1B,CAAC"}

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.36.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.38.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/version.d.ts

@@ -3,4 +3,4 @@
  * `User-Agent` without importing the public barrel. Kept in sync with
  * `package.json` — enforced by `tests/index.test.ts`.
  */
-export declare const SDK_VERSION = "0.36.0";
+export declare const SDK_VERSION = "0.38.0";

package/dist/version.js

@@ -3,5 +3,5 @@
  * `User-Agent` without importing the public barrel. Kept in sync with
  * `package.json` — enforced by `tests/index.test.ts`.
  */
-export const SDK_VERSION = "0.36.0";
+export const SDK_VERSION = "0.38.0";
 //# sourceMappingURL=version.js.map

package/docs/cli.md

@@ -52,9 +52,9 @@ exec npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@X.Y.Z run --met
 
 ## The environment
 
-The key comes from `PIPELEX_API_KEY` and nowhere else, since a flag would put it in the shell's history and the process list; its absence is a usage error that says where to get a key, and the command never prints it. The API's address comes from `PIPELEX_BASE_URL`, `https://api.pipelex.com` when unset; a refused base URL is reported without its credentials, path or query. An empty variable counts as unset, except `PIPELEX_BASE_URL`: an empty base URL is refused like any other the SDK cannot use, since it is most often a variable that was meant to name another API, as in `PIPELEX_BASE_URL=$STAGING_URL` with `STAGING_URL` unset, and counting it as unset would send the key to the default address. Every request carries `pipelex-sdk-cli/<version>` before the SDK's own token in its `User-Agent` ([`client-identification.md`](client-identification.md)).
+The key comes from `PIPELEX_API_KEY` and nowhere else, since a flag would put it in the shell's history and the process list; its absence is a usage error that says where to get a key and how to load one `pipelex login` saved, and the command never prints it. The API's address comes from `PIPELEX_BASE_URL`, `https://api.pipelex.com` when unset; a refused base URL is reported without its credentials, path or query. An empty variable counts as unset, except `PIPELEX_BASE_URL`: an empty base URL is refused like any other the SDK cannot use, since it is most often a variable that was meant to name another API, as in `PIPELEX_BASE_URL=$STAGING_URL` with `STAGING_URL` unset, and counting it as unset would send the key to the default address. Every request carries `pipelex-sdk-cli/<version>` before the SDK's own token in its `User-Agent` ([`client-identification.md`](client-identification.md)).
 
-**No `.env` file is read.** A command started through `npx` from wherever the person stands would otherwise pick up a credential from whichever file it found there. To load one into the shell: `set -a; . ./.env; set +a`.
+**No `.env` file is read.** A command started through `npx` from wherever the person stands would otherwise pick up a credential from whichever file it found there. To load one into the shell: `set -a; . ./.env; set +a`. That holds for the `.env` where `pipelex login` and `pipelex init` save the key, `~/.pipelex/.env`, or the `.env` of the directory `PIPELEX_HOME` names when that is set: load it the same way, `set -a; . "${PIPELEX_HOME:-$HOME/.pipelex}/.env"; set +a`, which finds the file in either place and exports every variable it holds, or export `PIPELEX_API_KEY` yourself. The help and the missing-key error both say so.
 
 **`PIPELEX_SDK_POLL_INTERVAL_MS` is for tests only.** It sets the poll interval in milliseconds, a whole number; the case table sets it to `0` so that a run answered "still running" is polled again at once, and serves its `202` answers with `Retry-After: 0`, since the SDK waits at least as long as the server's `Retry-After` and five seconds when a `202` gives none. Unset, the SDK's own interval applies. The Python command reads the same variable.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/sdk",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "TypeScript SDK for the Pipelex hosted API — execute methods, manage runs, and call the product surface.",
   "license": "MIT",
   "repository": {
@@ -65,7 +65,7 @@
     "@types/node": "^22.12.0",
     "@vitest/coverage-v8": "^4.1.9",
     "dependency-cruiser": "^17.4.3",
-    "esbuild": "^0.25.12",
+    "esbuild": "^0.28.2",
     "eslint": "^9.39.4",
     "globals": "^16.5.0",
     "prettier": "^3.8.4",