hatchkit 0.1.47 → 0.2.2

package/dist/dev-setup.js

@@ -2,14 +2,14 @@
  * `hatchkit dev-setup` — opt-in Tailscale-served dev URLs.
  *
  * Goal: every scaffolded project reachable from any Tailscale peer at
- * https://<slug>.local.ricoslabs.com/ with no per-project DNS work,
+ * https://<slug>.local.<project-domain>/ with no per-project DNS work,
  * no port juggling, no app-side base/basePath config, and zero
  * collisions between projects.
  *
  * Architecture (host-wide one-time setup):
  *
- *   phone ──HTTPS──▶ <slug>.local.ricoslabs.com:443
- *                          │ DNS CNAME → laptop.<tailnet>.ts.net
+ *   phone ──HTTPS──▶ <slug>.local.<project-domain>:443
+ *                          │ DNS A → laptop's 100.x tailnet IP
  *                          ▼
  *                  tailscale serve --tcp=443 (raw TCP passthrough)
  *                          ▼
@@ -29,9 +29,9 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { createServer } from "node:net";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CADDYFILE_PATH, DEV_CONFIG_DIR, isLocalDevActive, LOCAL_DEV_DOMAIN, LOCAL_DEV_DOMAIN_WILDCARD, MANAGED_MARKER, projectFragmentPath, PROJECTS_DIR, readCaddyPort, removeProjectFragment, tailscaleIdentity, tailscaleServeTcpTarget, writeProjectFragment, } from "@hatchkit/dev-shared";
+import { CADDYFILE_PATH, DEV_CONFIG_DIR, LOCAL_DEV_DOMAIN, LOCAL_DEV_DOMAIN_WILDCARD, MANAGED_MARKER, PROJECTS_DIR, isLocalDevActive, localDevDomainFromProjectDomain, localDevUrl, normaliseLocalDevDomain, projectFragmentPath, readCaddyLocalDevDomain, readCaddyPort, removeProjectFragment, tailscaleIdentity, tailscaleServeTcpTarget, writeProjectFragment, } from "@hatchkit/dev-shared";
 import { exec, execOk } from "./utils/exec.js";
-export { CADDYFILE_PATH, DEV_CONFIG_DIR, LOCAL_DEV_DOMAIN, LOCAL_DEV_DOMAIN_WILDCARD, MANAGED_MARKER, PROJECTS_DIR, isLocalDevActive, readCaddyPort, tailscaleIdentity, tailscaleServeTcpTarget, };
+export { CADDYFILE_PATH, DEV_CONFIG_DIR, LOCAL_DEV_DOMAIN, LOCAL_DEV_DOMAIN_WILDCARD, MANAGED_MARKER, PROJECTS_DIR, isLocalDevActive, readCaddyLocalDevDomain, readCaddyPort, tailscaleIdentity, tailscaleServeTcpTarget, };
 export const CADDY_LOG_PATH = join(DEV_CONFIG_DIR, "caddy.log");
 export const CADDY_ERR_LOG_PATH = join(DEV_CONFIG_DIR, "caddy.err.log");
 export const CADDY_WRAPPER_PATH = join(DEV_CONFIG_DIR, "caddy-wrapper.sh");
@@ -50,7 +50,9 @@ const CADDY_PORT_BUMP_LIMIT = 50;
 // ---------------------------------------------------------------------------
 // Caddyfile + launchd plist contents
 // ---------------------------------------------------------------------------
