@sasjs/api 0.4.0 → 0.5.0

package/README.md

@@ -9,9 +9,10 @@ The plan that this package implements is tracked in `sasjs/cli#1550`.
 
 ## What is in it
 
-**The route table** (`ROUTES`, `findRoute`) is every operation in the API - 31 paths, 61 operations - derived from `spec/swagger.yaml` by `npm run sync:routes`.
+**The route table** (`ROUTES`, `findRoute`) is every operation in the API, derived from `spec/swagger.yaml` by `npm run sync:routes`.
 The statuses come from that document and nowhere else: the overlay cannot add one, and an overlay entry naming a status the document does not state fails the build rather than describing a wish.
-The document cannot say everything a host needs, so the reviewed overlay adds the body each response carries, the capability a route needs, and whether this package implements it.
+The document cannot say everything a host needs, so the reviewed overlay adds the body each response carries, the capability a route needs, and the decision for the operation: `implemented: true`, or `implemented: false` with the reason it is not.
+Every operation has an entry - the table refuses one that does not, so "nobody has looked at this yet" cannot hide as silence - and a host asked for an unimplemented route answers `501` carrying that reason.
 Where the document is wrong, it is corrected in `sasjs/server` and re-vendored here - never worked around in the overlay.
 
 ### Regenerating the vendored document
@@ -67,7 +68,7 @@ Both hosts answer with the same shapes:
 
 - a successful write is `{ status: 'success' }`;
 - a refusal is an `ApiError` carrying `status` and `message`, which a host renders as its own transport requires (`res.status(code).send(...)` on the server, a `Response` in the worker);
-- an operation this package has no handler for is `501`, naming the operation - not a `404` that looks like a typo in the caller;
+- an operation this package has no handler for is `501`, naming the operation and the reason it is not implemented here - not a `404` that looks like a typo in the caller;
 - an operation the API does not have is `404`.
 
 ## Guarantees the build enforces
@@ -75,17 +76,14 @@ Both hosts answer with the same shapes:
 - **No runtime imports.** `src` compiles with `"types": []` and `lib: ES2020`, so a `Buffer`, a `process` or a `document` reference fails `npm run build` rather than a worker at run time. Nothing node-shaped can creep into the browser path.
 - **No Node-only APIs in the published surface.** Storage is a port (`DriveStore`), and `MemoryDriveStore` ships so a host without a filesystem has an implementation to use.
 - **Three builds from one source.** `build/cjs` for node, `build/esm` for a bundler (with `build/esm` marked `"type": "module"` by the build script so Node runs it as ESM), and `build/browser.js` - a classic-worker IIFE that assigns `self.SASjsApi` - for a service worker that has only `importScripts`. CI loads all three.
-- **The table cannot rot silently.** `npm run check:routes` fails when `src/routes/generated.ts` and `spec/swagger.yaml` disagree, and the module throws at import when an overlay entry names an operation the document does not have.
+- **The table cannot rot silently.** `npm run check:routes` fails when `src/routes/generated.ts` and `spec/swagger.yaml` disagree, and the module throws at import when an overlay entry names an operation the document does not have, or when an operation has no entry at all.
 
 ## Status
 
-Implemented, exercised by 55 corpus cases:
+`src/routes/overlay.ts` is the status, and the table refuses an operation that is not in it: each entry is `implemented: true` - the package answers the route - or `implemented: false` with the dependency it waits on.
+`ROUTES.filter((route) => !route.implemented)` is therefore the list of what is left, each row naming the port, host decision or plan it is waiting for; a host asked for one answers `501` with that reason.
 
-- the nine drive handlers - file read/write/replace/delete, folder read/create/delete, rename, file tree;
-- the seven sign-in handlers - `auth/token`, `auth/refresh`, `auth/logout`, `SASLogon/login`, `SASLogon/authorize`, `SASLogon/logout`, and the session read.
-
-Not implemented yet, in the order the plan sets: the rest of identity (`user`, `group`, `permission`, `auth/updatePassword`, `info/authorizedRoutes`), the session record behind `log`/`output`, program execution (`stp`, `code`), `drive/deploy` and its size cap, and the admin routes.
-`src/routes/overlay.ts` is the list: an operation with `implemented: true` has a handler, and everything else answers `501` with its own name.
+Every implemented operation is exercised by the corpus, and a handler without a case fails `spec/corpus-parity.spec.ts` - so "implemented" and "proven against the contract" are the same list rather than two that drift.
 
 A status the document states but only a host can send - an account lockout (`429`), a provider failure (`500`), a session-store failure - is marked `hostResponses` in the overlay. It stays in the document, because a client still receives it, and is excluded from the parity check, whose other side is what this package answers; the host's own suite pins it.
 
