@straitlink/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Strait authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+<h1 align="center">Strait CLI</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><strong>Straight to the screen. On the record.</strong><br>
+One command sets up Strait deep links in your app. Every link open and install is then recorded in your Strait dashboard.</p>
+
+<p align="center">
+  <a href="https://straitlink.in/docs/">Docs</a> ·
+  <a href="https://straitlink.in/platform-status/">Platform status</a> ·
+  <a href="#docs-and-support">Talk to the Strait team</a>
+</p>
+
+`@straitlink/cli`
+
+```bash
+npx @straitlink/cli init
+```
+
+`strait init` sets up Strait deep links in a React Native, Expo, Flutter or Android (Kotlin) app:
+
+1. Detects the app from its files (`package.json`, `app.json`, `pubspec.yaml`, Gradle files). Nothing is run.
+2. Takes your publishable key and link host as flags, or asks for them in a terminal. A secret key (`st_live_…`) is refused, because it must never ship in an app.
+3. Writes the integration file, with your key, host and an `onLink` handler:
+
+   | App | File written |
+   |---|---|
+   | React Native | `links.ts` (or `links.js`) |
+   | Expo | `links.ts`, plus `app/+native-intent.tsx` with Expo Router |
+   | Flutter | `lib/links.dart` |
+   | Android | `app/src/main/java/<package>/StraitLinks.kt` |
+
+4. Prints the remaining steps for your app: the install command, the AndroidManifest intent filters (or the `app.json` block for Expo), the iPhone (beta) Associated Domains entry, what to fill in under Dashboard → Settings, and the `curl` checks for `assetlinks.json` and `apple-app-site-association`. Steps the project already has, such as the intent filters, are marked `[already done]`.
+
+It never edits your existing files and never overwrites an earlier integration file unless you pass `--force`.
+
+## Use
+
+Run it in your app's folder. Node 18.17 or newer; nothing to install first.
+
+```bash
+npx @straitlink/cli init                                         # asks for the key and host
+npx @straitlink/cli init --key st_pub_live_… --host acme.strait.link
+npx @straitlink/cli init ../my-app --dry-run                     # show the files and steps, write nothing
+```
+
+From a checkout of this repo: `node bin/strait.mjs init ../my-app`, or `npm link && strait init`.
+
+| Option | |
+|---|---|
+| `--key` | Publishable key (Dashboard → Get started). Env: `STRAIT_PUBLISHABLE_KEY` |
+| `--host` | Link domain, e.g. `acme.strait.link`. A pasted link works too. Env: `STRAIT_LINK_HOST` |
+| `--scheme` | Custom scheme. Taken from `app.json`, or guessed from the package name (`com.acme.shop` → `acmeshop`) |
+| `--framework` | `react-native`, `expo`, `flutter` or `android`, to skip detection |
+| `--dry-run` | Print the files and steps; write nothing |
+| `--force` | Replace an existing integration file |
+| `--yes`, `-y` | Never prompt. Exits 2 if something is missing (for CI and agents) |
+
+Exit codes: `0` done, `2` usage problem (message on stderr), `1` unexpected error.
+
+## Install lines: one constant
+
+Every install line the CLI prints comes from `INSTALL` in `src/install.mjs` (`source` + `githubOwner`). It mirrors `install` in `site/site.config.json` and `INSTALL` in `dashboard/src/lib/install.ts`, and `test/install.test.mjs` fails if they drift while the repos sit side by side. Moving the SDK repos to an organisation means changing `githubOwner`. Publishing to npm, pub.dev and Maven Central means changing `source` to `"registry"`.
+
+## Test
+
+```bash
+npm test                                  # node:test, no dependencies
+node scripts/time-to-first-link.mjs       # see docs/TIME-TO-FIRST-LINK.md
+```
+
+Fixture apps live in `test/fixtures/` (bare React Native, Expo with and without Expo Router, Flutter, Kotlin, and a folder with no app).
+
+## Docs and support
+
+- **Docs:** [straitlink.in/docs/](https://straitlink.in/docs/) · [platform status](https://straitlink.in/platform-status/) · [troubleshooting](https://straitlink.in/docs/troubleshooting/)
+- **Talk to the Strait team:** [support@straitlink.in](mailto:support@straitlink.in) (replies within 1 working day, IST) or call +91 81218 61890.
+- **Bugs and feature requests:** [open an issue](https://github.com/bazingga08/strait-cli/issues) on this repo.
+- **Security:** never in a public issue. Write to security@straitlink.in.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/bin/strait.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (e) => {
+    process.stderr.write(`strait: unexpected error: ${e?.stack ?? e}\n`);
+    process.exit(1);
+  },
+);

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@straitlink/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "npx @straitlink/cli init: set up Strait deep links in a React Native, Expo, Flutter or Android app.",
+  "keywords": [
+    "strait",
+    "deep-linking",
+    "deferred-deep-linking",
+    "app-links",
+    "universal-links",
+    "react-native",
+    "expo",
+    "flutter",
+    "android",
+    "cli"
+  ],
+  "homepage": "https://straitlink.in/docs/",
+  "bugs": {
+    "url": "https://github.com/bazingga08/strait-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bazingga08/strait-cli.git"
+  },
+  "license": "MIT",
+  "author": "The Strait team <support@straitlink.in>",
+  "type": "module",
+  "bin": {
+    "strait": "bin/strait.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "ttfl": "node scripts/time-to-first-link.mjs"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,129 @@
+// Argument parsing and prompting. `main(argv, io)` returns an exit code, so tests
+// can drive it without spawning a process.
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { detectProject } from './detect.mjs';
+import { formatPlan, planInit, writeFiles } from './init.mjs';
+import { UsageError, normalizeHost, normalizeKey, normalizeScheme, suggestScheme } from './validate.mjs';
+import { resolve } from 'node:path';
+
+export const HELP = `strait: set up Strait deep links in your app
+
+Usage
+  strait init [dir] [options]
+
+Options
+  --key <st_pub_live_…>   Publishable key (Dashboard → Get started)
+  --host <host>           Your link domain, e.g. acme.strait.link
+  --scheme <scheme>       Your app's custom scheme, e.g. acmeshop (guessed from the package name)
+  --framework <name>      react-native | expo | flutter | android (detected by default)
+  --dry-run               Print what would be written; write nothing
+  --force                 Replace an existing integration file
+  --yes, -y               Never prompt; fail if something is missing
+  --help, -h              Show this help
+
+Environment
+  STRAIT_PUBLISHABLE_KEY, STRAIT_LINK_HOST are used when the flags are absent.
+
+Examples
+  npx @straitlink/cli init
+  npx @straitlink/cli init --key st_pub_live_… --host acme.strait.link --dry-run
+`;
+
+/**
+ * @param {string[]} argv  arguments after the program name
+ * @param {{ stdout, stderr, stdin, env, isTTY }} io
+ */
+export async function main(argv, io = {}) {
+  const out = io.stdout ?? process.stdout;
+  const err = io.stderr ?? process.stderr;
+  const env = io.env ?? process.env;
+  const isTTY = io.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  let args;
+  try {
+    args = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        key: { type: 'string' },
+        host: { type: 'string' },
+        scheme: { type: 'string' },
+        framework: { type: 'string' },
+        'dry-run': { type: 'boolean', default: false },
+        force: { type: 'boolean', default: false },
+        yes: { type: 'boolean', short: 'y', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+    });
+  } catch (e) {
+    err.write(`${e.message}\n\n${HELP}`);
+    return 2;
+  }
+  const [cmd, dirArg] = args.positionals;
+  if (args.values.help || !cmd) {
+    out.write(HELP);
+    return args.values.help ? 0 : 2;
+  }
+  if (cmd !== 'init') {
+    err.write(`Unknown command "${cmd}".\n\n${HELP}`);
+    return 2;
+  }
+
+  const v = args.values;
+  const dir = resolve(dirArg ?? '.');
+  let key = v.key ?? env.STRAIT_PUBLISHABLE_KEY;
+  let host = v.host ?? env.STRAIT_LINK_HOST;
+  let scheme = v.scheme;
+
+  try {
+    const canAsk = isTTY && !v.yes;
+    if (canAsk && (!key || !host || !scheme)) {
+      const ask = io.ask ?? (await terminalAsker(io.stdin ?? process.stdin, out));
+      try {
+        key = key ?? (await askValid(ask, 'Publishable key (Dashboard → Get started, st_pub_live_…): ', normalizeKey, err));
+        host = host ?? (await askValid(ask, 'Link host (e.g. acme.strait.link): ', normalizeHost, err));
+        if (!scheme) {
+          const guess = suggestScheme(detectProject(dir) ?? {});
+          scheme = await askValid(ask, `Custom scheme${guess ? ` [${guess}]` : ''}: `, (a) => normalizeScheme(a || guess || ''), err);
+        }
+      } finally {
+        ask.close?.();
+      }
+    }
+    const missing = [!key && '--key', !host && '--host'].filter(Boolean);
+    if (missing.length) throw new UsageError(`Missing ${missing.join(' and ')}. Pass them as flags, or run in a terminal to be asked.`);
+
+    const plan = planInit({ dir, key, host, scheme, framework: v.framework, force: v.force });
+    if (v['dry-run']) {
+      out.write(formatPlan(plan, { dryRun: true }) + '\n');
+      if (plan.conflicts.length) out.write(`\nNote: ${plan.conflicts.join(', ')} already exists; a real run needs --force.\n`);
+      return 0;
+    }
+    writeFiles(plan);
+    out.write(formatPlan(plan) + '\n');
+    return 0;
+  } catch (e) {
+    if (e instanceof UsageError) {
+      err.write(`strait: ${e.message}\n`);
+      return 2;
+    }
+    throw e;
+  }
+}
+
+async function askValid(ask, question, normalize, err) {
+  for (let i = 0; i < 3; i++) {
+    const a = (await ask.question(question)).trim();
+    try {
+      return normalize(a);
+    } catch (e) {
+      if (!(e instanceof UsageError)) throw e;
+      err.write(`  ${e.message}\n`);
+    }
+  }
+  throw new UsageError('Giving up after 3 tries.');
+}
+
+async function terminalAsker(input, output) {
+  return createInterface({ input, output });
+}

package/src/detect.mjs

@@ -0,0 +1,135 @@
+// Works out what kind of app lives in a folder, by reading its files only (no
+// commands run, nothing written).
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGES } from './install.mjs';
+
+export const FRAMEWORKS = ['react-native', 'expo', 'flutter', 'android'];
+export const LABELS = { 'react-native': 'React Native', expo: 'Expo', flutter: 'Flutter', android: 'Android (Kotlin)' };
+
+const read = (f) => {
+  try {
+    return readFileSync(f, 'utf8');
+  } catch {
+    return null;
+  }
+};
+const readJson = (f) => {
+  const t = read(f);
+  if (t == null) return null;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+};
+const first = (dir, names) => names.map((n) => join(dir, n)).find((p) => existsSync(p)) ?? null;
+
+/** applicationId (or namespace) from an app-module Gradle file. */
+// The React Native SDK under its npm name, or its pre-rename name (GitHub installs of older tags).
+const hasRnSdk = (deps) => Boolean(deps[PACKAGES.reactNative] || deps['@strait/sdk-react-native']);
+
+export function gradlePackage(text) {
+  if (!text) return null;
+  const m = /\bapplicationId\s*(?:=\s*)?["']([A-Za-z][\w.]*)["']/.exec(text) ?? /\bnamespace\s*(?:=\s*)?["']([A-Za-z][\w.]*)["']/.exec(text);
+  return m ? m[1] : null;
+}
+
+/** The scheme(s) and hosts already declared in an AndroidManifest.xml. */
+export function manifestLinks(text) {
+  if (!text) return { schemes: [], hosts: [], flutterDeepLinkingOff: false };
+  const schemes = [...text.matchAll(/android:scheme="([^"]+)"/g)].map((m) => m[1]);
+  const hosts = [...text.matchAll(/android:host="([^"]+)"/g)].map((m) => m[1]);
+  const flutterDeepLinkingOff = /android:name="flutter_deeplinking_enabled"\s+android:value="false"/.test(text);
+  return { schemes: [...new Set(schemes)], hosts: [...new Set(hosts)], flutterDeepLinkingOff };
+}
+
+/** The Java/Kotlin source root for an Android app module, if it exists. */
+function androidSourceRoot(appDir) {
+  for (const s of ['src/main/java', 'src/main/kotlin']) {
+    const p = join(appDir, s);
+    if (existsSync(p) && statSync(p).isDirectory()) return p;
+  }
+  return null;
+}
+
+/**
+ * Returns null when the folder holds no app we recognise, otherwise:
+ * { framework, label, typescript, expoRouter, appName, androidPackage, iosBundleId,
+ *   scheme, manifestPath, manifest: {schemes, hosts}, sdkInstalled, files: {...} }
+ */
+export function detectProject(dir) {
+  const pkg = readJson(join(dir, 'package.json'));
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  const pubspec = read(join(dir, 'pubspec.yaml'));
+  const base = { appName: null, androidPackage: null, iosBundleId: null, scheme: null, typescript: false, expoRouter: false, sdkInstalled: false };
+
+  if (pkg && deps.expo) {
+    const app = readJson(join(dir, 'app.json'));
+    const expo = app?.expo ?? app ?? {};
+    const scheme = Array.isArray(expo.scheme) ? expo.scheme[0] : expo.scheme;
+    return finish(dir, {
+      ...base,
+      framework: 'expo',
+      typescript: existsSync(join(dir, 'tsconfig.json')),
+      expoRouter: Boolean(deps['expo-router']),
+      appName: expo.name ?? pkg.name ?? null,
+      androidPackage: expo.android?.package ?? null,
+      iosBundleId: expo.ios?.bundleIdentifier ?? null,
+      scheme: typeof scheme === 'string' ? scheme : null,
+      sdkInstalled: hasRnSdk(deps),
+      dynamicConfig: !app && Boolean(first(dir, ['app.config.js', 'app.config.ts'])),
+      androidDir: join(dir, 'android'),
+    });
+  }
+  if (pkg && deps['react-native']) {
+    return finish(dir, {
+      ...base,
+      framework: 'react-native',
+      typescript: existsSync(join(dir, 'tsconfig.json')),
+      appName: readJson(join(dir, 'app.json'))?.name ?? pkg.name ?? null,
+      androidPackage: gradlePackage(read(first(join(dir, 'android/app'), ['build.gradle', 'build.gradle.kts']) ?? '')),
+      sdkInstalled: hasRnSdk(deps),
+      androidDir: join(dir, 'android'),
+    });
+  }
+  if (pubspec && /\bsdk:\s*flutter\b/.test(pubspec)) {
+    return finish(dir, {
+      ...base,
+      framework: 'flutter',
+      appName: /^name:\s*(\S+)/m.exec(pubspec)?.[1] ?? null,
+      androidPackage: gradlePackage(read(first(join(dir, 'android/app'), ['build.gradle', 'build.gradle.kts']) ?? '')),
+      sdkInstalled: /^\s{2}strait_sdk:/m.test(pubspec),
+      androidDir: join(dir, 'android'),
+    });
+  }
+  const appGradle = first(join(dir, 'app'), ['build.gradle.kts', 'build.gradle']);
+  const appGradleText = appGradle ? read(appGradle) : null;
+  if (appGradleText && /com\.android\.application|android\.application/.test(appGradleText)) {
+    return finish(dir, {
+      ...base,
+      framework: 'android',
+      appName: /rootProject\.name\s*=\s*["']([^"']+)["']/.exec(read(first(dir, ['settings.gradle.kts', 'settings.gradle']) ?? '') ?? '')?.[1] ?? null,
+      androidPackage: gradlePackage(appGradleText),
+      sdkInstalled: /strait-sdk-android/.test(appGradleText),
+      androidDir: dir,
+      sourceRoot: androidSourceRoot(join(dir, 'app')),
+    });
+  }
+  return null;
+}
+
+function finish(dir, p) {
+  const manifestPath = p.androidDir ? first(p.androidDir, ['app/src/main/AndroidManifest.xml']) : null;
+  const { androidDir, ...rest } = p;
+  return { ...rest, label: LABELS[p.framework], dir, manifestPath, manifest: manifestLinks(manifestPath ? read(manifestPath) : null) };
+}
+
+/** Folders are listed in error messages so people can see why nothing matched. */
+export function describeFolder(dir) {
+  try {
+    return readdirSync(dir).filter((n) => !n.startsWith('.')).slice(0, 12).join(', ') || '(empty)';
+  } catch {
+    return '(missing)';
+  }
+}

package/src/init.mjs

@@ -0,0 +1,87 @@
+// `strait init`: detect the app, collect key + host + scheme, write the
+// integration file(s), print the platform steps. Pure planning is separated from
+// writing so --dry-run and the tests see exactly what would happen.
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { FRAMEWORKS, LABELS, describeFolder, detectProject } from './detect.mjs';
+import { INSTALL } from './install.mjs';
+import { integrationFiles, nextSteps } from './templates.mjs';
+import { UsageError, normalizeHost, normalizeKey, normalizeScheme, suggestScheme } from './validate.mjs';
+
+/**
+ * Works out everything without touching the disk.
+ * @param {object} o { dir, key, host, scheme, framework, force }
+ * @returns {{ project, opts, files: Array<{path, abs, contents, why, exists}>, steps, conflicts: string[] }}
+ */
+export function planInit({ dir, key, host, scheme, framework, force = false, installSource = INSTALL }) {
+  const root = resolve(dir ?? '.');
+  let project = detectProject(root);
+  if (framework) {
+    if (!FRAMEWORKS.includes(framework)) throw new UsageError(`--framework must be one of ${FRAMEWORKS.join(', ')}`);
+    project = project && project.framework === framework ? project : { ...(project ?? emptyProject(root)), framework, label: LABELS[framework] };
+  }
+  if (!project) {
+    throw new UsageError(
+      `No React Native, Expo, Flutter or Android app found in ${root} (it has: ${describeFolder(root)}). ` +
+        'Run this in your app folder, or pass --framework react-native|expo|flutter|android.',
+    );
+  }
+  const k = normalizeKey(key);
+  const h = normalizeHost(host);
+  const chosen = scheme ?? suggestScheme(project);
+  if (!chosen) throw new UsageError("Couldn't guess your app's custom scheme. Pass --scheme, for example --scheme acmeshop.");
+  const opts = { key: k, host: h, scheme: normalizeScheme(chosen) };
+  const files = integrationFiles(project, opts).map((f) => {
+    const abs = join(root, f.path);
+    return { ...f, abs, exists: existsSync(abs) };
+  });
+  const conflicts = force ? [] : files.filter((f) => f.exists).map((f) => f.path);
+  return { project, opts, files, steps: nextSteps(project, opts, installSource), conflicts };
+}
+
+function emptyProject(dir) {
+  return { dir, appName: null, androidPackage: null, iosBundleId: null, scheme: null, typescript: false, expoRouter: false, sdkInstalled: false, manifestPath: null, manifest: { schemes: [], hosts: [] } };
+}
+
+/** Writes the planned files. Returns the paths written. */
+export function writeFiles(plan) {
+  if (plan.conflicts.length) throw new UsageError(`Not overwriting ${plan.conflicts.join(', ')}. Use --force to replace, or delete it first.`);
+  for (const f of plan.files) {
+    mkdirSync(dirname(f.abs), { recursive: true });
+    writeFileSync(f.abs, f.contents);
+  }
+  return plan.files.map((f) => f.path);
+}
+
+// ---------- output ----------
+
+const indent = (s, n = 4) => s.split('\n').map((l) => (l ? ' '.repeat(n) + l : l)).join('\n');
+
+export function formatPlan(plan, { dryRun = false } = {}) {
+  const { project, opts, files, steps } = plan;
+  const out = [];
+  const facts = [project.label, project.androidPackage && `package ${project.androidPackage}`, project.expoRouter && 'Expo Router', project.typescript && 'TypeScript'].filter(Boolean);
+  out.push(`Found: ${facts.join(' · ')}`);
+  out.push(`Link host: ${opts.host} · scheme: ${opts.scheme}://`);
+  out.push('');
+  out.push(dryRun ? 'Dry run: nothing written. These files would be created:' : 'Created:');
+  for (const f of files) out.push(`  ${f.path}${f.exists ? ' (replaced)' : ''}  ${f.why}`);
+  if (dryRun) {
+    for (const f of files) {
+      out.push('');
+      out.push(`--- ${f.path}`);
+      out.push(f.contents.trimEnd());
+    }
+  }
+  out.push('');
+  out.push('Next steps:');
+  steps.forEach((s, i) => {
+    out.push('');
+    out.push(`${i + 1}. ${s.title}${s.done ? '  [already done]' : ''}`);
+    if (s.body) out.push(indent(s.body, 3));
+    if (s.code) out.push(indent(s.code));
+  });
+  out.push('');
+  out.push('Docs: https://straitlink.in/docs/   Checker: https://straitlink.in/tools/app-links-checker/');
+  return out.join('\n');
+}

package/src/install.mjs

@@ -0,0 +1,48 @@
+// THE one place the CLI's SDK install lines come from. Mirrors site/site.config.json
+// `install` and dashboard/src/lib/install.ts (test/install.test.mjs fails if they
+// drift when the site repo sits next to this one).
+//
+// - SDK repos moved to an organisation: change `githubOwner`.
+// - SDKs published to npm / pub.dev / Maven Central: change `source` to "registry", or per
+//   registry { npm, pub, maven } (npm = React Native, pub = Flutter, maven = Android).
+//   16 Oct 2026: npm and pub.dev are published; Android stays on JitPack.
+// Never spell out the owner anywhere else in this package.
+
+export const INSTALL = {
+  source: { npm: 'registry', pub: 'registry', maven: 'github' },
+  githubOwner: 'bazingga08',
+};
+
+/** The source for one registry: `source` as one word applies to all three. */
+export const sourceFor = (src, registry) => (typeof src.source === 'string' ? src.source : src.source[registry]);
+
+/** SDK versions the generated code is written for (site.config.json packages). */
+export const VERSIONS = {
+  version: '0.9.2', // Swift (Unity 0.8.5 is not written by this CLI)
+  rnVersion: '0.9.1',
+  flutterVersion: '0.9.2',
+  androidVersion: '0.8.0',
+};
+
+export const PACKAGES = {
+  reactNative: '@straitlink/react-native',
+  flutter: 'strait_sdk',
+  android: 'strait-sdk-android',
+};
+
+export function installSpecs(src = INSTALL, v = VERSIONS) {
+  const o = src.githubOwner;
+  const gh = (repo) => `https://github.com/${o}/${repo}`;
+  const regNpm = sourceFor(src, 'npm') === 'registry';
+  const regPub = sourceFor(src, 'pub') === 'registry';
+  const reg = sourceFor(src, 'maven') === 'registry';
+  return {
+    reactNative: regNpm ? `${PACKAGES.reactNative}@${v.rnVersion}` : `github:${o}/strait-sdk-react-native#v${v.rnVersion}`,
+    flutterPubspec: regPub
+      ? `  ${PACKAGES.flutter}: ^${v.flutterVersion}`
+      : `  ${PACKAGES.flutter}:\n    git:\n      url: ${gh('strait-sdk-flutter')}\n      ref: v${v.flutterVersion}`,
+    android: reg ? `in.straitlink:${PACKAGES.android}:${v.androidVersion}` : `com.github.${o}:${PACKAGES.android}:v${v.androidVersion}`,
+    /** Extra Gradle repository the Android coordinate needs (null once on Maven Central). */
+    androidRepository: reg ? null : 'https://jitpack.io',
+  };
+}

package/src/templates.mjs

@@ -0,0 +1,385 @@
+// What `strait init` writes and prints, per framework. Every snippet mirrors the
+// docs (site/content/docs/sdks/*) so the two never disagree. Install lines come
+// from src/install.mjs only.
+import { join } from 'node:path';
+import { PACKAGES, VERSIONS, installSpecs } from './install.mjs';
+
+const HEADER = (pkg, version) => `Created by \`strait init\` (${pkg} ${version}). Safe to edit.`;
+
+// ---------- integration files ----------
+
+function rnLinks({ key, host }, { withRouting }) {
+  return `// ${HEADER(PACKAGES.reactNative, VERSIONS.rnVersion)}
+// Import this file once from your entry file (index.js) so the launch link is caught.
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { PlayInstallReferrer } from 'react-native-play-install-referrer';
+import { createStrait, fromPlayInstallReferrer } from '${PACKAGES.reactNative}';
+
+export const links = createStrait({
+  publishableKey: '${key}', // safe in apps; never the secret key
+  endpoint: 'https://${host}', // your workspace's link domain
+  storage: AsyncStorage, // required for reliable analytics
+  installReferrer: fromPlayInstallReferrer(PlayInstallReferrer),
+});
+${
+  withRouting
+    ? `
+// Every link arrives here: app opened from a link, browser hand-off, and the
+// first open after an install (kind: 'deferred'). Past events replay to late
+// subscribers, so your navigator can subscribe after start().
+links.onLink((e) => {
+  console.log('Strait link:', e.kind, e.route, e.matched, e.path);
+  if (e.matched && e.path) {
+    // Open the screen for e.path with e.params, for example:
+    // navigationRef.navigate(screenFor(e.path), e.params);
+  }
+});
+`
+    : `
+// Routing lives in app/_layout.tsx (links.onLink). This log helps while you set up.
+links.onLink((e) => console.log('Strait link:', e.kind, e.route, e.matched, e.path));
+`
+}
+links.start();
+`;
+}
+
+const NATIVE_INTENT = `// ${HEADER(PACKAGES.reactNative, VERSIONS.rnVersion)}
+// Links reach the app through Strait's onLink (app/_layout.tsx), which knows the
+// real destination. Keep Expo Router from routing the raw link URL.
+// If your app has other deep links of its own (a sign-in callback), return \`path\` for those.
+export function redirectSystemPath({ path }: { path: string; initial: boolean }) {
+  return '/';
+}
+`;
+
+function flutterLinks({ key, host }) {
+  const f = PACKAGES.flutter;
+  return `// ${HEADER(f, VERSIONS.flutterVersion)}
+// Call \`await startLinks();\` in main() before runApp.
+import 'dart:async';
+import 'dart:io' show Platform;
+import 'dart:ui';
+
+import 'package:app_links/app_links.dart';
+import 'package:${f}/${f}.dart';
+import 'package:flutter/widgets.dart';
+import 'package:flutter_timezone/flutter_timezone.dart';
+import 'package:play_install_referrer/play_install_referrer.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// Persists the once-per-install flag and unsent open reports.
+class PrefsStore implements KeyValueStore {
+  PrefsStore(this.prefs);
+  final SharedPreferences prefs;
+  @override
+  Future<String?> get(String key) async => prefs.getString(key);
+  @override
+  Future<void> set(String key, String value) => prefs.setString(key, value);
+}
+
+/// Feeds Flutter lifecycle changes to the SDK.
+class LifecycleFeed with WidgetsBindingObserver {
+  final _ctl = StreamController<AppLifecycle>.broadcast(sync: true);
+  Stream<AppLifecycle> get stream => _ctl.stream;
+  LifecycleFeed() { WidgetsBinding.instance.addObserver(this); }
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState s) => _ctl.add(switch (s) {
+        AppLifecycleState.resumed => AppLifecycle.active,
+        AppLifecycleState.inactive => AppLifecycle.inactive,
+        _ => AppLifecycle.background,
+      });
+}
+
+late final StraitLinks links;
+
+Future<void> startLinks() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  final timezone = await FlutterTimezone.getLocalTimezone(); // IANA, e.g. Asia/Kolkata
+  links = StraitLinks(
+    publishableKey: '${key}', // safe in apps; never the secret key
+    endpoint: 'https://${host}', // your workspace's link domain
+    platform: Platform.isIOS ? 'ios' : Platform.isAndroid ? 'android' : 'other',
+    storage: PrefsStore(await SharedPreferences.getInstance()),
+    installReferrer: () async =>
+        Platform.isAndroid ? (await PlayInstallReferrer.installReferrer).installReferrer : null,
+    deviceFields: () {
+      final view = PlatformDispatcher.instance.views.first;
+      return DeviceFields(
+        screenWidth: portraitScreenWidth(view.physicalSize.width / view.devicePixelRatio, view.physicalSize.height / view.devicePixelRatio),
+        pixelRatio: view.devicePixelRatio,
+        language: PlatformDispatcher.instance.locale.toLanguageTag(),
+        timezone: timezone,
+      );
+    },
+  );
+
+  // Every link arrives here: app opened from a link, browser hand-off, and the
+  // first open after an install.
+  links.onLink.listen((e) {
+    debugPrint('Strait link: \${e.kind.name} \${e.route.value} \${e.matched} \${e.path}');
+    if (e.matched && e.path != null) {
+      // Open the screen for e.path with e.params, for example:
+      // navigatorKey.currentState?.pushNamed(e.path!, arguments: e.params);
+    }
+  });
+
+  final appLinks = AppLinks();
+  await links.start(
+    initialUrl: (await appLinks.getInitialLink())?.toString(),
+    urls: appLinks.uriLinkStream.map((u) => u.toString()),
+    lifecycle: LifecycleFeed().stream,
+  );
+}
+`;
+}
+
+function androidLinks({ key, host }, pkg) {
+  return `// ${HEADER(PACKAGES.android, VERSIONS.androidVersion)}
+package ${pkg}
+
+import android.app.Application
+import android.content.Context
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.LifecycleEventObserver
+import androidx.lifecycle.ProcessLifecycleOwner
+import com.android.installreferrer.api.InstallReferrerClient
+import com.android.installreferrer.api.InstallReferrerStateListener
+import dev.strait.sdk.AppLifecycleState
+import dev.strait.sdk.DeviceFields
+import dev.strait.sdk.KeyValueStore
+import dev.strait.sdk.StraitClient
+import dev.strait.sdk.StraitConfig
+import dev.strait.sdk.portraitScreenWidth
+
+/** Call StraitLinks.init(this) from your Application's onCreate(). */
+object StraitLinks {
+    lateinit var client: StraitClient
+        private set
+
+    fun init(app: Application) {
+        val prefs = app.getSharedPreferences("links", Context.MODE_PRIVATE)
+        client = StraitClient(StraitConfig(
+            publishableKey = "${key}",          // safe in apps; never the secret key
+            endpoint = "https://${host}",       // your workspace's link domain
+            storage = object : KeyValueStore {
+                override fun get(key: String) = prefs.getString(key, null)
+                override fun set(key: String, value: String) { prefs.edit().putString(key, value).apply() }
+            },
+            installReferrer = { readInstallReferrer(app) },
+            device = {
+                val m = app.resources.displayMetrics
+                DeviceFields(
+                    screenWidth = portraitScreenWidth(m.widthPixels / m.density.toDouble(), m.heightPixels / m.density.toDouble()),
+                    pixelRatio = m.density.toDouble(),
+                    language = java.util.Locale.getDefault().toLanguageTag(),
+                    timezone = java.util.TimeZone.getDefault().id,
+                )
+            },
+            // Network calls block the calling thread; listeners run here too.
+            executor = java.util.concurrent.Executors.newSingleThreadExecutor(),
+        ))
+
+        ProcessLifecycleOwner.get().lifecycle.addObserver(LifecycleEventObserver { _, e ->
+            when (e) {
+                Lifecycle.Event.ON_RESUME -> client.onAppState(AppLifecycleState.ACTIVE)
+                Lifecycle.Event.ON_PAUSE -> client.onAppState(AppLifecycleState.INACTIVE)
+                Lifecycle.Event.ON_STOP -> client.onAppState(AppLifecycleState.BACKGROUND)
+                else -> Unit
+            }
+        })
+    }
+}
+
+/** The Play Install Referrer: how a link tapped before the install reaches the app. */
+fun readInstallReferrer(context: Context): String? {
+    val latch = java.util.concurrent.CountDownLatch(1)
+    var result: String? = null
+    val client = InstallReferrerClient.newBuilder(context).build()
+    try {
+        client.startConnection(object : InstallReferrerStateListener {
+            override fun onInstallReferrerSetupFinished(code: Int) {
+                if (code == InstallReferrerClient.InstallReferrerResponse.OK) {
+                    result = runCatching { client.installReferrer.installReferrer }.getOrNull()
+                }
+                latch.countDown()
+            }
+            override fun onInstallReferrerServiceDisconnected() { latch.countDown() }
+        })
+        latch.await(5, java.util.concurrent.TimeUnit.SECONDS)
+    } catch (_: Exception) {
+    } finally {
+        runCatching { client.endConnection() }
+    }
+    return result
+}
+`;
+}
+
+/** The files `strait init` writes, as [{ path (relative), contents, why }]. */
+export function integrationFiles(project, opts) {
+  const ext = project.typescript ? 'ts' : 'js';
+  switch (project.framework) {
+    case 'react-native':
+      return [{ path: `links.${ext}`, contents: rnLinks(opts, { withRouting: true }), why: 'creates the client and handles every link' }];
+    case 'expo': {
+      const files = [{ path: `links.${ext}`, contents: rnLinks(opts, { withRouting: !project.expoRouter }), why: 'creates the client' }];
+      if (project.expoRouter) files.push({ path: 'app/+native-intent.tsx', contents: NATIVE_INTENT, why: 'stops Expo Router routing the raw link URL' });
+      return files;
+    }
+    case 'flutter':
+      return [{ path: 'lib/links.dart', contents: flutterLinks(opts), why: 'creates the client and handles every link' }];
+    case 'android': {
+      const pkg = project.androidPackage ?? 'com.example.app';
+      const root = project.sourceRoot ? project.sourceRoot.slice(project.dir.length + 1) : 'app/src/main/java';
+      return [{ path: join(root, ...pkg.split('.'), 'StraitLinks.kt'), contents: androidLinks(opts, pkg), why: 'creates the client and reads the Play Install Referrer' }];
+    }
+    default:
+      throw new Error(`unknown framework ${project.framework}`);
+  }
+}
+
+// ---------- printed steps ----------
+
+export function manifestXml({ host, scheme }) {
+  return `<activity android:name=".MainActivity" android:launchMode="singleTask" android:exported="true">
+  <!-- Verified links: https://${host}/… opens the app directly -->
+  <intent-filter android:autoVerify="true">
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="https" android:host="${host}" />
+  </intent-filter>
+  <!-- Browser hand-off: ${scheme}://shop.example.com/product/42 -->
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW" />
+    <category android:name="android.intent.category.DEFAULT" />
+    <category android:name="android.intent.category.BROWSABLE" />
+    <data android:scheme="${scheme}" />
+  </intent-filter>
+</activity>`;
+}
+
+function expoAppJson({ host, scheme }, project) {
+  return JSON.stringify(
+    {
+      expo: {
+        scheme,
+        android: {
+          package: project.androidPackage ?? 'com.yourcompany.yourapp',
+          intentFilters: [{ action: 'VIEW', autoVerify: true, data: [{ scheme: 'https', host }], category: ['BROWSABLE', 'DEFAULT'] }],
+        },
+        ios: { bundleIdentifier: project.iosBundleId ?? 'com.yourcompany.yourapp', associatedDomains: [`applinks:${host}`] },
+      },
+    },
+    null,
+    2,
+  );
+}
+
+const EXPO_LAYOUT = `import { Stack, router, useRootNavigationState, type Href } from 'expo-router';
+import { useEffect } from 'react';
+import { links } from '../links';
+
+export default function RootLayout() {
+  const ready = useRootNavigationState()?.key;
+  useEffect(() => {
+    if (!ready) return;
+    // Opened from a link, or first open after install: same callback.
+    return links.onLink((e) => {
+      if (e.matched && e.path) router.push({ pathname: e.path, params: e.params } as Href);
+    });
+  }, [ready]);
+  return <Stack />;
+}`;
+
+const keytool = (fw) =>
+  fw === 'expo'
+    ? 'keytool -list -v -keystore android/app/debug.keystore -storepass android | grep SHA256   # local builds; EAS builds: eas credentials'
+    : fw === 'flutter' || fw === 'android'
+      ? 'keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android | grep SHA256'
+      : 'keytool -list -v -keystore android/app/debug.keystore -storepass android | grep SHA256';
+
+/**
+ * The steps printed after the files are written: [{ title, body, code?, lang? }].
+ * `done` marks a step the project already has.
+ */
+export function nextSteps(project, opts, installSrc) {
+  const { host, scheme } = opts;
+  const inst = installSpecs(installSrc);
+  const pkg = project.androidPackage ?? 'com.yourcompany.yourapp';
+  const hasHost = project.manifest.hosts.includes(host);
+  const hasScheme = project.manifest.schemes.includes(scheme);
+  const steps = [];
+  const fw = project.framework;
+
+  // 1. Install
+  if (fw === 'react-native') {
+    steps.push({ title: 'Install the SDK', done: project.sdkInstalled, code: `npm install ${inst.reactNative} @react-native-async-storage/async-storage react-native-play-install-referrer`, lang: 'bash' });
+  } else if (fw === 'expo') {
+    steps.push({ title: 'Install the SDK', done: project.sdkInstalled, code: `npm install ${inst.reactNative}\nnpx expo install @react-native-async-storage/async-storage react-native-play-install-referrer`, lang: 'bash' });
+  } else if (fw === 'flutter') {
+    steps.push({ title: 'Add the SDK to pubspec.yaml, then the helper packages', done: project.sdkInstalled, code: `dependencies:\n${inst.flutterPubspec}\n\n# then:\nflutter pub add app_links shared_preferences play_install_referrer flutter_timezone`, lang: 'yaml' });
+  } else {
+    const repo = inst.androidRepository ? `// settings.gradle.kts → dependencyResolutionManagement.repositories\nmaven("${inst.androidRepository}")\n\n` : '';
+    steps.push({ title: 'Add the dependencies', done: project.sdkInstalled, code: `${repo}// app/build.gradle.kts → dependencies\nimplementation("${inst.android}")\nimplementation("com.android.installreferrer:installreferrer:2.2")\nimplementation("androidx.lifecycle:lifecycle-process:2.8.7")`, lang: 'kotlin' });
+  }
+
+  // 2. Start it
+  if (fw === 'react-native') steps.push({ title: 'Load links at startup', body: `Add \`import './links';\` to the top of index.js, then rebuild (npx react-native run-android). The SDK adds a native module, so a Metro reload is not enough.` });
+  if (fw === 'expo') {
+    steps.push({ title: 'Add link settings to app.json (merge with what you have)', code: expoAppJson(opts, project), lang: 'json', body: project.dynamicConfig ? 'Your config is app.config.js/ts, so copy these keys into it by hand.' : undefined });
+    if (project.expoRouter) steps.push({ title: 'Route links in app/_layout.tsx', code: EXPO_LAYOUT, lang: 'tsx' });
+    else steps.push({ title: 'Load links at startup', body: "Add `import './links';` to your entry file." });
+    steps.push({ title: 'Make a development build (Expo Go cannot load the native module)', code: 'npx expo run:android     # or: eas build --profile development --platform android', lang: 'bash' });
+  }
+  if (fw === 'flutter') steps.push({ title: 'Start links in main()', code: "import 'links.dart';\n\nFuture<void> main() async {\n  await startLinks();\n  runApp(const MyApp());\n}", lang: 'dart' });
+  if (fw === 'android') {
+    steps.push({ title: 'Initialise it in your Application', code: 'class App : Application() {\n    override fun onCreate() {\n        super.onCreate()\n        StraitLinks.init(this)\n    }\n}\n// AndroidManifest.xml: <application android:name=".App" …>', lang: 'kotlin' });
+    steps.push({ title: 'Pass links from MainActivity', code: 'override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n    val links = StraitLinks.client\n    links.onLink { e -> runOnUiThread { if (e.matched) navigate(e.path, e.params) } }\n    if (savedInstanceState == null) links.start(intent?.dataString)\n}\n\noverride fun onNewIntent(intent: Intent) {\n    super.onNewIntent(intent)\n    intent.dataString?.let(StraitLinks.client::handleUrl) // app was already running\n}', lang: 'kotlin' });
+  }
+
+  // 3. Manifest
+  if (fw !== 'expo') {
+    const where = fw === 'android' ? 'app/src/main/AndroidManifest.xml' : 'android/app/src/main/AndroidManifest.xml';
+    const flutterMeta = '<!-- Flutter only, inside <activity>: let the SDK handle links -->\n<meta-data android:name="flutter_deeplinking_enabled" android:value="false" />';
+    const needsFlutterMeta = fw === 'flutter' && !project.manifest.flutterDeepLinkingOff;
+    const filtersDone = hasHost && hasScheme;
+    const done = filtersDone && !needsFlutterMeta;
+    steps.push({
+      title: `Add the intent filters to ${where}`,
+      done,
+      body: done
+        ? `Already there: ${host} and ${scheme}://.`
+        : filtersDone
+          ? `The intent filters for ${host} and ${scheme}:// are already there. Add this line inside your main activity:`
+          : 'Inside your main activity. Keep the intent filters you already have.',
+      code: done ? undefined : [filtersDone ? null : manifestXml(opts), needsFlutterMeta ? flutterMeta : null].filter(Boolean).join('\n'),
+      lang: 'xml',
+    });
+    steps.push({ title: 'iPhone (beta)', body: `In Xcode add Associated Domains → applinks:${host}, and ${scheme} under Info → URL Types.${fw === 'flutter' ? ' Set FlutterDeepLinkingEnabled = NO in Info.plist.' : ''}` });
+  }
+
+  // 4. Dashboard + verification files
+  steps.push({
+    title: 'Fill in Dashboard → Settings',
+    body: `Package name ${pkg}, custom scheme ${scheme}, and the SHA-256 fingerprint of every certificate your app is signed with (debug, upload, and Play App Signing from Play Console → App integrity). For iPhone (beta), your Apple Team ID and bundle ID.`,
+    code: keytool(fw),
+    lang: 'bash',
+  });
+  steps.push({
+    title: 'Check the verification files your link domain serves',
+    body: 'Each returns 404 until the matching Settings fields are filled in. assetlinks.json lets Android open https links in the app directly; apple-app-site-association does the same on iPhone (beta).',
+    code: `curl https://${host}/.well-known/assetlinks.json\ncurl https://${host}/.well-known/apple-app-site-association`,
+    lang: 'bash',
+  });
+
+  // 5. Try it
+  steps.push({
+    title: 'Try it',
+    body: 'Rebuild and install the app, then run this. Your log shows a "Strait link:" line. After that, tap a real link from Messages or Gmail.',
+    code: `adb shell am start -W -a android.intent.action.VIEW -d "${scheme}://shop.example.com/product/42"\nadb shell pm get-app-links ${pkg}   # look for ${host}: verified`,
+    lang: 'bash',
+  });
+  return steps;
+}

package/src/ttfl.mjs

@@ -0,0 +1,73 @@
+// Time to first link: how long the scripted parts of the path take.
+//   measureInit  – `strait init` on fresh copies of the fixture apps (offline).
+//   measureLive  – create a link through the API, then tap it as Android Chrome
+//                  would (no redirect follow) and read the verification file.
+// The human parts (sign-up, rebuild, tapping on a phone) are timed by hand with the
+// protocol in docs/TIME-TO-FIRST-LINK.md.
+import { cpSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { planInit, writeFiles } from './init.mjs';
+
+const ms = (t0) => Math.round((performance.now() - t0) * 10) / 10;
+
+export function measureInit(fixturesDir, { key, host }) {
+  const rows = [];
+  for (const name of readdirSync(fixturesDir)) {
+    const tmp = mkdtempSync(join(tmpdir(), `strait-ttfl-${name}-`));
+    cpSync(join(fixturesDir, name), tmp, { recursive: true });
+    const t0 = performance.now();
+    try {
+      const plan = planInit({ dir: tmp, key, host });
+      const written = writeFiles(plan);
+      rows.push({ fixture: name, framework: plan.project.framework, ms: ms(t0), files: written, steps: plan.steps.length });
+    } catch (e) {
+      rows.push({ fixture: name, framework: null, ms: ms(t0), error: e.message });
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+  return rows;
+}
+
+export const ANDROID_CHROME_UA =
+  'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36';
+
+/**
+ * @param {{ api: string, secretKey: string, slug?: string, longUrl?: string, fetch?: typeof fetch }} o
+ * @returns {Promise<Array<{ step, ms, ok, detail }>>}
+ */
+export async function measureLive({ api, secretKey, slug, longUrl = 'https://shop.example.com/product/42', fetch: f = fetch }) {
+  if (!/^st_(live|test)_/.test(secretKey ?? '')) throw new Error('STRAIT_SECRET_KEY must be a secret key (st_live_…)');
+  const base = `https://${api.replace(/^https?:\/\//, '').replace(/\/+$/, '')}`;
+  const steps = [];
+  const s = slug ?? `ttfl-${Date.now().toString(36)}`;
+
+  let t0 = performance.now();
+  const created = await f(`${base}/v1/links`, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${secretKey}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ slug: s, longUrl }),
+  });
+  const body = await created.json().catch(() => ({}));
+  steps.push({ step: 'create link (POST /v1/links)', ms: ms(t0), ok: created.status === 201, detail: `${created.status} ${body.shortUrl ?? body.error ?? ''}`.trim() });
+  if (created.status !== 201 || !body.shortUrl) return steps;
+
+  t0 = performance.now();
+  const tap = await f(body.shortUrl, { redirect: 'manual', headers: { 'user-agent': ANDROID_CHROME_UA } });
+  const loc = tap.headers.get('location') ?? '';
+  const where = loc ? loc.split(':')[0] + '://…' : `${tap.status} page`;
+  steps.push({ step: 'tap as Android Chrome', ms: ms(t0), ok: (tap.status >= 300 && tap.status < 400 && Boolean(loc)) || tap.status === 200, detail: `${tap.status} → ${where}` });
+
+  t0 = performance.now();
+  const host = new URL(body.shortUrl).host;
+  const al = await f(`https://${host}/.well-known/assetlinks.json`);
+  steps.push({ step: 'assetlinks.json', ms: ms(t0), ok: al.status === 200, detail: al.status === 200 ? '200 (App Links can verify)' : `${al.status} (fill package + SHA-256 in Settings)` });
+  return steps;
+}
+
+export function formatRows(rows, cols) {
+  const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
+  const line = (r) => cols.map((c, i) => String(r[c] ?? '').padEnd(widths[i])).join('  ');
+  return [line(Object.fromEntries(cols.map((c) => [c, c]))), widths.map((w) => '-'.repeat(w)).join('  '), ...rows.map(line)].join('\n');
+}

package/src/validate.mjs

@@ -0,0 +1,55 @@
+// Input checks for `strait init`. Each throws a UsageError with a message a person
+// can act on; the CLI prints it and exits 2.
+
+export class UsageError extends Error {}
+
+const PUB_KEY = /^st_pub_(live|test)_[A-Za-z0-9]{8,}$/;
+const SECRET_KEY = /^st_(live|test)_/;
+const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** A publishable key (st_pub_live_…). A secret key is refused: it must never ship in an app. */
+export function normalizeKey(value) {
+  const k = String(value ?? '').trim();
+  if (!k) throw new UsageError('A publishable key is required (--key st_pub_live_…). Find it in Dashboard → Get started.');
+  if (SECRET_KEY.test(k)) {
+    throw new UsageError(
+      'That is a secret key (st_live_…). Apps must use the publishable key (st_pub_live_…) from Dashboard → Get started. ' +
+        'If the secret key was pasted somewhere public, rotate it in Dashboard → Settings → Secret keys.',
+    );
+  }
+  if (!PUB_KEY.test(k)) throw new UsageError(`"${k}" is not a publishable key. It starts with st_pub_live_ (Dashboard → Get started).`);
+  return k;
+}
+
+/** "https://Acme.strait.link/summer" → "acme.strait.link". */
+export function normalizeHost(value) {
+  let h = String(value ?? '').trim().toLowerCase();
+  if (!h) throw new UsageError('A link host is required (--host acme.strait.link). It is your workspace link domain in Dashboard → Get started.');
+  h = h.replace(/^[a-z][a-z0-9+.-]*:\/\//, '').replace(/[/?#].*$/, '').replace(/\.$/, '');
+  const labels = h.split('.');
+  if (h.length > 253 || labels.length < 2 || !labels.every((l) => LABEL.test(l)) || !/^[a-z]{2,}$/.test(labels.at(-1))) {
+    throw new UsageError(`"${value}" is not a link host. Use your link domain, for example acme.strait.link.`);
+  }
+  return h;
+}
+
+/** A custom URL scheme such as "acmeshop". */
+export function normalizeScheme(value) {
+  const s = String(value ?? '').trim().toLowerCase().replace(/:\/*$/, '');
+  if (!/^[a-z][a-z0-9+.-]{1,63}$/.test(s) || ['http', 'https', 'intent', 'file', 'javascript', 'data'].includes(s)) {
+    throw new UsageError(`"${value}" can't be your app's custom scheme. Use a short lowercase word, for example acmeshop.`);
+  }
+  return s;
+}
+
+/** A scheme guess from the Android package or app name: "com.acme.shop" → "acmeshop". */
+export function suggestScheme({ scheme, androidPackage, appName } = {}) {
+  if (scheme) return scheme;
+  const parts = androidPackage?.split('.') ?? [];
+  const fromPkg = (parts.length > 1 && /^(com|org|net|io|dev|co|in|app|me)$/.test(parts[0]) ? parts.slice(1) : parts).join('').slice(0, 30);
+  for (const c of [fromPkg, appName]) {
+    const s = String(c ?? '').toLowerCase().replace(/[^a-z0-9]/g, '');
+    if (/^[a-z][a-z0-9]{1,}$/.test(s) && !['app', 'android', 'mobile', 'example'].includes(s)) return s;
+  }
+  return null;
+}