@actana/sdk 0.2.2 → 0.3.0

package/dist/core-files-http.d.ts

@@ -0,0 +1,94 @@
+import type { CoreLinkTlsMaterial } from "./core-link-socket.ts";
+/** The refusal codes the Core's file routes answer with (`docs/external-api.md`). */
+export type CoreFilesErrorCode = "unauthorized" | "not-found" | "project-not-found" | "method-not-allowed" | "bad-request" | "absolute-path" | "dot-dot-segment" | "outside-project-root" | "malformed-path" | "transfer-in-progress" | "insufficient-storage" | "corrupt-archive" | "absolute-entry-path" | "dot-dot-entry-path" | "root-entry-path" | "entry-outside-root" | "unsupported-entry-type" | "hardlink-outside-root" | "symlink-outside-root" | "directory-in-the-way" | "write-failed" | "read-failed";
+/** Base class for everything `project.files.*` throws, so one `catch` can name it. */
+export declare class CoreFilesError extends Error {
+    constructor(message: string);
+}
+/**
+ * This Core has no file surface (F9, #165's `files` capability).
+ *
+ * Thrown *before any request goes out*, which is the point: a client that
+ * called the route anyway would read a `404` off a Core that simply predates the
+ * surface and report it as an outage. The `reason` is prose for an operator
+ * because "unavailable" on its own sends somebody to check their network.
+ */
+export declare class CoreFilesUnavailableError extends CoreFilesError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** A refusal with a status line: the Core answered, and said no. */
+export declare class CoreFilesRequestError extends CoreFilesError {
+    readonly status: number;
+    readonly code: CoreFilesErrorCode | string;
+    constructor(status: number, code: CoreFilesErrorCode | string, message: string);
+}
+/**
+ * The one-write-per-Project rule (F8), as an error and **never as a retry**.
+ *
+ * `409 transfer-in-progress` is a conflict a human has to resolve — some other
+ * transfer is running on this Project right now, possibly a multi-gigabyte one
+ * with twenty minutes left. A client that retried under the hood would convert
+ * the Core's clear, immediate refusal into a hang with no output, which is
+ * strictly worse than the error: the operator loses both the reason and the
+ * chance to decide. So nothing in this package sleeps, backs off or re-sends —
+ * this class *is* the handling, and the decision is the caller's.
+ *
+ * `directory-in-the-way` shares the status and the same rule: it is a refusal
+ * to delete a tree, and it will still be a directory on the next attempt.
+ */
+export declare class CoreFilesConflictError extends CoreFilesRequestError {
+    constructor(status: number, code: CoreFilesErrorCode | string, message: string);
+}
+/**
+ * A failure that arrived as the **last line of a progress stream** rather than
+ * as a status code, because the `200` was spent on the first entry.
+ *
+ * This is why the progress stream is NDJSON and not a JSON document: a document
+ * would have to be well-formed to be read at all, and this one stops in the
+ * middle by design.
+ */
+export declare class CoreFilesStreamError extends CoreFilesError {
+    readonly code: CoreFilesErrorCode | string;
+    constructor(code: CoreFilesErrorCode | string, message: string);
+}
+/** One request, in the terms this surface actually uses. */
+export type CoreFilesRequest = {
+    method: "GET" | "HEAD" | "PUT";
+    url: string;
+    headers: Record<string, string>;
+    /** A stream, never a buffer — see {@link CoreFiles.upload}. */
+    body?: ReadableStream<Uint8Array> | null;
+    signal?: AbortSignal;
+};
+/**
+ * How a file request is actually sent.
+ *
+ * Injected rather than reached for, on the same terms as
+ * {@link CoreLinkSocketFactory}: it is what lets a suite drive this surface
+ * over a plain loopback server, and what lets a runtime with its own
+ * dispatcher — a proxy, a recorder, a browser — supply one. The default is
+ * {@link createCoreFilesFetch}.
+ */
+export type CoreFilesFetch = (req: CoreFilesRequest) => Promise<Response>;
+/**
+ * The default sender: `fetch`, with the client certificate carried in on a
+ * dispatcher.
+ *
+ * The `Agent` is built **once, lazily, and only when there is TLS material** —
+ * a `http://` loopback Core needs no dispatcher, and building one per request
+ * would open a fresh connection pool for every upload.
+ */
+export declare function createCoreFilesFetch(tls: CoreLinkTlsMaterial | null): CoreFilesFetch;
+/**
+ * Turn a non-2xx answer into the right error class, reading the `code` beside
+ * the prose rather than the prose.
+ *
+ * A client branches on `code` because a message is a sentence somebody will
+ * reword — and `transfer-in-progress` in particular *has* to stay
+ * distinguishable (F8). The body is read to completion here, and only here: a
+ * refusal body is a short JSON object, which is why buffering it does not
+ * violate the streaming rule the success paths keep.
+ */
+export declare function refusalFrom(res: Response, what: string): Promise<CoreFilesRequestError>;
+//# sourceMappingURL=core-files-http.d.ts.map

