@straitlink/cli 0.3.4 → 0.3.5

package/README.md

@@ -16,6 +16,7 @@ npx @straitlink/cli init                                     # set up deep links
 npx @straitlink/cli doctor --host acme.strait.link          # check the link host lists your app
 npx @straitlink/cli links create summer https://acme.com/s  # create a link (secret key in env)
 npx @straitlink/cli test                                    # key, engine and link domain: pass/fail (secret key in env)
+npx @straitlink/cli app verify                              # your whole setup, each problem with its fix (secret key in env)
 npx @straitlink/cli events add purchase                     # print the code that tracks an event
 ```
 
@@ -82,6 +83,8 @@ Android (assetlinks.json)
 | `--key` | Also check the publishable key. Env: `STRAIT_PUBLISHABLE_KEY`. Left out, the key check is skipped |
 | `--json` | The reports as JSON, for CI and agents |
 
+With a secret key (`STRAIT_SECRET_KEY` or `--secret-key`), `doctor` also runs [`strait app verify`](#whats-wrong-with-my-setup-strait-app-verify) and prints its checks under "Account"; `--host` is then optional. If those checks can't run (a refused or malformed key, no connection, the 6-a-minute limit) it says "Could not check" and exits `1`, never a silent pass. `--json` adds them as `verify`. If your CI sets `STRAIT_SECRET_KEY` and should check only the host, unset it for the doctor step (`env -u STRAIT_SECRET_KEY npx @straitlink/cli doctor --host …`).
+
 Exit codes: `0` no errors (warnings allowed), `1` a check failed, `2` usage problem. What a terminal can't see (intent filters, the Associated Domains entitlement) is checked by `doctor()` inside a debug build and by the [free tools](https://straitlink.in/tools/).
 
 ## Manage links: `strait links`
@@ -120,6 +123,30 @@ Your app's own setup (intent filters, Associated Domains): strait doctor --andro
 
 One read-only pass: the engine answers (`GET /healthz`), the secret key is valid and which workspace it belongs to, test or live (`GET /v1/workspace`), and the workspace's link domain serves `apple-app-site-association` and `assetlinks.json` listing your apps (the same checks as `strait doctor`). A failed check prints its fix; checks that need it are skipped. Exit `1` when any check fails, `2` for a missing or wrong kind of key, so it can gate a CI job. `--json` prints `{ ok, workspace, checks }`. Same key rules as `strait links`: never printed, publishable keys refused.
 
+## What's wrong with my setup? `strait app verify`
+
+```bash
+export STRAIT_SECRET_KEY=st_live_…        # Dashboard → Settings → Secret keys (read or full access)
+npx @straitlink/cli app            # the setup Strait has: apps, link domains and their files, SDKs seen
+npx @straitlink/cli app verify     # every check, with the fix for each problem
+```
+
+```
+Strait app verify (checked 2026-11-09 17:44 UTC)
+
+  pass     Android app details are complete
+  pass     Android file served correctly on acme.strait.link
+  warn     Your iPhone build runs a Strait SDK from before 5 Nov 2026
+           Its app opens don't say which SDK version sent them, so Strait can't tell what it misses.
+           Fix: Update the Strait SDK to its current version (Dashboard › Setup shows it) and ship a new build.
+  skip     No webhooks set up
+
+2 pass, 1 warn, 0 fail, 0 unknown, 1 skip.
+No failures. Check the warnings above.
+```
+
+The same checks as Dashboard › Setup › Integration health, from the API (`GET /v1/app`, `GET /v1/app/verify`): your Android and iPhone app details, each link domain's `assetlinks.json` and `apple-app-site-association` (fetched live), whether your app has reported in the last 24 hours, whether its SDK is current, whether app opens from a link show their screen, and webhooks. Exit `0` when nothing failed, `1` when a check failed or could not run, or the API refused the key (so an AI agent or CI job can loop until it passes), `2` for a missing or non-secret key. `--json` prints the API answer as is (`{ ok, checkedAt, summary, checks: [{ id, status, title, detail, fix, host?, platform? }] }`). Nothing secret is printed: no keys, emails or webhook URLs.
+
 ## Track an event: `strait events add`
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@straitlink/cli",
-  "version": "0.3.4",
-  "description": "Strait deep links from the terminal: init sets them up in a React Native, Expo, Flutter or Android app, doctor checks your link host, links creates and lists links and saves QR codes.",
+  "version": "0.3.5",
+  "description": "Strait deep links from the terminal: init sets them up in a React Native, Expo, Flutter or Android app, doctor checks your link host, app verify checks your whole setup with a fix for each problem, links creates and lists links and saves QR codes.",
   "keywords": [
     "strait",
     "deep-linking",

package/src/app.mjs

@@ -0,0 +1,106 @@
+// `strait app` and `strait app verify` (docs/adr/0003): the workspace's app setup and the engine's checks of it
+// (GET /v1/app, GET /v1/app/verify, engine ADR 0108), printed for people, or as the engine's JSON for agents.
+// The engine owns every rule and every fix's wording; this file only prints them.
+import { ApiError } from './links.mjs';
+
+// Engine text can carry user-controlled names (hosts, workspace text): one printed line stays one line, with no
+// terminal control characters and no bidi overrides that could make it read as something else.
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g;
+const clean = (line) => String(line).replace(UNSAFE, (c) => (c === '\n' || c === '\r' || c === '\t' ? ' ' : ''));
+const lines = (out) => out.map(clean).join('\n');
+/** JSON for agents: as is, with DEL, C1 and bidi characters escaped (JSON.stringify escapes only those below U+0020). */
+export const toJson = (x) => JSON.stringify(x, null, 2).replace(/[\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+const str = (x) => (typeof x === 'string' && x ? x : null);
+const objs = (x) => (Array.isArray(x) ? x.filter((o) => o && typeof o === 'object') : []);
+const day = (iso) => {
+  const t = Date.parse(str(iso) ?? '');
+  return Number.isFinite(t) ? `${new Date(t).toISOString().slice(0, 16).replace('T', ' ')} UTC` : '?';
+};
+
+/** `sub`: undefined (show the setup) or 'verify'; cli.mjs refuses anything else. @returns {Promise<{ text: string, code: number }>} */
+export async function appCommand(sub, v, { call }) {
+  if (sub === undefined) {
+    const setup = await getJson(call, '/v1/app');
+    return { text: v.json ? toJson(setup) : formatSetup(setup), code: 0 };
+  }
+  const answer = await getVerify(call);
+  return { text: v.json ? toJson(answer) : formatVerify(answer), code: answer?.ok === true ? 0 : 1 };
+}
+
+/** A 200 that isn't JSON (a proxy page, a wrong --api-url) is an ApiError, not a crash. */
+async function getJson(call, path) {
+  const res = await call('GET', path);
+  try {
+    return await res.json();
+  } catch {
+    throw new ApiError(`GET ${path}: the answer is not JSON. Is --api-url (STRAIT_API_URL) a Strait engine?`);
+  }
+}
+
+export const getVerify = (call) => getJson(call, '/v1/app/verify');
+
+function formatSetup(s) {
+  const a = s?.android;
+  const i = s?.ios;
+  const out = ['Strait app setup', ''];
+  if (a) {
+    out.push(`  Android   ${str(a.packageName) ?? '(no package name)'}${str(a.scheme) ? `  scheme ${a.scheme}` : ''}  ${a.appLinksReady ? 'App Links ready' : 'App Links NOT ready'}`);
+    for (const fp of Array.isArray(a.sha256Fingerprints) ? a.sha256Fingerprints : []) out.push(`            SHA-256 ${fp}`);
+  } else out.push('  Android   not set up');
+  if (i) {
+    const id = str(i.appId) ?? `${str(i.teamId) ?? '(no Team ID)'}.${str(i.bundleId) ?? '(no bundle ID)'}`;
+    out.push(`  iPhone    ${id}${str(i.appStoreId) ? `  App Store ${i.appStoreId}` : ''}  ${i.universalLinksReady ? 'Universal Links ready' : 'Universal Links NOT ready'}`);
+  } else out.push('  iPhone    not set up');
+
+  const domains = objs(s?.domains);
+  out.push('', `Link domains (files checked ${day(s?.filesCheckedAt)})`);
+  if (!domains.length) out.push('  none');
+  const PHONE = { android: 'Android', ios: 'iPhone' };
+  for (const d of domains) {
+    const files = objs(d.files).map((f) => `${PHONE[f.platform] ?? f.platform} file ${f.served === true ? 'served' : f.served === false ? 'NOT served' : 'not checked yet'}`);
+    out.push(`  ${d.host} (${d.kind})  ${files.join(' · ') || 'no app file (no app set up)'}`);
+  }
+
+  out.push('', `SDK seen (last ${s?.sdkWindow?.days ?? 30} days)`);
+  for (const [p, label] of [['android', 'Android'], ['ios', 'iPhone'], ['web', 'Web']]) {
+    const x = s?.sdk?.[p];
+    const what = !x ? 'not seen' : `${str(x.reported) ?? 'no SDK version sent'}, last app open ${day(x.lastSeenAt)}`;
+    out.push(`  ${label.padEnd(8)}  ${what}`);
+  }
+  out.push('', `Change these in ${str(s?.setupUrl) ?? 'Dashboard › Setup'}. Check everything: strait app verify`);
+  return lines(out);
+}
+
+/** One line per check; under anything not passed, what is wrong and the fix. */
+export function verifyLines(answer) {
+  const out = [];
+  for (const c of objs(answer?.checks)) {
+    out.push(`  ${String(c.status).padEnd(7)}  ${c.title}`);
+    if (c.status === 'pass' || c.status === 'skip') continue;
+    if (c.detail) out.push(`           ${c.detail}`);
+    if (c.fix) out.push(`           Fix: ${c.fix}`);
+  }
+  return out;
+}
+
+/** The verdict line: failures first, then checks that could not run. */
+export function verifyVerdict(answer) {
+  const n = answer?.summary ?? {};
+  if (n.fail) return `${n.fail} check${n.fail > 1 ? 's' : ''} failed. Fix them, then run strait app verify again.`;
+  if (n.unknown) return `${n.unknown} check${n.unknown > 1 ? 's' : ''} could not run. Run strait app verify again in a minute.`;
+  return answer?.ok === true ? (n.warn ? 'No failures. Check the warnings above.' : 'All checks passed.') : 'Not all checks passed.';
+}
+
+function formatVerify(answer) {
+  const n = answer?.summary ?? {};
+  const out = [`Strait app verify (checked ${day(answer?.checkedAt)})`, '', ...verifyLines(answer), ''];
+  out.push(`${n.pass ?? 0} pass, ${n.warn ?? 0} warn, ${n.fail ?? 0} fail, ${n.unknown ?? 0} unknown, ${n.skip ?? 0} skip.`, verifyVerdict(answer));
+  return lines(out);
+}
+
+/** `strait doctor`'s account block: the verify answer, or why it could not run (never a silent pass). */
+export function formatAccount(answer) {
+  const head = 'Account (strait app verify)';
+  if (answer?.error) return lines([head, `  Could not check: ${answer.error}`]);
+  return lines([head, ...verifyLines(answer), '', verifyVerdict(answer)]);
+}

package/src/cli.mjs

@@ -11,6 +11,7 @@ import { ApiError, DEFAULT_API_URL, apiClient, linksCommand, secretKey } from '.
 import { CLI_VERSION } from './version.mjs';
 import { formatSelfTest, runSelfTest } from './selftest.mjs';
 import { eventsCommand } from './events.mjs';
+import { appCommand, formatAccount, getVerify, toJson } from './app.mjs';
 
 const OPTIONS = {
   init: {
@@ -28,6 +29,8 @@ const OPTIONS = {
     android: { type: 'string' },
     ios: { type: 'string' },
     cert: { type: 'string', multiple: true },
+    'secret-key': { type: 'string' },
+    'api-url': { type: 'string' },
     json: { type: 'boolean', default: false },
   },
   links: {
@@ -53,17 +56,24 @@ const OPTIONS = {
   events: {
     platform: { type: 'string' },
   },
+  app: {
+    'secret-key': { type: 'string' },
+    'api-url': { type: 'string' },
+    json: { type: 'boolean', default: false },
+  },
 };
 
 export const HELP = `strait: set up and check Strait deep links, and manage links
 
 Usage
   strait init [dir] [options]                 Write the Strait integration into your app
