@tnldotdev/tnl 0.1.0-rc.17 → 0.1.0-rc.21

package/README.md

@@ -15,65 +15,125 @@ 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.
 
-## Project Runtime
+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.
 
-The framework integrations expose generated project metadata through the root
-module during development:
+For a project with existing `apps/api` and `apps/web` directories:
 
 ```ts
-import { tnl } from "@tnldotdev/tnl";
+// tnl.config.ts
+import { defineConfig } from "@tnldotdev/tnl/config";
 
-if (tnl) {
-  tnl.memberNamespace;
-  tnl.services.api.hostname;
-  tnl.services.api.url;
-  tnl.runningUnderTnlDev;
-}
+export default defineConfig({
+  dev: { command: ["pnpm", "dev"] },
+  services: {
+    api: { directory: "apps/api", publish: { target: 3001 } },
+    web: { directory: "apps/web" },
+  },
+});
 ```
 
-The `tnl` value is undefined during builds, previews, and production. During
-`tnl dev`, `runningUnderTnlDev` is true and the integration receives complete
-project metadata from the private protocol. During an ordinary framework
-development server, the integration reads the generated `.tnl/project.json`
-file without changing network configuration and sets `runningUnderTnlDev` to
-false. If generated metadata is absent, `tnl` is undefined.
+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.
 
-The tnl client also generates `.tnl/project.d.ts`. Include that directory in the
-application's TypeScript inputs to get exact service keys and literal hostname,
-URL, and common member-namespace values. Without the generated declaration,
-the root module uses safe broad string and service-record types.
+`defineConfig` also accepts a synchronous or asynchronous factory:
 
-`tnl publish` cannot inject metadata into an application process that is already
-running. Metadata generated earlier can still be available to ordinary local
-development, with `runningUnderTnlDev` remaining false.
+```ts
+export default defineConfig(({ worktree }) => ({
+  tunnel: { subdomain: worktree.label },
+  dev: { command: ["pnpm", "dev"], startupTimeout: "90s" },
+}));
+```
 
-## Configuration
+`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.
 
-The package exports `defineConfig` and project configuration types:
+## 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
-// tnl.config.ts
-import { defineConfig } from "@tnldotdev/tnl/config";
+import { tnl } from "@tnldotdev/tnl";
 
-export default defineConfig(({ worktree }) => ({
-  tunnel: { subdomain: worktree.label },
-  dev: { command: ["pnpm", "dev"] },
-}));
+if (tnl) {
+  tnl.memberNamespace;
+  tnl.services.api.hostname;
+  tnl.services.api.url;
+  tnl.runningUnderTnlDev;
+}
 ```
 
-`worktree.label` combines a readable worktree name with an eight-character hash.
-It is stable for one client state directory and differs across worktrees and
-installations. Its private random input is not exposed to the configuration
-factory.
+The `tnl` value is undefined during builds, previews, and production. During
+development, behavior depends on discovery:
 
-`tnl.config.ts` is implicitly configuration version 1. Static `tnl.yml`,
-`tnl.yaml`, and `tnl.json` files require `version: 1`; the JSON Schema is
-available at `https://tnl.dev/schema/v1.json`.
+| 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 |
 
-`tnl init` adds this package, creates project and framework configuration when
-it is absent, and ignores generated `.tnl` state. It preserves existing Next.js,
-Vite, and TypeScript configuration and reports the exact integration actions
-still needed.
+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
 
@@ -115,7 +175,7 @@ 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. During ordinary development the plugin
+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.
 
@@ -123,5 +183,14 @@ 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/dist/index.d.ts

@@ -1,16 +1,8 @@
-interface TnlServiceMetadata {
-    readonly memberNamespace: string;
-    readonly hostname: string;
-    readonly url: `https://${string}`;
-}
-interface BroadTnlProject {
-    readonly memberNamespace: string;
-    readonly services: Readonly<Record<string, TnlServiceMetadata>>;
-}
+import { type ProjectMetadata } from "./internal/runtime.js";
 /** Augmented by the `.tnl/project.d.ts` file generated by the tnl client. */
 export interface TnlProjectMetadata {
 }
