@openparachute/hub 0.3.0-rc.1

package/src/service-spec.ts

@@ -0,0 +1,296 @@
+import { fileURLToPath } from "node:url";
+import type { ServiceEntry } from "./services-manifest.ts";
+
+/**
+ * Canonical Parachute port range. Every ecosystem service reserves a slot in
+ * 1939–1949; third-party integrators are expected to avoid it.
+ *
+ *   1939  parachute-hub      internal static + proxy, CLI-managed
+ *   1940  parachute-vault    committed core
+ *   1941  parachute-channel  exploration (may retire)
+ *   1942  parachute-notes    committed core (PWA bundle)
+ *   1943  parachute-scribe   committed core
+ *   1944–1949  unassigned
+ *
+ * Hub pins 1939: `parachute expose` composes hub targets as
+ * `http://127.0.0.1:1939/` and that URL has to be stable across machines for
+ * tailscale serve to proxy it correctly. The hub-port fallback range is 1
+ * (see hub-control.ts) — if something else is on 1939 we fail loudly rather
+ * than walking up into a service's slot.
+ *
+ * **CLI is the port authority.** `parachute install <svc>` picks the port at
+ * install time and writes `PORT=<port>` into `~/.parachute/<svc>/.env`.
+ * lifecycle.start merges that .env into the spawn env, so the next daemon
+ * boot binds the port the CLI assigned. Algorithm (see port-assign.ts):
+ *
+ *   1. Prefer the canonical slot (`spec.seedEntry().port`).
+ *   2. On collision, walk the unassigned range (1944–1949 today).
+ *   3. Range exhausted: assign past 1949 with a warning.
+ *
+ * Idempotent: an existing `PORT=` in .env wins, so re-installs and
+ * operator-edited ports survive across upgrades. Services keep their
+ * compiled-in fallbacks (vault → 1940 etc.) so a stand-alone `bun run`
+ * still works without a CLI-managed .env, but the CLI's PORT wins on any
+ * install it manages.
+ *
+ * **No speculative reservations.** Future first-party modules claim a slot
+ * the moment they ship, not before — pre-reservation for unbuilt things has
+ * proven a hold-place we kept reshaping.
+ */
+export const CANONICAL_PORT_MIN = 1939;
+export const CANONICAL_PORT_MAX = 1949;
+
+export interface PortReservation {
+  readonly port: number;
+  readonly name: string;
+  readonly status: "assigned" | "reserved";
+}
+
+export const PORT_RESERVATIONS: readonly PortReservation[] = [
+  { port: 1939, name: "parachute-hub", status: "assigned" },
+  { port: 1940, name: "parachute-vault", status: "assigned" },
+  { port: 1941, name: "parachute-channel", status: "assigned" },
+  { port: 1942, name: "parachute-notes", status: "assigned" },
+  { port: 1943, name: "parachute-scribe", status: "assigned" },
+  { port: 1944, name: "unassigned", status: "reserved" },
+  { port: 1945, name: "unassigned", status: "reserved" },
+  { port: 1946, name: "unassigned", status: "reserved" },
+  { port: 1947, name: "unassigned", status: "reserved" },
+  { port: 1948, name: "unassigned", status: "reserved" },
+  { port: 1949, name: "unassigned", status: "reserved" },
+];
+
+export function isCanonicalPort(port: number): boolean {
+  return port >= CANONICAL_PORT_MIN && port <= CANONICAL_PORT_MAX;
+}
+
+/**
+ * Broad shape of a service. Matches the hub's card-kind taxonomy.
+ *   "frontend"  a user-facing UI (notes). Safe to expose by default.
+ *   "api"       a programmatic surface (vault, channel, scribe). Whether
+ *               it's safe to expose depends on `hasAuth`.
+ *   "tool"      like "api" but specifically MCP-shaped / agent-callable.
+ *               Treated the same as "api" for exposure defaults.
+ */
+export type ServiceKind = "api" | "tool" | "frontend";
+
+export interface ServiceSpec {
+  readonly package: string;
+  readonly manifestName: string;
+  readonly init?: readonly string[];
+  /**
+   * Command to spawn for `parachute start <svc>`. Receives the services.json
+   * entry so commands that need per-install data (e.g., the notes static-serve
+   * shim needs the configured port) can pull it from there.
+   *
+   * Returns `undefined` to declare "lifecycle not supported for this service."
+   * That never applies today but leaves a seam for future services that
+   * shouldn't be managed by `parachute start`.
+   */
+  readonly startCmd?: (entry: ServiceEntry) => readonly string[] | undefined;
+  /**
+   * Canonical initial services.json entry used when the service hasn't
+   * written its own entry yet. Fires post-install only if `findService`
+   * returns undefined — normal npm installs hit this almost never (the
+   * service's init or first boot writes the authoritative entry first).
+   *
+   * Main use case: `bun link` local-dev installs where the service hasn't
+   * run yet but `parachute expose` / `parachute start` need an entry to
+   * plan against. First service boot overwrites the seed with its own
+   * authoritative version.
+   */
+  readonly seedEntry?: () => ServiceEntry;
+  /**
+   * Declares the service's broad shape. Drives exposure defaults: api/tool
+   * services without auth fall back to `publicExposure: "auth-required"`
+   * (treated as loopback at launch); frontends default to "allowed".
+   */
+  readonly kind?: ServiceKind;
+  /**
+   * Does the service gate its endpoints behind auth today? Used together with
+   * `kind` to pick a safe default when the services.json entry omits
+   * `publicExposure`. True for vault/channel (owner-authenticated);
+   * conservatively false for scribe until its auth-gate ships.
+   */
+  readonly hasAuth?: boolean;
+  /**
+   * Canonical reachable URL for the service given its manifest entry. Drives
+   * the URL column in `parachute status` and any other place we need to
+   * render "where do I point a client?". Most services use port + paths[0],
+   * but some need to append a fixed suffix (vault's MCP endpoint lives at
+   * `/vault/<name>/mcp`, not the bare mount path).
+   *
+   * Returns undefined when the entry doesn't carry enough info — callers
+   * should fall back to the bare `http://127.0.0.1:<port>` form.
+   */
+  readonly urlForEntry?: (entry: ServiceEntry) => string | undefined;
+  /**
+   * Lines printed at the end of `parachute install <svc>` so the user has a
+   * clear next step. Vault's footer comes from `parachute-vault init` itself
+   * (PR #166) — richer because it can read the freshly-minted API token —
+   * so vault's spec leaves this off.
+   */
+  readonly postInstallFooter?: () => readonly string[];
+}
+
+const NOTES_SERVE_PATH = fileURLToPath(new URL("./notes-serve.ts", import.meta.url));
+
+/**
+ * Seed entries land in services.json as placeholder rows when a freshly
+ * installed service hasn't written its own. Version `"0.0.0-linked"`
+ * telegraphs the state: the row is a stopgap, and the service's first boot
+ * will overwrite with its own authoritative write.
+ */
+const SEED_VERSION = "0.0.0-linked";
+
+function pathBasedUrl(entry: ServiceEntry): string {
+  const first = entry.paths[0] ?? "";
+  // Strip a trailing slash so concatenation never doubles up.
+  const path = first.replace(/\/+$/, "");
+  return `http://127.0.0.1:${entry.port}${path}`;
+}
+
+export const SERVICE_SPECS: Record<string, ServiceSpec> = {
+  vault: {
+    package: "@openparachute/vault",
+    manifestName: "parachute-vault",
+    init: ["parachute-vault", "init"],
+    startCmd: () => ["parachute-vault", "serve"],
+    kind: "api",
+    hasAuth: true,
+    seedEntry: () => ({
+      name: "parachute-vault",
+      port: 1940,
+      paths: ["/vault/default"],
+      health: "/vault/default/health",
+      version: SEED_VERSION,
+    }),
+    // Vault's MCP endpoint lives one segment past the mount path. The bare
+    // `/vault/<name>` URL is the discovery shape; clients (claude.ai et al.)
+    // need `/vault/<name>/mcp` to actually open the stream.
+    urlForEntry: (entry) => `${pathBasedUrl(entry)}/mcp`,
+  },
+  notes: {
+    // Frontend product name is "Notes". vault's internal `/api/notes` endpoint
+    // is unrelated — different concept (vault data primitive vs. PWA brand).
+    package: "@openparachute/notes",
+    manifestName: "parachute-notes",
+    startCmd: (entry) => {
+      const first = entry.paths[0] ?? "/notes";
+      const mount = first === "/" ? "" : first.replace(/\/+$/, "");
+      return ["bun", NOTES_SERVE_PATH, "--port", String(entry.port), "--mount", mount];
+    },
+    kind: "frontend",
+    seedEntry: () => ({
+      name: "parachute-notes",
+      port: 1942,
+      paths: ["/notes"],
+      health: "/notes/health",
+      version: SEED_VERSION,
+    }),
+    urlForEntry: pathBasedUrl,
+    postInstallFooter: () => [
+      "",
+      "Open your Notes UI at http://localhost:1942/notes — paste the vault URL",
+      "  http://127.0.0.1:1940/vault/default",
+      "and the API token from your vault install.",
+    ],
+  },
+  scribe: {
+    package: "@openparachute/scribe",
+    manifestName: "parachute-scribe",
+    startCmd: () => ["parachute-scribe", "serve"],
+    // No auth gate today. Scribe's launch PR adds optional SCRIBE_AUTH_TOKEN;
+    // once it lands and scribe writes `publicExposure: "allowed"` when a token
+    // is configured, that explicit declaration overrides this default.
+    kind: "api",
+    hasAuth: false,
+    seedEntry: () => ({
+      name: "parachute-scribe",
+      port: 1943,
+      paths: ["/scribe"],
+      health: "/scribe/health",
+      version: SEED_VERSION,
+    }),
+    // Scribe's API is at the root, not under `/scribe`. The path prefix only
+    // shows up in the health endpoint; clients hit the bare port.
+    urlForEntry: (entry) => `http://127.0.0.1:${entry.port}`,
+    postInstallFooter: () => [
+      "",
+      "Scribe is listening on http://127.0.0.1:1943.",
+      "Vault will auto-call this for transcription (SCRIBE_URL has been wired to the vault env).",
+      "Provider config lives at ~/.parachute/scribe/config.json (key: transcribe.provider);",
+      "API keys live at ~/.parachute/scribe/.env. Available: parakeet-mlx (default), onnx-asr,",
+      "whisper, groq, openai.",
+    ],
+  },
+  channel: {
+    package: "@openparachute/channel",
+    manifestName: "parachute-channel",
+    startCmd: () => ["parachute-channel", "daemon"],
+    kind: "api",
+    hasAuth: true,
+    seedEntry: () => ({
+      name: "parachute-channel",
+      port: 1941,
+      paths: ["/channel"],
+      health: "/channel/health",
+      version: SEED_VERSION,
+    }),
+    urlForEntry: pathBasedUrl,
+  },
+};
+
+/**
+ * Effective publicExposure for a service, given what's on its services.json
+ * entry. Explicit wins. If absent, derive from the spec: known api/tool
+ * services without declared auth fall back to "auth-required" (treated as
+ * loopback at launch); everything else defaults to "allowed" — so vault,
+ * notes, channel and unknown third-party services continue to be exposed
+ * without needing to opt in.
+ */
+export function effectivePublicExposure(
+  entry: ServiceEntry,
+): "allowed" | "loopback" | "auth-required" {
+  if (entry.publicExposure !== undefined) return entry.publicExposure;
+  const short = shortNameForManifest(entry.name);
+  const spec = short !== undefined ? SERVICE_SPECS[short] : undefined;
+  if (spec && (spec.kind === "api" || spec.kind === "tool") && spec.hasAuth === false) {
+    return "auth-required";
+  }
+  return "allowed";
+}
+
+export function knownServices(): string[] {
+  return Object.keys(SERVICE_SPECS);
+}
+
+export function getSpec(service: string): ServiceSpec | undefined {
+  return SERVICE_SPECS[service];
+}
+
+/**
+ * Legacy manifest names kept so `parachute start` / `stop` / `logs` keep
+ * working on an already-installed services.json that still carries the
+ * old name.
+ *
+ * `parachute-notes` was the original; it became `parachute-lens` for ~3
+ * days during the Lens rebrand window (2026-04-19 → 2026-04-22), then
+ * reverted. Users who installed during that window have `parachute-lens`
+ * in their services.json and need lifecycle commands to keep finding
+ * their install — without this alias, `parachute start/stop/logs/status`
+ * silently skip those rows. Remove after launch, alongside the `lens →
+ * notes` install alias.
+ */
+const LEGACY_MANIFEST_ALIASES: Record<string, string> = {
+  "parachute-lens": "notes",
+};
+
+/** Short name (the key into SERVICE_SPECS) for a given manifest name, e.g.
+ *  `parachute-vault` → `vault`. Returns undefined for unknown manifests. */
+export function shortNameForManifest(manifestName: string): string | undefined {
+  for (const [short, spec] of Object.entries(SERVICE_SPECS)) {
+    if (spec.manifestName === manifestName) return short;
+  }
+  return LEGACY_MANIFEST_ALIASES[manifestName];
+}

