@substrio/cli 0.1.0 → 0.1.2

package/README.md

@@ -23,6 +23,7 @@ substrio deploy
 
 - `substrio init --url URL --tenant SLUG --yes` scaffolds a project (`substrio.toml`, no key stored in it).
 - `substrio login [--url URL] --key - [--tenant SLUG]` reads the key from stdin (never from argv, never in shell history) and saves a profile. Without `--url` the profile is the hosted platform, `https://mcp.substrio.com`. Set `--profile NAME` to save under a name other than the default.
+- `substrio connect CODE|- [--url URL] [--profile NAME] [--show]` redeems a one-time connect code (`substrio_ae_...`) from the console's Agents page: the agent session is saved as profile `agent`, owner-only, and never printed (`--show` prints the secret alone on stdout, for `$(...)`).
 - `substrio status` reports server health and the config in use.
 - `substrio dev [--attach URL] [--server PATH] [--port N] [--data DIR] [--no-build] [--no-logs]` runs the app on a local server with hot reload. Data and keys stay under `.substrio/dev` (or `--data DIR`).
 - `substrio deploy [--dry-run]` deploys the declared collections, functions and rules.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@substrio/cli",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Substrio CLI: deploy functions, manage secrets, stream logs",
     "homepage": "https://github.com/illtronicevents-a11y/substrio#readme",
     "bugs": "https://github.com/illtronicevents-a11y/substrio/issues",