-type RegisteredTnlProject = keyof TnlProjectMetadata extends never ? BroadTnlProject : Readonly<TnlProjectMetadata>;
+type RegisteredTnlProject = keyof TnlProjectMetadata extends never ? ProjectMetadata : Readonly<TnlProjectMetadata>;
 type TnlProject = RegisteredTnlProject & {
     readonly runningUnderTnlDev: boolean;
 };

package/dist/internal/dev.d.ts

@@ -4,17 +4,10 @@ export interface TnlDevBootstrap {
     readonly port?: number;
     readonly socket: string;
 }
-export interface ProjectDocumentService {
-    readonly memberNamespace: string;
-    readonly hostname: string;
-    readonly url: `https://${string}`;
-}
-export interface ProjectDocument {
-    readonly memberNamespace: string;
+export interface ProjectDocument extends ProjectMetadata {
     readonly projectRoot: string;
     readonly runningUnderTnlDev: boolean;
     readonly serviceDirectories: Readonly<Record<string, string>>;
-    readonly services: Readonly<Record<string, ProjectDocumentService>>;
     readonly version: 1;
 }
 export interface ProjectDiscovery {
@@ -44,3 +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. */
+export declare function parseListenerPort(value: string, source: string): number;

package/dist/internal/dev.js

@@ -4,13 +4,11 @@ import * as http from "node:http";
 import { isIP } from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
-import { exactKeys, parseProjectMetadata, parseProjectRuntime, record, requiredHostname, serializeRuntimePayload, } from "./runtime.js";
+import { exactKeys, parseProjectMetadata, parseProjectRuntime, record, requiredHostname, serializeRuntimePayload, validServiceName, } from "./runtime.js";
 const protocolVersion = "1";
 const maximumDocumentBytes = 64 * 1024;
 const maximumResponseBytes = 64 * 1024;
-const maximumServices = 32;
 const registrationTimeoutMilliseconds = 10 * 60 * 1000;
-const serviceNamePattern = /^[a-z](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
 export function readDevelopmentContext(environment = process.env, cwd = process.cwd()) {
     const protocol = environment.TNL_DEV_PROTOCOL;
     if (protocol !== undefined) {
@@ -112,7 +110,7 @@ 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 : parsePort(rawPort, "TNL_DEV_PORT");
+    const port = rawPort === undefined ? undefined : parseListenerPort(rawPort, "TNL_DEV_PORT");
     return Object.freeze({ port, socket });
 }
 function discoverDevSocket(discovery, environment) {
@@ -211,64 +209,27 @@ function parseProjectDocumentValue(value, description, projectRoot) {
     if (object.runningUnderTnlDev) {
         throw new Error(`${description} cannot be marked as running under tnl dev`);
     }
-    const memberNamespace = requiredHostname(object.memberNamespace, `${description} member namespace`);
-    const serviceValues = record(object.services, `${description} services`);
+    const project = parseProjectMetadata({ memberNamespace: object.memberNamespace, services: object.services }, description);
     const directoryValues = record(object.serviceDirectories, `${description} service directories`);
-    const entries = Object.entries(serviceValues);
-    if (entries.length > maximumServices) {
-        throw new Error(`${description} may contain at most ${maximumServices} services`);
-    }
-    if (Object.keys(directoryValues).length !== entries.length ||
-        entries.some(([name]) => !Object.hasOwn(directoryValues, name))) {
+    const names = Object.keys(project.services);
+    if (Object.keys(directoryValues).length !== names.length ||
+        names.some((name) => !Object.hasOwn(directoryValues, name))) {
         throw new Error(`${description} requires one directory for every service`);
     }
-    const services = {};
     const serviceDirectories = {};
-    const hostnames = new Set();
-    for (const [name, value] of entries) {
-        if (!validServiceName(name)) {
-            throw new Error(`${description} contains an invalid service name ${JSON.stringify(name)}`);
-        }
-        const service = record(value, `${description} service ${JSON.stringify(name)}`);
-        exactKeys(service, ["hostname", "memberNamespace", "url"], `${description} service ${JSON.stringify(name)}`);
-        const directory = relativeDirectory(directoryValues[name], `${description} service ${JSON.stringify(name)} directory`);
-        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}`) {
-            throw new Error(`${description} service ${JSON.stringify(name)} has an invalid URL`);
-        }
-        if (hostnames.has(hostname)) {
-            throw new Error(`${description} contains duplicate service hostname ${hostname}`);
-        }
-        hostnames.add(hostname);
-        services[name] = Object.freeze({
-            memberNamespace: serviceMemberNamespace,
-            hostname,
-            url: service.url,
-        });
-        serviceDirectories[name] = directory;
+    for (const name of names) {
+        serviceDirectories[name] = relativeDirectory(directoryValues[name], `${description} service ${JSON.stringify(name)} directory`);
     }
     return Object.freeze({
-        memberNamespace,
+        ...project,
         projectRoot,
         runningUnderTnlDev: object.runningUnderTnlDev,
         serviceDirectories: Object.freeze(serviceDirectories),
-        services: Object.freeze(services),
         version: 1,
     });
 }
 function projectMetadata(document) {
-    return parseProjectMetadata({
-        memberNamespace: document.memberNamespace,
-        services: Object.fromEntries(Object.entries(document.services).map(([name, service]) => [
-            name,
-            {
-                hostname: service.hostname,
-                memberNamespace: service.memberNamespace,
-                url: service.url,
-            },
-        ])),
-    }, "tnl project metadata");
+    return Object.freeze({ memberNamespace: document.memberNamespace, services: document.services });
 }
 function selectService(document, cwd) {
     const absoluteCwd = absoluteNormalizedPath(cwd, "working directory");
@@ -398,7 +359,8 @@ function absoluteNormalizedPath(value, description) {
     }
     return value;
 }
-function parsePort(value, source) {
+/** Parses digit-only listener ports in [1, 65535], preserving source-specific diagnostics. */
+export function parseListenerPort(value, source) {
     if (!/^[0-9]+$/.test(value)) {
         throw new Error(`${source} must be a port between 1 and 65535`);
     }
@@ -408,9 +370,6 @@ function parsePort(value, source) {
     }
     return port;
 }
-function validServiceName(value) {
-    return typeof value === "string" && serviceNamePattern.test(value);
-}
 function pathWithin(value, root) {
     const relative = path.relative(root, value);
     return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`));

package/dist/internal/runtime.d.ts

@@ -10,7 +10,10 @@ export interface ProjectMetadata {
 export interface ProjectRuntime extends ProjectMetadata {
     readonly runningUnderTnlDev: boolean;
 }
+/** Validates and deep-freezes public metadata, excluding runtime flags and Node-only discovery fields. */
 export declare function parseProjectMetadata(value: unknown, description: string): ProjectMetadata;
+/** Matches the native client's 1-32 byte ASCII service-name grammar without normalization. */
+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;
 export declare function serializeRuntimePayload(project: ProjectMetadata, runningUnderTnlDev: boolean): string;

package/dist/internal/runtime.js

@@ -1,6 +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. */
 export function parseProjectMetadata(value, description) {
     const object = record(value, description);
     exactKeys(object, ["memberNamespace", "services"], description);
@@ -13,7 +14,7 @@ export function parseProjectMetadata(value, description) {
     const services = {};
     const hostnames = new Set();
     for (const [name, value] of entries) {
-        if (!serviceNamePattern.test(name)) {
+        if (!validServiceName(name)) {
             throw new Error(`${description} contains an invalid service name ${JSON.stringify(name)}`);
         }
         const service = record(value, `${description} service ${JSON.stringify(name)}`);
@@ -38,6 +39,10 @@ export function parseProjectMetadata(value, description) {
         services: Object.freeze(services),
     });
 }
+/** Matches the native client's 1-32 byte ASCII service-name grammar without normalization. */
+export function validServiceName(value) {
+    return typeof value === "string" && serviceNamePattern.test(value);
+}
 export function parseRuntimePayload(serialized) {
     if (serialized === undefined) {
         return undefined;

package/dist/next.js

@@ -1,4 +1,4 @@
-import { canonicalLoopbackTarget, readDevelopmentContext, registerLocalTarget, requestTunnelAssignment, runtimePayload, } from "./internal/dev.js";
+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. */
@@ -63,23 +63,13 @@ function nextTarget(environment) {
     catch (error) {
         throw new Error("Next.js reported an invalid development listener", { cause: error });
     }
-    const port = parsePort(origin.port, "Next.js listener");
+    const port = parseListenerPort(origin.port, "Next.js listener");
     const reportedPort = environment.PORT;
-    if (reportedPort !== undefined && parsePort(reportedPort, "PORT") !== port) {
+    if (reportedPort !== undefined && parseListenerPort(reportedPort, "PORT") !== port) {
         throw new Error("Next.js reported inconsistent development listener ports");
     }
     return canonicalLoopbackTarget(origin.hostname, port);
 }
-function parsePort(value, source) {
-    if (!/^[0-9]+$/.test(value)) {
-        throw new Error(`${source} must be a port between 1 and 65535`);
-    }
-    const port = Number(value);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        throw new Error(`${source} must be a port between 1 and 65535`);
-    }
-    return port;
-}
 function unique(values) {
     return [...new Set(values)];
 }

package/lib/launcher.mjs

@@ -2,16 +2,17 @@ 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([
-  ["darwin-arm64", "@tnldotdev/tnl-darwin-arm64"],
-  ["darwin-x64", "@tnldotdev/tnl-darwin-x64"],
-  ["linux-arm64", "@tnldotdev/tnl-linux-arm64"],
-  ["linux-x64", "@tnldotdev/tnl-linux-x64"],
-]);
+const nativePackages = new Map(
+  nativeTargets.map(({ platform, architecture, packageName }) => [
+    `${platform}-${architecture}`,
+    packageName,
+  ]),
+);
 
 export function nativePackageName(platform, architecture) {
   const packageName = nativePackages.get(`${platform}-${architecture}`);

package/lib/native-targets.mjs

@@ -0,0 +1,12 @@
+/** 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(
+  [
+    { 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)),
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tnldotdev/tnl",
-  "version": "0.1.0-rc.17",
+  "version": "0.1.0-rc.21",
   "description": "The tnl client and framework integrations for project-local development.",
   "license": "MIT",
   "repository": {
@@ -71,12 +71,12 @@
     "node": ">=22.18"
   },
   "optionalDependencies": {
-    "@tnldotdev/tnl-darwin-arm64": "0.1.0-rc.17",
-    "@tnldotdev/tnl-darwin-x64": "0.1.0-rc.17",
-    "@tnldotdev/tnl-linux-arm64": "0.1.0-rc.17",
-    "@tnldotdev/tnl-linux-x64": "0.1.0-rc.17"
+    "@tnldotdev/tnl-darwin-arm64": "0.1.0-rc.21",
+    "@tnldotdev/tnl-darwin-x64": "0.1.0-rc.21",
+    "@tnldotdev/tnl-linux-arm64": "0.1.0-rc.21",
+    "@tnldotdev/tnl-linux-x64": "0.1.0-rc.21"
   },
   "tnl": {
-    "commit": "bd70c08fe7c09aef1153e1afbbb25161d519a7ec"
+    "commit": "41fdf3fc97a2e6ceb1bc495a985ff341a13ce30a"
   }
 }