@pipelex/sdk 0.47.0 → 0.48.1

package/dist/models.d.ts

@@ -8,8 +8,8 @@
  * the model reference check. Built on the protocol wire types imported from the
  * `mthds/protocol` subpath.
  */
-import type { InputForm, OutputForm, PipeIOContracts, RunResultExecute, RunResultStart } from "mthds/protocol";
-import type { BundleResources } from "./bundle-resources.js";
+import type { InputForm, MethodFiles, MethodTreeSource, OutputForm, PipeIOContracts, RunResultExecute, RunResultStart } from "mthds/protocol";
+import type { MethodTreeForm, NoMethodTree } from "./method-trees.js";
 export interface DictStuff {
     concept: string;
     content: unknown;
@@ -75,7 +75,7 @@ export interface PipelexRunResultStart extends RunResultStart {
  * The hosted tooling routes' own selector — the layer-3 extension the platform
  * adds on `POST /v1/validate`, `/v1/resolve`, `/v1/codegen`, and `/v1/pipe-io`: a stored
  * method's catalog id (`mt_…`), optionally naming a version, resolved server-side against
- * the org's catalog, the `.mthds` files of the version it names injected as inline source
+ * the org's catalog, the tree of the version it names injected as the method's `files`
  * before the runner sees the request. A bare `mt_…` names the latest published version,
  * `mt_…@<n>` version `n` and `mt_…@draft` the draft. A **pass-through to the hosted API**:
  * nothing is expanded client-side, and it is meaningless off-platform (a bare runner
@@ -97,11 +97,11 @@ export interface PipelexHostedToolingExtensions {
     method_id?: string;
 }
 /**
- * The method selector the tooling routes take in place of inline contents: a
+ * The method selector the tooling routes take in place of the method's tree: a
  * `method_ref` address (server-resolved by the runner through the same fetch
  * path as a `method_ref` run) OR a hosted `method_id` (platform-resolved) —
  * never both. The tooling routes are stateless, so the strict XOR applies:
- * exactly one of inline contents / `method_ref` / `method_id` per request.
+ * exactly one of the tree / `method_ref` / `method_id` per request.
  *
  * Lives here, beside the other wire shapes, rather than on the client: it is
  * the request's shape, and a module that composes a `validate` call of its own
@@ -115,6 +115,23 @@ export type ValidateMethodSelector = {
     method_id: string;
     method_ref?: never;
 };
+/**
+ * What `validate()` judges: the method's tree, in exactly one of the four forms of
+ * `MethodTreeForm` (a `directory`, `contents`, a `tree` or the `files` map), or one of the two
+ * selectors of `ValidateMethodSelector`. Each arm pins the others to `never`, so naming two is a
+ * compile error; an untyped caller naming none, or more than one, is refused with a
+ * `RequestArgumentError` before any request, as the route itself would refuse a second selector
+ * with a `422`. At run time a `null` member, an empty `directory` and an empty selector string
+ * are absent, and a `files` map or `contents` holding no file is refused, as the MTHDS standard
+ * refuses a tree holding no file.
+ *
+ * It widens the protocol's own `ValidateSource` (`{ files }` or `{ tree }`) with the two forms
+ * this client lists or encodes itself and the two selectors the Pipelex API resolves.
+ */
+export type PipelexValidateSource = (MethodTreeForm & {
+    method_ref?: never;
+    method_id?: never;
+}) | (ValidateMethodSelector & NoMethodTree);
 /** Per-pipe dry-run verdict in `validated_pipes[]` — mirror of pipelex's `DryRunStatus`. */
 export type DryRunStatus = "SUCCESS" | "FAILURE" | "SKIPPED";
 /** One entry of `PipelexValidationReport.validated_pipes` — `{pipe_ref, status}`. */
@@ -139,6 +156,35 @@ export interface LiftablePipeEntry {
     /** Where the possible absence originates (human-readable). */
     absence_source: string;
 }
+/**
+ * What a step reads a file of its method tree as — mirror of pipelex's `TreeFileUse`:
+ * `template`, the template a `PipeDocGen` step fills, named by its `template_file`;
+ * `template_asset`, an image, a stylesheet or a font that step's HTML template names by a
+ * literal relative URL, or that one of its stylesheets names; `python_module`, the module
+ * defining the function a `PipeFunc` step calls, named by the import path of its
+ * `function_name`.
+ *
+ * A report reads it open (see {@link TreeFileRead.use}): a runner of a later version may add
+ * a use as another kind of step comes to read files of its tree.
+ */
+export type TreeFileUse = "template" | "template_asset" | "python_module";
+/**
+ * One file of its method tree a step reads — mirror of pipelex's `TreeFileRead`, an entry of
+ * {@link PipelexValidationReport.tree_files_read}.
+ */
+export interface TreeFileRead {
+    /**
+     * The file's path from the root of the method's tree, with forward slashes, such as
+     * `templates/invoice.html`, never a path on the server.
+     */
+    tree_path: string;
+    /**
+     * What the step reads the file as. Read open: `string & {}` keeps the editor's completion
+     * on the uses this SDK knows, and a consumer that switches on this field has to say what a
+     * use it does not know does.
+     */
+    use: TreeFileUse | (string & {});
+}
 /**
  * Pipelex's `POST /v1/validate` 200 body for a VALID bundle — the canonical
  * `PipelexValidationReport`, carrying the `is_valid: true` discriminant of the
@@ -209,6 +255,27 @@ export interface PipelexValidationReport {
     output_form?: OutputForm;
     /** Pipes the runtime may skip when an optional slot resolves absent. */
     liftable_pipes: LiftablePipeEntry[];
+    /**
+     * Per step, the files of the method's tree it reads, keyed by namespaced `pipe_ref` over
+     * the same set as `pipe_io_contracts`, each file by its tree path with what the step reads
+     * it as. A `PipeDocGen` step reads its template and the images, stylesheets and fonts its
+     * HTML template names by literal relative URLs; a `PipeFunc` step reads the module of its
+     * function when that module is a file of the tree. A step that reads no file of the tree,
+     * a controller included, has an empty list. The paths come from what each step already
+     * names, so a client can show which step uses a file without parsing the method.
+     *
+     * OPTIONAL because a runner predating the field sends nothing: an absent field says the
+     * server did not report the reads, where an empty list says that step reads no file.
+     */
+    tree_files_read?: Record<string, TreeFileRead[]>;
+    /**
+     * The per-file view of `tree_files_read`: each tree path a step reads, in sorted order, to
+     * the namespaced refs of the steps that read it, each listed once. A file of the tree with
+     * no entry is read by no step: the bundles themselves, a README, a package's `__init__.py`
+     * beside its modules. Optional for the same reason as `tree_files_read`, and present
+     * whenever it is.
+     */
+    tree_file_readers?: Record<string, string[]>;
     /**
      * The qualified ref of the pipe a selector-less run of THIS request would execute —
      * the primary blueprint's declared `main_pipe` qualified by its domain and, for a
@@ -326,9 +393,8 @@ export type ValidationErrorCategory = "blueprint_validation" | "pipe_factory" |
  * not, so the same item arrives with explicit `null`s there. A truthiness check reads
  * both; an `=== undefined` check would be wrong on one of them.
  *
- * `source` is the declaring file path (CLI) or the per-content `mthds_sources` name
- * the API threads onto the in-memory load path — the owning file for cross-file
- * diagnostics.
+ * `source` is the declaring file: its path (CLI), or its tree path in the tree the
+ * request sent — the owning file for cross-file diagnostics.
  *
  * An `unknown_model` item (a model reference the runner's model deck does not know)
  * carries the reference as written, the kind of model the field takes and the close
@@ -514,50 +580,84 @@ export interface FormatResponse {
     diagnostics: Diagnostic[];
 }
 /**
- * One MTHDS file in a crate closure. `source` is an optional provenance label (a
- * filename, a URI) that the server threads onto every diagnostic it raises from
- * this file, so an invalid verdict can point at the file that caused it.
+ * The method every crate route takes — `/v1/resolve`, `/v1/codegen` and `/v1/pipe-io`
+ * (mirror of the runner's `MethodTreeRequest`).
  *
- * NOT the same type as `MthdsFile` (the one `validateFiles()` takes), which the
- * client adapts into `/v1/validate`'s parallel `mthds_contents` + `mthds_sources`
- * arrays: that route spells the label `uri`, this envelope spells it `source`. The
- * two collapse into one only if `/v1/validate` ever migrates onto `files[]` — a
- * protocol-level change owned by the MTHDS standard, not ours to make here.
- */
-export interface MthdsFileItem {
-    content: string;
-    source?: string;
-}
-/**
- * The closure selector every crate route shares — `/v1/resolve`, `/v1/codegen` and
- * `/v1/pipe-io` (mirror of the server's `MthdsFilesRequest`).
+ * Supply the method EITHER as its tree OR as a `method_ref` — never both, and never neither
+ * (both arms are a request-shape `422`); the hosted `method_id` joins them as a third form on
+ * each route's own request (see {@link PipelexHostedToolingExtensions}). The tree is the MTHDS
+ * protocol's map of file entries, keyed by tree path, given in exactly one of the four forms
+ * every route takes (`MethodTreeForms`):
  *
- * Supply the closure EITHER as inline `files` OR as a `method_ref` — never both, and
- * never neither (both arms are a request-shape `422`); the hosted `method_id` joins
- * them as a third form on each route's own request (see
- * {@link PipelexHostedToolingExtensions}). An **address-form** `method_ref`
- * (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is resolved by the server
- * (pipelex-api >= 0.21.0): the repository is fetched at the tag, the package is
- * located by manifest identity, and its `.mthds` files feed the closure with their
- * real relative paths as per-file sources. The **registry form** (any non-address
- * reference) stays reserved and answers `501` until a method registry exists.
+ * - `directory`, the method's directory on disk, listed by the `mthds` package's lister under
+ *   the standard's membership rule and the deployment's limits (Node only);
+ * - `contents`, each file's bytes or text by tree path;
+ * - `tree`, a `MethodTreeSource`, such as the `MethodTree` the `mthds` package's
+ *   `listMethodTree` returns;
+ * - `files`, the map itself, each value the file's text, `{ base64 }` or `{ sha256, size }` for
+ *   bytes the runner already holds, sent as given.
  *
- * The XOR is a server-side invariant, not a type-level one: expressing it as a union
- * here would make the common `{ files }` call site pick a branch for no gain, and the
- * server rejects the illegal shapes with a typed `ApiResponseError` either way.
+ * The client sends a `directory`, `contents` or `tree` inline when its inline map weighs 256 KiB
+ * or less and no more than the inline limit the API announces, or whatever its weight when the
+ * API keeps no blob store, and otherwise every file by hash, after uploading the files the API
+ * lacks, exactly as `createMethod` sends one (see `docs/method-trees.md`). Every `.mthds` file of
+ * the tree is one of the method's bundles, named by its tree path in diagnostics and in the
+ * crate's `source_map`, and every other file is one a step may read, such as a `PipeDocGen`
+ * template.
  *
- * `resources` accompanies inline `files`: the files the closure's steps read, such as a
- * `PipeDocGen` step's `template_file`, keyed by the path the step names, each as its bytes,
- * which the client encodes into the wire's base64 map before posting (see
- * `docs/bundle-resources.md`). It is the one member the client does not post verbatim. Beside
- * a `method_ref` it is the server's `422`, a published method's files being its package's
- * own; a step whose template file was not sent makes the closure invalid.
+ * An **address-form** `method_ref` (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is
+ * resolved by the server (pipelex-api >= 0.21.0): the package's whole tree is fetched at the tag
+ * and read as a tree sent in `files` is. The **registry form** (any non-address reference) stays
+ * reserved and answers `501` until a method registry exists.
+ *
+ * The XOR is a server-side invariant, not a type-level one: expressing it as a union here would
+ * make the common `{ files }` call site pick a branch for no gain, and the server rejects the
+ * illegal shapes with a typed `ApiResponseError` either way. Two forms of the tree at once are
+ * the one shape the client refuses itself, with a `RequestArgumentError`, since it prepares the
+ * tree before posting. An empty map or string is absent, as in the Python SDK: `files: {}`,
+ * `files: null`, `contents: {}`, `directory: ""` and `dependencies: {}` select and send nothing,
+ * so an empty one beside another selector never reaches the wire as a second selector.
+ *
+ * `dependencies` accompanies the tree: the method packages it calls by address that the runner
+ * cannot fetch, each a map of file entries keyed by its address, sent as given. These routes load
+ * a package the method calls only from what was shipped with it, so a call into one nothing
+ * shipped is the invalid verdict.
+ *
+ * The files the closure's steps read, such as a `PipeDocGen` step's `template_file`, are files of
+ * the tree like any other, so a directory sends them with its bundles.
+ *
+ * `read_scope` is the Pipelex API's scope the request reads the method under: a hash entry of
+ * `files` resolves in that scope's blob store, else in the caller's own. A tree sent by hash asks
+ * `POST /v1/blobs/missing` under the same scope, so its blobs are uploaded into the store the
+ * request reads. **The hosted platform ignores it**: it stamps the caller's organization as the
+ * read scope of every crate request and drops the one the caller sent, so it only reaches a
+ * runner called directly.
  */
 export interface CrateRequestBase {
-    files?: MthdsFileItem[];
+    /** The method's directory, listed by the standard's lister and sent as `tree` is. Node only. */
+    directory?: string | null;
+    /** The method's files, each one's bytes or text by tree path, sent as `tree` is. */
+    contents?: Readonly<Record<string, Uint8Array | string>> | null;
+    /** The method's tree as a listed source, sent inline when small and by hash otherwise. */
+    tree?: MethodTreeSource | null;
+    /** The method's tree as the protocol's map of file entries, sent as given. */
+    files?: MethodFiles | null;
+    /** The method packages the tree calls by address, each a map of file entries keyed by its address. */
+    dependencies?: Record<string, MethodFiles>;
     method_ref?: string;
-    /** The files the closure's steps read, keyed by the path a step names, each as its bytes. */
-    resources?: BundleResources | null;
+    /** The scope the runner reads the tree under; the hosted platform replaces it with the caller's organization. */
+    read_scope?: string;
+}
+/**
+ * What a crate route call — `resolve`, `codegen`, `pipeIo` — takes beside its request.
+ *
+ * `signal` is read between the steps a `tree` or `contents` costs before the request, and before
+ * the request itself: once it has aborted, no further file of the tree is read, neither the blob
+ * route nor an upload starts, and the route is not asked, and the call throws the abort. A request
+ * already sent runs to its end, as in `prepareInputs`, which passes its own `signal` here.
+ */
+export interface CrateRouteOptions {
+    signal?: AbortSignal;
 }
 /**
  * The `is_valid: false` arm shared by every crate route — `/v1/resolve`,
@@ -578,7 +678,7 @@ export interface CrateInvalidReport {
 }
 /**
  * `POST /v1/resolve` request — the crate envelope (no projection axes) plus the
- * hosted `method_id` selector. Exactly one of `files` / `method_ref` /
+ * hosted `method_id` selector. Exactly one of the tree / `method_ref` /
  * `method_id` — the strict tooling XOR; see {@link PipelexHostedToolingExtensions}.
  */
 export type ResolveRequest = CrateRequestBase & PipelexHostedToolingExtensions;
@@ -626,7 +726,7 @@ export type CodegenKind = "types";
 export type CodegenTarget = "ts-zod" | "python-pydantic" | "python-structures";
 /**
  * `POST /v1/codegen` request — the crate envelope plus the two explicit projection
- * axes and the hosted `method_id` selector (exactly one of `files` / `method_ref` /
+ * axes and the hosted `method_id` selector (exactly one of the tree / `method_ref` /
  * `method_id`; see {@link PipelexHostedToolingExtensions}).
  */
 export interface CodegenRequest extends CrateRequestBase, PipelexHostedToolingExtensions {
@@ -677,7 +777,7 @@ export interface CodegenValidReport {
 export type CodegenResponse = CodegenValidReport | CrateInvalidReport;
 /**
  * `POST /v1/pipe-io` request — the crate envelope plus the hosted `method_id` selector
- * (exactly one of `files` / `method_ref` / `method_id`; see
+ * (exactly one of the tree / `method_ref` / `method_id`; see
  * {@link PipelexHostedToolingExtensions}), a pipe selector, and two opt-ins.
  *
  * There is no `views` field: the valid arm always carries all three artifacts.
@@ -685,8 +785,9 @@ export type CodegenResponse = CodegenValidReport | CrateInvalidReport;
 export interface PipeIORequest extends CrateRequestBase, PipelexHostedToolingExtensions {
     /**
      * The pipe to describe, as a QUALIFIED `domain.pipe_code` ref. Omit it and the
-     * server's selection chain decides: a fetched package's manifest `main_pipe`, else
-     * the closure's single `main_pipe` declaration. A selection the server refuses is a
+     * server's selection chain decides: the `main_pipe` of the `METHODS.toml` at the tree's
+     * root, whether the tree was sent or fetched, else the closure's single `main_pipe`
+     * declaration. A selection the server refuses is a
      * `422` typed by what went wrong, with `error_domain: "input"` and the candidates, where
      * there are some, in its `detail`: `EntryPipeNotFoundError` for a ref that names no pipe
      * or (without `all_pipes`) a method with no entry pipe, `EntryPipeAmbiguousError` for a
@@ -705,9 +806,9 @@ export interface PipeIORequest extends CrateRequestBase, PipelexHostedToolingExt
      */
     all_pipes?: boolean;
     /**
-     * Echo the resolved closure's `.mthds` files on the valid arm as `files`, in the
-     * request's own `files[]` shape. Defaults to `false` server-side, and the field is then
-     * absent from the answer.
+     * Echo the text of the method's own `.mthds` bundles on the valid arm as `files`, keyed
+     * by tree path. Defaults to `false` server-side, and the field is then absent from the
+     * answer.
      */
     include_files?: boolean;
 }
@@ -739,7 +840,8 @@ export interface PipeIOValidReport {
     output_form: OutputForm;
     /**
      * The method's own entry pipe: the selection chain without the request's `pipe_ref` —
-     * the fetched manifest's `main_pipe`, else the closure's single declaration. A request
+     * the `main_pipe` of the `METHODS.toml` at the tree's root, sent or fetched, else the
+     * closure's single declaration. A request
      * that omits `pipe_ref` always answers `pipe_ref === default_pipe_ref`. A stated `null`
      * when the chain finds none or several.
      *
@@ -752,12 +854,13 @@ export interface PipeIOValidReport {
     /** `pending_signatures` is empty, as on `validate`. No dry run backs it. */
     is_runnable: boolean;
     /**
-     * The resolved closure's `.mthds` files, in the request's `files[]` shape. Present only
-     * when the request passed `include_files: true`: the request's files for inline
-     * `files`, the fetched package's `.mthds` files under their package-relative paths for
-     * a `method_ref`, the stored files under their stored names for a hosted `method_id`.
+     * The text of each `.mthds` bundle of the method's own tree, keyed by its tree path.
+     * Present only when the request passed `include_files: true`: for a tree the request
+     * sent, its bundles, whatever entry form carried them; for a `method_ref`, the fetched
+     * package's, keyed by their path from the package root; for a hosted `method_id`, the
+     * stored tree's. The tree's other files and its dependencies' bundles are never included.
      */
-    files?: MthdsFileItem[];
+    files?: Record<string, string>;
 }
 /** The `POST /v1/pipe-io` 200 response — pattern-match `is_valid` before reading the arm. */
 export type PipeIOResponse = PipeIOValidReport | CrateInvalidReport;

package/dist/node-host/node.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The Node host as Node resolves it: the one module of the SDK that loads what only Node has,
+ * `node:fs/promises`, `node:path`, the `mthds` package's tree lister and `undici`'s `Agent`.
+ *
+ * Nothing imports this file by its path. `src/node-host.ts` reaches it through `#node-host`, the
+ * package's own subpath import, which `package.json` maps to this file under the `node` condition
+ * and to `./unavailable.ts` under every other condition set, so a bundler building for a browser
+ * or an edge runtime never follows it (see `src/node-host.ts`).
+ *
+ * The two built-ins load with the host. The `mthds` root entry and `undici` are heavier, and only
+ * listing a directory or fetching an artifact needs one of them, so each loads on its first use.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { MethodTreeError, listMethodTree } from "mthds";
+import type { Agent } from "undici";
+/** The `mthds` package's lister of a method directory, and the error it refuses a tree with. */
+export interface TreeLister {
+    readonly listMethodTree: typeof listMethodTree;
+    readonly MethodTreeError: typeof MethodTreeError;
+}
+/** What only Node has, as the SDK uses it. */
+export interface NodeHost {
+    /** `node:fs/promises`. */
+    readonly fs: typeof fs;
+    /** `node:path`. */
+    readonly path: typeof path;
+    /** The `mthds` root entry's tree lister, loading that entry on the first call. */
+    loadTreeLister(): Promise<TreeLister>;
+    /** `undici`'s `Agent`, loading `undici` on the first call. */
+    loadAgent(): Promise<typeof Agent>;
+}
+export declare const nodeHost: NodeHost;

package/dist/node-host/node.js

@@ -0,0 +1,27 @@
+/**
+ * The Node host as Node resolves it: the one module of the SDK that loads what only Node has,
+ * `node:fs/promises`, `node:path`, the `mthds` package's tree lister and `undici`'s `Agent`.
+ *
+ * Nothing imports this file by its path. `src/node-host.ts` reaches it through `#node-host`, the
+ * package's own subpath import, which `package.json` maps to this file under the `node` condition
+ * and to `./unavailable.ts` under every other condition set, so a bundler building for a browser
+ * or an edge runtime never follows it (see `src/node-host.ts`).
+ *
+ * The two built-ins load with the host. The `mthds` root entry and `undici` are heavier, and only
+ * listing a directory or fetching an artifact needs one of them, so each loads on its first use.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export const nodeHost = {
+    fs,
+    path,
+    async loadTreeLister() {
+        const { listMethodTree, MethodTreeError } = await import("mthds");
+        return { listMethodTree, MethodTreeError };
+    },
+    async loadAgent() {
+        const { Agent } = await import("undici");
+        return Agent;
+    },
+};
+//# sourceMappingURL=node.js.map

package/dist/node-host/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/node-host/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAsBlC,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,EAAE;IACF,IAAI;IACJ,KAAK,CAAC,cAAc;QAClB,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAClE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;IAC7C,CAAC;IACD,KAAK,CAAC,SAAS;QACb,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;CACF,CAAC"}

package/dist/node-host/unavailable.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The Node host as every runtime other than Node resolves it: absent. `package.json` maps
+ * `#node-host` to this file under every condition set without `node`, a browser's or an edge
+ * runtime's, so the graph a bundler follows there holds no Node built-in, no `undici` and not the
+ * `mthds` root entry (see `src/node-host.ts`). It imports nothing at run time.
+ */
+import type { NodeHost } from "./node.js";
+export declare const nodeHost: NodeHost | null;

package/dist/node-host/unavailable.js

@@ -0,0 +1,8 @@
+/**
+ * The Node host as every runtime other than Node resolves it: absent. `package.json` maps
+ * `#node-host` to this file under every condition set without `node`, a browser's or an edge
+ * runtime's, so the graph a bundler follows there holds no Node built-in, no `undici` and not the
+ * `mthds` root entry (see `src/node-host.ts`). It imports nothing at run time.
+ */
+export const nodeHost = null;
+//# sourceMappingURL=unavailable.js.map

package/dist/node-host/unavailable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unavailable.js","sourceRoot":"","sources":["../../src/node-host/unavailable.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,CAAC,MAAM,QAAQ,GAAoB,IAAI,CAAC"}

package/dist/node-host.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The Node host: what the SDK uses that only Node has, behind one import that a bundler building
+ * for any other runtime never follows. See `docs/architecture.md`, "The Node host".
+ *
+ * The operations that need Node, reading a local path (`upload.ts`), downloading a run's files and
+ * the undici dispatcher of an artifact fetch (`artifacts.ts`), listing a method directory and
+ * writing a saved tree to disk (`method-trees.ts`), get it from `loadNodeHost()`, and never import
+ * a Node built-in, `undici` or the `mthds` root entry themselves. `loadNodeHost()` imports
+ * `#node-host`, the package's own subpath import, which the `imports` map of `package.json`
+ * resolves by condition: under `node` to `node-host/node.ts`, which holds those modules, and under
+ * every other condition set, a browser's or an edge runtime's, to `node-host/unavailable.ts`,
+ * which holds none. A bundler building for the browser therefore follows no Node built-in from the
+ * barrel, statically or dynamically, and `tests/browser-bundle.test.ts` bundles the built package
+ * for the browser to hold it to that. Node resolves the same import under its own condition, so
+ * the Node-only operations work there as they always did. Where the host cannot be had, outside
+ * Node, inside it without the `node` condition, or where the import itself fails, `loadNodeHost()`
+ * answers why rather than throwing, so each operation refuses with its own class and verdict.
+ */
+import type { NodeHost } from "./node-host/node.js";
+export type { NodeHost, TreeLister } from "./node-host/node.js";
+/** True when running under Node (has `process.versions.node`). */
+export declare function isNodeRuntime(): boolean;
+/**
+ * The Node host could not be had: why, for a refusal to say, and the error behind it when the
+ * host's import failed.
+ */
+export interface NodeHostAbsence {
+    readonly host: null;
+    /**
+     * Why, as a clause a refusal puts after its own subject; `null` outside Node, where the
+     * operation's own "Node only" refusal is the right one.
+     */
+    readonly reason: string | null;
+    /** The import's own error, when the host's import failed rather than resolving to nothing. */
+    readonly cause?: unknown;
+}
+/** The Node host, or why it could not be had. */
+export type NodeHostLoad = {
+    readonly host: NodeHost;
+} | NodeHostAbsence;
+/**
+ * The Node host, or its absence and why, in three cases: a runtime that is not Node; Node itself
+ * where the package was resolved without the `node` export condition, so `#node-host` resolved to
+ * the variant holding nothing; and Node where the import of `#node-host` failed, as in a
+ * toolchain that does not resolve the `imports` map of `package.json`, whose error is the
+ * absence's `cause`. It never throws, so every operation needing Node refuses with its own class
+ * and verdict. The runtime is checked first, so nothing is loaded where it is not Node.
+ */
+export declare function loadNodeHost(): Promise<NodeHostLoad>;
+/** The `cause` option of a refusal made for `absence`: the import's own error, when there is one. */
+export declare function absenceCause(absence: NodeHostAbsence): {
+    cause?: unknown;
+};

package/dist/node-host.js

@@ -0,0 +1,72 @@
+/**
+ * The Node host: what the SDK uses that only Node has, behind one import that a bundler building
+ * for any other runtime never follows. See `docs/architecture.md`, "The Node host".
+ *
+ * The operations that need Node, reading a local path (`upload.ts`), downloading a run's files and
+ * the undici dispatcher of an artifact fetch (`artifacts.ts`), listing a method directory and
+ * writing a saved tree to disk (`method-trees.ts`), get it from `loadNodeHost()`, and never import
+ * a Node built-in, `undici` or the `mthds` root entry themselves. `loadNodeHost()` imports
+ * `#node-host`, the package's own subpath import, which the `imports` map of `package.json`
+ * resolves by condition: under `node` to `node-host/node.ts`, which holds those modules, and under
+ * every other condition set, a browser's or an edge runtime's, to `node-host/unavailable.ts`,
+ * which holds none. A bundler building for the browser therefore follows no Node built-in from the
+ * barrel, statically or dynamically, and `tests/browser-bundle.test.ts` bundles the built package
+ * for the browser to hold it to that. Node resolves the same import under its own condition, so
+ * the Node-only operations work there as they always did. Where the host cannot be had, outside
+ * Node, inside it without the `node` condition, or where the import itself fails, `loadNodeHost()`
+ * answers why rather than throwing, so each operation refuses with its own class and verdict.
+ */
+/** True when running under Node (has `process.versions.node`). */
+export function isNodeRuntime() {
+    return (typeof process !== "undefined" && process.versions != null && process.versions.node != null);
+}
+/**
+ * Inside Node, the package was resolved without the `node` export condition, as a bundle built
+ * for the browser or for esbuild's `neutral` platform resolves it, so `#node-host` resolved to the
+ * variant holding nothing.
+ */
+const NODE_CONDITION_MISSING = 'this copy of @pipelex/sdk runs in Node but was resolved without the "node" export ' +
+    "condition, which selects the part of the package that reaches Node's file system. Bundle " +
+    'it for Node (esbuild platform "node", webpack target "node"), add "node" to the bundler\'s ' +
+    "conditions (esbuild conditions, webpack resolve.conditionNames, Vite resolve.conditions), " +
+    "or leave @pipelex/sdk out of the bundle.";
+/**
+ * Inside Node, the import of `#node-host` itself failed: the toolchain loading the package does
+ * not resolve the `imports` map of `package.json`, as Jest before 29.4 does not, or the package is
+ * installed in part. `detail` is the import's own error message.
+ */
+function hostImportFailed(detail) {
+    return (`the Node host of @pipelex/sdk could not be loaded (${detail}). The SDK reaches Node's file ` +
+        'system through "#node-host", an entry of the "imports" map of its package.json, and a ' +
+        'toolchain that does not resolve package "imports", such as Jest before 29.4, cannot load ' +
+        "it: run under one that does, such as Node's own loader, Jest 29.4 or later or a current " +
+        "bundler, or reinstall @pipelex/sdk if it is installed in part.");
+}
+/**
+ * The Node host, or its absence and why, in three cases: a runtime that is not Node; Node itself
+ * where the package was resolved without the `node` export condition, so `#node-host` resolved to
+ * the variant holding nothing; and Node where the import of `#node-host` failed, as in a
+ * toolchain that does not resolve the `imports` map of `package.json`, whose error is the
+ * absence's `cause`. It never throws, so every operation needing Node refuses with its own class
+ * and verdict. The runtime is checked first, so nothing is loaded where it is not Node.
+ */
+export async function loadNodeHost() {
+    if (!isNodeRuntime())
+        return { host: null, reason: null };
+    let loaded;
+    try {
+        loaded = await import("#node-host");
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        return { host: null, reason: hostImportFailed(detail), cause };
+    }
+    return loaded.nodeHost === null
+        ? { host: null, reason: NODE_CONDITION_MISSING }
+        : { host: loaded.nodeHost };
+}
+/** The `cause` option of a refusal made for `absence`: the import's own error, when there is one. */
+export function absenceCause(absence) {
+    return absence.cause === undefined ? {} : { cause: absence.cause };
+}
+//# sourceMappingURL=node-host.js.map

package/dist/node-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-host.js","sourceRoot":"","sources":["../src/node-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,kEAAkE;AAClE,MAAM,UAAU,aAAa;IAC3B,OAAO,CACL,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,QAAQ,IAAI,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAC5F,CAAC;AACJ,CAAC;AAoBD;;;;GAIG;AACH,MAAM,sBAAsB,GAC1B,oFAAoF;IACpF,2FAA2F;IAC3F,6FAA6F;IAC7F,4FAA4F;IAC5F,0CAA0C,CAAC;AAE7C;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,MAAc;IACtC,OAAO,CACL,sDAAsD,MAAM,iCAAiC;QAC7F,wFAAwF;QACxF,2FAA2F;QAC3F,0FAA0F;QAC1F,gEAAgE,CACjE,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,CAAC,aAAa,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1D,IAAI,MAA8C,CAAC;IACnD,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,KAAK,IAAI;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE;QAChD,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;AAChC,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,OAAwB;IACnD,OAAO,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;AACrE,CAAC"}