-  strait doctor --host <host> [options]       Check your link host is set up for your app
+  strait doctor [--host <host>] [options]     Check your link host (and with a secret key, your whole setup)
   strait links create <slug> <url> [options]  Create a link
   strait links list [options]                 List links
   strait links qr <slug> [options]            Save a link's QR code
   strait test [options]                       Check your key, the engine and your link domain
+  strait app [options]                        Show your app setup as Strait sees it
+  strait app verify [options]                 Check your whole setup: each problem with its fix
   strait events add <name> [dir] [options]    Print ready-to-paste code that tracks an event
 
 init options
@@ -82,6 +92,9 @@ doctor options (the same checks and messages as doctor() in the SDKs)
   --ios <bundleId>        iPhone bundle ID, e.g. com.acme.shop
   --cert <sha256>         Android signing certificate fingerprint (repeatable)
   --key <st_pub_live_…>   Also check the publishable key (env STRAIT_PUBLISHABLE_KEY)
+  --secret-key <st_live_…>  Also run strait app verify (env STRAIT_SECRET_KEY); --host is then optional.
+                          If it can't run (refused key, no connection), doctor says so and exits 1
+  --api-url <url>         Engine for those checks (env STRAIT_API_URL, default https://strait.link)
   --json                  Print the reports as JSON
   With neither --android nor --ios, both files are checked and the apps they list are shown.
   Exit 1 when a check fails.
@@ -102,6 +115,14 @@ test options
   workspace's link domain serves apple-app-site-association and assetlinks.json. Exit 1
   when a check fails (so it can run in CI), 2 for a missing or wrong kind of key.
 
+app options
+  --secret-key, --api-url   As for links (env STRAIT_SECRET_KEY, STRAIT_API_URL); a read or full key
+  --json                  Print the API answer as JSON (for agents and CI)
+  strait app prints the apps, link domains and SDKs Strait has for your workspace. strait app verify
+  runs the same checks as Dashboard › Setup › Integration health and prints each with its fix.
+  Exit 1 when a check fails or could not run (or the API refuses the key), 2 for a missing or
+  non-secret key.
+
 events options
   --platform <name>       react-native | flutter | ios | android | web (detected by default)
 
@@ -114,6 +135,7 @@ Examples
   npx @straitlink/cli doctor --host acme.strait.link --android com.acme.shop --ios com.acme.shop
   STRAIT_SECRET_KEY=st_live_… npx @straitlink/cli links create summer https://acme.com/summer
   STRAIT_SECRET_KEY=st_live_… npx @straitlink/cli test
+  STRAIT_SECRET_KEY=st_live_… npx @straitlink/cli app verify
   npx @straitlink/cli events add purchase
 `;
 
@@ -146,7 +168,7 @@ export async function main(argv, io = {}) {
   }
   if (cmd !== 'init') {
     try {
-      return await { doctor, links, test: selfTest, events }[cmd](args, { out, err, env, io });
+      return await { doctor, links, test: selfTest, events, app }[cmd](args, { out, err, env, io });
     } catch (e) {
       if (e instanceof UsageError) {
         err.write(`strait: ${e.message}\n`);
@@ -223,15 +245,41 @@ async function terminalAsker(input, output) {
 
 async function doctor({ values: v }, { out, env, io }) {
   const hostIn = v.host ?? env.STRAIT_LINK_HOST;
-  if (!hostIn) throw new UsageError('Missing --host: your link domain from Dashboard → Get started, e.g. --host acme.strait.link.');
-  const host = normalizeHost(hostIn);
-  const keyIn = v.key ?? env.STRAIT_PUBLISHABLE_KEY;
-  const key = keyIn ? String(keyIn).trim() : undefined;
-  const result = await runDoctor({ host, key, android: v.android?.trim(), ios: v.ios?.trim(), certs: v.cert ?? [], fetch: io.fetch ?? fetch });
-  out.write((v.json ? JSON.stringify(result, null, 2) : formatDoctor(result)) + '\n');
+  const secretIn = v['secret-key'] ?? env.STRAIT_SECRET_KEY;
+  if (!hostIn && !secretIn) throw new UsageError('Missing --host: your link domain from Dashboard → Get started, e.g. --host acme.strait.link. Or set STRAIT_SECRET_KEY to check your whole setup.');
+  const fetchImpl = io.fetch ?? fetch;
+  let result = { ok: true };
+  if (hostIn) {
+    const keyIn = v.key ?? env.STRAIT_PUBLISHABLE_KEY;
+    const key = keyIn ? String(keyIn).trim() : undefined;
+    result = await runDoctor({ host: normalizeHost(hostIn), key, android: v.android?.trim(), ios: v.ios?.trim(), certs: v.cert ?? [], fetch: fetchImpl });
+  }
+  if (secretIn) {
+    // A secret key adds the engine's checks (docs/adr/0003). If they can't run, say so and fail: never a silent pass.
+    try {
+      const call = apiClient({ apiUrl: v['api-url'] ?? env.STRAIT_API_URL ?? DEFAULT_API_URL, key: secretKey(secretIn), fetch: fetchImpl, userAgent: `strait-cli/${CLI_VERSION}` });
+      result.verify = await getVerify(call);
+    } catch (e) {
+      if (!(e instanceof ApiError || e instanceof UsageError)) throw e;
+      result.verify = { error: e.message };
+    }
+    if (result.verify?.ok !== true) result.ok = false;
+  }
+  const text = v.json ? toJson(result) : [hostIn && formatDoctor(result), secretIn && formatAccount(result.verify)].filter(Boolean).join('\n\n');
+  out.write(text + '\n');
   return result.ok ? 0 : 1;
 }
 
+async function app({ values: v, positionals }, { out, env, io }) {
+  const [sub, extra] = positionals;
+  if (extra !== undefined || (sub !== undefined && sub !== 'verify'))
+    throw new UsageError(`Unknown "${extra ?? sub}". strait app shows your setup; strait app verify checks it (--json for agents).`);
+  const call = apiClient({ apiUrl: v['api-url'] ?? env.STRAIT_API_URL ?? DEFAULT_API_URL, key: secretKey(v['secret-key'] ?? env.STRAIT_SECRET_KEY), fetch: io.fetch ?? fetch, userAgent: `strait-cli/${CLI_VERSION}` });
+  const { text, code } = await appCommand(sub, v, { call });
+  out.write(text + '\n');
+  return code;
+}
+
 async function selfTest({ values: v, positionals }, { out, env, io }) {
   if (positionals.length) throw new UsageError(`strait test takes no arguments ("${positionals[0]}"). Options: --secret-key, --api-url, --json.`);
   const key = secretKey(v['secret-key'] ?? env.STRAIT_SECRET_KEY);

package/src/doctor.mjs

@@ -148,7 +148,8 @@ export function formatDoctor(result) {
   if (keyLines.length) out.push('', 'Key', ...keyLines.map(line));
   for (const p of reports) out.push('', LABEL[p], ...result[p].findings.filter((f) => !f.id.startsWith('key.')).map(line));
   const warned = reports.some((p) => result[p].findings.some((f) => f.severity === 'warn'));
-  out.push('', !result.ok ? 'Fix the errors above, then run strait doctor again.' : warned ? 'No errors. Check the warnings above.' : 'All checks passed.');
+  // The host's own verdict: a secret key's account checks (cli.mjs) have their own.
+  out.push('', reports.some((p) => !result[p].ok) ? 'Fix the errors above, then run strait doctor again.' : warned ? 'No errors. Check the warnings above.' : 'All checks passed.');
   out.push("Intent filters and the Associated Domains entitlement aren't visible from here: call doctor() in a debug build, or see https://straitlink.in/tools/.");
   return out.join('\n');
 }

package/src/version.mjs

@@ -1,2 +1,2 @@
 // Kept equal to package.json version (test/links.test.mjs checks it). Sent as the API User-Agent.
-export const CLI_VERSION = '0.3.4';
+export const CLI_VERSION = '0.3.5';