package/src/services-manifest.ts

@@ -0,0 +1,171 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { SERVICES_MANIFEST_PATH } from "./config.ts";
+
+/**
+ * Whether the service is safe to mount on public-facing expose layers.
+ *
+ *   "allowed"       mount on every layer (tailnet + public). Use when the
+ *                   service gates its own endpoints with auth.
+ *   "loopback"      never mount on tailnet/funnel — only reachable at
+ *                   http://127.0.0.1:<port>. For internal services that
+ *                   shouldn't leave the box.
+ *   "auth-required" the service wants auth but isn't guaranteed to have it
+ *                   configured (e.g., scribe without SCRIBE_AUTH_TOKEN set).
+ *                   At launch this is treated the same as "loopback"; future
+ *                   work can flip to "allowed" once the service reports its
+ *                   auth state over `/.parachute/info`.
+ *
+ * Absent field: the CLI derives a safe default from the service's ServiceSpec
+ * (known api/tool services without declared auth → "auth-required"; everything
+ * else → "allowed"). Unknown services default to "allowed" for back-compat.
+ */
+export type PublicExposure = "allowed" | "loopback" | "auth-required";
+
+export interface ServiceEntry {
+  name: string;
+  port: number;
+  paths: string[];
+  health: string;
+  version: string;
+  /** Human-readable name for the hub page. Falls back to the short manifest name. */
+  displayName?: string;
+  /** One-line subtitle for the hub page card. */
+  tagline?: string;
+  /** Opt-in or opt-out of public-facing expose layers. See PublicExposure. */
+  publicExposure?: PublicExposure;
+}
+
+export interface ServicesManifest {
+  services: ServiceEntry[];
+}
+
+export class ServicesManifestError extends Error {
+  override name = "ServicesManifestError";
+}
+
+const EMPTY: ServicesManifest = { services: [] };
+
+function validateEntry(raw: unknown, where: string): ServiceEntry {
+  if (!raw || typeof raw !== "object") {
+    throw new ServicesManifestError(`${where}: expected object, got ${typeof raw}`);
+  }
+  const e = raw as Record<string, unknown>;
+  const name = e.name;
+  const port = e.port;
+  const paths = e.paths;
+  const health = e.health;
+  const version = e.version;
+  if (typeof name !== "string" || name.length === 0) {
+    throw new ServicesManifestError(`${where}: "name" must be a non-empty string`);
+  }
+  if (typeof port !== "number" || !Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new ServicesManifestError(`${where}: "port" must be an integer 1..65535`);
+  }
+  if (!Array.isArray(paths) || paths.some((p) => typeof p !== "string")) {
+    throw new ServicesManifestError(`${where}: "paths" must be an array of strings`);
+  }
+  if (typeof health !== "string" || !health.startsWith("/")) {
+    throw new ServicesManifestError(`${where}: "health" must be a path starting with "/"`);
+  }
+  if (typeof version !== "string") {
+    throw new ServicesManifestError(`${where}: "version" must be a string`);
+  }
+  const displayName = e.displayName;
+  const tagline = e.tagline;
+  const publicExposure = e.publicExposure;
+  if (displayName !== undefined && typeof displayName !== "string") {
+    throw new ServicesManifestError(`${where}: "displayName" must be a string if present`);
+  }
+  if (tagline !== undefined && typeof tagline !== "string") {
+    throw new ServicesManifestError(`${where}: "tagline" must be a string if present`);
+  }
+  if (
+    publicExposure !== undefined &&
+    publicExposure !== "allowed" &&
+    publicExposure !== "loopback" &&
+    publicExposure !== "auth-required"
+  ) {
+    throw new ServicesManifestError(
+      `${where}: "publicExposure" must be "allowed" | "loopback" | "auth-required" if present`,
+    );
+  }
+  const entry: ServiceEntry = { name, port, paths: paths as string[], health, version };
+  if (displayName !== undefined) entry.displayName = displayName;
+  if (tagline !== undefined) entry.tagline = tagline;
+  if (publicExposure !== undefined) entry.publicExposure = publicExposure as PublicExposure;
+  return entry;
+}
+
+function validateManifest(raw: unknown, where: string): ServicesManifest {
+  if (!raw || typeof raw !== "object") {
+    throw new ServicesManifestError(`${where}: root must be an object`);
+  }
+  const services = (raw as Record<string, unknown>).services;
+  if (!Array.isArray(services)) {
+    throw new ServicesManifestError(`${where}: "services" must be an array`);
+  }
+  return {
+    services: services.map((s, i) => validateEntry(s, `${where} services[${i}]`)),
+  };
+}
+
+export function readManifest(path: string = SERVICES_MANIFEST_PATH): ServicesManifest {
+  if (!existsSync(path)) return { services: [] };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new ServicesManifestError(
+      `failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return validateManifest(raw, path);
+}
+
+export function writeManifest(
+  manifest: ServicesManifest,
+  path: string = SERVICES_MANIFEST_PATH,
+): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+export function upsertService(
+  entry: ServiceEntry,
+  path: string = SERVICES_MANIFEST_PATH,
+): ServicesManifest {
+  validateEntry(entry, "entry");
+  const current = existsSync(path) ? readManifest(path) : structuredClone(EMPTY);
+  const idx = current.services.findIndex((s) => s.name === entry.name);
+  if (idx >= 0) {
+    current.services[idx] = entry;
+  } else {
+    current.services.push(entry);
+  }
+  writeManifest(current, path);
+  return current;
+}
+
+export function removeService(
+  name: string,
+  path: string = SERVICES_MANIFEST_PATH,
+): ServicesManifest {
+  if (!existsSync(path)) return structuredClone(EMPTY);
+  const current = readManifest(path);
+  const next: ServicesManifest = {
+    services: current.services.filter((s) => s.name !== name),
+  };
+  writeManifest(next, path);
+  return next;
+}
+
+export function findService(
+  name: string,
+  path: string = SERVICES_MANIFEST_PATH,
+): ServiceEntry | undefined {
+  if (!existsSync(path)) return undefined;
+  return readManifest(path).services.find((s) => s.name === name);
+}

package/src/tailscale/commands.ts

@@ -0,0 +1,41 @@
+export interface ServeEntry {
+  kind: "proxy" | "file";
+  mount: string;
+  target: string;
+  service: string;
+}
+
+export interface BringupOpts {
+  funnel?: boolean;
+  port?: number;
+}
+
+/**
+ * Funnel was a flag on `tailscale serve` through ~1.80; from 1.82 onward
+ * it's a separate `tailscale funnel` subcommand with the same syntax minus
+ * the `--funnel` flag. Modern tailscale (1.82+) rejects `serve --funnel`
+ * outright: "flag provided but not defined: -funnel". Pick the subcommand
+ * up-front; we don't support the pre-split syntax.
+ */
+function serveVerb(funnel: boolean): string {
+  return funnel ? "funnel" : "serve";
+}
+
+export function bringupCommand(entry: ServeEntry, opts: BringupOpts = {}): string[] {
+  const port = opts.port ?? 443;
+  const funnel = opts.funnel === true;
+  return [
+    "tailscale",
+    serveVerb(funnel),
+    "--bg",
+    `--https=${port}`,
+    `--set-path=${entry.mount}`,
+    entry.target,
+  ];
+}
+
+export function teardownCommand(entry: ServeEntry, opts: BringupOpts = {}): string[] {
+  const port = opts.port ?? 443;
+  const funnel = opts.funnel === true;
+  return ["tailscale", serveVerb(funnel), `--https=${port}`, `--set-path=${entry.mount}`, "off"];
+}

package/src/tailscale/detect.ts

@@ -0,0 +1,107 @@
+import type { Runner } from "./run.ts";
+import { TailscaleError } from "./run.ts";
+
+/** ACL capability keys Tailscale emits on `Self.CapMap` when the node is
+ * allowed to run Funnel. Modern tailscaled (≥ ~1.96) emits the bare
+ * `"funnel"` key; older builds emit the URL form. Accept either — the probe
+ * is best-effort (see {@link getTailscaleStatus}) and we'd rather cross
+ * versions than over-nag users whose ACL is correctly granted. */
+export const FUNNEL_CAP_KEYS = ["funnel", "https://tailscale.com/cap/funnel"] as const;
+
+export async function isTailscaleInstalled(runner: Runner): Promise<boolean> {
+  try {
+    const { code } = await runner(["tailscale", "version"]);
+    return code === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Consolidated read of `tailscale status --json`, returning everything the
+ * readiness check needs in one subprocess call:
+ *
+ * - `loggedIn` — Self.DNSName is present and non-empty. False on `Logged out`,
+ *   `Stopped`, install/PATH errors, or parse failures — callers use this to
+ *   decide whether to prompt the user to run `tailscale up` before anything
+ *   else.
+ * - `funnelCapable` — best-effort probe for whether this node is allowed to
+ *   expose Funnel, via any key in {@link FUNNEL_CAP_KEYS} on `Self.CapMap`.
+ *
+ * Caveat on `funnelCapable`: `CapMap` is a semi-internal field whose shape
+ * Tailscale can shift across versions. This probe is not load-bearing — a
+ * false negative only means we'll point the user at the admin console when
+ * they don't actually need to do anything. The downstream `tailscale funnel`
+ * call is the real gate; this just lets us nudge the user earlier in the flow.
+ *
+ * Any error (non-zero exit, parse failure) returns `{ loggedIn: false,
+ * funnelCapable: false }` rather than throwing; the readiness check is an
+ * advisory pre-flight, not a hard gate.
+ */
+export async function getTailscaleStatus(
+  runner: Runner,
+): Promise<{ loggedIn: boolean; funnelCapable: boolean }> {
+  try {
+    const result = await runner(["tailscale", "status", "--json"]);
+    if (result.code !== 0) return { loggedIn: false, funnelCapable: false };
+    const parsed = JSON.parse(result.stdout) as {
+      Self?: { DNSName?: unknown; CapMap?: Record<string, unknown> };
+    };
+    const dnsName = parsed.Self?.DNSName;
+    const loggedIn = typeof dnsName === "string" && dnsName.length > 0;
+    const capMap = parsed.Self?.CapMap;
+    const funnelCapable =
+      loggedIn &&
+      !!capMap &&
+      typeof capMap === "object" &&
+      FUNNEL_CAP_KEYS.some((k) => k in capMap);
+    return { loggedIn, funnelCapable };
+  } catch {
+    return { loggedIn: false, funnelCapable: false };
+  }
+}
+
+export async function getFqdn(runner: Runner): Promise<string> {
+  const result = await runner(["tailscale", "status", "--json"]);
+  if (result.code !== 0) {
+    throw new TailscaleError(
+      `tailscale status --json exited ${result.code}: ${result.stderr.trim()}`,
+      ["tailscale", "status", "--json"],
+      result,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch (err) {
+    throw new TailscaleError(
+      `failed to parse tailscale status JSON: ${err instanceof Error ? err.message : String(err)}`,
+      ["tailscale", "status", "--json"],
+      result,
+    );
+  }
+  const self = (parsed as { Self?: { DNSName?: unknown } }).Self;
+  const dnsName = self?.DNSName;
+  if (typeof dnsName !== "string" || dnsName.length === 0) {
+    throw new TailscaleError(
+      "tailscale status did not return Self.DNSName — is this machine logged in?",
+      ["tailscale", "status", "--json"],
+      result,
+    );
+  }
+  return dnsName.replace(/\.$/, "");
+}
+
+/**
+ * Detect whether wildcard MagicDNS is active — i.e. whether subdomains of the
+ * current machine (vault.<fqdn>, notes.<fqdn>, …) resolve back to this node.
+ *
+ * Tailscale's standard MagicDNS gives each machine a single hostname and does
+ * not auto-resolve arbitrary subdomains; wildcard MagicDNS exists in the
+ * Services feature but requires explicit advertisement. For launch we return
+ * false (path-routing) and let a later PR add real detection once the
+ * subdomain-per-service path is supported end-to-end.
+ */
+export async function detectWildcardMagicDNS(_runner: Runner): Promise<boolean> {
+  return false;
+}

package/src/tailscale/run.ts

@@ -0,0 +1,28 @@
+export interface CommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export type Runner = (cmd: readonly string[]) => Promise<CommandResult>;
+
+export async function defaultRunner(cmd: readonly string[]): Promise<CommandResult> {
+  const proc = Bun.spawn([...cmd], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stdout, stderr };
+}
+
+export class TailscaleError extends Error {
+  override name = "TailscaleError";
+  constructor(
+    message: string,
+    public readonly cmd: readonly string[],
+    public readonly result: CommandResult,
+  ) {
+    super(message);
+  }
+}