-export function caddyfileContents(caddyPort) {
+export function caddyfileContents(caddyPort, localDevDomain = LOCAL_DEV_DOMAIN) {
+    const domain = normaliseLocalDevDomain(localDevDomain) ?? LOCAL_DEV_DOMAIN;
+    const wildcard = `*.${domain}`;
     return `${MANAGED_MARKER}. Edit at your own risk — re-running
 # \`hatchkit dev-setup init\` will overwrite this file (delete the marker
 # line above to keep your edits across re-runs; doctor will then skip
@@ -66,11 +68,11 @@ export function caddyfileContents(caddyPort) {
   auto_https disable_redirects
 }
 
-https://${LOCAL_DEV_DOMAIN_WILDCARD}:${caddyPort} {
+https://${wildcard}:${caddyPort} {
   bind 127.0.0.1
   # No explicit \`tls\` directive: the site address already names the
   # wildcard subject, and the global \`acme_dns cloudflare\` block
-  # drives DNS-01 issuance. Adding \`tls *.local.ricoslabs.com\` here
+  # drives DNS-01 issuance. Adding an explicit wildcard \`tls\` arg here
   # would be parsed as the email-or-keyword form and Caddy 2 rejects
   # it ("single argument must either be 'internal', 'force_automate',
   # or an email address").
@@ -413,9 +415,36 @@ export async function checkLocalDevHost() {
     }
     return out;
 }
+export function localDevDomainSafetyIssue(input) {
+    const domain = normaliseLocalDevDomain(input);
+    if (!domain)
+        return "Local-dev domain is invalid. Use a domain like local.example.com.";
+    const labels = domain.split(".");
+    if (labels.length < 3 || labels[0] !== "local") {
+        const suggested = domain.startsWith("local.") ? domain : `local.${domain}`;
+        return (`Unsafe local-dev domain "${domain}". Use a dedicated local-dev subdomain, ` +
+            `for example "${suggested}", so Hatchkit manages "*.local..." DNS instead ` +
+            "of a production wildcard.");
+    }
+    return null;
+}
+export function isTailscaleIpv4(ip) {
+    const parts = ip.split(".").map((p) => Number(p));
+    if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+        return false;
+    }
+    const n = ((parts[0] << 24) >>> 0) + (parts[1] << 16) + (parts[2] << 8) + parts[3];
+    // Tailscale IPv4s live in CGNAT space 100.64.0.0/10.
+    return n >= 0x64400000 && n <= 0x647fffff;
+}
 export async function runDevSetupInit(opts = {}) {
     if (!existsSync(PROJECTS_DIR))
         mkdirSync(PROJECTS_DIR, { recursive: true });
+    const localDevDomain = normaliseLocalDevDomain(opts.localDevDomain) ??
+        (isLocalDevActive() ? readCaddyLocalDevDomain() : LOCAL_DEV_DOMAIN);
+    const domainSafetyIssue = localDevDomainSafetyIssue(localDevDomain);
+    if (domainSafetyIssue)
+        throw new Error(domainSafetyIssue);
     let caddyPort = opts.force ? null : readCaddyPort();
     if (caddyPort === null) {
         caddyPort = await pickFreeCaddyPort();
@@ -428,7 +457,7 @@ export async function runDevSetupInit(opts = {}) {
     // unless --force is set; the user may be running their own dev domain
     // setup we shouldn't trample on first encounter.
     let wroteCaddyfile = false;
-    const nextCaddyfile = caddyfileContents(caddyPort);
+    const nextCaddyfile = caddyfileContents(caddyPort, localDevDomain);
     if (existsSync(CADDYFILE_PATH)) {
         const existing = readFileSync(CADDYFILE_PATH, "utf-8");
         if (!existing.includes(MANAGED_MARKER) && !opts.force) {
@@ -483,7 +512,8 @@ export async function runDevSetupInit(opts = {}) {
             wroteWrapper = true;
         }
         const nextPlist = launchdPlistContentsWrapped(CADDY_WRAPPER_PATH);
-        if (!existsSync(LAUNCHD_PLIST_PATH) || readFileSync(LAUNCHD_PLIST_PATH, "utf-8") !== nextPlist) {
+        if (!existsSync(LAUNCHD_PLIST_PATH) ||
+            readFileSync(LAUNCHD_PLIST_PATH, "utf-8") !== nextPlist) {
             writeFileSync(LAUNCHD_PLIST_PATH, nextPlist);
             wrotePlist = true;
         }
@@ -501,7 +531,8 @@ export async function runDevSetupInit(opts = {}) {
             notes.push(`For keychain-backed storage: \`security add-generic-password -s ${DEFAULT_CADDY_KEYCHAIN_SERVICE} -a ${DEFAULT_CADDY_KEYCHAIN_ACCOUNT} -w '<token>' -U\` then re-run \`dev-setup init\`.`);
         }
         const nextPlist = launchdPlistContents(caddyBinPath, token ?? null);
-        if (!existsSync(LAUNCHD_PLIST_PATH) || readFileSync(LAUNCHD_PLIST_PATH, "utf-8") !== nextPlist) {
+        if (!existsSync(LAUNCHD_PLIST_PATH) ||
+            readFileSync(LAUNCHD_PLIST_PATH, "utf-8") !== nextPlist) {
             writeFileSync(LAUNCHD_PLIST_PATH, nextPlist);
             wrotePlist = true;
         }
@@ -528,7 +559,7 @@ export async function runDevSetupInit(opts = {}) {
             registeredServe = true;
         }
     }
-    // DNS: ensure *.local.ricoslabs.com → laptop's tailnet IP (A record,
+    // DNS: ensure the local-dev wildcard → laptop's tailnet IP (A record,
     // DNS-only). Without this every project URL hits whatever the parent
     // zone's wildcard says (typically the Coolify host IP, proxied — which
     // doesn't reach the tailnet) and phone requests die at the TLS