@@ -107,9 +105,9 @@ npm run check:routes  # the generated table matches spec/swagger.yaml
 npm run lint
 ```
 
-Refreshing the API surface: regenerate `api/public/swagger.yaml` in `sasjs/server` (`npm run swagger`), copy it to `spec/swagger.yaml`, and run `npm run sync:routes`. Review the diff - a new operation needs an overlay entry before a host can say whether it implements it.
+Refreshing the API surface: regenerate `api/public/swagger.yaml` in `sasjs/server` (`npm run swagger`), copy it to `spec/swagger.yaml`, and run `npm run sync:routes`. Review the diff: a new operation needs an overlay entry, and the table refuses to build without one.
 
-Re-vendoring is a two-repository change and the server half merges first: the document is only true once the controllers it is generated from answer what it states, so a copy taken from an unmerged server branch describes a server that does not exist yet. The current body is the output of `npm run swagger` on sasjs/server#541, which is where the sign-in statuses were added; regenerating before that lands would drop them.
+Re-vendoring is a two-repository change and the server half merges first: the document is only true once the controllers it is generated from answer what it states, so a copy taken from an unmerged server branch describes a server that does not exist yet. Take the copy from a released tag of `sasjs/server` rather than from its `main`, and the document and the code a host runs cannot disagree.
 
 ## Licence
 

package/build/browser.js

@@ -1,4 +1,4 @@
-/* @sasjs/api 0.4.0 - the SASjs Server API, for a service worker. https://github.com/sasjs/api */
+/* @sasjs/api 0.5.0 - the SASjs Server API, for a service worker. https://github.com/sasjs/api */
 "use strict";
 var SASjsApi = (() => {
   var __defProp = Object.defineProperty;
@@ -2070,6 +2070,16 @@ var SASjsApi = (() => {
     Client: ["identity"],
     Web: ["identity"]
   };
+  var IDENTITY_RECORDS = "The identity service answers the sign-in flow. User, group, permission rule, client and provider records need read and write methods on the same store, which this package does not have yet.";
+  var EDITOR = "Linting and formatting come from @sasjs/lint, which this package does not depend on. They land with the code routes so an editor has one wiring.";
+  var RUNTIME = "Starting a program needs a runtime port, which this package does not have: a host decides which languages it holds, and answers this itself until then.";
+  var SESSION_RECORD = "A triggered session's record, log, output and state belong to the runtime that ran the program, and this package has no runtime port.";
+  var HOST_CONFIG = "The body is the host's own configuration - ports, run times and providers - which a mock states for itself and this package cannot know.";
+  var PERMISSIONS = "The route inventory is the host's permission model, which this package does not hold.";
+  var HOST_OWNED = "The host owns this report: it describes the host's own process and files, which a browser build has no equivalent of.";
+  var WEB_BUNDLE = "The host serves its own web bundle; there is no API decision here for this package to answer.";
+  var DEPLOY_CAP = "Writing a whole tree in one request can exhaust the host's storage, so the deploy routes land with the size cap that bounds it.";
+  var UNPUBLISH = "Unpublishing inverts the deploy route, so the two land together.";
   var success = { status: "success" };
   var user = {
     uid: "",
@@ -2079,11 +2089,61 @@ var SASjsApi = (() => {
     needsToUpdatePassword: false
   };
   var OVERLAY = {
-    // the route inventory reports what the CALLER may use, so it needs an identity
-    // even though the rest of the Info tag needs nothing
-    "GET /SASjsApi/info/authorizedRoutes": { capabilities: ["identity"] },
-    "GET /SASjsApi/info/myAuthorizedRoutes": { capabilities: ["identity"] },
-    // the body is the file itself, so there is nothing to annotate
+    // Web - the sign-in pages the identity service answers, and the bundle itself
+    "GET /": { implemented: false, reason: WEB_BUNDLE },
+    "POST /SASLogon/login": {
+      implemented: true,
+      // The lockout and the provider failure are answered before the package is
+      // consulted (routes/web/web.ts in sasjs/server).
+      hostResponses: [429, 500],
+      responses: { 200: { loggedIn: true, user } }
+    },
+    "POST /SASLogon/authorize": {
+      implemented: true,
+      responses: { 200: { code: "" } }
+    },
+    "GET /SASLogon/logout": {
+      implemented: true,
+      hostResponses: [500],
+      responses: { 200: "OK!" }
+    },
+    // Admin - the host's own process and files
+    "GET /SASjsApi/admin/diagnostics": { implemented: false, reason: HOST_OWNED },
+    "GET /SASjsApi/admin/logs": { implemented: false, reason: HOST_OWNED },
+    "GET /SASjsApi/admin/logs/{fileName}": {
+      implemented: false,
+      reason: HOST_OWNED
+    },
+    // Auth - the token flow, plus a password change the identity store cannot write
+    "POST /SASjsApi/auth/token": {
+      implemented: true,
+      responses: { 200: { accessToken: "", refreshToken: "" } }
+    },
+    "POST /SASjsApi/auth/refresh": {
+      implemented: true,
+      responses: { 200: { accessToken: "", refreshToken: "" } }
+    },
+    "POST /SASjsApi/auth/logout": { implemented: true },
+    "PATCH /SASjsApi/auth/updatePassword": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    // Auth Config - the providers a host was started with, and an LDAP import
+    "GET /SASjsApi/authConfig": { implemented: false, reason: HOST_CONFIG },
+    "POST /SASjsApi/authConfig/synchroniseWithLDAP": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    // Client - the OAuth clients the identity store already holds for sign-in
+    "GET /SASjsApi/client": { implemented: false, reason: IDENTITY_RECORDS },
+    "POST /SASjsApi/client": { implemented: false, reason: IDENTITY_RECORDS },
+    // Code - the editor's three calls, and the runtime one
+    "POST /SASjsApi/code/execute": { implemented: false, reason: RUNTIME },
+    "POST /SASjsApi/code/trigger": { implemented: false, reason: RUNTIME },
+    "POST /SASjsApi/code/lint": { implemented: false, reason: EDITOR },
+    "POST /SASjsApi/code/format": { implemented: false, reason: EDITOR },
+    // Drive - the file and folder rules, and the three deploy routes
+    // The body is the file itself, so there is nothing to annotate
     "GET /SASjsApi/drive/file": { implemented: true },
     "POST /SASjsApi/drive/file": {
       implemented: true,
@@ -2121,60 +2181,120 @@ var SASjsApi = (() => {
       implemented: true,
       responses: { 200: { status: "success", tree: {} } }
     },
-    // The two deploy routes write a whole tree in one request. They are the only
-    // ones where a caller can exhaust the host's storage, so they carry a cap -
-    // see the plan in sasjs/cli#1550 - and they are not implemented yet.
-    "POST /SASjsApi/drive/deploy": {
-      implemented: false
-    },
+    "POST /SASjsApi/drive/deploy": { implemented: false, reason: DEPLOY_CAP },
     "POST /SASjsApi/drive/deploy/upload": {
-      implemented: false
-    },
-    // Unpublishing is the counterpart of the two above and lands with them: the
-    // document in sasjs/server states it (sasjs/server#543), so a host may answer
-    // it in the meantime, but this package cannot until the publish side it would
-    // invert is implemented here. The statuses are the document's; `404` is a pair
-    // - the registry name and the appLoc it was published from - that matches no
-    // entry, and the drive's content is deliberately left alone.
-    "DELETE /SASjsApi/drive/deploy": {
-      implemented: false
-    },
-    // The lockout and the provider failure are answered before the package is
-    // consulted (routes/web/web.ts in sasjs/server).
-    "POST /SASLogon/login": {
-      implemented: true,
-      hostResponses: [429, 500],
-      responses: { 200: { loggedIn: true, user } }
-    },
-    // The sign-in flow. The statuses are the document's; these entries state the
-    // body a client keys on, and that this package answers the operation.
-    "POST /SASjsApi/auth/token": {
-      implemented: true,
-      responses: { 200: { accessToken: "", refreshToken: "" } }
-    },
-    "POST /SASjsApi/auth/refresh": {
-      implemented: true,
-      responses: { 200: { accessToken: "", refreshToken: "" } }
-    },
-    "POST /SASjsApi/auth/logout": { implemented: true },
-    "POST /SASLogon/authorize": {
-      implemented: true,
-      responses: { 200: { code: "" } }
-    },
-    "GET /SASLogon/logout": {
-      implemented: true,
-      hostResponses: [500],
-      responses: { 200: "OK!" }
+      implemented: false,
+      reason: DEPLOY_CAP
     },
+    // `404` is a pair - the registry name and the appLoc it was published from -
+    // that matches no entry, and the drive's content is deliberately left alone.
+    "DELETE /SASjsApi/drive/deploy": {
+      implemented: false,
+      reason: UNPUBLISH
+    },
+    // Group - members and the groups themselves
+    "GET /SASjsApi/group": { implemented: false, reason: IDENTITY_RECORDS },
+    "GET /SASjsApi/group/{uid}": { implemented: false, reason: IDENTITY_RECORDS },
+    "GET /SASjsApi/group/by/groupname/{name}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "POST /SASjsApi/group": { implemented: false, reason: IDENTITY_RECORDS },
+    "POST /SASjsApi/group/{groupUid}/{userUid}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "DELETE /SASjsApi/group/{groupUid}/{userUid}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "DELETE /SASjsApi/group/{uid}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    // Info - what the host is, and what this caller may use
+    "GET /SASjsApi/info": { implemented: false, reason: HOST_CONFIG },
+    "GET /SASjsApi/info/authorizedRoutes": {
+      implemented: false,
+      // the route inventory reports what the CALLER may use, so it needs an
+      // identity even though the rest of the Info tag needs nothing
+      capabilities: ["identity"],
+      reason: PERMISSIONS
+    },
+    "GET /SASjsApi/info/myAuthorizedRoutes": {
+      implemented: false,
+      capabilities: ["identity"],
+      reason: PERMISSIONS
+    },
+    // Permission - the rules the inventory above is derived from
+    "GET /SASjsApi/permission": { implemented: false, reason: IDENTITY_RECORDS },
+    "POST /SASjsApi/permission": { implemented: false, reason: IDENTITY_RECORDS },
+    "PATCH /SASjsApi/permission/{uid}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "DELETE /SASjsApi/permission/{uid}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    // Session - the caller's own session, then the record behind a triggered one
     "GET /SASjsApi/session": {
       implemented: true,
       responses: { 200: user }
+    },
+    "GET /SASjsApi/session/{sessionId}": {
+      implemented: false,
+      reason: SESSION_RECORD
+    },
+    "GET /SASjsApi/session/{sessionId}/log": {
+      implemented: false,
+      reason: SESSION_RECORD
+    },
+    "GET /SASjsApi/session/{sessionId}/output": {
+      implemented: false,
+      reason: SESSION_RECORD
+    },
+    "GET /SASjsApi/session/{sessionId}/state": {
+      implemented: false,
+      reason: SESSION_RECORD
+    },
+    // STP - a stored program, on the runtime port
+    "GET /SASjsApi/stp/execute": { implemented: false, reason: RUNTIME },
+    "POST /SASjsApi/stp/execute": { implemented: false, reason: RUNTIME },
+    "POST /SASjsApi/stp/trigger": { implemented: false, reason: RUNTIME },
+    // User - the accounts the identity store already holds for sign-in
+    "GET /SASjsApi/user": { implemented: false, reason: IDENTITY_RECORDS },
+    "GET /SASjsApi/user/{uid}": { implemented: false, reason: IDENTITY_RECORDS },
+    "GET /SASjsApi/user/by/username/{username}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "POST /SASjsApi/user": { implemented: false, reason: IDENTITY_RECORDS },
+    "PATCH /SASjsApi/user/{uid}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "PATCH /SASjsApi/user/by/username/{username}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "DELETE /SASjsApi/user/{uid}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
+    },
+    "DELETE /SASjsApi/user/by/username/{username}": {
+      implemented: false,
+      reason: IDENTITY_RECORDS
     }
   };
 
   // src/routes/index.ts
   var merge = (generated) => {
-    const overlay = OVERLAY[generated.id] || {};
+    const overlay = OVERLAY[generated.id];
+    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])
     );
@@ -2203,7 +2323,8 @@ var SASjsApi = (() => {
       responses,
       hostResponses: overlay.hostResponses || [],
       capabilities: overlay.capabilities || TAG_CAPABILITIES[generated.tag] || [],
-      implemented: overlay.implemented === true
+      implemented: overlay.implemented,
+      ...overlay.implemented ? {} : { reason: overlay.reason }
     };
   };
   var ROUTES = GENERATED_ROUTES.map(merge);
@@ -2367,8 +2488,13 @@ var SASjsApi = (() => {
         };
       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: {
+        const reason = routeById(routeId)?.reason;
+        throw new ApiError(
+          501,
+          `This package has no handler for ${routeId}.${reason ? ` ${reason}` : ""}`
+        );
+      }
     }
   };
   var HANDLED_ROUTES = [

package/build/cjs/host/dispatch.js

@@ -131,8 +131,13 @@ const dispatch = async (services, routeId, request = {}) => {
             };
         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;

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);

package/build/cjs/routes/overlay.js

@@ -17,6 +17,23 @@ exports.TAG_CAPABILITIES = {
     Client: ['identity'],
     Web: ['identity']
 };
+/**
+ * Why a block of operations is not implemented here.
+ *
+ * One per dependency rather than one per route: the reason states what the
+ * operation waits on, and thirty copies of the same sentence would say the same
+ * thing thirty times.
+ */
+const IDENTITY_RECORDS = 'The identity service answers the sign-in flow. User, group, permission rule, client and provider records need read and write methods on the same store, which this package does not have yet.';
+const EDITOR = 'Linting and formatting come from @sasjs/lint, which this package does not depend on. They land with the code routes so an editor has one wiring.';
+const RUNTIME = 'Starting a program needs a runtime port, which this package does not have: a host decides which languages it holds, and answers this itself until then.';
+const SESSION_RECORD = "A triggered session's record, log, output and state belong to the runtime that ran the program, and this package has no runtime port.";
+const HOST_CONFIG = "The body is the host's own configuration - ports, run times and providers - which a mock states for itself and this package cannot know.";
+const PERMISSIONS = "The route inventory is the host's permission model, which this package does not hold.";
+const HOST_OWNED = "The host owns this report: it describes the host's own process and files, which a browser build has no equivalent of.";
+const WEB_BUNDLE = 'The host serves its own web bundle; there is no API decision here for this package to answer.';
+const DEPLOY_CAP = "Writing a whole tree in one request can exhaust the host's storage, so the deploy routes land with the size cap that bounds it.";
+const UNPUBLISH = 'Unpublishing inverts the deploy route, so the two land together.';
 const success = { status: 'success' };
 const user = {
     uid: '',
@@ -26,11 +43,61 @@ const user = {
     needsToUpdatePassword: false
 };
 exports.OVERLAY = {
-    // the route inventory reports what the CALLER may use, so it needs an identity
-    // even though the rest of the Info tag needs nothing
-    'GET /SASjsApi/info/authorizedRoutes': { capabilities: ['identity'] },
-    'GET /SASjsApi/info/myAuthorizedRoutes': { capabilities: ['identity'] },
-    // the body is the file itself, so there is nothing to annotate
+    // Web - the sign-in pages the identity service answers, and the bundle itself
+    'GET /': { implemented: false, reason: WEB_BUNDLE },
+    'POST /SASLogon/login': {
+        implemented: true,
+        // The lockout and the provider failure are answered before the package is
+        // consulted (routes/web/web.ts in sasjs/server).
+        hostResponses: [429, 500],
+        responses: { 200: { loggedIn: true, user } }
+    },
+    'POST /SASLogon/authorize': {
+        implemented: true,
+        responses: { 200: { code: '' } }
+    },
+    'GET /SASLogon/logout': {
+        implemented: true,
+        hostResponses: [500],
+        responses: { 200: 'OK!' }
+    },
+    // Admin - the host's own process and files
+    'GET /SASjsApi/admin/diagnostics': { implemented: false, reason: HOST_OWNED },
+    'GET /SASjsApi/admin/logs': { implemented: false, reason: HOST_OWNED },
+    'GET /SASjsApi/admin/logs/{fileName}': {
+        implemented: false,
+        reason: HOST_OWNED
+    },
+    // Auth - the token flow, plus a password change the identity store cannot write
+    'POST /SASjsApi/auth/token': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/refresh': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/logout': { implemented: true },
+    'PATCH /SASjsApi/auth/updatePassword': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Auth Config - the providers a host was started with, and an LDAP import
+    'GET /SASjsApi/authConfig': { implemented: false, reason: HOST_CONFIG },
+    'POST /SASjsApi/authConfig/synchroniseWithLDAP': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Client - the OAuth clients the identity store already holds for sign-in
+    'GET /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
+    // Code - the editor's three calls, and the runtime one
+    'POST /SASjsApi/code/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/code/trigger': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/code/lint': { implemented: false, reason: EDITOR },
+    'POST /SASjsApi/code/format': { implemented: false, reason: EDITOR },
+    // Drive - the file and folder rules, and the three deploy routes
+    // The body is the file itself, so there is nothing to annotate
     'GET /SASjsApi/drive/file': { implemented: true },
     'POST /SASjsApi/drive/file': {
         implemented: true,
@@ -68,54 +135,110 @@ exports.OVERLAY = {
         implemented: true,
         responses: { 200: { status: 'success', tree: {} } }
     },
-    // The two deploy routes write a whole tree in one request. They are the only
-    // ones where a caller can exhaust the host's storage, so they carry a cap -
-    // see the plan in sasjs/cli#1550 - and they are not implemented yet.
-    'POST /SASjsApi/drive/deploy': {
-        implemented: false
-    },
+    'POST /SASjsApi/drive/deploy': { implemented: false, reason: DEPLOY_CAP },
     'POST /SASjsApi/drive/deploy/upload': {
-        implemented: false
-    },
-    // Unpublishing is the counterpart of the two above and lands with them: the
-    // document in sasjs/server states it (sasjs/server#543), so a host may answer
-    // it in the meantime, but this package cannot until the publish side it would
-    // invert is implemented here. The statuses are the document's; `404` is a pair
-    // - the registry name and the appLoc it was published from - that matches no
-    // entry, and the drive's content is deliberately left alone.
-    'DELETE /SASjsApi/drive/deploy': {
-        implemented: false
-    },
-    // The lockout and the provider failure are answered before the package is
-    // consulted (routes/web/web.ts in sasjs/server).
-    'POST /SASLogon/login': {
-        implemented: true,
-        hostResponses: [429, 500],
-        responses: { 200: { loggedIn: true, user } }
-    },
-    // The sign-in flow. The statuses are the document's; these entries state the
-    // body a client keys on, and that this package answers the operation.
-    'POST /SASjsApi/auth/token': {
-        implemented: true,
-        responses: { 200: { accessToken: '', refreshToken: '' } }
-    },
-    'POST /SASjsApi/auth/refresh': {
-        implemented: true,
-        responses: { 200: { accessToken: '', refreshToken: '' } }
-    },
-    'POST /SASjsApi/auth/logout': { implemented: true },
-    'POST /SASLogon/authorize': {
-        implemented: true,
-        responses: { 200: { code: '' } }
-    },
-    'GET /SASLogon/logout': {
-        implemented: true,
-        hostResponses: [500],
-        responses: { 200: 'OK!' }
+        implemented: false,
+        reason: DEPLOY_CAP
     },
+    // `404` is a pair - the registry name and the appLoc it was published from -
+    // that matches no entry, and the drive's content is deliberately left alone.
+    'DELETE /SASjsApi/drive/deploy': {
+        implemented: false,
+        reason: UNPUBLISH
+    },
+    // Group - members and the groups themselves
+    'GET /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/group/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/group/by/groupname/{name}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'POST /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/group/{groupUid}/{userUid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/group/{groupUid}/{userUid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/group/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Info - what the host is, and what this caller may use
+    'GET /SASjsApi/info': { implemented: false, reason: HOST_CONFIG },
+    'GET /SASjsApi/info/authorizedRoutes': {
+        implemented: false,
+        // the route inventory reports what the CALLER may use, so it needs an
+        // identity even though the rest of the Info tag needs nothing
+        capabilities: ['identity'],
+        reason: PERMISSIONS
+    },
+    'GET /SASjsApi/info/myAuthorizedRoutes': {
+        implemented: false,
+        capabilities: ['identity'],
+        reason: PERMISSIONS
+    },
+    // Permission - the rules the inventory above is derived from
+    'GET /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
+    'PATCH /SASjsApi/permission/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/permission/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Session - the caller's own session, then the record behind a triggered one
     'GET /SASjsApi/session': {
         implemented: true,
         responses: { 200: user }
+    },
+    'GET /SASjsApi/session/{sessionId}': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/log': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/output': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/state': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    // STP - a stored program, on the runtime port
+    'GET /SASjsApi/stp/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/stp/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/stp/trigger': { implemented: false, reason: RUNTIME },
+    // User - the accounts the identity store already holds for sign-in
+    'GET /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/user/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'POST /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
+    'PATCH /SASjsApi/user/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'PATCH /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/user/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
     }
 };
 /** Every method the table may state, in the order a diff reads best. */

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;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,CA8HrB,CAAA;AAED,0DAA0D;AAC1D,eAAO,MAAM,cAAc,EAAE,MAAM,EAiBlC,CAAA"}

package/build/esm/host/dispatch.js

@@ -128,8 +128,13 @@ export const dispatch = async (services, routeId, request = {}) => {
             };
         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. */

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;AAEzD,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,CAkNhD,CAAA;AAED,wEAAwE;AACxE,eAAO,MAAM,OAAO,EAAE,UAAU,EAA8C,CAAA"}

package/build/esm/routes/overlay.js

@@ -14,6 +14,23 @@ export const TAG_CAPABILITIES = {
     Client: ['identity'],
     Web: ['identity']
 };
+/**
+ * Why a block of operations is not implemented here.
+ *
+ * One per dependency rather than one per route: the reason states what the
+ * operation waits on, and thirty copies of the same sentence would say the same
+ * thing thirty times.
+ */
+const IDENTITY_RECORDS = 'The identity service answers the sign-in flow. User, group, permission rule, client and provider records need read and write methods on the same store, which this package does not have yet.';
+const EDITOR = 'Linting and formatting come from @sasjs/lint, which this package does not depend on. They land with the code routes so an editor has one wiring.';
+const RUNTIME = 'Starting a program needs a runtime port, which this package does not have: a host decides which languages it holds, and answers this itself until then.';
+const SESSION_RECORD = "A triggered session's record, log, output and state belong to the runtime that ran the program, and this package has no runtime port.";
+const HOST_CONFIG = "The body is the host's own configuration - ports, run times and providers - which a mock states for itself and this package cannot know.";
+const PERMISSIONS = "The route inventory is the host's permission model, which this package does not hold.";
+const HOST_OWNED = "The host owns this report: it describes the host's own process and files, which a browser build has no equivalent of.";
+const WEB_BUNDLE = 'The host serves its own web bundle; there is no API decision here for this package to answer.';
+const DEPLOY_CAP = "Writing a whole tree in one request can exhaust the host's storage, so the deploy routes land with the size cap that bounds it.";
+const UNPUBLISH = 'Unpublishing inverts the deploy route, so the two land together.';
 const success = { status: 'success' };
 const user = {
     uid: '',
@@ -23,11 +40,61 @@ const user = {
     needsToUpdatePassword: false
 };
 export const OVERLAY = {
-    // the route inventory reports what the CALLER may use, so it needs an identity
-    // even though the rest of the Info tag needs nothing
-    'GET /SASjsApi/info/authorizedRoutes': { capabilities: ['identity'] },
-    'GET /SASjsApi/info/myAuthorizedRoutes': { capabilities: ['identity'] },
-    // the body is the file itself, so there is nothing to annotate
+    // Web - the sign-in pages the identity service answers, and the bundle itself
+    'GET /': { implemented: false, reason: WEB_BUNDLE },
+    'POST /SASLogon/login': {
+        implemented: true,
+        // The lockout and the provider failure are answered before the package is
+        // consulted (routes/web/web.ts in sasjs/server).
+        hostResponses: [429, 500],
+        responses: { 200: { loggedIn: true, user } }
+    },
+    'POST /SASLogon/authorize': {
+        implemented: true,
+        responses: { 200: { code: '' } }
+    },
+    'GET /SASLogon/logout': {
+        implemented: true,
+        hostResponses: [500],
+        responses: { 200: 'OK!' }
+    },
+    // Admin - the host's own process and files
+    'GET /SASjsApi/admin/diagnostics': { implemented: false, reason: HOST_OWNED },
+    'GET /SASjsApi/admin/logs': { implemented: false, reason: HOST_OWNED },
+    'GET /SASjsApi/admin/logs/{fileName}': {
+        implemented: false,
+        reason: HOST_OWNED
+    },
+    // Auth - the token flow, plus a password change the identity store cannot write
+    'POST /SASjsApi/auth/token': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/refresh': {
+        implemented: true,
+        responses: { 200: { accessToken: '', refreshToken: '' } }
+    },
+    'POST /SASjsApi/auth/logout': { implemented: true },
+    'PATCH /SASjsApi/auth/updatePassword': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Auth Config - the providers a host was started with, and an LDAP import
+    'GET /SASjsApi/authConfig': { implemented: false, reason: HOST_CONFIG },
+    'POST /SASjsApi/authConfig/synchroniseWithLDAP': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Client - the OAuth clients the identity store already holds for sign-in
+    'GET /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/client': { implemented: false, reason: IDENTITY_RECORDS },
+    // Code - the editor's three calls, and the runtime one
+    'POST /SASjsApi/code/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/code/trigger': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/code/lint': { implemented: false, reason: EDITOR },
+    'POST /SASjsApi/code/format': { implemented: false, reason: EDITOR },
+    // Drive - the file and folder rules, and the three deploy routes
+    // The body is the file itself, so there is nothing to annotate
     'GET /SASjsApi/drive/file': { implemented: true },
     'POST /SASjsApi/drive/file': {
         implemented: true,
@@ -65,54 +132,110 @@ export const OVERLAY = {
         implemented: true,
         responses: { 200: { status: 'success', tree: {} } }
     },
-    // The two deploy routes write a whole tree in one request. They are the only
-    // ones where a caller can exhaust the host's storage, so they carry a cap -
-    // see the plan in sasjs/cli#1550 - and they are not implemented yet.
-    'POST /SASjsApi/drive/deploy': {
-        implemented: false
-    },
+    'POST /SASjsApi/drive/deploy': { implemented: false, reason: DEPLOY_CAP },
     'POST /SASjsApi/drive/deploy/upload': {
-        implemented: false
-    },
-    // Unpublishing is the counterpart of the two above and lands with them: the
-    // document in sasjs/server states it (sasjs/server#543), so a host may answer
-    // it in the meantime, but this package cannot until the publish side it would
-    // invert is implemented here. The statuses are the document's; `404` is a pair
-    // - the registry name and the appLoc it was published from - that matches no
-    // entry, and the drive's content is deliberately left alone.
-    'DELETE /SASjsApi/drive/deploy': {
-        implemented: false
-    },
-    // The lockout and the provider failure are answered before the package is
-    // consulted (routes/web/web.ts in sasjs/server).
-    'POST /SASLogon/login': {
-        implemented: true,
-        hostResponses: [429, 500],
-        responses: { 200: { loggedIn: true, user } }
-    },
-    // The sign-in flow. The statuses are the document's; these entries state the
-    // body a client keys on, and that this package answers the operation.
-    'POST /SASjsApi/auth/token': {
-        implemented: true,
-        responses: { 200: { accessToken: '', refreshToken: '' } }
-    },
-    'POST /SASjsApi/auth/refresh': {
-        implemented: true,
-        responses: { 200: { accessToken: '', refreshToken: '' } }
-    },
-    'POST /SASjsApi/auth/logout': { implemented: true },
-    'POST /SASLogon/authorize': {
-        implemented: true,
-        responses: { 200: { code: '' } }
-    },
-    'GET /SASLogon/logout': {
-        implemented: true,
-        hostResponses: [500],
-        responses: { 200: 'OK!' }
+        implemented: false,
+        reason: DEPLOY_CAP
     },
+    // `404` is a pair - the registry name and the appLoc it was published from -
+    // that matches no entry, and the drive's content is deliberately left alone.
+    'DELETE /SASjsApi/drive/deploy': {
+        implemented: false,
+        reason: UNPUBLISH
+    },
+    // Group - members and the groups themselves
+    'GET /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/group/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/group/by/groupname/{name}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'POST /SASjsApi/group': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/group/{groupUid}/{userUid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/group/{groupUid}/{userUid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/group/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Info - what the host is, and what this caller may use
+    'GET /SASjsApi/info': { implemented: false, reason: HOST_CONFIG },
+    'GET /SASjsApi/info/authorizedRoutes': {
+        implemented: false,
+        // the route inventory reports what the CALLER may use, so it needs an
+        // identity even though the rest of the Info tag needs nothing
+        capabilities: ['identity'],
+        reason: PERMISSIONS
+    },
+    'GET /SASjsApi/info/myAuthorizedRoutes': {
+        implemented: false,
+        capabilities: ['identity'],
+        reason: PERMISSIONS
+    },
+    // Permission - the rules the inventory above is derived from
+    'GET /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
+    'POST /SASjsApi/permission': { implemented: false, reason: IDENTITY_RECORDS },
+    'PATCH /SASjsApi/permission/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/permission/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    // Session - the caller's own session, then the record behind a triggered one
     'GET /SASjsApi/session': {
         implemented: true,
         responses: { 200: user }
+    },
+    'GET /SASjsApi/session/{sessionId}': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/log': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/output': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    'GET /SASjsApi/session/{sessionId}/state': {
+        implemented: false,
+        reason: SESSION_RECORD
+    },
+    // STP - a stored program, on the runtime port
+    'GET /SASjsApi/stp/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/stp/execute': { implemented: false, reason: RUNTIME },
+    'POST /SASjsApi/stp/trigger': { implemented: false, reason: RUNTIME },
+    // User - the accounts the identity store already holds for sign-in
+    'GET /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/user/{uid}': { implemented: false, reason: IDENTITY_RECORDS },
+    'GET /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'POST /SASjsApi/user': { implemented: false, reason: IDENTITY_RECORDS },
+    'PATCH /SASjsApi/user/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'PATCH /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/user/{uid}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
+    },
+    'DELETE /SASjsApi/user/by/username/{username}': {
+        implemented: false,
+        reason: IDENTITY_RECORDS
     }
 };
 /** Every method the table may state, in the order a diff reads best. */

package/build/esm/types.d.ts

@@ -85,6 +85,13 @@ export interface Route extends GeneratedRoute {
      * not an absence nobody can see.
      */
     implemented: boolean;
+    /**
+     * Why this package does not implement the operation, and what it waits on.
+     * Present exactly when `implemented` is false: the overlay's entries are a
+     * decision either way, and `src/routes/index.ts` refuses to build a table with
+     * an operation nobody has decided about. A 501 carries it to the caller.
+     */
+    reason?: string;
 }
 /**
  * The drive, as the services see it.

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sasjs/api",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The SASjs Server API, described once - a generated route table, the services behind it, and the conformance corpus both hosts run",
   "license": "MIT",
   "author": "SASjs",