@sasjs/api 0.4.0 → 0.6.0

package/build/cjs/corpus/drive.js

@@ -8,6 +8,12 @@ const success = { status: 'success' };
  * host that does not have one. An explicit byte array is both.
  */
 const bytes = (...values) => Uint8Array.from(values);
+/** A flat tree of `count` empty file members, for the cap's entry dimension. */
+const manyMembers = (count) => Array.from({ length: count }, (_, at) => ({
+    name: `f${at}.txt`,
+    type: 'file',
+    code: ''
+}));
 exports.DRIVE_CORPUS = [
     {
         id: 'create-file',
@@ -297,6 +303,119 @@ exports.DRIVE_CORPUS = [
             }
         }
     },
+    {
+        id: 'deploy-tree',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'writes a whole tree under the appLoc it names',
+        request: {
+            body: {
+                appLoc: '/Public/apps/demo',
+                fileTree: {
+                    members: [
+                        {
+                            name: 'services',
+                            type: 'folder',
+                            members: [{ name: 'run', type: 'service', code: '%put hi;' }]
+                        },
+                        { name: 'index.html', type: 'file', code: 'PGgxPkhlbGxvPC9oMT4=' }
+                    ]
+                }
+            }
+        },
+        expect: {
+            status: 200,
+            body: {
+                status: 'success',
+                message: 'Files deployed successfully to @sasjs/server.'
+            }
+        }
+    },
+    {
+        id: 'deploy-refused-by-entry-count',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses a tree over the entry cap, naming the figure and the cap',
+        request: {
+            body: {
+                appLoc: '/Public/apps/many',
+                fileTree: { members: manyMembers(10001) }
+            }
+        },
+        expect: {
+            status: 413,
+            body: {
+                status: 'failure',
+                message: 'The file tree exceeds the deploy limit: 10001 entries (maximum 10000).'
+            },
+            error: 'The file tree exceeds the deploy limit: 10001 entries (maximum 10000).'
+        }
+    },
+    {
+        id: 'deploy-refused-by-name',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses a member name that would escape the deployment root',
+        request: {
+            body: {
+                appLoc: '/Public/apps/hostile',
+                fileTree: {
+                    members: [{ name: '../escape', type: 'service', code: '%put hi;' }]
+                }
+            }
+        },
+        expect: {
+            status: 400,
+            body: {
+                status: 'failure',
+                message: "Invalid member name: '../escape.sas'. Member names must be single path segments (no '/', '\\', '..')."
+            },
+            error: "Invalid member name: '../escape.sas'. Member names must be single path segments (no '/', '\\', '..')."
+        }
+    },
+    {
+        id: 'deploy-refused-by-shape',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses a fileTree that is not a tree, in the routes own envelope',
+        request: { body: { appLoc: '/Public/apps/bad', fileTree: { members: 1 } } },
+        expect: {
+            status: 400,
+            body: {
+                status: 'failure',
+                message: 'Provided not supported data format.'
+            },
+            error: 'Provided not supported data format.'
+        }
+    },
+    {
+        id: 'deploy-refused-by-store',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'answers the routes 500 when the drive refuses the write',
+        unwritable: true,
+        request: {
+            body: {
+                appLoc: '/Public/apps/demo',
+                fileTree: {
+                    members: [{ name: 'run', type: 'service', code: '%put hi;' }]
+                }
+            }
+        },
+        expect: {
+            status: 500,
+            body: { status: 'failure', message: 'Deployment failed!' },
+            error: 'Deployment failed!'
+        }
+    },
+    {
+        id: 'deploy-refused-outside-drive',
+        route: 'POST /SASjsApi/drive/deploy',
+        description: 'refuses an appLoc that resolves outside the drive',
+        request: {
+            body: { appLoc: '/../outside', fileTree: { members: [] } }
+        },
+        expect: {
+            status: 400,
+            body: { status: 'failure', message: 'appLoc cannot be outside drive.' },
+            error: 'appLoc cannot be outside drive.'
+        }
+    },
     {
         id: 'bytes-round-trip',
         route: 'GET /SASjsApi/drive/file',

package/build/cjs/corpus/runner.js

@@ -15,10 +15,26 @@ const types_js_1 = require("../types.js");
  * mid-flow can declare the tokens and codes it begins with.
  */
 const servicesFor = (testCase) => ({
-    drive: (0, service_js_1.createDriveService)(new memory_store_js_1.MemoryDriveStore(testCase.seed || {})),
+    drive: (0, service_js_1.createDriveService)(testCase.unwritable
+        ? new RefusingDriveStore(testCase.seed || {})
+        : new memory_store_js_1.MemoryDriveStore(testCase.seed || {})),
     identity: (0, service_js_2.createIdentityService)(new memory_store_js_2.MemoryIdentityStore(testCase.identity || fixture_js_1.DEFAULT_IDENTITY))
 });
 exports.servicesFor = servicesFor;
+/**
+ * A drive that reads but refuses every write.
+ *
+ * Only the corpus uses it: `POST /drive/deploy` answers `500` when storing
+ * fails, and a case for that answer needs a store that fails.
+ */
+class RefusingDriveStore extends memory_store_js_1.MemoryDriveStore {
+    async write() {
+        throw new Error('the store refused the write');
+    }
+    async mkdirp() {
+        throw new Error('the store refused the write');
+    }
+}
 /**
  * Runs a corpus case against the drive the case seeds itself, or against
  * services a caller supplies - that is how a host (or a failing store) is put
@@ -37,7 +53,7 @@ const runCase = async (testCase, services = (0, exports.servicesFor)(testCase))
         // only a refusal the API decided on becomes a status; anything else is a
         // broken host, and reporting it as a 500 would hide it from the suite
         if ((0, types_js_1.isApiError)(error))
-            return { status: error.status, error: error.message };
+            return { status: error.status, body: error.body, error: error.message };
         throw error;
     }
 };

package/build/cjs/drive/deploy.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deployTree = exports.isDeployTree = exports.checkDeployTree = exports.measureDeployTree = exports.decodeBase64 = exports.DEPLOY_SUCCESS = exports.DEPLOY_PAYLOAD_BYTES = exports.DEPLOY_LIMITS = void 0;
+const types_js_1 = require("../types.js");
+const paths_js_1 = require("./paths.js");
+exports.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.
+ */
+exports.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.
+ */
+exports.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. */
+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);
+};
+exports.decodeBase64 = decodeBase64;
+/** 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`.
+ */
+const measureDeployTree = (members) => {
+    const acc = emptyWalk();
+    walk(members, '', acc);
+    return {
+        entries: acc.entries,
+        totalBytes: acc.totalBytes,
+        largest: acc.largest
+    };
+};
+exports.measureDeployTree = measureDeployTree;
+/**
+ * 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.
+ */
+const checkDeployTree = (members, limits = exports.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;
+};
+exports.checkDeployTree = checkDeployTree;
+/**
+ * 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.
+ */
+const isDeployTree = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const members = value.members;
+    return Array.isArray(members) && members.every(isDeployMember);
+};
+exports.isDeployTree = isDeployTree;
+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.
+ */
+const deployTree = async (store, appLoc, tree, limits = exports.DEPLOY_LIMITS) => {
+    if (!(0, exports.isDeployTree)(tree))
+        throw new types_js_1.ApiError(400, 'Provided not supported data format.', {
+            status: 'failure',
+            message: 'Provided not supported data format.'
+        });
+    const root = (0, paths_js_1.normaliseDrivePath)(appLoc);
+    if (root === null)
+        throw new types_js_1.ApiError(400, 'appLoc cannot be outside drive.', {
+            status: 'failure',
+            message: 'appLoc cannot be outside drive.'
+        });
+    const refusal = (0, exports.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 types_js_1.ApiError(refusal.code, refusal.message, {
+            status: refusal.status,
+            message: refusal.message
+        });
+    try {
+        await writeMembers(store, tree.members, root);
+    }
+    catch {
+        throw new types_js_1.ApiError(500, 'Deployment failed!', {
+            status: 'failure',
+            message: 'Deployment failed!'
+        });
+    }
+};
+exports.deployTree = deployTree;
+/** 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' ? (0, exports.decodeBase64)(member.code) : member.code);
+    }
+};

package/build/cjs/drive/service.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDriveService = void 0;
 const types_js_1 = require("../types.js");
+const deploy_js_1 = require("./deploy.js");
 const paths_js_1 = require("./paths.js");
 /** A path a file operation may act on, or the refusal the operation answers. */
 const filePath = (input, outside) => {
@@ -145,6 +146,10 @@ const createDriveService = (store) => {
             if (!stat.directory)
                 throw new types_js_1.ApiError(400, 'Not a Folder.');
             return { status: 'success', tree: await treeOf(path) };
+        },
+        async deploy(appLoc, tree) {
+            await (0, deploy_js_1.deployTree)(store, appLoc, tree);
+            return { status: 'success' };
         }
     };
 };

