@sasjs/api 0.4.0 → 0.6.0

package/build/esm/drive/deploy.js

@@ -0,0 +1,262 @@
+import { ApiError } from '../types.js';
+import { normaliseDrivePath } from './paths.js';
+export const DEPLOY_LIMITS = {
+    entries: 10000,
+    totalBytes: 100 * 1024 * 1024,
+    fileBytes: 20 * 1024 * 1024
+};
+/**
+ * The largest a deploy tree can be on the wire, which is what a host's transport
+ * has to admit.
+ *
+ * The cap is stated in DECODED bytes; the tree travels as JSON in which a file
+ * member's contents are base64 - 4/3 of what they write - and a service's are
+ * escaped text (~1.04). A tree at `totalBytes` therefore reaches the parser at
+ * up to ~134MB, and a transport that admits less refuses first with its own
+ * shape, so the cap it was meant to enforce is never consulted. 140MB leaves
+ * room for the tree's JSON scaffolding.
+ *
+ * Only the deploy routes use it: everywhere else a smaller limit applies,
+ * because a body is buffered before authentication and nothing else needs the
+ * headroom.
+ */
+export const DEPLOY_PAYLOAD_BYTES = 140 * 1024 * 1024;
+/**
+ * The body a deploy answers success with.
+ *
+ * The wording is the published contract - a client may key on the message - so
+ * it is one constant here rather than a string in each host. It names
+ * `@sasjs/server` because that is the document's example, which predates this
+ * package; changing it is a document change, not a host's choice.
+ */
+export const DEPLOY_SUCCESS = {
+    status: 'success',
+    message: 'Files deployed successfully to @sasjs/server.'
+};
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** A base64 body without its padding, which is what the arithmetic needs. */
+const base64Body = (value) => value.replace(/[^A-Za-z0-9+/]/g, '');
+/** The bytes a base64 body decodes to, without decoding it. */
+const base64Length = (value) => Math.floor((base64Body(value).length * 3) / 4);
+/** The bytes a base64 body decodes to, for a store that writes bytes. */
+export const decodeBase64 = (value) => {
+    const body = base64Body(value);
+    const bytes = new Uint8Array(Math.floor((body.length * 3) / 4));
+    let buffer = 0;
+    let bits = 0;
+    let at = 0;
+    for (const char of body) {
+        buffer = (buffer << 6) | BASE64_ALPHABET.indexOf(char);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes[at++] = (buffer >> bits) & 0xff;
+        }
+    }
+    return bytes.subarray(0, at);
+};
+/** The bytes a string occupies as UTF-8, without an encoding API. */
+const utf8Length = (value) => {
+    let bytes = 0;
+    for (let at = 0; at < value.length; at++) {
+        const code = value.charCodeAt(at);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && at + 1 < value.length) {
+            // a surrogate pair is one code point of four bytes
+            bytes += 4;
+            at++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+};
+/** The name a member is written under - a service gains the extension. */
+const memberName = (member) => member.type === 'service' ? `${member.name}.sas` : member.name;
+/** The bytes a member writes. */
+const memberBytes = (member) => member.type === 'file' ? base64Length(member.code) : utf8Length(member.code);
+/**
+ * Sizes as the messages state them: one decimal in binary megabytes, and bytes
+ * below a megabyte - a limit small enough to be measured in bytes should not
+ * read as "0 MB", which is what a stricter host would otherwise report.
+ */
+const describeSize = (bytes) => bytes < 1024 * 1024
+    ? `${bytes} bytes`
+    : `${Math.round((bytes / (1024 * 1024)) * 10) / 10} MB`;
+/** A walk's starting point. */
+const emptyWalk = () => ({
+    entries: 0,
+    totalBytes: 0,
+    largest: { path: '', bytes: 0 }
+});
+/**
+ * Every member name becomes a path SEGMENT under the deployment root, so a name
+ * carrying '/', '\' or '..' is a traversal attempt rather than a name.
+ */
+const isSafeSegment = (name) => name !== '' &&
+    name !== '.' &&
+    name !== '..' &&
+    !/[/\\]/.test(name) &&
+    // a Windows drive or a NUL byte is never a segment either
+    !/[\0]/.test(name);
+/**
+ * Walks a tree, counting it and noting the first unsafe name.
+ *
+ * A name problem is RECORDED rather than returned, so the walk always finishes:
+ * a caller that only wants the numbers gets the size of the whole tree, and the
+ * validator decides whether the name matters. Returning early would report a
+ * truncated tree as if it were the real one.
+ */
+const walk = (members, parentPath, acc) => {
+    for (const member of members) {
+        const name = memberName(member);
+        const memberPath = parentPath ? `${parentPath}/${name}` : name;
+        if (!isSafeSegment(name) && !acc.nameRefusal)
+            acc.nameRefusal = {
+                code: 400,
+                status: 'failure',
+                message: `Invalid member name: '${name}'. Member names must be single path segments (no '/', '\\', '..').`
+            };
+        acc.entries++;
+        if (member.type === 'folder') {
+            walk(member.members, memberPath, acc);
+            continue;
+        }
+        const bytes = memberBytes(member);
+        acc.totalBytes += bytes;
+        if (bytes > acc.largest.bytes)
+            acc.largest = { path: memberPath, bytes };
+    }
+};
+/**
+ * Measures a tree without touching a drive.
+ *
+ * Every member is counted, whatever its name: this answers "how big is this
+ * tree", and a caller that also needs the names checked is `checkDeployTree`.
+ */
+export const measureDeployTree = (members) => {
+    const acc = emptyWalk();
+    walk(members, '', acc);
+    return {
+        entries: acc.entries,
+        totalBytes: acc.totalBytes,
+        largest: acc.largest
+    };
+};
+/**
+ * The refusal a file tree earns, or `null` when it can be written.
+ *
+ * Names are checked first, then the dimensions in a fixed order - entries,
+ * total, single file - so a tree breaching two of them is refused for the same
+ * one every time, which is what lets a caller key on the message and a test pin
+ * it.
+ *
+ * `limits` defaults to `DEPLOY_LIMITS`; a host may pass its own, stricter set.
+ */
+export const checkDeployTree = (members, limits = DEPLOY_LIMITS) => {
+    const measured = emptyWalk();
+    walk(members, '', measured);
+    if (measured.nameRefusal)
+        return measured.nameRefusal;
+    if (measured.entries > limits.entries)
+        return {
+            code: 413,
+            status: 'failure',
+            message: `The file tree exceeds the deploy limit: ${measured.entries} entries (maximum ${limits.entries}).`
+        };
+    if (measured.totalBytes > limits.totalBytes)
+        return {
+            code: 413,
+            status: 'failure',
+            message: `The file tree exceeds the deploy limit: ${describeSize(measured.totalBytes)} (maximum ${describeSize(limits.totalBytes)}).`
+        };
+    if (measured.largest.bytes > limits.fileBytes)
+        return {
+            code: 413,
+            status: 'failure',
+            message: `A file in the tree exceeds the deploy limit: ${measured.largest.path} is ${describeSize(measured.largest.bytes)} (maximum ${describeSize(limits.fileBytes)} per file).`
+        };
+    return null;
+};
+/**
+ * The tree's shape, as the wire format states it.
+ *
+ * A port of `isFileTree` from `@sasjs/utils`, which is what sasjs/server
+ * validates with: a tree is an object with a `members` array, and every member
+ * is a folder with its own members, or a service/file with a string `code` and
+ * a string `name`. Anything else is the `400` the routes already answer.
+ */
+export const isDeployTree = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const members = value.members;
+    return Array.isArray(members) && members.every(isDeployMember);
+};
+const isDeployMember = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const member = value;
+    if (typeof member.name !== 'string')
+        return false;
+    if (member.type === 'folder')
+        return Array.isArray(member.members) && member.members.every(isDeployMember);
+    if (member.type === 'service' || member.type === 'file')
+        return typeof member.code === 'string';
+    return false;
+};
+/**
+ * Deploys a tree into `appLoc`, or refuses without writing.
+ *
+ * The order is the promise: shape, then containment, then the cap and the names,
+ * and only then the first write. `appLoc` is caller-supplied and every segment
+ * must stay a segment, so it is resolved against the drive root and refused when
+ * it leaves it - joined naively, a `..` would write outside the drive.
+ *
+ * A write that fails part-way answers the deploy routes' `500`; the tree before
+ * the failure is already on the drive, which the message does not hide.
+ */
+export const deployTree = async (store, appLoc, tree, limits = DEPLOY_LIMITS) => {
+    if (!isDeployTree(tree))
+        throw new ApiError(400, 'Provided not supported data format.', {
+            status: 'failure',
+            message: 'Provided not supported data format.'
+        });
+    const root = normaliseDrivePath(appLoc);
+    if (root === null)
+        throw new ApiError(400, 'appLoc cannot be outside drive.', {
+            status: 'failure',
+            message: 'appLoc cannot be outside drive.'
+        });
+    const refusal = checkDeployTree(tree.members, limits);
+    // the body is the envelope WITHOUT the refusal's own `code`: that field is
+    // how a host turns the refusal into a status, and it is not sent
+    if (refusal)
+        throw new ApiError(refusal.code, refusal.message, {
+            status: refusal.status,
+            message: refusal.message
+        });
+    try {
+        await writeMembers(store, tree.members, root);
+    }
+    catch {
+        throw new ApiError(500, 'Deployment failed!', {
+            status: 'failure',
+            message: 'Deployment failed!'
+        });
+    }
+};
+/** Writes every member under `parentPath`, depth first. */
+const writeMembers = async (store, members, parentPath) => {
+    for (const member of members) {
+        const path = `${parentPath}/${memberName(member)}`;
+        if (member.type === 'folder') {
+            await store.mkdirp(path);
+            await writeMembers(store, member.members, path);
+            continue;
+        }
+        await store.write(path, member.type === 'file' ? decodeBase64(member.code) : member.code);
+    }
+};

