@thinger-io/cli-core 0.3.0 → 0.4.0

package/docs/thinger-product-code.md

@@ -0,0 +1,159 @@
+# Product code
+
+JavaScript that a product's profile calls to compute, transform or route data for its devices:
+resource values (including simulated devices), payload transforms, the device a product call is
+for. Platform concepts: the document `concepts`. It describes Thinger 7.5; what needs a later
+version says "since Thinger X" (a server's version: `GET /v1/server/version`).
+
+## Where it lives
+
+`PUT /v1/users/{user}/products/{product}/profile/code` with
+`{ "code": "<JavaScript>", "storage": "" }`, or `{ "storage": "<storage id>" }` to load
+`<storage>/index.js` from a file storage (with its `node_modules`). Since Thinger 7.5, add
+`"path": "<folder>"` to
+load `<storage>/<folder>/index.js` (and that folder's `node_modules`) instead: one storage can then
+hold a whole application, e.g. the dashboard in `app/` and each product's code in
+`code/<product>/`. Read it back with `GET` on the same path.
+
+The code takes effect at once: every change to the profile (code, any category or entry, or
+enabling the product) reloads it. Editing `index.js` in the storage does **not**: `PUT
+profile/code` again afterwards.
+
+## Runtime
+
+- Node.js embedded in the server, one instance per product.
+- Functions are found by name as globals: declare them with `function name(…) {}` (or
+  `var name = …`, `globalThis.name = …`). Top-level `const` / `let` / `class` names and
+  `module.exports` are not visible to the profile.
+- **Synchronous only.** There is no event loop: promises, `async` functions, timers, `fetch` and
+  network modules never complete (an `async` function returns `{}`). Synchronous built-ins
+  (`Math`, `Date`, `JSON`, `require('crypto')`…) work.
+- `Date` runs in **UTC** (`getHours()` is the UTC hour). For local time use `Intl`, which knows
+  time zones and daylight saving:
+  `new Intl.DateTimeFormat('en-GB', { timeZone: 'Europe/Madrid', hour: 'numeric', hourCycle: 'h23' }).formatToParts(new Date())`
+  gives the hour in Madrid.
+- Return JSON values: objects, arrays, numbers, strings, booleans. A `Date` or other class
+  instance becomes `{}`: return `Date.now()` (milliseconds) instead.
+- A function that throws returns `null`. There is no time limit: keep functions short.
+- No access to the filesystem except reading user storages, no processes, no environment.
+- The code cannot call Thinger directly (no API object). It talks to the platform only through
+  the profile: placeholders bring data in, targets send results out (below).
+
+`console.log` / `info` / `warn` / `error` are sent as `product_script_log` events while someone
+listens: the product's console in the web console, or the websocket
+`/v1/users/{user}/products/{product}/profile/console`.
+
+## Where functions are called
+
+A function receives one argument (two for `device_id_resolver`) and returns the new value.
+
+| Hook | Config | Receives | Returns |
+|---|---|---|---|
+| API resource, request target `function` | `api.<r>.request.data` `{ "target": "function", "function": "<name>" }` | the request payload, shaped by `payload_type` (below) | the resource result (with response `source: "request_response"`) |
+| API resource, response source `function` | `api.<r>.response.data` `{ "source": "function", "function": "<name>" }` | `{ user, device, resource, product }` | the resource result |
+| Payload transform | `payload_function: "<name>"` in a request, response, bucket, property or flow `data` | the payload after `payload_type` | the new payload (an empty result skips a bucket / property write or a flow) |
+| Device of a product call | `device_id_resolver: "<name>"` at the root of an API resource or flow | `(payload, placeholders)` | a device id (string) |
+| Placeholder converter | `{{<placeholder>:<name>}}` inside any template | the placeholder value | the replacement |
+
+`payload_type` decides what a function or target gets:
+
+- `template_payload` (default): the `payload` template with placeholders filled, parsed as JSON.
+  Without a `payload` it is empty, so a bucket or property entry writes nothing.
+- `source_payload`: the incoming value as is (in a response, the target's result); the same as
+  `"payload": "{{payload}}"`.
+- `source_event`: everything: `{ user, device, resource, product, payload }`.
+- `none`: nothing.
+
+Placeholders available in templates: `{{device}}`, `{{user}}`, `{{product}}`, `{{resource}}`,
+`{{payload}}` / `{{payload.<field>}}`, `{{property.<id>}}` (a device property's value, inherited
+like any device property: device → asset type → asset group → product, the first that defines it,
+whole value),
+`{{meta.<field>}}` (a field of the device document), `{{api.<resource>}}` (another API resource),
+and `{{x=default}}` for defaults.
+
+## Resources computed by code
+
+An API resource whose request target is a function makes a value out of nothing: the basis of
+simulated devices.
+
+```json
+"api": {
+  "climate": {
+    "enabled": true,
+    "request":  { "data": { "target": "function", "function": "simulateClimate", "payload_type": "source_event" } },
+    "response": { "data": { "source": "request_response", "payload_type": "source_payload" } }
+  }
+}
+```
+
+```js
+// ctx = { user, device, resource, product, payload }
+function simulateClimate(ctx) {
+  var day = Math.sin(((Date.now() / 3600000) % 24 - 6) / 24 * 2 * Math.PI);  // day/night cycle
+  return {
+    temperature: Math.round((22 + 6 * day + (Math.random() - 0.5)) * 10) / 10,
+    humidity: Math.round((60 - 15 * day + (Math.random() - 0.5) * 4) * 10) / 10
+  };
+}
+```
+
+`GET /v3/users/{user}/devices/{device}/resources/climate` then returns the object for any device
+of the product, including `Virtual` devices, which have no hardware and get every resource from
+their product. A profile bucket or property with `source: "resource"` and an interval calls the
+resource for every connected device of the product on that schedule (see
+the document `concepts`, Buckets).
+
+Without `"response": { "source": "request_response" }` the function runs but the resource
+returns nothing; without `payload_type: "source_payload"` (or `"payload": "{{payload}}"`) in the
+response, it returns `null`.
+
+## State between calls
+
+- **In memory**: globals survive between calls of the same product, so
+  `globalThis.state = globalThis.state || {}; state[ctx.device] = …` keeps per-device state.
+  It is lost when the profile reloads (any profile change) and when the server restarts. Code
+  that keeps "what happened since the last call" in memory starts over after each reload: it can
+  repeat or skip one step (e.g. emit an event twice). Keep that cursor in a property if it matters.
+- **Persistent**: keep the state in a device property. Read it with `{{property.<id>}}` in the
+  request payload template and write the function's result back with request target
+  `property`:
+
+```json
+"api": {
+  "tank": {
+    "enabled": true,
+    "request": { "data": {
+      "target": "property", "property": "tank",
+      "payload": "{\"prev\": {{property.tank}}, \"in\": {{payload}} }",
+      "payload_function": "stepTank" } },
+    "response": { "data": { "source": "request_response", "payload_type": "source_payload" } }
+  }
+}
+```
+
+```js
+// p = { prev: <last tank property or {}>, in: <input sent to the resource or null> }
+function stepTank(p) {
+  var s = typeof p.prev.level === 'number' ? p.prev : { level: 50, inflow: 1, outflow: 0.8, ts: Date.now() };
+  var now = Date.now(), minutes = (now - s.ts) / 60000;
+  var inflow = p.in && p.in.inflow !== undefined ? p.in.inflow : s.inflow;
+  var outflow = p.in && p.in.outflow !== undefined ? p.in.outflow : s.outflow;
+  var level = Math.min(100, Math.max(0, s.level + (inflow - outflow) * minutes));
+  return { level: level, inflow: inflow, outflow: outflow, ts: now };   // saved as property "tank"
+}
+```
+
+Each call advances the level from the stored state; calling the resource with
+`{ "inflow": 3 }` changes the flow. Do not combine it with a `{{payload=property.tank}}`
+default: defaults that read a property re-run the resource when that property changes, and this
+resource writes it.
+
+## Limits and pitfalls
+
+- No asynchronous work and no outgoing requests from code: to call an external service use an
+  endpoint (request target `endpoint_call`).
+- One argument per function (two for `device_id_resolver`); use `payload_type: "source_event"`
+  to get the device id and the rest of the context.
+- Keep per-call work small: functions run synchronously in the server, without a timeout.
+- A product must be `enabled`, and every API / bucket / property / flow entry needs
+  `"enabled": true`, or it is skipped.

package/docs/thinger-server-admin.md

@@ -0,0 +1,165 @@
+# Thinger server administration
+
+For agents acting as a server **admin**: host settings, domains and brands, user accounts,
+OAuth clients, identity providers and proxies. Every route here needs an admin session or
+token. Read the OpenAPI document for each body; this guide covers what the schemas cannot say:
+order of steps, side effects and risks. It describes Thinger 7.5; what needs a later version says
+"since Thinger X" (a server's version: `GET /v1/server/version`).
+
+Before changing anything, read the current value and tell the user what will change. Several
+actions here can take the server or a domain offline.
+
+## Hosts and server settings
+
+A host is one server process; its id is the machine's hostname (`GET /v1/hosts`).
+
+- `GET /v1/hosts/{host}/settings` returns the editable settings (database, plugins and similar
+  internals are hidden).
+- `PUT /v1/hosts/{host}/settings` is a **merge patch** (RFC 7386) over the host's custom
+  settings: send only the sections you change; `null` removes a custom value, so the provider
+  default applies again. Values are validated against the schema.
+- **Settings apply only after a restart**: `POST /v1/hosts/{host}/restart`. The process exits
+  and the container restarts it: every connection drops (devices, consoles, websockets) for a
+  few seconds or more. Ask the user before restarting, and prefer a quiet moment.
+- Ports are **strings** (`"1883"`), as the server reads them.
+- Logs: `GET /v1/hosts/{host}/logs?lines=200` returns the last lines as text; the same route
+  over a websocket streams them live.
+
+Main sections: `http_server`, `thing_server` (IOTMP), `mqtt_server`, `proxies` (dynamic port
+range), `email` (server mail: `smtp` or `ses`), `buckets.storage` / `buckets.export`, `ssl`,
+`accounts` (sign-up, login methods, password rules, `limits.<collection>.max_count` with -1 =
+unlimited and 0 = disabled), `deployment` (`contact_email`: whoever registers with it becomes
+admin), `scripting_engine`.
+
+Some features are off by default (`max_count` 0): projects, project members, domains, brands and
+identity providers. On Thinger cloud instances the subscription plan sets these limits; on a
+self-hosted server raise `accounts.limits.<collection>.max_count` (`projects`,
+`projects_members`, `domains`, `brands`, `identity_providers`) and restart. The domains and
+brands limits are not shown by `GET settings`.
+
+On cloud instances the plan owns `accounts.limits.{accounts,brands,domains,members}`, `database`,
+`plugins`, `rate_limiter` and `http_server.hosts`: since Thinger 7.5, writing them returns 403.
+To raise them, the customer changes the plan.
+
+## Custom domain with its own brand
+
+A **brand** is the look and login behaviour of the console for one hostname. Its id **is** the
+hostname (`console.example.com`); there is no other link between a domain and a brand. The
+**domain** resource only manages the TLS certificate of that hostname.
+
+1. **DNS (done by the user).** Make the hostname resolve to this server: an `A` / `AAAA` record
+   with the server's public IP, or a `CNAME` to the server's existing hostname (the one the user
+   already uses to reach the console). There is no special verification value or TXT record.
+   Port **80** must be reachable from the internet. Tell the user exactly which record to
+   create, then wait until it resolves (it can take minutes; up to the record's TTL).
+2. **Create the domain**: `POST /v1/domains` `{ "domain": "console.example.com" }`. No side
+   effects yet.
+3. **Verify**: `POST /v1/domains/{domain}/verify`. The server asks Let's Encrypt for a
+   certificate (HTTP-01: Let's Encrypt fetches `http://<domain>/.well-known/acme-challenge/...`
+   from this server). On failure the error carries Let's Encrypt's reason (DNS not found,
+   connection refused, rate limit…): report it to the user as is. A certificate with more than
+   30 days left counts as verified. Wildcards (`*.example.com`) use DNS-01 and only work on
+   instances hosted by Thinger.
+4. **Create the brand**: `POST /v1/brands` `{ "brand": "console.example.com", "name": ..., "config": {...} }`.
+5. **Configure it**: texts, logos, colors, login page, PWA, account options (`config`), and its
+   email (`email`). See below.
+6. Open `https://console.example.com` to check.
+
+Certificates renew automatically (daily check, 30 days before expiry). If the DNS record is
+later changed or removed, renewal fails silently and HTTPS breaks when the current certificate
+expires. Deleting a domain removes its certificate at once.
+
+Local or development builds may use Let's Encrypt **staging**, whose certificates browsers do not
+trust: verification "works" but the site shows a warning.
+
+### Brand configuration
+
+- `PUT /v1/brands/{brand}` **replaces** `config` and `email` as a whole, and deletes the logo
+  files missing from the new `config`. Use it only with the full object.
+- `PATCH /v1/brands/{brand}` **merges** into the stored ones (`null` removes a key). Prefer it:
+  `{ "config": { "title": "Acme IoT" } }` changes only the title.
+- Logos and icons (`favicon`, `share_image`, `dark_logo` for login and exports, `bright_logo`
+  for the menu, `icon` for the folded menu, `pwa.icons[].src`) are sent as **data URLs**
+  (`data:image/png;base64,...` or webp). The server stores the file and keeps a
+  `/brand/images/...` URL. Sending that URL back keeps the image; `null` or `""` deletes it.
+- `config.accounts` overrides the server's account settings for this hostname: public sign-up
+  (and its role), password / passkey login, 2FA, `cross_sign_in` (false: only users registered
+  on this hostname can log in), reCAPTCHA (`no_robot`), federated login and its identity
+  providers.
+- The brand is readable without login (login pages need it); secrets in it are only returned to
+  admins.
+
+### Brand email
+
+`email.custom: true` with `email.settings` makes this brand send its emails (account
+verification, password reset, account creation, device disabled) through its own server:
+`type: "smtp"` with `smtp.host`, `smtp.port` (string), `username`, `password`, `secure` (true
+for implicit TLS, e.g. 465; otherwise STARTTLS), or `type: "ses"` with AWS keys and region.
+`settings.from` / `from_name` are the sender. `email.templates.<name>` can override `subject`
+and `body` (HTML). Start from the defaults (`GET /v1/brands/{brand}/email` returns them) and keep
+their links:
+
+| Template | Link in the body |
+|---|---|
+| `email_verification` | `{{host_url}}/verify_email?code={{code}}` |
+| `forgot_password` | `{{host_url}}/password?code={{code}}` |
+| `create_password` | `{{host_url}}/create_password?code={{code}}` |
+| `device_disabled` | (no link; `{{device}}` is the device) |
+
+Placeholders filled when sending: `{{code}}`, `{{user}}`, `{{email}}`, `{{host}}`, `{{admin}}`
+(server contact email), `{{host_url}}`. `{{name}}`, `{{url}}`, `{{logo}}` and `{{description}}`
+only exist in the built-in defaults: in a custom template write the brand name and the logo URL
+(`https://<brand>/brand/images/dark_logo.png`) directly. Email clients do not load `data:` images,
+so use that public URL. The `enabled` flag of a template is not enforced yet.
+
+`POST /v1/brands/{brand}/email/test` `{ "template": "email_verification" }` sends that template to
+the **calling admin's** email address with the **saved** settings: save first, then test.
+
+## User accounts
+
+`POST /v1/users` creates an account; `role` is `user`, `member` (only inside projects, needs a
+default project), `domain_admin` (admin of the hostnames in its `host` list) or `admin`. Only
+admins create admins. An empty password sends the "create password" email instead. Per-user
+`limits` override the server limits. Deleting a user deletes **all** its resources (devices,
+buckets, plugins, files): confirm explicitly.
+
+## OAuth clients
+
+Applications that log users in with this server (authorization code or device flow).
+`redirect_uri` is a **newline-separated** list of exact URLs. The `secret` is stored and returned
+in plain text to admins: handle it as a credential. `enabled: false` blocks the client.
+
+## Identity providers (log in with Google, Microsoft…)
+
+OIDC providers users can log in with.
+
+1. Allow them: `accounts.limits.identity_providers.max_count` in the host settings (0 by
+   default), then restart.
+2. Register this server in the provider: callback URL `https://<brand or console host>/oauth/callback`.
+3. Create the provider with its `domain` (issuer), `client_id`, `client_secret`, provisioning
+   (`auto_provision` creates accounts, `match_only` only links existing ones; `allowed_domains`
+   limits email domains) and `email_trust_mode`.
+4. Test it: `POST /v1/identity_providers/{id}/test` checks discovery and keys.
+5. Turn on `federated_login` (host `accounts` or the brand's `config.accounts`) and optionally
+   restrict `identity_providers` to some ids.
+
+Auto-provisioning creates accounts even when public sign-up is off.
+
+## Proxies
+
+Expose a TCP / UDP service, a plugin, or a device service through this server.
+
+- Created and updated proxies start or replace a **live listener** at once; deleting one closes
+  the port. A wrong port can collide with other services.
+- `source.routing: "subdomain"` serves `https://<proxy id>.<server hostname>` and needs a
+  wildcard certificate for that hostname.
+- Send the full `config` on update: a partial one works until the next restart and then breaks.
+
+## Safety checklist
+
+- Read before write; describe the change; keep the previous value to undo it.
+- Never restart, delete a domain, delete a user or change login settings without the user's
+  explicit confirmation.
+- Changing `accounts` login options (password, 2FA, cross sign-in, sign-up) can lock users out:
+  make sure an admin can still log in.
+- Do not echo secrets (SMTP passwords, client secrets, AWS keys) back to the user unless asked.

package/lib/cli.js

@@ -9,16 +9,17 @@ import { registerProfileCommands } from './commands/profile.js';
 import { registerDeviceCommands } from './commands/device.js';
 import { registerProductCommands } from './commands/product.js';
 import { registerBucketCommands } from './commands/bucket.js';
+import { registerDashboardCommands } from './commands/dashboard.js';
 
 /**
  * Build and run a CLI on top of the core: global options, the generic
- * commands (login, logout, profile, device, product, bucket) and `mcp`.
+ * commands (login, logout, profile, device, product, bucket, dashboard) and `mcp`.
  * The identity must be defined before calling it.
  *
  * @param {{
  *   version: string,
  *   argv?: string[],
- *   register?: (program: Command, groups: { device: Command, product: Command, bucket: Command }) => void,
+ *   register?: (program: Command, groups: { device: Command, product: Command, bucket: Command, dashboard: Command }) => void,
  *   onNoCommand?: (program: Command) => Promise<void> | void,
  *   mcpTools?: Array<object>,
  *   mcpInstructions?: string,
@@ -81,6 +82,7 @@ export async function runCli({
         device: registerDeviceCommands(program),
         product: registerProductCommands(program),
         bucket: registerBucketCommands(program),
+        dashboard: registerDashboardCommands(program),
     };
     registerAuthCommands(program);
     registerProfileCommands(program);

package/lib/commands/auth.js

@@ -10,6 +10,7 @@ import {
     setActiveProfile,
 } from '../config.js';
 import { hint, info, warning } from '../format.js';
+import { env, identity } from '../identity.js';
 import { classifyError, createSpinner, printErr } from '../output.js';
 
 /**
@@ -46,6 +47,13 @@ export function registerAuthCommands(program) {
                     clientId: opts.clientId,
                 });
                 console.log(info(`Signed in (profile ${getActiveProfile()}).`));
+                if (env('TOKEN')) {
+                    console.log(
+                        warning(
+                            `${identity().envPrefix}_TOKEN is set: commands use it instead of this profile until you unset it.`,
+                        ),
+                    );
+                }
             } catch (error) {
                 const { message, code } = classifyError(error);
                 printErr(message, { code });
@@ -65,7 +73,18 @@ export function registerAuthCommands(program) {
                 console.log(warning('No configuration found. Already logged out.'));
                 return;
             }
-            const names = opts.all ? listProfiles() : [getActiveProfile()];
+            const active = getActiveProfile();
+            if (!opts.all && !active && env('TOKEN')) {
+                // <PREFIX>_TOKEN stands for the profile: there is nothing saved to forget.
+                const prefix = identity().envPrefix;
+                console.log(
+                    warning(
+                        `${prefix}_TOKEN is set and stands for the profile: unset it, or pass --profile to log out of a saved one.`,
+                    ),
+                );
+                return;
+            }
+            const names = opts.all ? listProfiles() : [active];
             for (const name of names) {
                 const spinner = createSpinner(`Logging out of ${name}...`).start();
                 if (!opts.keepToken) {

package/lib/commands/dashboard.js

@@ -0,0 +1,262 @@
+// @ts-check
+import path from 'node:path';
+import open from 'open';
+import {
+    collectFiles,
+    destinationContext,
+    manifestName,
+    parseDestination,
+    publishApp,
+    publishSummary,
+    readManifest,
+} from '../dashboard.js';
+import { DEV_HOURS, devLink } from '../dashboard-dev.js';
+import { DEFAULT_TEMPLATE, initApp } from '../dashboard-init.js';
+import { inputError } from '../errors.js';
+import { accent, hint, warning } from '../format.js';
+import { identity } from '../identity.js';
+import { isJsonMode, printOk } from '../output.js';
+import { applyJsonFlag, ensureConfigured, getGlobalUser, runCommand } from './_shared.js';
+
+const collect = (value, previous = []) => [...previous, value];
+
+/** Destinations of the command line, each with the shared --entry / --route / --name. */
+function flagDestinations(opts) {
+    return (opts.to || []).map((value) => ({
+        ...parseDestination(value),
+        ...(opts.entry ? { entry: opts.entry } : {}),
+        ...(opts.route ? { route: opts.route } : {}),
+        ...(opts.name ? { name: opts.name } : {}),
+    }));
+}
+
+/** `<cli> dashboard dev|publish` — url-source dashboard apps. */
+export function registerDashboardCommands(program) {
+    const cli = identity().name;
+    const dashboard = program
+        .command('dashboard')
+        .helpGroup('Operations:')
+        .description(
+            'Dashboard apps (HTML + the dashboard SDK): develop them on their dev server and publish them',
+        )
+        .addHelpText(
+            'after',
+            `
+Both commands read defaults from ${manifestName()} in the working folder (or --config):
+  { "dashboard": { "dir": "dist/greenhouse/browser", "storage": "app_greenhouse", "prune": true,
+                   "to": [{ "type": "device", "id": "gh_01" }],
+                   "dev": { "url": "http://localhost:4200/", "context": { "device": "gh_01" } } } }
+
+In CI, ${identity().envPrefix}_TOKEN and ${identity().envPrefix}_SERVER replace the saved profile (unless --profile or ${identity().envPrefix}_PROFILE names one).`,
+        );
+
+    dashboard
+        .command('init <dir>')
+        .description(
+            'Create a dashboard app (TypeScript, on @thinger-io/dashboard-sdk) from a template of the SDK',
+        )
+        .option(
+            '-t, --template <name>',
+            `Template of the SDK package: react, angular… (default ${DEFAULT_TEMPLATE})`,
+        )
+        .option(
+            '--to <destination>',
+            'Where it publishes: device:<id>, product:<id>, dashboard:<id>…',
+        )
+        .option('-s, --storage <id>', 'Storage it publishes to (default app_<folder>_<random>)')
+        .option(
+            '--from <package>',
+            'SDK package to take the template from: a version or tag on npm, or a folder or .tgz',
+        )
+        .option('--ci', 'Add a GitHub workflow that publishes it on every push to main')
+        .option('--install', 'Run npm install')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (dir, opts) => {
+            applyJsonFlag(opts);
+            await runCommand({
+                start: 'Creating the app...',
+                fn: () =>
+                    initApp({
+                        dir,
+                        template: opts.template,
+                        to: opts.to ? parseDestination(opts.to) : undefined,
+                        storage: opts.storage,
+                        from: opts.from,
+                        ci: !!opts.ci,
+                        install: !!opts.install,
+                    }),
+                success: (r) =>
+                    `Created ${r.name} (${r.template}, ${r.sdk ? `SDK ${r.sdk}` : 'SDK'})`,
+                failure: 'Failed to create the app',
+                onSuccess: (r) => {
+                    if (isJsonMode()) {
+                        printOk(r);
+                        return;
+                    }
+                    console.log(
+                        hint(
+                            `  ${r.dir}: ${r.template} app on ${r.dependency.startsWith('file:') ? r.dependency : `@thinger-io/dashboard-sdk ${r.dependency}`}, ${manifestName()} (publishes ${r.build} to ${r.storage}) and AGENTS.md.`,
+                        ),
+                    );
+                    console.log(`\n  cd ${dir}`);
+                    if (!r.installed) console.log('  npm install');
+                    console.log(`  ${r.devCommand}`);
+                    console.log(
+                        `  ${cli} dashboard dev${Object.keys(r.context).length ? '' : ' --device <id>'}   ${hint('# link to the running app against the server')}`,
+                    );
+                    console.log(`  npm run build && ${cli} dashboard publish`);
+                },
+            });
+        });
+
+    dashboard
+        .command('dev [url]')
+        .description(
+            'Link that opens the app on its own dev server (ng serve, Vite…) against the server, with a temporary token',
+        )
+        .option(
+            '--to <destination>',
+            'Context of a destination: device:<id>, product:<id>, dashboard:<id>…',
+        )
+        .option('--device <id>', 'Device in the SDK context')
+        .option('--product <id>', 'Product in the SDK context')
+        .option('--asset-type <id>', 'Asset type in the SDK context')
+        .option('--asset-group <id>', 'Asset group in the SDK context')
+        .option('--project <id>', 'Project the app runs in')
+        .option('--route <route>', 'Initial route, e.g. /devices')
+        .option('--hours <hours>', `Hours the token lasts (default ${DEV_HOURS})`, Number)
+        .option('--open', 'Open the link in the browser')
+        .option(
+            '--allow-remote',
+            'Allow an app url that is not on this machine (the link carries a full-access token)',
+        )
+        .option('--config <file>', `Manifest (default ${manifestName()})`)
+        .option('-j, --json', 'Output as JSON')
+        .addHelpText(
+            'after',
+            `
+Start the app's dev server first (the command warns when nothing answers at the url).
+The app bundles @thinger-io/dashboard-sdk, which takes the server, a temporary token and the
+context from the link: its dev server needs no proxy. Each run replaces the previous link's
+token (one per project).`,
+        )
+        .action(async (url, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            await runCommand({
+                start: 'Creating the dev link...',
+                fn: async () => {
+                    const manifest = readManifest(opts.config);
+                    const dev = manifest?.dev || {};
+                    const app = url || dev.url;
+                    if (!app) {
+                        throw inputError(
+                            `pass the app's dev server url (e.g. ${cli} dashboard dev http://localhost:4200/ --device gw1), or set dev.url in ${manifestName()}`,
+                        );
+                    }
+                    const explicit = {
+                        device: opts.device,
+                        product: opts.product,
+                        type: opts.assetType,
+                        group: opts.assetGroup,
+                        project: opts.project,
+                    };
+                    const to = opts.to ? parseDestination(opts.to) : manifest?.to?.[0];
+                    const context = Object.values(explicit).some(Boolean)
+                        ? explicit
+                        : !opts.to && dev.context
+                          ? dev.context
+                          : destinationContext(to);
+                    return devLink({
+                        url: app,
+                        context,
+                        route: opts.route ?? dev.route ?? to?.route,
+                        hours: opts.hours ?? dev.hours,
+                        user,
+                        dir: manifest ? path.dirname(manifest.file) : process.cwd(),
+                        allowRemote: !!opts.allowRemote,
+                    });
+                },
+                success: () => 'Dev link ready',
+                failure: 'Failed to create the dev link',
+                onSuccess: async (dev) => {
+                    if (isJsonMode()) printOk(dev);
+                    else {
+                        const ctx = Object.entries(dev.context).map(([k, v]) => `${k} ${v}`);
+                        const until = new Date(dev.expire).toTimeString().slice(0, 5);
+                        console.log(`  ${accent(dev.link)}`);
+                        console.log(
+                            hint(
+                                `  ${dev.app} → ${dev.server} as ${dev.user}${ctx.length ? `, ${ctx.join(', ')}` : ''}. Temporary token ${dev.token} until ${until}: writes are real.`,
+                            ),
+                        );
+                        for (const note of dev.notes) console.log(warning(`  ${note}`));
+                    }
+                    if (opts.open) await open(dev.link).catch(() => {});
+                },
+            });
+        });
+
+    dashboard
+        .command('publish [dir]')
+        .description('Upload an app to a public storage and point dashboards at it')
+        .option('-s, --storage <id>', 'Storage of the app (created public if missing)')
+        .option(
+            '--to <destination>',
+            'Dashboard to point (repeatable): dashboard:<id>, device:<id>, product:<id>, asset_type:<id>, asset_group:<id>, project:<id>',
+            collect,
+        )
+        .option('--entry <page>', 'Page the destinations open (default index.html)')
+        .option('--route <route>', 'Initial route of the destinations')
+        .option('--name <name>', 'Name of a collection dashboard')
+        .option('--prune', 'Delete files of the storage that are not in this upload')
+        .option('--no-prune', "Keep the storage's other files (overrides the manifest)")
+        .option('--bump', 'Make consoles that have the app open reload it at once')
+        .option(
+            '--preview [hours]',
+            'Also print standalone preview links (read-only, 1 h by default)',
+        )
+        .option('--no-point', 'Upload without pointing the destinations (preview links only)')
+        .option('--config <file>', `Manifest (default ${manifestName()})`)
+        .option('-j, --json', 'Output as JSON')
+        .action(async (dir, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            await runCommand({
+                start: 'Publishing...',
+                fn: async () => {
+                    const manifest = readManifest(opts.config);
+                    const folder = dir || manifest?.dir;
+                    const to = opts.to ? flagDestinations(opts) : manifest?.to || [];
+                    const prune = opts.prune ?? manifest?.prune;
+                    const preview =
+                        opts.preview === undefined
+                            ? false
+                            : opts.preview === true
+                              ? true
+                              : Number(opts.preview);
+                    return publishApp({
+                        storage: opts.storage || manifest?.storage,
+                        files: folder ? collectFiles(folder) : undefined,
+                        prune: !!prune,
+                        to,
+                        preview,
+                        point: opts.point,
+                        bump: !!opts.bump,
+                        user,
+                        dir: folder,
+                    });
+                },
+                success: (r) => `Published ${r.storage}`,
+                failure: 'Failed to publish',
+                onSuccess: (result) => {
+                    if (isJsonMode()) printOk(result);
+                    else console.log(publishSummary(result, { point: opts.point }));
+                },
+            });
+        });
+
+    return dashboard;
+}