package/dist/core-files-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-files-http.d.ts","sourceRoot":"","sources":["../src/core-files-http.ts"],"names":[],"mappings":"AA2DA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,qFAAqF;AACrF,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,WAAW,GACX,mBAAmB,GACnB,oBAAoB,GACpB,aAAa,GACb,eAAe,GACf,iBAAiB,GACjB,sBAAsB,GACtB,gBAAgB,GAChB,sBAAsB,GACtB,sBAAsB,GACtB,iBAAiB,GACjB,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,oBAAoB,GACpB,wBAAwB,GACxB,uBAAuB,GACvB,sBAAsB,GACtB,sBAAsB,GACtB,cAAc,GACd,aAAa,CAAC;AAElB,sFAAsF;AACtF,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,cAAc;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED,oEAAoE;AACpE,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC;gBAE/B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM;CAM/E;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,SAAQ,qBAAqB;gBACnD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM;CAI/E;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC;gBAE/B,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM;CAK/D;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,GAAG,cAAc,CA8BpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAe7F"}

package/dist/core-files-http.js

@@ -0,0 +1,198 @@
+// The SDK's first HTTPS surface (#167, F12) — how a file request reaches a
+// Core, and what a refusal from one means.
+//
+// Everything in this package before this module spoke one protocol: the
+// core-link WebSocket. File bytes deliberately do not cross it (ADR 0028), so
+// `project.files.*` dials the *same* mTLS server on the *same* port with the
+// *same* certificate and bearer, over HTTP instead of a WebSocket upgrade.
+// `CoreConnection.httpsBaseUrl` has named that origin since phase 1 precisely
+// so this module would not be the thing that changed a published shape.
+//
+// ## The `fetch` shape is frozen, not chosen here
+//
+// The phase-1 spike (#151, PR 189) settled how a client certificate reaches
+// `fetch` and its verdict is reused verbatim rather than rediscovered:
+//
+//     const agent = new Agent({ connect: { ca, cert, key } });
+//     await fetch(url, { dispatcher: agent });
+//
+// **`fetch` is undici and ignores `options.cert` / `options.key`.** There is no
+// option bag on `fetch` that reaches TLS at all — the dispatcher is the only
+// seam. A client built the `https.request` way silently makes an *anonymous*
+// connection, which a Core with `requestCert: true, rejectUnauthorized: true`
+// refuses at the handshake with an error that names no certificate; that is a
+// long debugging session, and it is the whole reason the spike exists. The
+// spike's leg 2b is the control that makes the shape mean anything: the same
+// `fetch` through a CA-only `Agent` is refused at the TLS layer. D12 also held
+// — both legs pass on Node 22 — so this package's `engines: ">=22"` stands.
+//
+// ### One thing the spike could not have found, and this had to
+//
+// **The `fetch` above is undici's own, not the global one**, and the two are
+// not interchangeable. Node embeds a *copy* of undici for its global `fetch`,
+// and a `Dispatcher` only satisfies the implementation it came from: handing a
+// dispatcher from the `undici` package to Node 24's built-in `fetch` fails with
+// `InvalidArgumentError: invalid onRequestStart method`, because undici 8
+// changed the handler interface that the embedded copy still expects. The
+// spike never met this — it loaded `ws` and `undici` as a matching pair from
+// one directory and used the global `fetch`, which happened to agree at those
+// versions.
+//
+// Importing both halves from the same package is what makes that class of skew
+// impossible rather than merely absent today: this package's `fetch` and its
+// `Agent` are the same implementation, whatever Node bundles underneath. The
+// frozen finding is untouched — the dispatcher is still the only seam, and the
+// CA-only control still has to be refused — and `core-files-mtls.test.ts` holds
+// both against a real handshake.
+//
+// ## Why `undici` is this package's second dependency
+//
+// `ws` is here because Node's global `WebSocket` cannot present a client
+// certificate. `undici` is here for the identical reason one layer up: Node's
+// global `fetch` cannot either, and the `Agent` that lets it is not exposed by
+// any builtin. It is a public package on the registry, so unlike `@actana/shared`
+// it is resolvable by everyone who installs this SDK — the boundary ADR 0025 D4
+// draws is around *private workspace* packages, not around dependencies as such.
+// A caller who never dials `https://` never constructs an `Agent`: the dispatcher
+// is built lazily, on the first request that needs one.
+import { Agent, fetch as undiciFetch } from "undici";
+/** Base class for everything `project.files.*` throws, so one `catch` can name it. */
+export class CoreFilesError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CoreFilesError";
+    }
+}
+/**
+ * This Core has no file surface (F9, #165's `files` capability).
+ *
+ * Thrown *before any request goes out*, which is the point: a client that
+ * called the route anyway would read a `404` off a Core that simply predates the
+ * surface and report it as an outage. The `reason` is prose for an operator
+ * because "unavailable" on its own sends somebody to check their network.
+ */
+export class CoreFilesUnavailableError extends CoreFilesError {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.name = "CoreFilesUnavailableError";
+        this.reason = reason;
+    }
+}
+/** A refusal with a status line: the Core answered, and said no. */
+export class CoreFilesRequestError extends CoreFilesError {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "CoreFilesRequestError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * The one-write-per-Project rule (F8), as an error and **never as a retry**.
+ *
+ * `409 transfer-in-progress` is a conflict a human has to resolve — some other
+ * transfer is running on this Project right now, possibly a multi-gigabyte one
+ * with twenty minutes left. A client that retried under the hood would convert
+ * the Core's clear, immediate refusal into a hang with no output, which is
+ * strictly worse than the error: the operator loses both the reason and the
+ * chance to decide. So nothing in this package sleeps, backs off or re-sends —
+ * this class *is* the handling, and the decision is the caller's.
+ *
+ * `directory-in-the-way` shares the status and the same rule: it is a refusal
+ * to delete a tree, and it will still be a directory on the next attempt.
+ */
+export class CoreFilesConflictError extends CoreFilesRequestError {
+    constructor(status, code, message) {
+        super(status, code, message);
+        this.name = "CoreFilesConflictError";
+    }
+}
+/**
+ * A failure that arrived as the **last line of a progress stream** rather than
+ * as a status code, because the `200` was spent on the first entry.
+ *
+ * This is why the progress stream is NDJSON and not a JSON document: a document
+ * would have to be well-formed to be read at all, and this one stops in the
+ * middle by design.
+ */
+export class CoreFilesStreamError extends CoreFilesError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CoreFilesStreamError";
+        this.code = code;
+    }
+}
+/**
+ * The default sender: `fetch`, with the client certificate carried in on a
+ * dispatcher.
+ *
+ * The `Agent` is built **once, lazily, and only when there is TLS material** —
+ * a `http://` loopback Core needs no dispatcher, and building one per request
+ * would open a fresh connection pool for every upload.
+ */
+export function createCoreFilesFetch(tls) {
+    let dispatcher = null;
+    return async (req) => {
+        if (tls && !dispatcher) {
+            dispatcher = new Agent({ connect: { ca: tls.ca, cert: tls.cert, key: tls.key } });
+        }
+        // `duplex: "half"` is mandatory for a streamed request body and is not a
+        // detail that can be left out: without it `fetch` rejects the body outright,
+        // which would take this surface straight back to buffering an upload in
+        // memory — the one thing #167 exists to not do.
+        //
+        // The casts are the type-level shadow of the same two-copies problem the
+        // header describes: `@types/node` declares the global `fetch` with its own
+        // bundled `undici-types`, and this module deliberately uses the real
+        // package's `fetch` instead. The two `Response` and `RequestInit`
+        // declarations are structurally near-identical and neither is wrong — they
+        // are simply not the same declaration. Everything this package reads off a
+        // response (`ok`, `status`, `headers.get`, `json`, `body`) is common to
+        // both, and the global `Response` is what callers and tests hold, so that
+        // is the type this surface promises.
+        const init = {
+            method: req.method,
+            headers: req.headers,
+            ...(req.body ? { body: req.body, duplex: "half" } : {}),
+            ...(req.signal ? { signal: req.signal } : {}),
+            ...(dispatcher ? { dispatcher } : {}),
+        };
+        const res = await undiciFetch(req.url, init);
+        return res;
+    };
+}
+/**
+ * Turn a non-2xx answer into the right error class, reading the `code` beside
+ * the prose rather than the prose.
+ *
+ * A client branches on `code` because a message is a sentence somebody will
+ * reword — and `transfer-in-progress` in particular *has* to stay
+ * distinguishable (F8). The body is read to completion here, and only here: a
+ * refusal body is a short JSON object, which is why buffering it does not
+ * violate the streaming rule the success paths keep.
+ */
+export async function refusalFrom(res, what) {
+    let code = "";
+    let message = "";
+    try {
+        const body = (await res.json());
+        if (typeof body.code === "string")
+            code = body.code;
+        if (typeof body.error === "string")
+            message = body.error;
+    }
+    catch {
+        // A refusal that is not the Core's JSON shape — a proxy's HTML error page,
+        // a truncated body. Say what is actually known rather than inventing a code.
+    }
+    const described = message || `${what} was refused with HTTP ${res.status}`;
+    const withCode = code ? `${described} (${code})` : described;
+    if (res.status === 409)
+        return new CoreFilesConflictError(res.status, code || "conflict", withCode);
+    return new CoreFilesRequestError(res.status, code || `http-${res.status}`, withCode);
+}
+//# sourceMappingURL=core-files-http.js.map