package/build/esm/drive/service.d.ts

@@ -37,6 +37,14 @@ export interface DriveService {
     rmdir(folderPath: string): Promise<DriveResult>;
     rename(oldPath: string, newPath: string): Promise<DriveResult>;
     tree(folderPath?: string): Promise<DriveTree>;
+    /**
+     * Writes a whole tree under `appLoc`, or refuses without writing.
+     *
+     * `tree` is `unknown` on purpose: the wire payload is the caller's JSON, and
+     * the shape is one of the things this decides - a mistyped tree earns the
+     * routes' `400` rather than a crash in a host that trusted it.
+     */
+    deploy(appLoc: string, tree: unknown): Promise<DriveResult>;
 }
 export declare const createDriveService: (store: DriveStore) => DriveService;
 //# sourceMappingURL=service.d.ts.map

package/build/esm/drive/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/drive/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAWvD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,QAAQ,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAChD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC7E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC9C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC9D,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CAC9C;AAqBD,eAAO,MAAM,kBAAkB,GAAI,OAAO,UAAU,KAAG,YAoJtD,CAAA"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/drive/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAYvD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,QAAQ,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAChD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC7E,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC9C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/C,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC9D,IAAI,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IAC7C;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CAC5D;AAqBD,eAAO,MAAM,kBAAkB,GAAI,OAAO,UAAU,KAAG,YA0JtD,CAAA"}