@@ -12,7 +12,7 @@
     "type": "module",
     "sideEffects": false,
     "bin": {
-        "substrio": "./bin/substrio.mjs"
+        "substrio": "bin/substrio.mjs"
     },
     "exports": {
         "./test": "./src/testing/index.mjs",
@@ -26,7 +26,7 @@
         "src/"
     ],
     "dependencies": {
-        "@substrio/sdk": "^0.1.0",
+        "@substrio/sdk": "^0.1.1",
         "esbuild": "^0.25.10"
     },
     "engines": {

package/src/apply.mjs

@@ -22,7 +22,7 @@ import { OpError, callOperation } from './commands/op.mjs';
 import { loadConfig, parseTOML } from './config.mjs';
 import { COLLECTIONS_MEMBER, checkVersionCarriesCollections, versionCollectionSteps } from './collections.mjs';
 import { blobsByHash, collectApp, declaredFunction, declaredLedger, declaredPermissions, manifestOf, versionBody, withSiteVars } from './manifest.mjs';
-import { carrySettings, checkSettings, declaredPlans, declaredSettings } from './settings.mjs';
+import { carrySettings, checkSettings, declaredDashboard, declaredPlans, declaredSettings } from './settings.mjs';
 
 /** What the server says of a source it checked (function.check): the severity of a diagnostic. */
 export const Severity = Object.freeze({
@@ -90,7 +90,7 @@ export function runBuild(steps, cwd, announce = () => {}) {
  * `functionCache` is forwarded to collectApp (substrio dev's Reloader keeps one
  * across applies; substrio push passes none, so every function is built fresh).
  * `resolveEsbuild` is forwarded to collectApp, then to every buildFunction call it makes.
- * Returns {app, settings, plans, collections, body, byHash}; throws a CliError.
+ * Returns {app, settings, plans, dashboard, collections, body, byHash}; throws a CliError.
  */
 export async function loadApp(config, manifest, cwd, message, functionCache, resolveEsbuild) {
     let app;
@@ -103,11 +103,13 @@ export async function loadApp(config, manifest, cwd, message, functionCache, res
     let plans;
     let permissions;
     let ledger;
+    let dashboard;
     try {
         settings = declaredSettings(config);
         plans = declaredPlans(config, cwd);
         permissions = declaredPermissions(config);
         ledger = declaredLedger(config);
+        dashboard = declaredDashboard(config, cwd);
     } catch (err) {
         throw new CliError(`substrio.toml: ${err.message}`);
     }
@@ -116,7 +118,10 @@ export async function loadApp(config, manifest, cwd, message, functionCache, res
     // goes live (append only), so a promote switches them with the code that uses them.
     if (permissions !== null) body.permissions = permissions;
     if (ledger !== null) body.ledger = ledger;
-    return { app, settings, plans, collections: app.collections, body, byHash: blobsByHash(app) };
+    // APP-DASH: the dashboard rides the version too; the server checks it against the
+    // version's own routes (DASHBOARD_INVALID naming the path).
+    if (dashboard !== null) body.dashboard = dashboard;
+    return { app, settings, plans, dashboard, collections: app.collections, body, byHash: blobsByHash(app) };
 }
 
 /**

package/src/command-table.mjs

@@ -51,6 +51,13 @@ const FLOWS = [
         ],
         run: async ({ args }) => (await importCmd('login.mjs')).cmdLogin(args),
     },
+    {
+        names: ['connect'], section: 'START', needs: Needs.NOTHING,
+        usage: [
+            ['connect CODE|- [--url URL] [--profile NAME] [--default] [--show]', 'An agent redeems the one-time connect code (substrio_ae_...) from the console\'s Agents page: the session that acts as its owner is saved as profile NAME (default agent), owner-only, and the MCP setup is printed. The secret is never printed, except with --show: stdout then carries it alone, for $(...) in an MCP client\'s setup'],
+        ],
+        run: async ({ args }) => (await importCmd('connect.mjs')).cmdConnect(args),
+    },
     {
         names: ['whoami'], section: 'START', needs: Needs.CONFIG,
         usage: [['whoami', 'Tenant, server and profile in use, and where each came from']],

package/src/commands/connect.mjs

@@ -0,0 +1,107 @@
+/**
+ * Substrio CLI: `substrio connect` (AGENT-CODE-CONNECT): redeem a one-time connect code from the console's
+ * Agents page ("Connect an agent", substrio_ae_...) for an agent session acting as its owner.
+ *
+ * Usage:
+ *   substrio connect CODE [--url URL] [--profile NAME] [--default] [--show]
+ *   substrio connect - ...          The code read from stdin (kept out of argv and shell history)
+ *
+ * One request: POST URL/v1/_agent/exchange {code} (agent.enroll.exchange), the server
+ * https://mcp.substrio.com unless --url names another. The answer is a bearer session; its secret is
+ * saved as profile NAME (default "agent") in the owner-only profiles file, exactly as `substrio login`
+ * saves a key, and becomes the default profile only with --default (or when there is none). The code is
+ * spent by the exchange and never printed back. The secret is never printed either, except with --show:
+ * then stdout carries the secret alone on one line, for `$(...)` in an MCP client's setup command, and
+ * everything else goes to stderr.
+ */
+
+import { CliError, ErrorCode, emit, errorText, fail, globals } from '../cli.mjs';
+import { rcPath, writeProfile } from '../config.mjs';
+import { DEFAULT_URL } from './login.mjs';
+import { MCP_KEY_ENV, MCP_PATH } from './mcp-config.mjs';
+
+/** The profile a connect saves when --profile names none. */
+export const CONNECT_PROFILE = 'agent';
+/** The platform route that redeems a connect code (agent.enroll.exchange). */
+export const EXCHANGE_PATH = '/v1/_agent/exchange';
+
+const USAGE = 'substrio connect CODE|- [--url URL] [--profile NAME] [--default] [--show]';
+
+const C = { reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', green: '\x1b[92m' };
+
+/**
+ * The setup lines an MCP client needs for the session saved as `profile` on the server at `url` (pure):
+ * none holds the secret. `export` writes it owner-only as MCP_KEY_ENV; `header` is what the client sends;
+ * `claude` is Claude Code's one-step form, which redeems a NEW code straight into its config.
+ */
+export function connectSetup(url, profile) {
+    const endpoint = `${url}${MCP_PATH}`;
+    const npx = url === DEFAULT_URL ? 'npx @substrio/cli connect' : `npx @substrio/cli connect --url ${url}`;
+    return {
+        endpoint,
+        export: `substrio --profile ${profile} key export --env .substrio.env`,
+        header: `Authorization: Bearer \${${MCP_KEY_ENV}}`,
+        claude: `claude mcp add --transport http substrio ${endpoint} --header "Authorization: Bearer $(${npx} CODE --show)"`,
+    };
+}
+
+// The whole of stdin, one trailing newline trimmed (never printed, never logged).
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8').trim();
+}
+
+export async function cmdConnect(args) {
+    let code = null;
+    let url = DEFAULT_URL;
+    let makeDefault = false;
+    let show = false;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--url' && args[i + 1]) url = args[++i];
+        else if (args[i] === '--default') makeDefault = true;
+        else if (args[i] === '--show') show = true;
+        else if (code === null && !args[i].startsWith('--')) code = args[i];
+        else return fail(`unexpected argument "${args[i]}"`, USAGE);
+    }
+    if (code === null || code === '-') code = await readStdin();
+    if (!code) return fail('a connect code is required: the substrio_ae_... code from the console\'s Agents page', USAGE, ErrorCode.INVALID_ARGUMENT);
+    url = url.replace(/\/+$/, '');
+    const profile = globals.profile || CONNECT_PROFILE;
+
+    let response;
+    try {
+        response = await fetch(`${url}${EXCHANGE_PATH}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ code }),
+        });
+    } catch (err) {
+        return fail(new CliError(`Could not reach ${url}: ${err.message}`, { code: ErrorCode.NETWORK_ERROR }), USAGE);
+    }
+    const data = await response.json().catch(() => null);
+    if (!response.ok || typeof data?.key !== 'string') {
+        return fail(CliError.fromResponse(`The code was not redeemed: ${errorText(data, response.status)}`, data, response.status),
+            'Ask your owner for a new code on the console\'s Agents page');
+    }
+
+    writeProfile(profile, url, data.key, null, { makeDefault, checked: true });
+    if (show) process.stdout.write(`${data.key}\n`);
+    const setup = connectSetup(url, profile);
+    const summary = {
+        profile, url, path: rcPath(), session_id: data.id, kind: data.kind, account_id: data.account_id,
+        expires_at: data.expires_at, mcp_url: setup.endpoint,
+    };
+    const human = () => {
+        const until = Number.isFinite(data.expires_at) ? new Date(data.expires_at * 1000).toISOString() : 'its end';
+        const log = show ? console.error : console.log;
+        log(`${C.green}✓${C.reset} Connected: agent session ${data.id} acts as your owner in account ${data.account_id} until ${until} (${data.kind}).`);
+        log(`  The secret is saved as profile ${C.bold}${profile}${C.reset} in ${rcPath()} (owner-only)${show ? '' : ' and is not shown'}.`);
+        log(`${C.dim}  An MCP client: ${setup.export} writes ${MCP_KEY_ENV}, owner-only;`);
+        log(`  the client sends "${setup.header}" to ${setup.endpoint}.`);
+        log(`  Claude Code in one step, with a new code: ${setup.claude}${C.reset}`);
+    };
+    // --show keeps stdout to the secret alone: the summary goes to stderr as text, never as JSON on stdout.
+    if (show) human();
+    else emit(summary, human);
+}

package/src/commands/deploy.mjs

@@ -188,8 +188,10 @@ export async function cmdDeploy(api, config, args) {
         if (!existsSync(functionsDir) && !named) {
             console.log(`${C.yellow}⚠ No functions/ directory found. Skipping function deployment.${C.reset}`);
         } else {
-            const files = existsSync(functionsDir) ? readdirSync(functionsDir).filter(f => f.endsWith('.js')) : [];
-            const found = new Set(files.map(f => f.replace(/\.js$/, '')));
+            // WASM-P1: a function is functions/<name>.js, or functions/<name>.rs (its Rust source, sent as "rust":
+            // the server compiles it).
+            const files = existsSync(functionsDir) ? readdirSync(functionsDir).filter(f => FUNCTION_FILE.test(f)) : [];
+            const found = new Set(files.map(f => f.replace(FUNCTION_FILE, '')));
 
             if (named) {
                 const known = new Set([...found, ...Object.keys(config.functions)]);
@@ -201,22 +203,25 @@ export async function cmdDeploy(api, config, args) {
             } else {
                 const missing = Object.keys(config.functions).filter(name => !found.has(name));
                 if (missing.length > 0) {
-                    fail(`substrio.toml declares ${missing.join(', ')} but ${config.functions_dir}/ has no ${missing.map(n => n + '.js').join(', ')}`,
+                    fail(`substrio.toml declares ${missing.join(', ')} but ${config.functions_dir}/ has no ${missing.map(n => n + '.js or .rs').join(', ')}`,
                         null, ErrorCode.FILE_NOT_FOUND);
                 }
             }
 
-            const toDeploy = named ? names : files.map(f => f.replace(/\.js$/, ''));
+            const toDeploy = named ? names : files.map(f => f.replace(FUNCTION_FILE, ''));
             if (toDeploy.length === 0) {
-                console.log(`${C.dim}  No .js files in ${config.functions_dir}/. Skipping.${C.reset}`);
+                console.log(`${C.dim}  No .js or .rs files in ${config.functions_dir}/. Skipping.${C.reset}`);
             } else {
                 console.log(`${C.bold}Functions${C.reset} ${C.dim}(${toDeploy.length} file${toDeploy.length > 1 ? 's' : ''})${C.reset}`);
 
                 for (const name of toDeploy) {
                     const filePath = join(functionsDir, `${name}.js`);
+                    const rustPath = join(functionsDir, `${name}.rs`);
                     let built;
                     try {
-                        built = await buildFunction({ entry: filePath, projectDir: cwd });
+                        built = existsSync(rustPath) && !existsSync(filePath)
+                            ? rustSource(rustPath)
+                            : await buildFunction({ entry: filePath, projectDir: cwd });
                     } catch (err) {
                         // Its exit code is exitCodeFor's, the same one a server refusal of this
                         // function would give: run.failed keeps the first failure for that.
@@ -235,7 +240,7 @@ export async function cmdDeploy(api, config, args) {
                         continue;
                     }
 
-                    const step = await run.send('function.deploy', deployment(name, built.code, config.functions[name], cwd, publicDir));
+                    const step = await run.send('function.deploy', deployment(name, built, config.functions[name], cwd, publicDir));
                     report.functions.push({ name, size_bytes: built.bytes, inputs: built.inputs, ...step });
                     if (step.ok) {
                         const hash = step.result?.content_hash ? `, content_hash ${step.result.content_hash}` : '';
@@ -471,10 +476,21 @@ export async function sendDeclared(run, report, { key, operation, body, would, s
 // The deploy request for one function: its source plus the routes, entry point
 // and vars substrio.toml declares for it. Only what is declared is sent, so a
 // function substrio.toml says nothing about keeps what it had.
-function deployment(name, script, declared = {}, cwd, siteDir) {
+function deployment(name, built, declared = {}, cwd, siteDir) {
     // VERSION-VALUES: a deploy makes no version, so site_vars are filled here from the site folder this
     // deploy publishes, as the server fills them from a version's own site.
-    return { name, script, ...withSiteVars(declaredFunction(name, declared, cwd), siteDir) };
+    // WASM-P1: Rust goes as "rust" (its source: the server compiles it), a script as "script".
+    const source = built.rust !== undefined ? { rust: built.rust } : { script: built.code };
+    return { name, ...source, ...withSiteVars(declaredFunction(name, declared, cwd), siteDir) };
+}
+
+// WASM-P1: a function's file: <name>.js, or <name>.rs (Rust; docs/runtime/wasm-functions.md).
+const FUNCTION_FILE = /\.(js|rs)$/;
+
+// A .rs function as deploy sends it: its source as written, compiled by the server at deploy. Nothing is built here.
+function rustSource(path) {
+    const rust = readFileSync(path, 'utf8');
+    return { rust, bytes: Buffer.byteLength(rust), inputs: [path], esbuildAvailable: true };
 }
 
 // Whether `step`'s failure of `built` looks like the server refusing an import it cannot resolve:

package/src/commands/groups.mjs

@@ -272,15 +272,20 @@ export const GROUPS = {
     live_view: {}, log_alert: {}, log_drain: {},
     // mcp.* runs by its words; config is the CLI's own word, for the client side of the same endpoint.
     mcp: { config: { flow: GroupFlow.MCP_CONFIG, valueFlags: ['--client', '--name', '--env'], note: 'a ready MCP client config for this profile\'s app (--client claude|cursor|generic); the key as an environment variable reference' } },
-    // host.* and node_label.* (the operator's host manifest) run by their words; host remove and
-    // node_label delete are gated by their own trailing word, as every other.
-    host: {}, node_label: {},
+    // host.*, node_label.* and region.* (the operator's host manifest and its regions; region choices is an
+    // account's) run by their words; host remove, node_label delete and region remove are gated by their own
+    // trailing word, as every other.
+    host: {}, node_label: {}, region: {},
     // TEST-HOSTS: root_domain.* (the platform admin's roots) runs by its words: substrio root_domain add
     // domain=onstax.com. env.host.* runs through the env command (commands/env.mjs), beside its pull and push.
     root_domain: {},
     // BILLING, FEATURED-APPS, MCP-MODULES, PLATFORM-UPGRADES: their operations run by their words: substrio billing
     // cart create, substrio featured enable, substrio package add, substrio release list.
     billing: {}, featured: {}, package: {}, release: {},
+    // SUBSCRIPTIONS: substrio subscriptions mine, substrio subscriptions cancel id=7.
+    subscriptions: {},
+    // APP-DASH: substrio dashboard get id=7 slug=shop.
+    dashboard: {},
     mesh: {}, meta: {}, namespace: {}, oauth: {}, object: {}, observability: {},
     oidc: {}, plans: {}, queue: {}, rag: {}, rate_limit: {}, sql: {}, index: {},
     realtime: {}, role: {}, route: {}, search: {}, settings: {}, sync: {}, system: {}, thread: {}, user: {},
@@ -294,9 +299,9 @@ export const REGISTRY_GROUPS = Object.freeze({
     function: 'functions', graph: 'graph', host: 'host', index: 'index', job: 'job', kv: 'kv', ledger: 'ledger', live_view: 'live_view',
     log_alert: 'log_alert', log_drain: 'log_drain', mcp: 'mcp', mesh: 'mesh', meta: 'meta', namespace: 'namespace', node_label: 'node_label', oauth: 'oauth',
     root_domain: 'root_domain', env: 'env', apps: 'tenants', billing: 'billing', featured: 'featured', package: 'package',
-    release: 'release',
+    release: 'release', subscriptions: 'subscriptions', dashboard: 'dashboard',
     object: 'object', observability: 'observability', oidc: 'oidc', permissions: 'permissions', plans: 'plans', queue: 'queue',
-    platform: 'platform', query: 'data', rag: 'rag', rate_limit: 'rate_limit', realtime: 'realtime',
+    platform: 'platform', query: 'data', rag: 'rag', rate_limit: 'rate_limit', realtime: 'realtime', region: 'region',
     branch: 'branch', tag: 'tag', ref: 'ref', merge: 'merge',
     role: 'role', route: 'route', sandbox: 'sandbox', schedule: 'cron', schema: 'collections',
     search: 'search', secret: 'secrets', source: 'source', security: 'rules', settings: 'settings', site: 'site',
@@ -304,6 +309,12 @@ export const REGISTRY_GROUPS = Object.freeze({
     user: 'user', version: 'versions', view: 'views', webhook: 'webhooks',
 });
 
+// The operations a flow runs by a word of its own, ahead of its registry words: tenants show SLUG (and get
+// SLUG) is the operator's tenant.get, while tenants get with no slug is the app's own app.get by its words.
+export const FLOW_OPERATIONS = Object.freeze({
+    tenants: Object.freeze({ show: 'tenant.get' }),
+});
+
 /** The registry groups `command` runs (pure). */
 export function registryGroupsOf(command) {
     return Object.keys(REGISTRY_GROUPS).filter((group) => REGISTRY_GROUPS[group] === command);

package/src/commands/push.mjs

@@ -144,7 +144,7 @@ export async function cmdPush(api, config, args) {
     // the manifest describes: the version's content (and so its hash) is the
     // same whichever branch it is committed on.
     if (branch) loaded.body.branch = branch;
-    const { app, settings, plans, collections, body, byHash } = loaded;
+    const { app, settings, plans, dashboard, collections, body, byHash } = loaded;
     const total = [...byHash.values()].reduce((sum, f) => sum + f.size, 0);
     const siteFiles = app.site?.files.length ?? 0;
     console.log(`  ${app.functions.length} function${app.functions.length === 1 ? '' : 's'}` +
@@ -156,6 +156,7 @@ export async function cmdPush(api, config, args) {
         ` ${C.dim}(${byHash.size} blobs, ${formatSize(total)})${C.reset}`);
     for (const s of settings) console.log(`  ${s.label} [${s.table}] ${Object.keys(s.values).join(', ')}`);
     if (plans !== null) console.log(`  Plans from ${config.plans_file} (${plans.plans?.length ?? 0})`);
+    if (dashboard !== null) console.log(`  Dashboard from ${config.dashboard_file} (${dashboard.nav?.length ?? 0})`);
     if (app.site?.replaced.length) {
         const shown = app.site.replaced.slice(0, 5).join(', ');
         const more = app.site.replaced.length > 5 ? ` and ${app.site.replaced.length - 5} more` : '';

package/src/commands/tenants.mjs

@@ -23,6 +23,7 @@
 
 import { ErrorCode, confirmDestructive, emit, emitIssuedKey, fail } from '../cli.mjs';
 import { cmdRegistry } from './groups-runtime.mjs';
+import { FLOW_OPERATIONS } from './groups.mjs';
 import { OpError, callOperation, invokeOperation, loadOperations, runOperation } from './op.mjs';
 import { listProfiles, writeProfile } from '../config.mjs';
 
@@ -55,8 +56,11 @@ export async function cmdTenants(api, config, args) {
     case 'list':
     case 'ls':
       return tenantsList(api, args.slice(1));
-    case 'show':
     case 'get':
+      // With no slug, the app's own record (app.get, its words); with one, the operator's read as show.
+      if (!args[1] || args[1].startsWith('-')) return cmdRegistry(api, 'tenants', args);
+    // falls through
+    case 'show':
       return tenantsShow(api, args.slice(1));
     case 'create':
     case 'new':
@@ -94,7 +98,7 @@ function printTenants(data) {
 
 async function tenantsShow(api, args) {
   if (!args[0] || args[0].startsWith('--')) fail(`Usage: ${USAGE}`);
-  return runOperation(api, 'tenant.get', args.slice(1), { positional: [args[0]] });
+  return runOperation(api, FLOW_OPERATIONS.tenants.show, args.slice(1), { positional: [args[0]] });
 }
 
 // The account id of the profile's key (auth.whoami), when it is an account

package/src/config.mjs

@@ -428,6 +428,8 @@ export function loadConfig(cwd = process.cwd()) {
         mcp_file: null,
         // JSON file of the tenant's plans, counters and feature flags, set by `substrio deploy`
         plans_file: null,
+        // APP-DASH: JSON file of the app's console dashboard (docs/dashboard.md), carried in the version `substrio push` makes
+        dashboard_file: null,
         // [apps.offer] and [apps.use]: the functions the app offers other apps and the ones it calls, set by
         // `substrio deploy` (apps.calls.set; substrio.apps.<app>.<entry>(...) in a function); [apps.query.<name>]
         // and [apps.use_query]: the reads it offers and the ones it makes (substrio.apps.<app>.query.<name>(...))
@@ -495,6 +497,7 @@ export function loadConfig(cwd = process.cwd()) {
     if (flat.collections_dir) config.collections_dir = flat.collections_dir;
     if (flat.mcp_file) config.mcp_file = flat.mcp_file;
     if (flat.plans_file) config.plans_file = flat.plans_file;
+    if (flat.dashboard_file) config.dashboard_file = flat.dashboard_file;
     if (flat.apps !== undefined) config.apps = flat.apps;
     if (flat.site_ignore !== undefined) config.site_ignore = flat.site_ignore;
     if (flat.build !== undefined) config.build = flat.build;

package/src/settings.mjs

@@ -4,6 +4,7 @@
  * push, the app on promote, the older ones again on a rollback):
  *
  *   plans_file = "plans.json"               # version member "plans", as POST /v1/_plans takes
+ *   dashboard_file = "dashboard.json"       # version member "dashboard" (docs/dashboard.md)
  *   [auth]                                  # version member "auth", as PUT /v1/_auth/settings takes
  *   email_function = "send_auth_mail"
  *   reset_url = "https://app.example/reset?token={token}"
@@ -109,6 +110,30 @@ export function declaredPlans(config, cwd) {
     }
 }
 
+/** The largest dashboard file the server takes (types::DashboardPolicy::FILE_MAX_BYTES). */
+export const DASHBOARD_FILE_MAX_BYTES = 64 * 1024;
+
+/**
+ * APP-DASH: the dashboard substrio.toml's dashboard_file names, parsed (the version
+ * member "dashboard"; docs/dashboard.md), or null when it names none. Throws when
+ * the file is missing, larger than the server takes, or not JSON. Its fields and
+ * routes are the server's to check (DASHBOARD_INVALID naming the path).
+ */
+export function declaredDashboard(config, cwd) {
+    if (!config.dashboard_file) return null;
+    const path = resolve(cwd, config.dashboard_file);
+    if (!existsSync(path)) throw new Error(`dashboard_file ${config.dashboard_file} does not exist`);
+    const text = readFileSync(path, 'utf-8');
+    if (Buffer.byteLength(text) > DASHBOARD_FILE_MAX_BYTES) {
+        throw new Error(`dashboard_file ${config.dashboard_file} is larger than ${DASHBOARD_FILE_MAX_BYTES} bytes`);
+    }
+    try {
+        return JSON.parse(text);
+    } catch (err) {
+        throw new Error(`dashboard_file ${config.dashboard_file} is not JSON: ${err.message}`);
+    }
+}
+
 /** Puts the declared settings and plans into a version body as its members. */
 export function carrySettings(body, declared, plans) {
     for (const setting of declared) body[setting.member] = setting.values;