@tnldotdev/tnl 0.1.0-rc.25 → 0.1.0-rc.27

package/dist/bin/tnl.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/tnl.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { resolveNativeBinary } from "../internal/launcher.js";
+try {
+    const binary = resolveNativeBinary();
+    if (process.execve === undefined) {
+        throw new Error("Node.js does not support replacing the launcher process");
+    }
+    process.execve(binary, [binary, ...process.argv.slice(2)], process.env);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`tnl: ${message}\n`);
+    process.exitCode = 1;
+}

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { TnlConfigInput } from "./config.gen.js";
+export type * from "./config.gen.js";
+/** Adds type checking to a version-1 tnl.config.ts configuration. */
+export declare function defineConfig<const Config extends TnlConfigInput>(config: Config): Config;

package/dist/config.gen.d.ts

@@ -0,0 +1,133 @@
+export interface TnlConfig {
+    /**
+     * Control URL used by this project.
+     */
+    server?: string;
+    /**
+     * Team ID or unambiguous display name used by this project.
+     */
+    team?: string;
+    /**
+     * Default route and tunnel settings.
+     */
+    tunnel?: {
+        /**
+         * Complete route hostname to publish.
+         */
+        host?: string;
+        /**
+         * One DNS label beneath the current member namespace.
+         */
+        subdomain?: string;
+        /**
+         * Remove the route when this tunnel stops.
+         */
+        ephemeral?: boolean;
+        /**
+         * Allow visitors from every IP address.
+         */
+        allowAllIPs?: boolean;
+        /**
+         * Visitor IP addresses or prefixes allowed to use the route; the current client IP is added automatically.
+         *
+         * @maxItems 63
+         */
+        allowIP?: string[];
+        /**
+         * Maximum concurrent requests forwarded by the publisher for this route, including streams and upgrades.
+         */
+        requestLimit?: number;
+    };
+    publish?: Publish;
+    dev?: Dev;
+    /**
+     * Named local services with optional project-setting overrides.
+     */
+    services?: {
+        [k: string]: {
+            /**
+             * Service directory relative to the project configuration.
+             */
+            directory?: string;
+            /**
+             * Control URL override for this service.
+             */
+            server?: string;
+            /**
+             * Team override for this service.
+             */
+            team?: string;
+            /**
+             * Route and tunnel overrides for this service.
+             */
+            tunnel?: {
+                /**
+                 * Complete route hostname to publish.
+                 */
+                host?: string;
+                /**
+                 * One DNS label beneath the current member namespace.
+                 */
+                subdomain?: string;
+                /**
+                 * Remove the route when this tunnel stops.
+                 */
+                ephemeral?: boolean;
+                /**
+                 * Allow visitors from every IP address.
+                 */
+                allowAllIPs?: boolean;
+                /**
+                 * Visitor IP addresses or prefixes allowed to use the route; the current client IP is added automatically.
+                 *
+                 * @maxItems 63
+                 */
+                allowIP?: string[];
+                /**
+                 * Maximum concurrent requests forwarded by the publisher for this route, including streams and upgrades.
+                 */
+                requestLimit?: number;
+            };
+            publish?: Publish;
+            dev?: Dev;
+        } | undefined;
+    };
+}
+export interface Publish {
+    /**
+     * Local HTTP URL or port reached by the publisher.
+     */
+    target?: string | number;
+}
+export interface Dev {
+    /**
+     * Child command and arguments run by tnl dev.
+     *
+     * @minItems 1
+     */
+    command?: [string, ...string[]];
+    /**
+     * Required local service port for tnl dev.
+     */
+    port?: number;
+    /**
+     * Maximum time to wait for the local service to start.
+     */
+    startupTimeout?: string;
+}
+/** The Git worktree or project directory that contains tnl.config.ts. */
+export interface TnlWorktree {
+    readonly isGit: boolean;
+    /** DNS-safe worktree label derived from this worktree and client state. */
+    readonly label: string;
+    readonly name: string;
+    readonly root: string;
+}
+/** Values passed to a tnl.config.ts configuration factory. */
+export interface TnlConfigContext {
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly worktree: TnlWorktree;
+}
+export type TnlConfigFactory = (context: TnlConfigContext) => TnlConfig | Promise<TnlConfig>;
+export type TnlConfigInput = TnlConfig | TnlConfigFactory;

package/dist/config.gen.js

@@ -0,0 +1,2 @@
+// Code generated by scripts/generate-config-types.ts. DO NOT EDIT.
+export {};

package/dist/config.js

@@ -0,0 +1,4 @@
+/** Adds type checking to a version-1 tnl.config.ts configuration. */
+export function defineConfig(config) {
+    return config;
+}

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { type ProjectMetadata } from "./internal/runtime.js";
-/** Augmented by the `.tnl/project.d.ts` file generated by the tnl client. */
+/** Extended with service types from the generated `.tnl/project.d.ts` file. */
 export interface TnlProjectMetadata {
 }
 type RegisteredTnlProject = keyof TnlProjectMetadata extends never ? ProjectMetadata : Readonly<TnlProjectMetadata>;
 type TnlProject = RegisteredTnlProject & {
     readonly runningUnderTnlDev: boolean;
 };