package/build/esm/drive/service.js

@@ -1,4 +1,5 @@
 import { ApiError } from '../types.js';
+import { deployTree } from './deploy.js';
 import { basename, checkFilePath, dirname, hasBlockedExtension, isRoot, normaliseDrivePath } from './paths.js';
 /** A path a file operation may act on, or the refusal the operation answers. */
 const filePath = (input, outside) => {
@@ -142,6 +143,10 @@ export const createDriveService = (store) => {
             if (!stat.directory)
                 throw new ApiError(400, 'Not a Folder.');
             return { status: 'success', tree: await treeOf(path) };
+        },
+        async deploy(appLoc, tree) {
+            await deployTree(store, appLoc, tree);
+            return { status: 'success' };
         }
     };
 };

package/build/esm/host/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/host/dispatch.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAGnD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,oFAAoF;IACpF,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;IACtD;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,YAAY,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAsCD,eAAO,MAAM,QAAQ,GACnB,UAAU,QAAQ,EAClB,SAAS,MAAM,EACf,UAAS,UAAe,KACvB,OAAO,CAAC,WAAW,CAqHrB,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,EAiBlC,CAAA"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/host/dispatch.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAInD,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,oFAAoF;IACpF,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;IACtD;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB;IACnB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,YAAY,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAsCD,eAAO,MAAM,QAAQ,GACnB,UAAU,QAAQ,EAClB,SAAS,MAAM,EACf,UAAS,UAAe,KACvB,OAAO,CAAC,WAAW,CAsIrB,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,EAkBlC,CAAA"}