package/build/cjs/host/dispatch.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HANDLED_ROUTES = exports.dispatch = void 0;
 const index_js_1 = require("../routes/index.js");
 const types_js_1 = require("../types.js");
+const deploy_js_1 = require("../drive/deploy.js");
 /**
  * The parameters the table marks required, checked before the handler runs.
  *
@@ -129,10 +130,21 @@ 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_js_1.DEPLOY_SUCCESS };
+        }
         case 'GET /SASjsApi/drive/filetree':
             return { status: 200, body: await drive.tree(query._folderPath) };
-        default:
-            throw new types_js_1.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 = (0, index_js_1.routeById)(routeId)?.reason;
+            throw new types_js_1.ApiError(501, `This package has no handler for ${routeId}.${reason ? ` ${reason}` : ''}`);
+        }
     }
 };
 exports.dispatch = dispatch;
@@ -147,6 +159,7 @@ exports.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/cjs/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.servicesFor = exports.runCase = exports.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = exports.createIdentityService = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
+exports.servicesFor = exports.runCase = exports.IDENTITY_CORPUS = exports.DRIVE_CORPUS = exports.parseIdentity = exports.IDENTITY_FORMAT = exports.DEFAULT_IDENTITY = exports.MemoryIdentityStore = exports.createIdentityService = exports.HANDLED_ROUTES = exports.dispatch = exports.TAG_CAPABILITIES = exports.OVERLAY = exports.findRoute = exports.routeById = exports.ROUTES = exports.MemoryDriveStore = exports.measureDeployTree = exports.isDeployTree = exports.deployTree = exports.decodeBase64 = exports.checkDeployTree = exports.DEPLOY_SUCCESS = exports.DEPLOY_PAYLOAD_BYTES = exports.DEPLOY_LIMITS = exports.createDriveService = exports.isRoot = exports.basename = exports.dirname = exports.hasBlockedExtension = exports.normaliseDrivePath = void 0;
 /**
  * `@sasjs/api` - the SASjs Server API described once.
  *
@@ -39,6 +39,15 @@ Object.defineProperty(exports, "basename", { enumerable: true, get: function ()
 Object.defineProperty(exports, "isRoot", { enumerable: true, get: function () { return paths_js_1.isRoot; } });
 var service_js_1 = require("./drive/service.js");
 Object.defineProperty(exports, "createDriveService", { enumerable: true, get: function () { return service_js_1.createDriveService; } });
+var deploy_js_1 = require("./drive/deploy.js");
+Object.defineProperty(exports, "DEPLOY_LIMITS", { enumerable: true, get: function () { return deploy_js_1.DEPLOY_LIMITS; } });
+Object.defineProperty(exports, "DEPLOY_PAYLOAD_BYTES", { enumerable: true, get: function () { return deploy_js_1.DEPLOY_PAYLOAD_BYTES; } });
+Object.defineProperty(exports, "DEPLOY_SUCCESS", { enumerable: true, get: function () { return deploy_js_1.DEPLOY_SUCCESS; } });
+Object.defineProperty(exports, "checkDeployTree", { enumerable: true, get: function () { return deploy_js_1.checkDeployTree; } });
+Object.defineProperty(exports, "decodeBase64", { enumerable: true, get: function () { return deploy_js_1.decodeBase64; } });
+Object.defineProperty(exports, "deployTree", { enumerable: true, get: function () { return deploy_js_1.deployTree; } });
+Object.defineProperty(exports, "isDeployTree", { enumerable: true, get: function () { return deploy_js_1.isDeployTree; } });
+Object.defineProperty(exports, "measureDeployTree", { enumerable: true, get: function () { return deploy_js_1.measureDeployTree; } });
 var memory_store_js_1 = require("./drive/memory-store.js");
 Object.defineProperty(exports, "MemoryDriveStore", { enumerable: true, get: function () { return memory_store_js_1.MemoryDriveStore; } });
 var index_js_1 = require("./routes/index.js");

package/build/cjs/routes/generated.js

@@ -472,6 +472,10 @@ exports.GENERATED_ROUTES = [
                 status: 400,
                 description: 'Invalid Format'
             },
+            {
+                status: 413,
+                description: 'File tree exceeds the deploy limit'
+            },
             {
                 status: 500,
                 description: 'Execution Error'
@@ -502,6 +506,10 @@ exports.GENERATED_ROUTES = [
                 status: 400,
                 description: 'Invalid Format'
             },
+            {
+                status: 413,
+                description: 'File tree exceeds the deploy limit'
+            },
             {
                 status: 500,
                 description: 'Execution Error'

package/build/cjs/routes/index.js

@@ -13,7 +13,12 @@ exports.findRoute = exports.routeById = exports.ROUTES = void 0;
 const generated_js_1 = require("./generated.js");
 const overlay_js_1 = require("./overlay.js");
 const merge = (generated) => {
-    const overlay = overlay_js_1.OVERLAY[generated.id] || {};
+    const overlay = overlay_js_1.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
@@ -46,7 +51,8 @@ const merge = (generated) => {
         responses,
         hostResponses: overlay.hostResponses || [],
         capabilities: overlay.capabilities || overlay_js_1.TAG_CAPABILITIES[generated.tag] || [],
-        implemented: overlay.implemented === true
+        implemented: overlay.implemented,
+        ...(overlay.implemented ? {} : { reason: overlay.reason })
     };
 };
 exports.ROUTES = generated_js_1.GENERATED_ROUTES.map(merge);