-/** Validated project metadata injected by a tnl framework integration during development. */
+/** Project metadata added by a tnl framework integration during development. */
 export declare const tnl: TnlProject | undefined;
 export {};

package/dist/index.js

@@ -1,4 +1,6 @@
 import { parseRuntimePayload } from "./internal/runtime.js";
 const serializedRuntime = typeof process === "undefined" ? undefined : process.env?.TNL_PROJECT_RUNTIME;
-/** Validated project metadata injected by a tnl framework integration during development. */
+/** Project metadata added by a tnl framework integration during development. */
+// The parser validates the runtime shape; generated project declarations supply
+// project-specific service names and literals unavailable to this shared module.
 export const tnl = parseRuntimePayload(serializedRuntime);

package/dist/internal/dev.d.ts

@@ -37,5 +37,5 @@ export declare function registerLocalTarget(assignment: TnlTunnelAssignment, tar
 export declare function runtimePayload(project: ProjectMetadata, runningUnderTnlDev: boolean): string;
 export declare function discoverProject(cwd: string): ProjectDiscovery | null;
 export declare function socketIdentity(projectRoot: string, service: string | null): string;
-/** Parses digit-only listener ports in [1, 65535], preserving source-specific diagnostics. */
+/** Parses a decimal listener port from 1 through 65535. */
 export declare function parseListenerPort(value: string, source: string): number;

package/dist/internal/dev.js

@@ -59,7 +59,7 @@ export function canonicalLoopbackTarget(host, port) {
     if (hostname === "::1") {
         return `http://[::1]:${port}`;
     }
-    throw new Error("tnl development target must use a loopback listener");
+    throw new Error("tnl development target must listen on localhost or all interfaces");
 }
 export async function registerLocalTarget(assignment, target) {
     const body = JSON.stringify({ protocol: 1, framework: assignment.framework, target });
@@ -110,8 +110,10 @@ function parseBootstrapEnvironment(environment) {
         throw new Error(`TNL_DEV_SOCKET is required by tnl dev protocol ${protocolVersion}`);
     }
     const rawPort = environment.TNL_DEV_PORT;
-    const port = rawPort === undefined ? undefined : parseListenerPort(rawPort, "TNL_DEV_PORT");
-    return Object.freeze({ port, socket });
+    if (rawPort === undefined) {
+        return Object.freeze({ socket });
+    }
+    return Object.freeze({ port: parseListenerPort(rawPort, "TNL_DEV_PORT"), socket });
 }
 function discoverDevSocket(discovery, environment) {
     const getuid = process.getuid;
@@ -157,7 +159,8 @@ function parseAssignment(value, bootstrap, framework) {
     }
     const memberNamespace = requiredHostname(object.memberNamespace, "tnl dev returned member namespace");
     const hostname = requiredHostname(object.hostname, "tnl dev returned public hostname");
-    if (object.publicURL !== `https://${hostname}`) {
+    const publicURL = `https://${hostname}`;
+    if (object.publicURL !== publicURL) {
         throw new Error("tnl dev returned an invalid public URL");
     }
     const project = parseProjectRuntime(object.project, "tnl dev project metadata");
@@ -182,7 +185,7 @@ function parseAssignment(value, bootstrap, framework) {
         hostname,
         memberNamespace,
         project,
-        publicURL: object.publicURL,
+        publicURL,
         service: object.service,
         tunnelID: object.tunnelID,
     });
@@ -359,7 +362,7 @@ function absoluteNormalizedPath(value, description) {
     }
     return value;
 }
-/** Parses digit-only listener ports in [1, 65535], preserving source-specific diagnostics. */
+/** Parses a decimal listener port from 1 through 65535. */
 export function parseListenerPort(value, source) {
     if (!/^[0-9]+$/.test(value)) {
         throw new Error(`${source} must be a port between 1 and 65535`);
@@ -383,5 +386,5 @@ function canonicalPath(value) {
     }
 }
 function isMissing(error) {
-    return error.code === "ENOENT";
+    return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
 }

package/dist/internal/launcher.d.ts

@@ -0,0 +1,8 @@
+interface NativeBinaryOptions {
+    readonly architecture?: NodeJS.Architecture;
+    readonly platform?: NodeJS.Platform;
+    readonly resolve?: (specifier: string) => string;
+}
+export declare function nativePackageName(platform: NodeJS.Platform, architecture: NodeJS.Architecture): string;
+export declare function resolveNativeBinary(options?: NativeBinaryOptions): string;
+export {};

package/dist/internal/launcher.js

@@ -0,0 +1,55 @@
+import { constants, accessSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { nativeTargets } from "./native-targets.js";
+const require = createRequire(import.meta.url);
+const launcherManifest = new URL("../../package.json", import.meta.url);
+const nativePackages = new Map(nativeTargets.map(({ platform, architecture, packageName }) => [
+    `${platform}-${architecture}`,
+    packageName,
+]));
+export function nativePackageName(platform, architecture) {
+    const packageName = nativePackages.get(`${platform}-${architecture}`);
+    if (packageName === undefined) {
+        throw new Error(`unsupported platform ${platform}-${architecture}; tnl supports macOS and Linux on arm64 and x64`);
+    }
+    return packageName;
+}
+export function resolveNativeBinary(options = {}) {
+    const { architecture = process.arch, platform = process.platform, resolve = require.resolve, } = options;
+    const packageName = nativePackageName(platform, architecture);
+    let nativeManifestPath;
+    try {
+        nativeManifestPath = resolve(`${packageName}/package.json`);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND") {
+            throw new Error(`${packageName} is missing; reinstall @tnldotdev/tnl without disabling optional dependencies`, { cause: error });
+        }
+        throw error;
+    }
+    const mainManifest = readManifest(launcherManifest);
+    const nativeManifest = readManifest(nativeManifestPath);
+    if (nativeManifest.version !== mainManifest.version) {
+        throw new Error(`${packageName}@${String(nativeManifest.version)} does not match @tnldotdev/tnl@${String(mainManifest.version)}`);
+    }
+    const binary = path.join(path.dirname(nativeManifestPath), "bin", "tnl");
+    try {
+        accessSync(binary, constants.X_OK);
+    }
+    catch (error) {
+        throw new Error(`${packageName} does not contain an executable tnl binary`, { cause: error });
+    }
+    return binary;
+}
+function readManifest(file) {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (value === null ||
+        typeof value !== "object" ||
+        !("version" in value) ||
+        typeof value.version !== "string") {
+        throw new Error("package manifest has an invalid shape");
+    }
+    return { version: value.version };
+}

package/dist/internal/native-targets.d.ts

@@ -0,0 +1,9 @@
+export type NativeArchitecture = "arm64" | "x64";
+export type NativePlatform = "darwin" | "linux";
+export interface NativeTarget {
+    readonly architecture: NativeArchitecture;
+    readonly packageName: `@tnldotdev/tnl-${NativePlatform}-${NativeArchitecture}`;
+    readonly platform: NativePlatform;
+}
+/** Internal distribution catalog shared by the launcher and release scripts. */
+export declare const nativeTargets: readonly Readonly<NativeTarget>[];

package/{lib/native-targets.mjs → dist/internal/native-targets.js}

@@ -1,12 +1,8 @@
-/** Internal distribution catalog shared by the launcher and release scripts.
- * Node architecture names belong here; Go artifact paths and versions do not.
- * Entries retain native publish order. This module is not a public package export.
- */
-export const nativeTargets = Object.freeze(
-  [
+const targets = [
     { platform: "darwin", architecture: "arm64", packageName: "@tnldotdev/tnl-darwin-arm64" },
     { platform: "darwin", architecture: "x64", packageName: "@tnldotdev/tnl-darwin-x64" },
     { platform: "linux", architecture: "arm64", packageName: "@tnldotdev/tnl-linux-arm64" },
     { platform: "linux", architecture: "x64", packageName: "@tnldotdev/tnl-linux-x64" },
-  ].map((target) => Object.freeze(target)),
-);
+];
+/** Internal distribution catalog shared by the launcher and release scripts. */
+export const nativeTargets = Object.freeze(targets.map((target) => Object.freeze(target)));

package/dist/internal/runtime.d.ts

@@ -5,14 +5,14 @@ export interface ProjectServiceMetadata {
 }
 export interface ProjectMetadata {
     readonly memberNamespace: string;
-    readonly services: Readonly<Record<string, ProjectServiceMetadata>>;
+    readonly services: Readonly<Record<string, ProjectServiceMetadata | undefined>>;
 }
 export interface ProjectRuntime extends ProjectMetadata {
     readonly runningUnderTnlDev: boolean;
 }
-/** Validates and deep-freezes public metadata, excluding runtime flags and Node-only discovery fields. */
+/** Checks browser-safe project metadata and makes it read-only. */
 export declare function parseProjectMetadata(value: unknown, description: string): ProjectMetadata;
-/** Matches the native client's 1-32 byte ASCII service-name grammar without normalization. */
+/** Reports whether a value is a valid 1-32 character ASCII service name. */
 export declare function validServiceName(value: unknown): value is string;
 export declare function parseRuntimePayload(serialized: string | undefined): ProjectRuntime | undefined;
 export declare function parseProjectRuntime(value: unknown, description: string): ProjectRuntime;

package/dist/internal/runtime.js

@@ -1,7 +1,7 @@
 const maximumRuntimeBytes = 64 * 1024;
 const maximumServices = 32;
 const serviceNamePattern = /^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
-/** Validates and deep-freezes public metadata, excluding runtime flags and Node-only discovery fields. */
+/** Checks browser-safe project metadata and makes it read-only. */
 export function parseProjectMetadata(value, description) {
     const object = record(value, description);
     exactKeys(object, ["memberNamespace", "services"], description);
@@ -21,7 +21,8 @@ export function parseProjectMetadata(value, description) {
         exactKeys(service, ["hostname", "memberNamespace", "url"], `${description} service ${JSON.stringify(name)}`);
         const serviceMemberNamespace = requiredHostname(service.memberNamespace, `${description} service ${JSON.stringify(name)} member namespace`);
         const hostname = requiredHostname(service.hostname, `${description} service ${JSON.stringify(name)} hostname`);
-        if (service.url !== `https://${hostname}`) {
+        const url = `https://${hostname}`;
+        if (service.url !== url) {
             throw new Error(`${description} service ${JSON.stringify(name)} has an invalid URL`);
         }
         if (hostnames.has(hostname)) {
@@ -31,7 +32,7 @@ export function parseProjectMetadata(value, description) {
         services[name] = Object.freeze({
             memberNamespace: serviceMemberNamespace,
             hostname,
-            url: service.url,
+            url,
         });
     }
     return Object.freeze({
@@ -39,7 +40,7 @@ export function parseProjectMetadata(value, description) {
         services: Object.freeze(services),
     });
 }
-/** Matches the native client's 1-32 byte ASCII service-name grammar without normalization. */
+/** Reports whether a value is a valid 1-32 character ASCII service name. */
 export function validServiceName(value) {
     return typeof value === "string" && serviceNamePattern.test(value);
 }

package/dist/next.d.ts

@@ -6,5 +6,5 @@ export interface NextConfigContext {
 /** A function that returns Next.js configuration. */
 export type NextConfigFactory = (phase: string, context: NextConfigContext) => NextConfig | Promise<NextConfig>;
 export type NextConfigInput = NextConfig | Promise<NextConfig> | NextConfigFactory;
-/** Adds tnl project metadata and safe `tnl dev` routing to a Next.js development server. */
+/** Configures a Next.js development server for `tnl dev` and adds project metadata. */
 export declare function withTnl(config?: NextConfigInput, ...extra: never[]): NextConfigFactory;

package/dist/next.js

@@ -1,7 +1,7 @@
 import { canonicalLoopbackTarget, parseListenerPort, readDevelopmentContext, registerLocalTarget, requestTunnelAssignment, runtimePayload, } from "./internal/dev.js";
 const developmentServerPhase = "phase-development-server";
 const runtimeEnvironmentName = "TNL_PROJECT_RUNTIME";
-/** Adds tnl project metadata and safe `tnl dev` routing to a Next.js development server. */
+/** Configures a Next.js development server for `tnl dev` and adds project metadata. */
 export function withTnl(config = {}, ...extra) {
     if (extra.length !== 0) {
         throw new Error("withTnl() does not accept tunnel options; use project configuration");

package/dist/vite.d.ts

@@ -1,3 +1,3 @@
 import type { Plugin } from "vite";
-/** Adds tnl project metadata and safe `tnl dev` routing to a Vite development server. */
+/** Configures a Vite development server for `tnl dev` and adds project metadata. */
 export default function tnl(...arguments_: never[]): Plugin;

package/dist/vite.js

@@ -1,6 +1,6 @@
 import { canonicalLoopbackTarget, readDevelopmentContext, registerLocalTarget, requestTunnelAssignment, runtimePayload, } from "./internal/dev.js";
 const runtimeDefineName = "process.env.TNL_PROJECT_RUNTIME";
-/** Adds tnl project metadata and safe `tnl dev` routing to a Vite development server. */
+/** Configures a Vite development server for `tnl dev` and adds project metadata. */
 export default function tnl(...arguments_) {
     if (arguments_.length !== 0) {
         throw new Error("tnl() does not accept tunnel options; use project configuration");

package/package.json

@@ -1,25 +1,9 @@
 {
   "name": "@tnldotdev/tnl",
-  "version": "0.1.0-rc.25",
-  "description": "The tnl client and framework integrations for project-local development.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tnldotdev/tnl.git",
-    "directory": "packages/tnl"
-  },
+  "version": "0.1.0-rc.27",
   "bin": {
-    "tnl": "bin/tnl.mjs"
+    "tnl": "dist/bin/tnl.js"
   },
-  "files": [
-    "bin",
-    "dist",
-    "lib",
-    "NOTICE",
-    "THIRD_PARTY_LICENSES.txt"
-  ],
-  "type": "module",
-  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -27,8 +11,9 @@
       "default": "./dist/index.js"
     },
     "./config": {
-      "types": "./lib/config.d.ts",
-      "import": "./lib/config.mjs"
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
     },
     "./next": {
       "types": "./dist/next.d.ts",
@@ -41,19 +26,33 @@
       "default": "./dist/vite.js"
     }
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "scripts": {
     "build": "pnpm run clean && tsc --project tsconfig.json",
-    "clean": "node ../../scripts/clean-package.mjs",
+    "clean": "node ../../scripts/clean-package.ts",
     "prepack": "pnpm run build"
   },
+  "description": "The tnl client and framework integrations for project-local development.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tnldotdev/tnl.git",
+    "directory": "packages/tnl"
+  },
+  "files": [
+    "dist",
+    "NOTICE",
+    "THIRD_PARTY_LICENSES.txt"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
-    "next": "16.3.4",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
-    "vite": "8.2.2"
+    "next": "16.3.5",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "vite": "8.3.0"
   },
   "peerDependencies": {
     "next": ">=16.3.4",
@@ -71,12 +70,12 @@
     "node": ">=22.18"
   },
   "optionalDependencies": {
-    "@tnldotdev/tnl-darwin-arm64": "0.1.0-rc.25",
-    "@tnldotdev/tnl-darwin-x64": "0.1.0-rc.25",
-    "@tnldotdev/tnl-linux-arm64": "0.1.0-rc.25",
-    "@tnldotdev/tnl-linux-x64": "0.1.0-rc.25"
+    "@tnldotdev/tnl-darwin-arm64": "0.1.0-rc.27",
+    "@tnldotdev/tnl-darwin-x64": "0.1.0-rc.27",
+    "@tnldotdev/tnl-linux-arm64": "0.1.0-rc.27",
+    "@tnldotdev/tnl-linux-x64": "0.1.0-rc.27"
   },
   "tnl": {
-    "commit": "a9b3066ab2d1a71b06655b983894b96926e27452"
+    "commit": "f446e681bf5e70f9170b082aea9518681cddf532"
   }
 }

package/readme.md

@@ -0,0 +1,177 @@
+# `@tnldotdev/tnl`
+
+This package installs the native `tnl` client and provides project configuration
+types, a browser-safe project runtime, and official Next.js and Vite
+integrations. It does not include the `tnld` server process.
+
+## install
+
+```console
+pnpm add --save-dev @tnldotdev/tnl@next
+```
+
+The package selects an exact-version native dependency for macOS or Linux on
+arm64 or x64. It does not run an install script or download executable code from
+another host. Node.js 22.18 or newer is required.
+
+The native client enables pseudonymous telemetry by default. Disable it with
+`TNL_NO_TELEMETRY=true` or `--no-telemetry`; see the
+[telemetry disclosure](../../docs/cli-reference.md#telemetry).
+
+## initialize a project
+
+Run the initializer from your project root:
+
+```console
+pnpm exec tnl init
+```
+
+The initializer detects supported package managers and frameworks. It creates
+missing tnl and framework configuration, preserves existing configuration, and
+lists any changes you need to make yourself.
+
+Once you've completed those steps, start your app:
+
+```console
+pnpm exec tnl dev
+```
+
+tnl starts the configured command and prints its HTTPS URL. Sign in when
+prompted; tnl uses the hosted service by default. The integration follows the
+port your app actually uses, even if another app has taken its preferred port.
+Live reload works through the URL.
+
+Each Git worktree gets its own URL by default. Restarting the same worktree
+with the same local tnl state reuses the URL. See the integration examples for
+[Next.js](#integrate-nextjs) and [Vite](#integrate-vite).
+
+Keep service names, commands, targets, route policy, and team selection in
+[project configuration](../../docs/project-configuration.md). Framework
+integrations do not accept separate route options.
+
+## generate project metadata
+
+Sign in, then generate project metadata:
+
+```console
+tnl login
+tnl config generate
+```
+
+The command writes:
+
+```text
+.tnl/project.json   browser-safe project and service addresses
+.tnl/project.d.ts   exact TypeScript service and hostname types
+```
+
+Add `.tnl/` to `.gitignore`. Regenerate after changing services, servers, teams,
+or domains. `tnl dev` also regenerates metadata when the project has a
+configuration file.
+
+Include the declaration in the application's existing TypeScript inputs. For a
+service in `apps/web`, for example:
+
+```json
+{
+  "include": ["**/*.ts", "**/*.tsx", "../../.tnl/project.d.ts"]
+}
+```
+
+Keep every other entry required by the framework.
+
+## read project metadata
+
+Framework integrations expose the generated, browser-safe metadata through the
+root package export:
+
+```ts
+import { tnl } from "@tnldotdev/tnl";
+
+if (tnl) {
+  tnl.memberNamespace;
+  tnl.services.api.hostname;
+  tnl.services.api.url;
+  tnl.runningUnderTnlDev;
+}
+```
+
+The value describes assigned addresses. It does not prove that a route or local
+service is currently healthy.
+
+| Development context                            | Result                                                   |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| No metadata and no `tnl dev` environment       | `tnl` is undefined.                                      |
+| Metadata without a matching development socket | Metadata is available and `runningUnderTnlDev` is false. |
+| A matching `tnl dev` environment or socket     | Metadata is available and `runningUnderTnlDev` is true.  |
+| Build, preview, or production                  | `tnl` is undefined.                                      |
+
+The values are read-only. Malformed metadata causes an error. No control access
+token or saved login is included.
+
+## integrate next.js
+
+Next.js 16.3.4 or newer is supported.
+
+```ts
+// next.config.ts
+import { withTnl } from "@tnldotdev/tnl/next";
+
+export default withTnl({
+  reactStrictMode: true,
+});
+```
+
+`withTnl` accepts a configuration object, promise, or synchronous or asynchronous
+configuration function. During `tnl dev`, it:
+
+- adds the assigned hostname to `allowedDevOrigins`;
+- injects project metadata;
+- reports the actual listener after Next.js binds.
+
+The integration preserves existing host and port settings. Without
+`tnl dev --port`, Next.js can choose another port when its preferred port is
+occupied. With `--port`, the reported port must match exactly.
+
+## integrate vite
+
+Vite 6.0.9 or newer is supported.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import tnl from "@tnldotdev/tnl/vite";
+
+export default defineConfig({
+  plugins: [tnl()],
+});
+```
+
+During `tnl dev`, the plugin:
+
+- adds the assigned hostname to Vite's allowed hosts;
+- injects project metadata;
+- reports the actual listener after Vite binds.
+
+Vite keeps its normal host and port behavior, including next-port fallback. A
+port set by `tnl dev --port` must match exactly. Middleware mode is not
+supported because it does not provide a listener to register.
+
+## run the framework separately
+
+The framework does not have to be a child of `tnl dev`. You can start
+`tnl dev web` in one terminal and start the framework from the service directory
+in another.
+
+The integration looks for the matching private development socket when the
+framework configuration loads. It does not keep searching afterward. Start
+`tnl dev` first when you use this workflow.
+
+## listener requirements
+
+The listener must accept HTTP on localhost. A wildcard binding such as
+`0.0.0.0` or `::` is allowed because it includes localhost. Binding only to a
+specific LAN address is not supported.
+
+Host settings remain independent. Your framework can still listen on the LAN,
+but tnl does not require or enable that exposure.

package/README.md

@@ -1,196 +0,0 @@
-# `@tnldotdev/tnl`
-
-This package installs the `tnl` client for macOS or Linux on arm64 or x64 and
-provides its browser-safe project runtime plus official Next.js and Vite
-integrations. It does not include the `tnld` server process.
-
-## Install
-
-```console
-pnpm add --save-dev @tnldotdev/tnl@next
-```
-
-The package selects an exact-version native optional dependency for the current
-platform. It has no install script and does not download executable code from a
-third-party host. Node.js 22.18 or newer is required by the launcher,
-integrations, and TypeScript configuration loader.
-
-The native CLI enables pseudonymous telemetry by default. Use
-`TNL_NO_TELEMETRY=true` or `--no-telemetry` to disable it; see the
-[telemetry disclosure](../../README.md#telemetry).
-
-## Configuration
-
-Run `tnl init` to add the package and missing project/framework configuration.
-It preserves existing Next.js, Vite, and TypeScript configuration and reports
-remaining integration actions. Configure an integration below before starting
-a framework-discovered tunnel.
-
-For a project with existing `apps/api` and `apps/web` directories:
-
-```ts
-// tnl.config.ts
-import { defineConfig } from "@tnldotdev/tnl/config";
-
-export default defineConfig({
-  dev: { command: ["pnpm", "dev"] },
-  services: {
-    api: { directory: "apps/api", publish: { target: 3001 } },
-    web: { directory: "apps/web" },
-  },
-});
-```
-
-Each service overrides root defaults. Commands run in the service directory,
-which must exist within the project root. Choose explicitly when several
-services exist: `tnl dev web` or `tnl publish api`. A single service is selected
-automatically. Service names are 1-32 lowercase ASCII letters/digits/hyphens,
-begin with a letter, and cannot end with a hyphen; at most 32 services are allowed.
-
-`defineConfig` also accepts a synchronous or asynchronous factory:
-
-```ts
-export default defineConfig(({ worktree }) => ({
-  tunnel: { subdomain: worktree.label },
-  dev: { command: ["pnpm", "dev"], startupTimeout: "90s" },
-}));
-```
-
-`worktree.label` combines a readable name with an eight-character hash, stable
-for one client state directory but distinct across worktrees and installations.
-Its private random input is not exposed. Factories receive deeply frozen
-`cwd`, `env`, and `worktree` context. `cwd` is the invocation directory; Node
-executes from the configuration directory. Both the loader environment and
-`context.env` omit `TNL_*` and `TNLD_*`, not arbitrary application secrets.
-
-Configuration executes trusted project code, not a sandbox. `defineConfig` is
-type assistance, not runtime validation; the native client validates the result.
-TypeScript uses camel-case fields and implicitly version 1. Static YAML/JSON
-requires `version: 1` and snake-case fields; see
-[discovery and precedence](../../README.md#project-configuration) and the
-[JSON Schema](https://tnl.dev/schema/v1.json).
-
-`tunnel.host` and `tunnel.subdomain` are alternatives, as are `public: true` and
-`allowIP`. Service overrides replace the corresponding inherited alternative.
-`dev.port` forces the exact listener port. `dev.startupTimeout` defaults to two
-minutes and must be positive and at most ten minutes. `dev.command` is an
-argument array, not a shell command string.
-
-## Project Runtime
-
-Authenticate to the configured server, then generate metadata from the project
-root:
-
-```console
-tnl login https://control.tnl.example.com --token
-tnl config generate
-```
-
-Generation resolves the authenticated membership and ready domain for the root
-and every service, including services with server/team overrides. It writes
-`.tnl/project.json` and `.tnl/project.d.ts`. Regenerate after changing service,
-server, team, or domain configuration; `tnl dev` also generates metadata when
-project configuration is present. Keep `.tnl` ignored by Git.
-
-Add the declaration to the application's existing TypeScript `include` list.
-For an app at the project root, include `.tnl/project.d.ts`; for the example's
-`apps/web/tsconfig.json`, include `../../.tnl/project.d.ts`:
-
-```json
-{
-  "include": ["**/*.ts", "**/*.tsx", "../../.tnl/project.d.ts"]
-}
-```
-
-Preserve other framework-required includes. The augmentation gives exact
-service keys and literal hostname/URL types. Without it, types remain broad;
-check that a service exists before accessing it.
-
-The integrations expose this browser-safe runtime during development:
-
-```ts
-import { tnl } from "@tnldotdev/tnl";
-
-if (tnl) {
-  tnl.memberNamespace;
-  tnl.services.api.hostname;
-  tnl.services.api.url;
-  tnl.runningUnderTnlDev;
-}
-```
-
-The `tnl` value is undefined during builds, previews, and production. During
-development, behavior depends on discovery:
-
-| Development context                                        | Runtime and network behavior                                                              |
-| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| No generated metadata or explicit bootstrap                | `tnl` is undefined; no tunnel configuration                                               |
-| Metadata without a matching development socket             | Frozen metadata, `runningUnderTnlDev: false`; no tunnel configuration                     |
-| Explicit bootstrap or discovered matching `tnl dev` socket | Assigned metadata, `runningUnderTnlDev: true`; configure and register the actual listener |
-
-Socket discovery supports starting `tnl dev web` first and the framework from
-its service directory in another terminal. Discovery happens when framework
-configuration loads, not continuously. Metadata is a snapshot, not route
-readiness or service health. Values are deeply frozen; malformed metadata throws
-rather than silently becoming undefined. `tnl publish` cannot inject metadata
-into an already-running application.
-
-## Next.js
-
-```ts
-// next.config.ts
-import { withTnl } from "@tnldotdev/tnl/next";
-
-export default withTnl({
-  reactStrictMode: true,
-});
-```
-
-`withTnl` preserves object, promised, synchronous-function, and
-asynchronous-function configuration. During `tnl dev`, it adds the assigned
-hostname to `allowedDevOrigins`, injects the project runtime, and registers the
-actual listener target reported by Next.js after it binds. Existing host and
-port choices, including Next.js defaults and custom values, are preserved. An
-unforced port may use Next.js's normal occupied-port retry behavior without
-tunneling a different process on the preferred port. A port forced by
-`tnl dev --port` remains exact. Host settings remain independent, so a project
-can intentionally expose its development server on the LAN as well as through
-tnl.
-
-Next.js 16.3.4 or newer is supported.
-
-## Vite
-
-```ts
-// vite.config.ts
-import { defineConfig } from "vite";
-import tnl from "@tnldotdev/tnl/vite";
-
-export default defineConfig({
-  plugins: [tnl()],
-});
-```
-
-During `tnl dev`, the plugin allows the assigned hostname, injects the project
-runtime, and registers Vite's actual post-bind target. It preserves Vite's
-default or configured host and port behavior, including occupied-port retries;
-a port forced by `tnl dev --port` remains exact. User host settings can
-independently expose Vite on the LAN. Without a development socket the plugin
-only injects generated metadata. Builds and previews remain inert. Vite 6.0.9
-or newer is supported.
-
-Next.js and Vite are optional peers, so only the framework already used by the
-project is required. Keep hostname, policy, server, service, and command
-settings in project configuration rather than passing integration options.
-
-### Listener Requirements
-
-The target must be loopback HTTP. Wildcard bindings (`0.0.0.0` or `::`) allow
-LAN exposure while tnl connects through loopback; binding only a specific LAN
-address is rejected. Vite middleware mode has no supported listening target.
-Next.js must report an HTTP listener origin. Forced ports are checked against
-the actual listener, not assumed from configuration. Vite's `allowedHosts: true`
-is preserved; the integration does not re-enable host filtering you disabled.
-
-Deploy `tnld` with the release container or install it from Homebrew or a
-release archive.

package/bin/tnl.mjs

@@ -1,13 +0,0 @@
-#!/usr/bin/env node
-
-import process from "node:process";
-import { resolveNativeBinary } from "../lib/launcher.mjs";
-
-try {
-  const binary = resolveNativeBinary();
-  process.execve(binary, [binary, ...process.argv.slice(2)], process.env);
-} catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  process.stderr.write(`tnl: ${message}\n`);
-  process.exitCode = 1;
-}

package/lib/config.d.ts

@@ -1,69 +0,0 @@
-export interface TNL {
-  server?: string;
-  team?: string;
-  tunnel?: {
-    host?: string;
-    subdomain?: string;
-    public?: boolean;
-    ephemeral?: boolean;
-    /**
-     * @maxItems 63
-     */
-    allowIP?: string[];
-  };
-  publish?: Publish;
-  dev?: Dev;
-  services?: {
-    [k: string]: {
-      directory?: string;
-      server?: string;
-      team?: string;
-      tunnel?: {
-        host?: string;
-        subdomain?: string;
-        public?: boolean;
-        ephemeral?: boolean;
-        /**
-         * @maxItems 63
-         */
-        allowIP?: string[];
-      };
-      publish?: Publish;
-      dev?: Dev;
-    };
-  };
-}
-export interface Publish {
-  target?: string | number;
-}
-export interface Dev {
-  /**
-   * @minItems 1
-   */
-  command?: [string, ...string[]];
-  port?: number;
-  startupTimeout?: string;
-}
-
-/** Details about the Git worktree or project directory containing tnl.config.ts. */
-export interface TnlWorktree {
-  readonly isGit: boolean;
-  /** DNS-safe name keyed to this worktree and client state directory. */
-  readonly label: string;
-  readonly name: string;
-  readonly root: string;
-}
-
-/** Values available to a tnl.config.ts configuration factory. */
-export interface TnlConfigContext {
-  readonly cwd: string;
-  readonly env: Readonly<Record<string, string>>;
-  readonly worktree: TnlWorktree;
-}
-
-export type TnlConfigFactory = (context: TnlConfigContext) => TNL | Promise<TNL>;
-
-export type TnlConfigInput = TNL | TnlConfigFactory;
-
-/** Provides type checking for an implicit-version-1 tnl.config.ts configuration. */
-export declare function defineConfig<const Config extends TnlConfigInput>(config: Config): Config;

package/lib/config.mjs

@@ -1,3 +0,0 @@
-export function defineConfig(config) {
-  return config;
-}

package/lib/launcher.mjs

@@ -1,65 +0,0 @@
-import { constants, accessSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
-import process from "node:process";
-import { nativeTargets } from "./native-targets.mjs";
-
-const require = createRequire(import.meta.url);
-const launcherManifest = new URL("../package.json", import.meta.url);
-
-const nativePackages = new Map(
-  nativeTargets.map(({ platform, architecture, packageName }) => [
-    `${platform}-${architecture}`,
-    packageName,
-  ]),
-);
-
-export function nativePackageName(platform, architecture) {
-  const packageName = nativePackages.get(`${platform}-${architecture}`);
-  if (packageName === undefined) {
-    throw new Error(
-      `unsupported platform ${platform}-${architecture}; tnl supports macOS and Linux on arm64 and x64`,
-    );
-  }
-  return packageName;
-}
-
-export function resolveNativeBinary({
-  architecture = process.arch,
-  platform = process.platform,
-  resolve = require.resolve,
-} = {}) {
-  const packageName = nativePackageName(platform, architecture);
-  let nativeManifestPath;
-  try {
-    nativeManifestPath = resolve(`${packageName}/package.json`);
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "MODULE_NOT_FOUND") {
-      throw new Error(
-        `${packageName} is missing; reinstall @tnldotdev/tnl without disabling optional dependencies`,
-        { cause: error },
-      );
-    }
-    throw error;
-  }
-
-  const mainManifest = readManifest(launcherManifest);
-  const nativeManifest = readManifest(nativeManifestPath);
-  if (nativeManifest.version !== mainManifest.version) {
-    throw new Error(
-      `${packageName}@${String(nativeManifest.version)} does not match @tnldotdev/tnl@${String(mainManifest.version)}`,
-    );
-  }
-
-  const binary = path.join(path.dirname(nativeManifestPath), "bin", "tnl");
-  try {
-    accessSync(binary, constants.X_OK);
-  } catch (error) {
-    throw new Error(`${packageName} does not contain an executable tnl binary`, { cause: error });
-  }
-  return binary;
-}
-
-function readManifest(file) {
-  return JSON.parse(readFileSync(file, "utf8"));
-}