package/dist/core-files-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-files-http.js","sourceRoot":"","sources":["../src/core-files-http.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2CAA2C;AAC3C,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,wEAAwE;AACxE,EAAE;AACF,kDAAkD;AAClD,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,EAAE;AACF,+DAA+D;AAC/D,+CAA+C;AAC/C,EAAE;AACF,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,EAAE;AACF,gEAAgE;AAChE,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,0EAA0E;AAC1E,0EAA0E;AAC1E,6EAA6E;AAC7E,8EAA8E;AAC9E,YAAY;AACZ,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,iCAAiC;AACjC,EAAE;AACF,sDAAsD;AACtD,EAAE;AACF,yEAAyE;AACzE,8EAA8E;AAC9E,+EAA+E;AAC/E,kFAAkF;AAClF,gFAAgF;AAChF,iFAAiF;AACjF,kFAAkF;AAClF,wDAAwD;AACxD,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,QAAQ,CAAC;AA6BrD,sFAAsF;AACtF,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,cAAc;IAClD,MAAM,CAAS;IAExB,YAAY,MAAc;QACxB,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IAC9C,MAAM,CAAS;IACf,IAAI,CAA8B;IAE3C,YAAY,MAAc,EAAE,IAAiC,EAAE,OAAe;QAC5E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,sBAAuB,SAAQ,qBAAqB;IAC/D,YAAY,MAAc,EAAE,IAAiC,EAAE,OAAe;QAC5E,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IAC7C,IAAI,CAA8B;IAE3C,YAAY,IAAiC,EAAE,OAAe;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAuBD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAA+B;IAClE,IAAI,UAAU,GAAiB,IAAI,CAAC;IACpC,OAAO,KAAK,EAAE,GAAqB,EAAqB,EAAE;QACxD,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACvB,UAAU,GAAG,IAAI,KAAK,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,yEAAyE;QACzE,6EAA6E;QAC7E,wEAAwE;QACxE,gDAAgD;QAChD,EAAE;QACF,yEAAyE;QACzE,2EAA2E;QAC3E,qEAAqE;QACrE,kEAAkE;QAClE,2EAA2E;QAC3E,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,qCAAqC;QACrC,MAAM,IAAI,GAA4B;YACpC,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtC,CAAC;QACF,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,IAAyC,CAAC,CAAC;QAClF,OAAO,GAA0B,CAAC;IACpC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAa,EAAE,IAAY;IAC3D,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwC,CAAC;QACvE,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACpD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,6EAA6E;IAC/E,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,IAAI,GAAG,IAAI,0BAA0B,GAAG,CAAC,MAAM,EAAE,CAAC;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,sBAAsB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,IAAI,UAAU,EAAE,QAAQ,CAAC,CAAC;IACpG,OAAO,IAAI,qBAAqB,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,IAAI,QAAQ,GAAG,CAAC,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC;AACvF,CAAC"}