package/build/esm/host/dispatch.js

@@ -1,5 +1,6 @@
 import { routeById } from '../routes/index.js';
 import { ApiError } from '../types.js';
+import { DEPLOY_SUCCESS } from '../drive/deploy.js';
 /**
  * The parameters the table marks required, checked before the handler runs.
  *
@@ -126,10 +127,21 @@ export const dispatch = async (services, routeId, request = {}) => {
                 status: 200,
                 body: await drive.rename(String(request.body?.oldPath || ''), String(request.body?.newPath || ''))
             };
+        case 'POST /SASjsApi/drive/deploy': {
+            // `streamWebFolder` is the host's: publishing an app stream is not a drive
+            // operation, and a host that has no app stream ignores it.
+            await drive.deploy(String(body.appLoc ?? ''), body.fileTree);
+            return { status: 200, body: DEPLOY_SUCCESS };
+        }
         case 'GET /SASjsApi/drive/filetree':
             return { status: 200, body: await drive.tree(query._folderPath) };
-        default:
-            throw new ApiError(501, `This package has no handler for ${routeId}.`);
+        default: {
+            // The reason the table carries travels with the refusal: a host developer
+            // reading a 501 wants to know what the operation waits on, not only that
+            // it is missing.
+            const reason = routeById(routeId)?.reason;
+            throw new ApiError(501, `This package has no handler for ${routeId}.${reason ? ` ${reason}` : ''}`);
+        }
     }
 };
 /** Whether a route is one `dispatch` can answer today. */