@@ -536,8 +567,9 @@ export async function runDevSetupInit(opts = {}) {
     // but only when each peer has Tailscale's resolver in front of its
     // public DNS — fragile on iOS, where stub resolvers cache the
     // intermediate NXDOMAIN. Direct A record is the bulletproof shape.
-    const dnsRecord = await ensureLocalDevDnsRecord(opts, notes);
+    const dnsRecord = await ensureLocalDevDnsRecord({ ...opts, localDevDomain }, notes);
     return {
+        localDevDomain,
         caddyPort,
         wroteCaddyfile,
         wrotePlist,
@@ -548,11 +580,13 @@ export async function runDevSetupInit(opts = {}) {
         notes,
     };
 }
-/** Upsert the `*.local.ricoslabs.com` A record to the laptop's current
+/** Upsert the local-dev wildcard A record to the laptop's current
  *  tailnet IP. Idempotent. Returns the action taken (or a reason it
  *  was skipped). All failures are non-fatal — they only nudge the
  *  user toward the manual command. */
 async function ensureLocalDevDnsRecord(opts, notes) {
+    const localDevDomain = normaliseLocalDevDomain(opts.localDevDomain) ?? LOCAL_DEV_DOMAIN;
+    const wildcard = `*.${localDevDomain}`;
     const identity = await tailscaleIdentity();
     if (!identity) {
         notes.push("DNS record skipped: tailscale daemon offline (no IP to point the record at).");
@@ -577,14 +611,27 @@ async function ensureLocalDevDnsRecord(opts, notes) {
     try {
         const { CloudflareApi } = await import("./utils/cloudflare-api.js");
         const cf = new CloudflareApi({ token });
-        const zone = await resolveZoneForName(cf, `${LOCAL_DEV_DOMAIN_WILDCARD}`);
+        const zone = await resolveZoneForName(cf, wildcard);
         if (!zone) {
-            notes.push(`DNS record skipped: no Cloudflare zone found for ${LOCAL_DEV_DOMAIN}. The token may lack Zone:Zone:Read scope.`);
+            notes.push(`DNS record skipped: no Cloudflare zone found for ${localDevDomain}. The token may lack Zone:Zone:Read scope.`);
             return "failed";
         }
+        const existing = await findLocalDevWildcardRecords(cf, zone.id, wildcard);
+        const conflict = existing.find((r) => r.type !== "A" || !isTailscaleIpv4(r.content));
+        if (conflict) {
+            notes.push(`DNS record skipped: ${formatRecord(conflict)} already exists. Hatchkit will not overwrite non-Tailscale wildcard DNS; choose --domain local.<your-domain> or change the record manually.`);
+            return "skipped-existing";
+        }
+        if (existing.length > 1) {
+            notes.push(`DNS record skipped: ${wildcard} has multiple local-dev-looking records. Clean them up manually before re-running.`);
+            return "skipped-existing";
+        }
+        const current = existing[0];
+        if (current && current.content === identity.ip && !current.proxied)
+            return "unchanged";
         const upsert = await cf.upsertRecord(zone.id, {
             type: "A",
-            name: LOCAL_DEV_DOMAIN_WILDCARD,
+            name: wildcard,
             content: identity.ip,
             proxied: false,
             ttl: 60,
@@ -600,10 +647,21 @@ async function ensureLocalDevDnsRecord(opts, notes) {
         return "failed";
     }
 }
+async function findLocalDevWildcardRecords(cf, zoneId, wildcard) {
+    const [a, aaaa, cname] = await Promise.all([
+        cf.findRecordsByName(zoneId, wildcard, "A"),
+        cf.findRecordsByName(zoneId, wildcard, "AAAA"),
+        cf.findRecordsByName(zoneId, wildcard, "CNAME"),
+    ]);
+    return [...a, ...aaaa, ...cname];
+}
+function formatRecord(record) {
+    return `${record.type} ${record.name} -> ${record.content}${record.proxied ? " (proxied)" : ""}`;
+}
 /** Walk the candidate label chain looking for a Cloudflare zone we can
- *  manage. For `*.local.ricoslabs.com` this tries `local.ricoslabs.com`
+ *  manage. For `*.local.example.com` this tries `local.example.com`
  *  first (in case the user has it delegated as its own zone), then
- *  `ricoslabs.com`, then `com` (which won't be ours but completes the
+ *  `example.com`, then `com` (which won't be ours but completes the
  *  chain symmetrically). Returns the first hit. */
 async function resolveZoneForName(cf, name) {
     const labels = name.replace(/^\*\./, "").split(".");
@@ -615,41 +673,76 @@ async function resolveZoneForName(cf, name) {
     }
     return null;
 }
-/** Probe the live `*.local.ricoslabs.com` Cloudflare record. Returns
+/** Probe the live local-dev wildcard Cloudflare record. Returns
  *  null when there's no token to check with — that's a configuration
  *  state, not a failure. Otherwise reports drift between the record
  *  and the laptop's current tailnet IP. */
 async function checkLocalDevDnsRecord(currentIp) {
+    const localDevDomain = readCaddyLocalDevDomain();
+    const domainSafetyIssue = localDevDomainSafetyIssue(localDevDomain);
+    if (domainSafetyIssue) {
+        return {
+            name: "Local-dev / DNS domain",
+            status: "fail",
+            detail: domainSafetyIssue,
+            hint: [
+                "Re-run `hatchkit dev-setup init --domain local.<your-domain>`.",
+                "This prevents Hatchkit from managing a production wildcard such as *.example.com.",
+            ],
+        };
+    }
+    const wildcard = `*.${localDevDomain}`;
     const token = (await readCloudflareTokenFromConfig()) ?? (await readCloudflareTokenFromKeychain());
     if (!token)
         return null;
     try {
         const { CloudflareApi } = await import("./utils/cloudflare-api.js");
         const cf = new CloudflareApi({ token });
-        const zone = await resolveZoneForName(cf, LOCAL_DEV_DOMAIN_WILDCARD);
+        const zone = await resolveZoneForName(cf, wildcard);
         if (!zone) {
             return {
                 name: `Local-dev / DNS A record`,
                 status: "fail",
-                detail: `no Cloudflare zone found for ${LOCAL_DEV_DOMAIN}`,
+                detail: `no Cloudflare zone found for ${localDevDomain}`,
                 hint: [
                     "Token may lack Zone:Zone:Read on the parent zone, or the zone isn't on Cloudflare.",
                     "Add the record manually if you're using a different DNS provider:",
-                    `  *.local.ricoslabs.com  A  ${currentIp}  (DNS-only / unproxied, TTL 60)`,
+                    `  ${wildcard}  A  ${currentIp}  (DNS-only / unproxied, TTL 60)`,
                 ],
             };
         }
-        const record = await cf.findRecord(zone.id, LOCAL_DEV_DOMAIN_WILDCARD, "A");
-        if (!record) {
+        const existing = await findLocalDevWildcardRecords(cf, zone.id, wildcard);
+        const conflict = existing.find((r) => r.type !== "A" || !isTailscaleIpv4(r.content));
+        if (conflict) {
+            return {
+                name: "Local-dev / DNS A record",
+                status: "fail",
+                detail: `existing non-local-dev wildcard record: ${formatRecord(conflict)}`,
+                hint: [
+                    "Hatchkit will not overwrite this record automatically.",
+                    "Use a dedicated local-dev suffix such as local.<your-domain>, or change DNS manually.",
+                ],
+            };
+        }
+        if (existing.length > 1) {
             return {
                 name: "Local-dev / DNS A record",
                 status: "fail",
-                detail: `no A record for ${LOCAL_DEV_DOMAIN_WILDCARD} in zone ${zone.name}`,
+                detail: `${wildcard} has multiple A/AAAA/CNAME records`,
                 hint: [
-                    "Run `hatchkit dev-setup init` to create it automatically.",
+                    "Clean up duplicate wildcard records manually, then re-run `hatchkit dev-setup init`.",
                 ],
             };
         }
+        const record = existing[0];
+        if (!record) {
+            return {
+                name: "Local-dev / DNS A record",
+                status: "fail",
+                detail: `no A record for ${wildcard} in zone ${zone.name}`,
+                hint: ["Run `hatchkit dev-setup init` to create it automatically."],
+            };
+        }
         if (record.content !== currentIp) {
             return {
                 name: "Local-dev / DNS A record",
@@ -674,7 +767,7 @@ async function checkLocalDevDnsRecord(currentIp) {
         return {
             name: "Local-dev / DNS A record",
             status: "ok",
-            detail: `${LOCAL_DEV_DOMAIN_WILDCARD} → ${currentIp} (DNS-only)`,
+            detail: `${wildcard} → ${currentIp} (DNS-only)`,
         };
     }
     catch (err) {
@@ -747,10 +840,27 @@ async function pluginVersionRange() {
  *  safe to call from scaffold (first run) AND from `dev-setup enable`
  *  on an already-wired project. */
 export async function enableProjectLocalDev(input) {
-    const wroteFragment = writeProjectFragment(input.slug, input.devPort);
+    const manifest = await (async () => {
+        try {
+            const { readManifest } = await import("./scaffold/manifest.js");
+            return readManifest(input.projectDir);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const localDevDomain = normaliseLocalDevDomain(input.localDevDomain) ??
+        normaliseLocalDevDomain(manifest?.localDev?.domain) ??
+        localDevDomainFromProjectDomain(manifest?.domain) ??
+        LOCAL_DEV_DOMAIN;
+    const domainSafetyIssue = localDevDomainSafetyIssue(localDevDomain);
+    if (domainSafetyIssue)
+        throw new Error(domainSafetyIssue);
+    const wroteFragment = writeProjectFragment(input.slug, input.devPort, localDevDomain);
     const docsPath = join(input.projectDir, "docs", "dev-setup.md");
     const docsContent = renderDevSetupDocs({
         slug: input.slug,
+        localDevDomain,
         tailscale: await tailscaleIdentity(),
     });
     let wroteDocs = false;
@@ -954,8 +1064,10 @@ function patchPluginPackageJsonDep(projectDir, versionRange, framework) {
     return "added";
 }
 export function renderDevSetupDocs(input) {
+    const localDevDomain = normaliseLocalDevDomain(input.localDevDomain) ?? LOCAL_DEV_DOMAIN;
+    const wildcard = `*.${localDevDomain}`;
     const tailnetHostname = input.tailscale?.fullName ?? "<your-machine>.<tailnet>.ts.net";
-    const url = `https://${input.slug}.${LOCAL_DEV_DOMAIN}/`;
+    const url = localDevUrl(input.slug, localDevDomain);
     return `# Dev URL setup (\`${url}\`)
 
 This project ships with the **hatchkit local-dev** integration: when you run
@@ -973,20 +1085,25 @@ framework \`base\` / \`basePath\` config.
 
 ## One-time host setup
 
-Do this **once per machine**, not per project. After it's wired,
-every hatchkit project that opts in just works.
+Do this **once per machine**, not per project. New hatchkit projects opt in by
+default, so after the host is wired they just work.
+
+\`\`\`
+hatchkit dev-setup init --domain ${localDevDomain}
+\`\`\`
 
 ### 1. Cloudflare DNS — auto-managed
 
 \`hatchkit dev-setup init\` creates a DNS-only A record:
 
 \`\`\`
-*.local.ricoslabs.com   A   <your-tailnet-ip>   (DNS-only, TTL 60)
+${wildcard}   A   <your-tailnet-ip>   (DNS-only, TTL 60)
 \`\`\`
 
 It uses your hatchkit DNS token (or the \`caddy-dev/cloudflare-acme\`
 keychain entry as a fallback) — the same token Caddy already needs for
-DNS-01 ACME. \`Zone:DNS:Edit\` + \`Zone:Zone:Read\` on the parent zone.
+DNS-01 ACME. Required permissions: \`Zone:DNS:Edit\` + \`Zone:Zone:Read\`
+on the parent zone.
 
 **Why a direct A record instead of a CNAME to ${tailnetHostname}?**
 A CNAME to a \`.ts.net\` name only resolves when each peer has
@@ -999,7 +1116,7 @@ else gets a useless 100.x address (intended).
 If you're using a non-Cloudflare DNS provider, add the record yourself:
 
 \`\`\`
-*.local.ricoslabs.com   A   <your-tailnet-ip>   (DNS-only)
+${wildcard}   A   <your-tailnet-ip>   (DNS-only)
 \`\`\`
 
 ### 2. Cloudflare API token
@@ -1013,8 +1130,16 @@ hatchkit config add dns
 \`\`\`
 
 Permissions: \`Zone:DNS:Edit\` + \`Zone:Zone:Read\` scoped to
-\`ricoslabs.com\`. The token gets embedded in the launchd plist
-during \`dev-setup init\`.
+\`${localDevDomain}\`. For the cleanest setup, keep the token in Keychain:
+
+\`\`\`
+security add-generic-password -s caddy-dev -a cloudflare-acme -w '<token>' -U
+\`\`\`
+
+When that keychain entry exists, \`dev-setup init\` writes a tiny Caddy
+wrapper that reads the token at startup, so the launchd plist never stores
+the token in plaintext. Without the keychain entry, hatchkit falls back to
+embedding the DNS token from \`hatchkit config add dns\` in the plist.
 
 ### 3. Caddy with the Cloudflare DNS plugin
 
@@ -1037,10 +1162,11 @@ xcaddy build --with github.com/caddy-dns/cloudflare
 hatchkit dev-setup init
 \`\`\`
 
-This writes \`~/.config/dev/Caddyfile\`, a launchd plist that runs Caddy
-on a free port (default 9443, auto-bumps if taken), loads the launchd
-job, and registers \`tailscale serve --tcp=443 → localhost:<caddyPort>\`.
-Idempotent — safe to re-run.
+This writes \`~/.config/dev/Caddyfile\`, writes/loads a launchd job that runs
+Caddy on a free port (default 9443, auto-bumps if taken), registers
+\`tailscale serve --tcp=443 → localhost:<caddyPort>\`, and upserts the
+\`${wildcard}\` DNS-only A record when Cloudflare credentials are
+available. Idempotent — safe to re-run.
 
 ### 5. Verify
 
@@ -1048,13 +1174,14 @@ Idempotent — safe to re-run.
 hatchkit doctor
 \`\`\`
 
-Look for the **Local-dev** rows. All six should be green:
+Look for the **Local-dev** rows. They should be green:
 
 - Tailscale daemon
 - Caddy installed
 - Caddy cloudflare plugin
-- Cloudflare API token in plist
+- Cloudflare ACME token in keychain, or Cloudflare API token in plist
 - Caddy launchd job
+- DNS A record
 - Tailscale serve bridge
 
 ## Per-project bits
@@ -1077,6 +1204,35 @@ hatchkit dev plugin:
 \`HATCHKIT_LOCAL_DEV=0\` in the environment disables the plugin entirely;
 the dev server falls back to its default banner.
 
+## Mobile/devices
+
+For browser testing on a phone or tablet, install Tailscale on the device,
+sign in to the same tailnet, and open:
+
+\`\`\`
+${url}
+\`\`\`
+
+For the native Capacitor loop, the scaffolded \`pnpm dev:ios\` and
+\`pnpm dev:android\` scripts run the WebView against \`CAP_DEV_URL\`.
+The iOS script targets the Simulator; the Android script targets an emulator
+or attached device. Simulators/emulators use local host routes automatically.
+Android physical devices auto-pick this Tailscale URL when \`.hatchkit.json\`
+has \`localDev.slug\`; otherwise Android devices can use either:
+
+\`\`\`
+LAN_IP=<your-lan-ip> pnpm dev:android
+\`\`\`
+
+or, when the device is on Tailscale and this host setup is green:
+
+\`\`\`
+CAP_DEV_URL=${url} pnpm dev:android
+\`\`\`
+
+For a real iPhone, set \`CAP_DEV_URL=${url}\`, run \`npx cap sync ios\`,
+then launch from Xcode via \`npx cap open ios\`.
+
 ## Cleanup
 
 If you tear down this project:
@@ -1104,6 +1260,32 @@ export async function runDevSetupCli(args) {
     }
     if (sub === "init") {
         const force = args.includes("--force");
+        const domainFlagIdx = args.findIndex((a) => a === "--domain" || a.startsWith("--domain="));
+        const rawDomain = domainFlagIdx === -1
+            ? undefined
+            : args[domainFlagIdx].includes("=")
+                ? args[domainFlagIdx].slice("--domain=".length)
+                : args[domainFlagIdx + 1];
+        let localDevDomain = rawDomain ? normaliseLocalDevDomain(rawDomain) : undefined;
+        if (rawDomain && !localDevDomain) {
+            console.log("Usage: --domain <local-dev-domain> (for example: local.example.com)");
+            process.exit(1);
+        }
+        if (!localDevDomain) {
+            const { resolve } = await import("node:path");
+            const { readManifest } = await import("./scaffold/manifest.js");
+            const manifest = readManifest(resolve("."));
+            localDevDomain =
+                normaliseLocalDevDomain(manifest?.localDev?.domain) ??
+                    localDevDomainFromProjectDomain(manifest?.domain) ??
+                    undefined;
+        }
+        const domainSafetyIssue = localDevDomainSafetyIssue(localDevDomain ?? LOCAL_DEV_DOMAIN);
+        if (domainSafetyIssue) {
+            const chalk = (await import("chalk")).default;
+            console.log(chalk.red(`  ${domainSafetyIssue}`));
+            process.exit(1);
+        }
         // --caddy-token-keychain <service>:<account>   → wrapper mode with custom pair
         // --no-caddy-token-keychain                    → force inline-env mode
         // (default)                                     → auto-detect default pair
@@ -1125,9 +1307,10 @@ export async function runDevSetupCli(args) {
                 caddyTokenKeychain = { service, account };
             }
         }
-        const result = await runDevSetupInit({ force, caddyTokenKeychain });
+        const result = await runDevSetupInit({ force, caddyTokenKeychain, localDevDomain });
         const chalk = (await import("chalk")).default;
         console.log(chalk.bold("\n  hatchkit dev-setup init\n"));
+        console.log(`  Local-dev domain:     ${chalk.cyan(result.localDevDomain)}`);
         console.log(`  Caddy port:           ${chalk.cyan(result.caddyPort)}`);
         console.log(`  Caddyfile:            ${result.wroteCaddyfile ? chalk.green("wrote") : chalk.dim("unchanged")} ${chalk.dim(CADDYFILE_PATH)}`);
         if (result.wroteWrapper) {
@@ -1141,10 +1324,12 @@ export async function runDevSetupCli(args) {
                 ? chalk.green(result.dnsRecord)
                 : result.dnsRecord === "unchanged"
                     ? chalk.dim("unchanged")
-                    : result.dnsRecord === "failed"
-                        ? chalk.red("failed")
-                        : chalk.dim("skipped (no CF token)");
-            console.log(`  DNS A record:         ${dnsLabel}  ${chalk.dim(`*.${LOCAL_DEV_DOMAIN}`)}`);
+                    : result.dnsRecord === "skipped-existing"
+                        ? chalk.yellow("skipped (existing wildcard)")
+                        : result.dnsRecord === "failed"
+                            ? chalk.red("failed")
+                            : chalk.dim("skipped (no CF token)");
+            console.log(`  DNS A record:         ${dnsLabel}  ${chalk.dim(`*.${result.localDevDomain}`)}`);
         }
         if (result.notes.length > 0) {
             console.log(chalk.bold("\n  Notes:"));
@@ -1162,13 +1347,17 @@ export async function runDevSetupCli(args) {
         }
         const chalk = (await import("chalk")).default;
         for (const r of checks) {
-            const icon = r.status === "ok" ? chalk.green("✓") : r.status === "fail" ? chalk.red("✗") : chalk.dim("·");
+            const icon = r.status === "ok"
+                ? chalk.green("✓")
+                : r.status === "fail"
+                    ? chalk.red("✗")
+                    : chalk.dim("·");
             console.log(`  ${icon} ${r.name}${r.detail ? chalk.dim(` — ${r.detail}`) : ""}`);
         }
         return;
     }
     console.log("Usage: hatchkit dev-setup <init|status|enable|disable> [flags]");
-    console.log("\n  init             Auto-write ~/.config/dev/Caddyfile, launchd plist, register tailscale TCP bridge.");
+    console.log("\n  init [--domain]  Auto-write ~/.config/dev/Caddyfile, launchd plist, register tailscale TCP bridge.");
     console.log("  status           Run the same checks doctor runs, but only the Local-dev rows.");
     console.log("  enable [--slug]  Wire the project in cwd for Tailscale dev URLs (writes Caddy fragment,");
     console.log("                   docs/dev-setup.md, patches next.config, adds plugin dep).");
@@ -1176,7 +1365,7 @@ export async function runDevSetupCli(args) {
 }
 async function runDevSetupEnableCli(args) {
     const chalk = (await import("chalk")).default;
-    const { resolve, join: joinPath } = await import("node:path");
+    const { resolve } = await import("node:path");
     const { readManifest, writeManifest } = await import("./scaffold/manifest.js");
     const { sanitiseSlug } = await import("@hatchkit/dev-shared");
     const { input, confirm: askConfirm } = await import("@inquirer/prompts");
@@ -1198,6 +1387,12 @@ async function runDevSetupEnableCli(args) {
         : args[projectDirFlagIdx].includes("=")
             ? args[projectDirFlagIdx].slice("--project-dir=".length)
             : args[projectDirFlagIdx + 1];
+    const domainFlagIdx = args.findIndex((a) => a === "--domain" || a.startsWith("--domain="));
+    const rawLocalDevDomain = domainFlagIdx === -1
+        ? undefined
+        : args[domainFlagIdx].includes("=")
+            ? args[domainFlagIdx].slice("--domain=".length)
+            : args[domainFlagIdx + 1];
     const projectDir = projectDirFlag ? resolve(projectDirFlag) : resolve(".");
     const manifest = readManifest(projectDir);
     if (!manifest) {
@@ -1205,12 +1400,25 @@ async function runDevSetupEnableCli(args) {
         console.log(chalk.dim(`  Run from a hatchkit-managed project root, or pass --project-dir <path>.`));
         process.exit(1);
     }
+    const localDevDomain = normaliseLocalDevDomain(rawLocalDevDomain) ??
+        normaliseLocalDevDomain(manifest.localDev?.domain) ??
+        localDevDomainFromProjectDomain(manifest.domain) ??
+        LOCAL_DEV_DOMAIN;
+    if (rawLocalDevDomain && !normaliseLocalDevDomain(rawLocalDevDomain)) {
+        console.log(chalk.red(`  --domain ${rawLocalDevDomain} is not a valid local-dev domain.`));
+        process.exit(1);
+    }
+    const domainSafetyIssue = localDevDomainSafetyIssue(localDevDomain);
+    if (domainSafetyIssue) {
+        console.log(chalk.red(`  ${domainSafetyIssue}`));
+        process.exit(1);
+    }
     // Slug: flag → manifest.localDev → manifest.name → prompt.
     let slug = slugFlag ? sanitiseSlug(slugFlag) : manifest.localDev?.slug;
     if (!slug) {
         const defaultSlug = sanitiseSlug(manifest.name);
         slug = await input({
-            message: "Slug for this project (https://<slug>.local.ricoslabs.com/):",
+            message: `Slug for this project (${localDevUrl("<slug>", localDevDomain)}):`,
             default: defaultSlug,
             validate: (v) => {
                 const s = sanitiseSlug(v);
@@ -1237,8 +1445,9 @@ async function runDevSetupEnableCli(args) {
     }
     console.log(chalk.bold(`\n  Enabling local-dev for ${chalk.cyan(manifest.name)}\n`));
     console.log(`  Slug:      ${chalk.cyan(slug)}`);
+    console.log(`  Domain:    ${chalk.cyan(localDevDomain)}`);
     console.log(`  Dev port:  ${chalk.cyan(devPort)}`);
-    console.log(`  URL:       ${chalk.cyan(`https://${slug}.${LOCAL_DEV_DOMAIN}/`)}`);
+    console.log(`  URL:       ${chalk.cyan(localDevUrl(slug, localDevDomain))}`);
     const skipConfirm = args.includes("--yes") || args.includes("-y");
     if (!skipConfirm) {
         const ok = await askConfirm({ message: "Proceed?", default: true });
@@ -1247,11 +1456,11 @@ async function runDevSetupEnableCli(args) {
             return;
         }
     }
-    const result = await enableProjectLocalDev({ projectDir, slug, devPort });
+    const result = await enableProjectLocalDev({ projectDir, slug, localDevDomain, devPort });
     // Persist the slug in the manifest so subsequent runs (plugin, doctor,
     // future `dev-setup disable`) all converge on the same identity.
-    if (manifest.localDev?.slug !== slug) {
-        const updated = { ...manifest, localDev: { slug } };
+    if (manifest.localDev?.slug !== slug || manifest.localDev?.domain !== localDevDomain) {
+        const updated = { ...manifest, localDev: { slug, domain: localDevDomain } };
         writeManifest(projectDir, updated);
     }
     console.log(`\n  Framework:       ${chalk.cyan(result.framework)}`);
@@ -1272,14 +1481,14 @@ async function runDevSetupEnableCli(args) {
         console.log(chalk.dim("    // …"));
         console.log(chalk.dim("    plugins: ["));
         console.log(chalk.dim("      // …your existing plugins"));
-        console.log(chalk.dim(`      localDev({ slug: "${slug}" }),`));
+        console.log(chalk.dim(`      localDev({ slug: "${slug}", localDevDomain: "${localDevDomain}" }),`));
         console.log(chalk.dim("    ],"));
-        console.log(chalk.dim('    server: { allowedHosts: [".local.ricoslabs.com", ".ts.net", ".local"] },'));
+        console.log(chalk.dim(`    server: { allowedHosts: [".${localDevDomain}", ".ts.net", ".local"] },`));
     }
     if (result.patchedConfig === "unsupported-shape") {
         console.log(chalk.bold("\n  Next config wiring (CJS / non-standard shape):"));
         console.log(chalk.dim('    const { withLocalDev } = require("@hatchkit/dev-plugin-next");'));
-        console.log(chalk.dim(`    module.exports = withLocalDev(nextConfig, { slug: "${slug}" });`));
+        console.log(chalk.dim(`    module.exports = withLocalDev(nextConfig, { slug: "${slug}", localDevDomain: "${localDevDomain}" });`));
     }
     console.log(chalk.dim(`\n  Verify with: \`hatchkit doctor\` (or \`hatchkit dev-setup status\`).`));
 }