package/dist/core-files.d.ts

@@ -0,0 +1,227 @@
+import { type CoreFilesFetch } from "./core-files-http.ts";
+/**
+ * Whether this Core's file surface may be used at all, and — when it may not —
+ * why, in words an operator can act on (F9).
+ */
+export type CoreFilesAvailability = {
+    available: true;
+} | {
+    available: false;
+    reason: string;
+};
+/** How a written entry landed. `overwritten` names a file that was already there (F5). */
+export type CoreFileWriteResult = "written" | "overwritten";
+/**
+ * One entry of a listing, in the manifest shape PR 215 established: `{path,
+ * size, mtime, mode, sha256}`.
+ *
+ * `path` is **Project-relative**, which is the address space F1 gives the
+ * operator — the same string that goes back to `download`.
+ *
+ * `sha256` is nullable on purpose, and the Core settled which way it means:
+ * hashing every entry of a large tree is expensive, so a listing computes
+ * digests **on request** ({@link CoreFileListOptions.sha256}) and a transfer
+ * computes them eagerly, the bytes being already in hand. So `null` reads as
+ * "no bytes" for a directory and "nobody asked" for anything else.
+ */
+export type CoreFileEntry = {
+    path: string;
+    size: number;
+    mtime: number;
+    mode: number;
+    sha256: string | null;
+    /** Present when the listing distinguishes them; absent listings read as files. */
+    kind?: "file" | "directory" | "symlink";
+};
+/** One line of a write's NDJSON progress stream. */
+export type CoreFileProgress = ({
+    type: "entry";
+    result: CoreFileWriteResult;
+} & CoreFileEntry) | {
+    type: "done";
+    entries: number;
+    bytes: number;
+};
+/**
+ * What a read hands back: metadata, and **a stream**.
+ *
+ * There is no `bytes` or `buffer` field here and that absence is the feature.
+ * A gigabyte file must not materialise in memory, so the only way to get at the
+ * content is to consume `stream` — a caller who wants it whole has to write
+ * that themselves and own the decision. `size` is what the Core declared, which
+ * is `null` for a folder, whose tar length is not known until it has been walked.
+ */
+export type CoreFileDownload = {
+    /** `file` for raw bytes, `tar` for a folder crossing as one archive (ADR 0029). */
+    kind: "file" | "tar";
+    size: number | null;
+    mode: number | null;
+    mtime: number | null;
+    stream: ReadableStream<Uint8Array>;
+};
+/**
+ * Anything a caller can upload.
+ *
+ * A Node `Readable` — `fs.createReadStream(…)` — is an async iterable of
+ * `Buffer`, so it is accepted directly and without this package importing
+ * `node:stream` to say so. A web `ReadableStream` passes through untouched.
+ */
+export type CoreFileSource = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array | string>;
+export type CoreFileUploadOptions = {
+    /** Project-relative destination. `""` is the Project root, which only a tar may target. */
+    path: string;
+    body: CoreFileSource;
+    /**
+     * `file` writes one file at `path`; `tar` unpacks an archive into it
+     * (ADR 0029). Default `file`.
+     */
+    kind?: "file" | "tar";
+    /** Unix permission bits for a single-file write. The Core defaults to `0o644`. */
+    mode?: number;
+    /** Modification time in epoch milliseconds, preserved across the wire. */
+    mtime?: number;
+    /**
+     * Declared body length, when the caller knows it.
+     *
+     * Worth passing: it is what lets the Core run its free-space precheck and
+     * refuse `507 insufficient-storage` before the transfer rather than fail with
+     * `ENOSPC` half-way through. Omitted, the upload is chunked and there is
+     * nothing to check against.
+     */
+    contentLength?: number;
+    signal?: AbortSignal;
+};
+export type CoreFileDownloadOptions = {
+    /** Project-relative path. A directory comes back as one streamed tar. */
+    path: string;
+    signal?: AbortSignal;
+};
+export type CoreFileListOptions = {
+    /** Subtree to list, Project-relative. Default: the whole Project. */
+    path?: string;
+    /** Maximum depth to descend. `1` is the immediate children. Default: the whole tree. */
+    depth?: number;
+    /**
+     * Ask the Core to compute {@link CoreFileEntry.sha256} for every file and
+     * symlink under the path. **Off by default, and not free**: a listing does not
+     * have the bytes in hand, so digests mean reading every one of them (ADR 0027
+     * D6). Left off, every `sha256` comes back `null`.
+     */
+    sha256?: boolean;
+    signal?: AbortSignal;
+};
+export type CoreFilesOptions = {
+    projectId: string;
+    /** The Core's HTTPS origin — `CoreConnection.httpsBaseUrl`. No trailing slash. */
+    baseUrl: string;
+    /** The same signed bearer the core link's `auth` frame presents, or null on a loopback rig. */
+    bearer: string | null;
+    /**
+     * Read at the top of every call rather than once at construction: a Core can
+     * be downgraded and a client survives reconnects, so the answer belongs to
+     * the *current* connection and a remembered one would send a caller at a route
+     * that is no longer there.
+     */
+    availability: () => CoreFilesAvailability;
+    fetch: CoreFilesFetch;
+};
+/**
+ * A Project's files, over the Core's HTTPS routes.
+ *
+ * Reached as `client.project(id).files` rather than constructed directly.
+ */
+export declare class CoreFiles {
+    private readonly opts;
+    constructor(opts: CoreFilesOptions);
+    /**
+     * The Project's tree, one entry at a time.
+     *
+     * Reads the Core's real listing route — `GET …/files/list`, see
+     * {@link listUrl} — which streams `{path, kind, size, mtime, mode, sha256}`
+     * per entry as NDJSON. `core-files-list-contract.test.ts` drives this method
+     * against that route in process and runs in **both** packages' suites, so the
+     * two halves of the URL cannot drift apart again without a red test (#218).
+     *
+     * Both line shapes are accepted — a bare manifest entry and one wrapped as
+     * `{type: "entry", …}`, which is what the Core's listing and its write route
+     * both emit. `skipped` lines are passed over: a path the walk could not read
+     * is a fact about the tree, not an entry in it, and not a reason to stop.
+     */
+    list(opts?: CoreFileListOptions): AsyncGenerator<CoreFileEntry, void, undefined>;
+    /**
+     * Write a stream into the Project, and watch it land.
+     *
+     * The returned iterable is the Core's NDJSON progress stream, parsed: one
+     * `entry` line per file — each carrying `result: "written" | "overwritten"`,
+     * so **every overwrite is named** rather than inferred — then one `done` line
+     * with the totals.
+     *
+     * **Lazy, like everything else here.** Calling `upload` sends nothing; the
+     * request goes out on the first `next()`. A caller who does not care about
+     * progress still has to drain the iterable, and that is the honest shape: the
+     * alternative is a method that returns a promise and quietly buffers a
+     * gigabyte of progress nobody read.
+     *
+     * Throws {@link CoreFilesConflictError} when another write already holds this
+     * Project's lease (F8) — immediately, and without retrying. Throws
+     * {@link CoreFilesStreamError} when the write fails part-way through, which
+     * arrives as the stream's last line rather than as a status code, the `200`
+     * having been spent on the first entry.
+     */
+    upload(opts: CoreFileUploadOptions): AsyncGenerator<CoreFileProgress, void, undefined>;
+    /**
+     * Read a file — or a folder, as one streamed tar — **as a stream**.
+     *
+     * The response body is handed through untouched. Nothing on this path calls
+     * `arrayBuffer`, `text` or `blob`, so a gigabyte file crosses in whatever
+     * chunks the socket delivers and only ever occupies what the consumer has not
+     * yet read. `core-files-streaming.test.ts` holds that claim to a real
+     * gigabyte and watches the heap while it crosses.
+     *
+     * The metadata comes off headers the Core already had — `stat` on the file it
+     * was about to open — so nothing is read twice to produce it.
+     */
+    download(opts: CoreFileDownloadOptions): Promise<CoreFileDownload>;
+    /**
+     * `…/v1/projects/:projectId/files/list?path=<relative>` — a route of its own.
+     *
+     * This module used to send `?list=1` on the read route instead, and argued for
+     * it on cost: the Core's `parseRoute` matched `/v1/projects/:id/files` on an
+     * exact four-segment split, so a `…/files/list` leaf was a change to that
+     * parser and a query parameter was not. That cost is now paid — #216 shipped a
+     * parser that reads the fifth segment — and what is left is the Core's
+     * argument, which was never about cost: a listing and a read of the same
+     * folder answer with completely different things, one a manifest and one a
+     * tar. A query parameter that a proxy, a redirect or a hand-edited URL can
+     * drop turns "list this folder" into "download this folder", which for a
+     * `node_modules` is a mistake measured in gigabytes rather than in a 400. A
+     * path segment cannot be dropped silently. See issue 218.
+     *
+     * Still `protected`: a caller pinned to an older Core can subclass rather than
+     * wait for a release.
+     */
+    protected listUrl(opts: CoreFileListOptions): string;
+    /** `…/v1/projects/:projectId/files?path=<relative>` — the read and write route. */
+    protected fileUrl(filePath: string): string;
+    /**
+     * `<baseUrl>/v1/projects/:projectId/<leaf>`, with the Project id escaped.
+     *
+     * The two routes above differ by their leaf and by nothing else, and that is
+     * worth having in one place: the day this surface gains a third, the origin,
+     * the version prefix and the escaping should not be a third opportunity to get
+     * one of them subtly wrong.
+     */
+    private routeUrl;
+    private authHeaders;
+    /**
+     * The F9 gate, checked before every call and *before any byte leaves*.
+     *
+     * The reason is carried into the error rather than flattened to a boolean,
+     * because the two ways this fails want different actions from an operator: a
+     * Core that has not finished connecting is a wait, and a Core that announced
+     * no `files` capability is a Core that predates the surface — which is a
+     * supported state, not a fault and not a needs-update.
+     */
+    private requireAvailable;
+}
+//# sourceMappingURL=core-files.d.ts.map

package/dist/core-files.d.ts.map

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