@@ -143,6 +155,7 @@ export const HANDLED_ROUTES = [
     'DELETE /SASjsApi/drive/folder',
     'POST /SASjsApi/drive/rename',
     'GET /SASjsApi/drive/filetree',
+    'POST /SASjsApi/drive/deploy',
     'POST /SASjsApi/auth/token',
     'POST /SASjsApi/auth/refresh',
     'POST /SASjsApi/auth/logout',

package/build/esm/index.d.ts

@@ -16,6 +16,8 @@
 export * from './types.js';
 export { normaliseDrivePath, hasBlockedExtension, dirname, basename, isRoot } from './drive/paths.js';
 export { createDriveService } from './drive/service.js';
+export { DEPLOY_LIMITS, DEPLOY_PAYLOAD_BYTES, DEPLOY_SUCCESS, checkDeployTree, decodeBase64, deployTree, isDeployTree, measureDeployTree } from './drive/deploy.js';
+export type { DeployLimits, DeployMeasurements, DeployMember, DeployRefusal, DeployTree } from './drive/deploy.js';
 export type { DriveService, DriveResult, DriveListing, DriveFile, DriveTree } from './drive/service.js';
 export { MemoryDriveStore } from './drive/memory-store.js';
 export { ROUTES, routeById, findRoute } from './routes/index.js';

package/build/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,OAAO,EACP,QAAQ,EACR,MAAM,EACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,YAAY,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACd,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,OAAO,EACP,SAAS,EACV,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACzD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,cAAc,YAAY,CAAA;AAC1B,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,OAAO,EACP,QAAQ,EACR,MAAM,EACP,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,iBAAiB,EAClB,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,UAAU,EACX,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAC7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,YAAY,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACd,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,OAAO,EACP,SAAS,EACV,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACzD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA"}

package/build/esm/index.js

@@ -16,6 +16,7 @@
 export * from './types.js';
 export { normaliseDrivePath, hasBlockedExtension, dirname, basename, isRoot } from './drive/paths.js';
 export { createDriveService } from './drive/service.js';
+export { DEPLOY_LIMITS, DEPLOY_PAYLOAD_BYTES, DEPLOY_SUCCESS, checkDeployTree, decodeBase64, deployTree, isDeployTree, measureDeployTree } from './drive/deploy.js';
 export { MemoryDriveStore } from './drive/memory-store.js';
 export { ROUTES, routeById, findRoute } from './routes/index.js';
 export { OVERLAY, TAG_CAPABILITIES } from './routes/overlay.js';

package/build/esm/routes/generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../../src/routes/generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,gBAAgB,EAAE,cAAc,EAirD5C,CAAA"}
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../../src/routes/generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,gBAAgB,EAAE,cAAc,EAyrD5C,CAAA"}

package/build/esm/routes/generated.js

@@ -469,6 +469,10 @@ export const GENERATED_ROUTES = [
                 status: 400,
                 description: 'Invalid Format'
             },
+            {
+                status: 413,
+                description: 'File tree exceeds the deploy limit'
+            },
             {
                 status: 500,
                 description: 'Execution Error'
@@ -499,6 +503,10 @@ export const GENERATED_ROUTES = [
                 status: 400,
                 description: 'Invalid Format'
             },
+            {
+                status: 413,
+                description: 'File tree exceeds the deploy limit'
+            },
             {
                 status: 500,
                 description: 'Execution Error'

package/build/esm/routes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/routes/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAA;AAkDvD,eAAO,MAAM,MAAM,EAAE,KAAK,EAAgC,CAAA;AAW1D,4EAA4E;AAC5E,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,KAAG,KAAK,GAAG,SAAyB,CAAA;AAExE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAA;IACZ,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAgCD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,MAAM,EACd,MAAM,MAAM,KACX,UAAU,GAAG,SAuBf,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/routes/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAiB,MAAM,aAAa,CAAA;AA4DvD,eAAO,MAAM,MAAM,EAAE,KAAK,EAAgC,CAAA;AAW1D,4EAA4E;AAC5E,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,KAAG,KAAK,GAAG,SAAyB,CAAA;AAExE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAA;IACZ,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAgCD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,MAAM,EACd,MAAM,MAAM,KACX,UAAU,GAAG,SAuBf,CAAA"}

package/build/esm/routes/index.js

@@ -10,7 +10,12 @@
 import { GENERATED_ROUTES } from './generated.js';
 import { OVERLAY, TAG_CAPABILITIES } from './overlay.js';
 const merge = (generated) => {
-    const overlay = OVERLAY[generated.id] || {};
+    const overlay = OVERLAY[generated.id];
+    // Every operation states its decision. A route with no entry is a route
+    // nobody has looked at, which reads exactly like a route that is about to be
+    // done - so it fails the build instead, and the message says what to add.
+    if (!overlay)
+        throw new Error(`src/routes/overlay.ts has no entry for ${generated.id}. Every operation states whether this package implements it and, when it does not, the reason it does not: add \`{ implemented: false, reason: '...' }\` until a handler exists.`);
     const documented = new Map(generated.responses.map((r) => [r.status, r.description]));
     // The document states the statuses and the overlay only annotates the ones a
     // client keys a body on. Naming a status the document does not state is a
@@ -43,7 +48,8 @@ const merge = (generated) => {
         responses,
         hostResponses: overlay.hostResponses || [],
         capabilities: overlay.capabilities || TAG_CAPABILITIES[generated.tag] || [],
-        implemented: overlay.implemented === true
+        implemented: overlay.implemented,
+        ...(overlay.implemented ? {} : { reason: overlay.reason })
     };
 };
 export const ROUTES = GENERATED_ROUTES.map(merge);

package/build/esm/routes/overlay.d.ts

@@ -14,7 +14,16 @@
  *     server does not send;
  *   - which capability the route needs, so a host can answer 501 with a reason
  *     instead of 404 with none;
- *   - whether this package implements it yet, so "not done" is visible.
+ *   - whether this package implements it and, when it does not, what the
+ *     operation is waiting on.
+ *
+ * EVERY operation in the document has an entry, and the type carries the rule:
+ * `implemented: true`, or `implemented: false` with the `reason` it is not. An
+ * operation with no entry is a build failure (`src/routes/index.ts`), because
+ * silence is indistinguishable from "nobody has looked at this yet" - which is
+ * the state this file exists to remove. The reason is also what a 501 carries
+ * to whoever asked (`src/host/dispatch.ts`), so the answer names the dependency
+ * rather than the absence.
  *
  * The statuses come from the document, and an overlay body is attached to the
  * status it belongs to: naming a status the document does not state is a build
@@ -23,9 +32,9 @@
  * re-vendored here.
  */
 import type { Capability, HttpMethod } from '../types.js';
-export interface RouteOverlay {
+/** The annotations both states of an entry can carry. */
+interface OverlayFields {
     capabilities?: Capability[];
-    implemented?: boolean;
     /**
      * Statuses the document states that this package cannot send because they are
      * the host's to send: an account lockout is the host's login limiter, a
@@ -41,9 +50,23 @@ export interface RouteOverlay {
      */
     responses?: Record<number, unknown>;
 }
+/**
+ * One operation's decision: carried here, or carried by the host.
+ *
+ * A union rather than an optional field, so a route marked unimplemented
+ * without saying why does not compile. The reason is the point of the entry -
+ * "not done yet" on its own tells a reader nothing they can act on.
+ */
+export type RouteOverlay = OverlayFields & ({
+    implemented: true;
+} | {
+    implemented: false;
+    reason: string;
+});
 /** The default capability for each tag, overridden per route where it differs. */
 export declare const TAG_CAPABILITIES: Record<string, Capability[]>;
 export declare const OVERLAY: Record<string, RouteOverlay>;
 /** Every method the table may state, in the order a diff reads best. */
 export declare const METHODS: HttpMethod[];
+export {};
 //# sourceMappingURL=overlay.d.ts.map

package/build/esm/routes/overlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/routes/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEzD,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,UAAU,EAAE,CAAA;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAczD,CAAA;AAYD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA6FhD,CAAA;AAED,wEAAwE;AACxE,eAAO,MAAM,OAAO,EAAE,UAAU,EAA8C,CAAA"}
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/routes/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGzD,yDAAyD;AACzD,UAAU,aAAa;IACrB,YAAY,CAAC,EAAE,UAAU,EAAE,CAAA;IAC3B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,GACtC,CAAC;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,WAAW,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAElE,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,CAczD,CAAA;AAiDD,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAmOhD,CAAA;AAED,wEAAwE;AACxE,eAAO,MAAM,OAAO,EAAE,UAAU,EAA8C,CAAA"}