@spawn-dock/create 0.2.0-canary.20260321111558.f5e5655

package/README.md

@@ -0,0 +1,55 @@
+# @spawn-dock/create
+
+SpawnDock bootstrap CLI for local TMA projects.
+
+This repository now follows an `effect-template`-style layout:
+
+- root workspace with `packages/app`
+- TypeScript + Effect entrypoint
+- built-in TMA overlay bundled inside the CLI repo
+
+The canonical TMA starter lives in `https://github.com/SpawnDock/tma-project`.
+`@spawn-dock/create` clones that repo, applies the bundled SpawnDock TMA overlay,
+and then writes project-specific runtime files.
+
+## Usage
+
+```bash
+npx @spawn-dock/create --token <pairing-token> [project-dir]
+```
+
+If npm registry access is unavailable, the GitHub fallback remains:
+
+```bash
+npx --yes github:SpawnDock/create#main --token <pairing-token> [project-dir]
+```
+
+## What it writes
+
+- `spawndock.config.json`
+- `.env.local`
+- `spawndock.dev-tunnel.json`
+- `opencode.json`
+- `public/tonconnect-manifest.json`
+
+## Built-in Overlay
+
+The package also ships a built-in TMA overlay and applies it after cloning
+`SpawnDock/tma-project`. This overlay is responsible for:
+
+- `spawndock/dev.mjs`
+- `spawndock/next.mjs`
+- `spawndock/tunnel.mjs`
+- `next.config.ts`
+- `public/tonconnect-manifest.json`
+- patching project scripts and `@spawn-dock/dev-tunnel`
+
+Generated MCP config points to `<controlPlaneUrl>/mcp/sse`.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@spawn-dock/create",
+  "version": "0.2.0-canary.20260321111558.f5e5655",
+  "type": "module",
+  "description": "SpawnDock bootstrap CLI for local TMA projects",
+  "license": "ISC",
+  "packageManager": "pnpm@10.32.1",
+  "workspaces": [
+    "packages/*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpawnDock/create.git"
+  },
+  "homepage": "https://github.com/SpawnDock/create-spawn-dock#readme",
+  "bugs": {
+    "url": "https://github.com/SpawnDock/create/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "packages/app/dist",
+    "packages/app/template-nextjs-overlay"
+  ],
+  "bin": {
+    "create": "./packages/app/dist/src/app/main.js"
+  },
+  "scripts": {
+    "prepare": "node ./scripts/prepare.mjs",
+    "build": "pnpm --filter @spawn-dock/create-app build",
+    "check": "pnpm --filter @spawn-dock/create-app check",
+    "test": "pnpm --filter @spawn-dock/create-app test",
+    "typecheck": "pnpm --filter @spawn-dock/create-app typecheck",
+    "start": "pnpm --filter @spawn-dock/create-app start"
+  },
+  "dependencies": {
+    "effect": "^3.21.0"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@types/node": "^24.12.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/packages/app/dist/src/app/main.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { Effect } from "effect";
+import { program } from "./program.js";
+Effect.runPromise(program).catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/packages/app/dist/src/app/program.js

@@ -0,0 +1,17 @@
+import { Console, Effect, pipe } from "effect";
+import { bootstrapProject } from "../shell/bootstrap.js";
+import { formatUsage, readCliOptions } from "../shell/cli.js";
+const formatSuccess = (summary) => [
+    "",
+    `SpawnDock project created at ${summary.projectDir}`,
+    `Project: ${summary.projectName}`,
+    `Preview URL: ${summary.previewOrigin}`,
+    `Run: cd "${summary.projectDir}" && npm run dev`,
+].join("\n");
+const cliProgram = pipe(readCliOptions, Effect.flatMap((options) => options.token.length > 0
+    ? bootstrapProject(options)
+    : Effect.fail(new Error(formatUsage()))));
+export const program = Effect.matchEffect(cliProgram, {
+    onFailure: (error) => Console.error(error.message),
+    onSuccess: (summary) => Console.log(formatSuccess(summary)),
+});

package/packages/app/dist/src/core/bootstrap.js

@@ -0,0 +1,123 @@
+export const DEFAULT_PROJECT_DIR = "spawndock-tma";
+export const DEFAULT_CONTROL_PLANE_URL = "https://api.spawndock.app";
+export const DEFAULT_CLAIM_PATH = "/v1/bootstrap/claim";
+export const DEFAULT_TEMPLATE_REPO = "https://github.com/SpawnDock/tma-project.git";
+export const DEFAULT_TEMPLATE_BRANCH = "master";
+export const TEMPLATE_ID = "nextjs-template";
+export const normalizeDisplayName = (value) => value
+    .split(/[^a-zA-Z0-9]+/g)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1).toLowerCase())
+    .join(" ");
+export const resolveProjectContext = (projectDir) => {
+    const projectSlug = projectDir.split(/[\\/]/g).filter(Boolean).at(-1) ?? projectDir;
+    return {
+        projectDir,
+        projectSlug,
+        projectName: normalizeDisplayName(projectSlug),
+        templateId: TEMPLATE_ID,
+    };
+};
+export const resolvePreviewPath = (previewOrigin) => {
+    const url = new URL(previewOrigin);
+    const normalizedPath = url.pathname.replace(/\/$/, "");
+    return normalizedPath.length > 0 ? normalizedPath : "";
+};
+export const resolvePreviewHost = (previewOrigin) => new URL(previewOrigin).host;
+export const buildMcpServerUrl = (controlPlaneUrl) => {
+    const url = new URL(controlPlaneUrl);
+    const normalizedPath = url.pathname.replace(/\/$/, "");
+    url.pathname = normalizedPath.length > 0 ? `${normalizedPath}/mcp/sse` : "/mcp/sse";
+    return url.toString();
+};
+export const buildTonConnectManifest = (context, claim) => `${JSON.stringify({
+    url: claim.previewOrigin,
+    name: context.projectName,
+    iconUrl: `${claim.previewOrigin}/favicon.ico`,
+}, null, 2)}\n`;
+export const buildGeneratedFiles = (context, claim) => {
+    const previewPath = resolvePreviewPath(claim.previewOrigin);
+    const previewHost = resolvePreviewHost(claim.previewOrigin);
+    const mcpServerUrl = buildMcpServerUrl(claim.controlPlaneUrl);
+    const appConfig = {
+        templateId: context.templateId,
+        projectId: claim.projectId,
+        projectSlug: claim.projectSlug,
+        projectName: context.projectName,
+        controlPlaneUrl: claim.controlPlaneUrl,
+        previewOrigin: claim.previewOrigin,
+        previewPath,
+        previewHost,
+        localPort: claim.localPort,
+        deviceSecret: claim.deviceSecret,
+        mcpServerUrl,
+    };
+    const env = {
+        SPAWNDOCK_CONTROL_PLANE_URL: claim.controlPlaneUrl,
+        SPAWNDOCK_PREVIEW_ORIGIN: claim.previewOrigin,
+        SPAWNDOCK_PREVIEW_PATH: previewPath,
+        SPAWNDOCK_ASSET_PREFIX: previewPath,
+        SPAWNDOCK_PREVIEW_HOST: previewHost,
+        SPAWNDOCK_SERVER_ACTIONS_ALLOWED_ORIGINS: previewHost,
+        SPAWNDOCK_DEVICE_SECRET: claim.deviceSecret,
+        SPAWNDOCK_PROJECT_ID: claim.projectId,
+        SPAWNDOCK_PROJECT_SLUG: claim.projectSlug,
+        SPAWNDOCK_ALLOWED_DEV_ORIGINS: claim.previewOrigin,
+    };
+    const opencode = {
+        $schema: "https://opencode.ai/config.json",
+        mcp: {
+            spawndock: {
+                type: "local",
+                command: ["npx", "-y", "@spawn-dock/mcp"],
+                enabled: true,
+                environment: {
+                    MCP_SERVER_URL: mcpServerUrl,
+                },
+            },
+        },
+    };
+    return [
+        {
+            path: "spawndock.config.json",
+            content: `${JSON.stringify(appConfig, null, 2)}\n`,
+        },
+        {
+            path: ".env.local",
+            content: `${Object.entries(env)
+                .map(([key, value]) => `${key}=${value}`)
+                .join("\n")}\n`,
+        },
+        {
+            path: "spawndock.dev-tunnel.json",
+            content: `${JSON.stringify({
+                controlPlane: claim.controlPlaneUrl,
+                projectSlug: claim.projectSlug,
+                deviceSecret: claim.deviceSecret,
+                port: claim.localPort,
+            }, null, 2)}\n`,
+        },
+        {
+            path: "opencode.json",
+            content: `${JSON.stringify(opencode, null, 2)}\n`,
+        },
+        {
+            path: "public/tonconnect-manifest.json",
+            content: buildTonConnectManifest(context, claim),
+        },
+    ];
+};
+export const patchPackageJsonContent = (input) => {
+    const packageJson = JSON.parse(input);
+    packageJson.scripts = {
+        ...(packageJson.scripts ?? {}),
+        dev: "node ./spawndock/dev.mjs",
+        "dev:next": "node ./spawndock/next.mjs",
+        "dev:tunnel": "node ./spawndock/tunnel.mjs",
+    };
+    packageJson.devDependencies = {
+        ...(packageJson.devDependencies ?? {}),
+        "@spawn-dock/dev-tunnel": "latest",
+    };
+    return `${JSON.stringify(packageJson, null, 2)}\n`;
+};

package/packages/app/dist/src/shell/bootstrap.js

@@ -0,0 +1,201 @@
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { Effect } from "effect";
+import { buildGeneratedFiles, patchPackageJsonContent, resolveProjectContext, } from "../core/bootstrap.js";
+const TEMPLATE_OVERLAY_DIR = resolve(fileURLToPath(new URL("../../../template-nextjs-overlay", import.meta.url)));
+export const bootstrapProject = (options) => Effect.gen(function* () {
+    if (options.token.length === 0) {
+        yield* Effect.fail(new Error("Missing pairing token."));
+    }
+    const projectDir = resolve(process.cwd(), options.projectDir);
+    const context = resolveProjectContext(projectDir);
+    yield* ensureEmptyProjectDir(projectDir);
+    yield* ensureParentDirectory(projectDir);
+    yield* cloneTemplateRepo(projectDir, options.templateRepo, options.templateBranch);
+    yield* applyTemplateOverlay(projectDir);
+    const claim = yield* claimProject(options.controlPlaneUrl, options.claimPath, {
+        token: options.token,
+        ["projectSlug"]: context.projectSlug,
+        projectName: context.projectName,
+        templateId: context.templateId,
+        ["localPort"]: 3000,
+    });
+    yield* writeGeneratedFilesToProject(projectDir, context, claim);
+    yield* installDependencies(projectDir);
+    return {
+        projectDir,
+        projectName: context.projectName,
+        previewOrigin: claim.previewOrigin,
+    };
+});
+const ensureEmptyProjectDir = (projectDir) => Effect.try({
+    try: () => {
+        try {
+            const entries = readdirSync(projectDir);
+            if (entries.length > 0) {
+                throw new Error(`Target directory is not empty: ${projectDir}`);
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                return;
+            }
+            throw toError(error);
+        }
+    },
+    catch: toError,
+});
+const ensureParentDirectory = (projectDir) => Effect.try({
+    try: () => {
+        mkdirSync(dirname(projectDir), { recursive: true });
+    },
+    catch: toError,
+});
+const cloneTemplateRepo = (projectDir, templateRepo, templateBranch) => runCommand("git", [
+    "clone",
+    "--depth",
+    "1",
+    "--branch",
+    templateBranch,
+    templateRepo,
+    projectDir,
+]).pipe(Effect.asVoid);
+const applyTemplateOverlay = (projectDir) => Effect.gen(function* () {
+    yield* copyOverlayTree(TEMPLATE_OVERLAY_DIR, projectDir);
+    yield* patchPackageJson(projectDir);
+});
+const copyOverlayTree = (sourceDir, targetDir) => Effect.try({
+    try: () => {
+        copyOverlayTreeSync(sourceDir, targetDir);
+    },
+    catch: toError,
+});
+const patchPackageJson = (projectDir) => Effect.try({
+    try: () => {
+        const packageJsonPath = join(projectDir, "package.json");
+        const content = readFileSync(packageJsonPath, "utf8");
+        writeFileSync(packageJsonPath, patchPackageJsonContent(content), "utf8");
+    },
+    catch: toError,
+});
+const claimProject = (controlPlaneUrl, claimPath, payload) => Effect.tryPromise({
+    try: async () => {
+        const normalizedControlPlaneUrl = controlPlaneUrl.replace(/\/$/, "");
+        const resolvedClaimPath = claimPath.startsWith("/") ? claimPath : `/${claimPath}`;
+        const response = await fetch(`${normalizedControlPlaneUrl}${resolvedClaimPath}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            throw new Error(`SpawnDock control plane claim failed: ${response.status}`);
+        }
+        const json = (await response.json());
+        const parsed = parseClaimResponse(json, payload["projectSlug"], normalizedControlPlaneUrl, payload["localPort"]);
+        if (parsed === null) {
+            throw new Error("SpawnDock control plane response is missing required bootstrap fields");
+        }
+        return parsed;
+    },
+    catch: toError,
+});
+const writeGeneratedFilesToProject = (projectDir, context, claim) => Effect.try({
+    try: () => {
+        for (const file of buildGeneratedFiles(context, claim)) {
+            const targetPath = join(projectDir, file.path);
+            mkdirSync(dirname(targetPath), { recursive: true });
+            writeFileSync(targetPath, file.content, "utf8");
+        }
+    },
+    catch: toError,
+});
+const installDependencies = (projectDir) => Effect.gen(function* () {
+    const corepackResult = yield* runCommand("corepack", ["pnpm", "install"], projectDir, false);
+    if (corepackResult.status === 0) {
+        return;
+    }
+    yield* runCommand("pnpm", ["install"], projectDir);
+});
+const runCommand = (command, args, cwd = process.cwd(), failOnNonZero = true) => Effect.try({
+    try: () => {
+        const result = spawnSync(command, [...args], {
+            cwd,
+            encoding: "utf8",
+            stdio: "pipe",
+        });
+        if (failOnNonZero && result.status !== 0) {
+            throw new Error(result.stderr.trim() ||
+                result.stdout.trim() ||
+                `Command failed: ${command} ${args.join(" ")}`);
+        }
+        return result;
+    },
+    catch: toError,
+});
+const parseClaimResponse = (input, fallbackProjectSlug, fallbackControlPlaneUrl, fallbackLocalPort) => {
+    if (!isRecord(input)) {
+        return null;
+    }
+    const projectValue = input["project"];
+    const project = isRecord(projectValue) ? projectValue : {};
+    const projectId = readString(input, "projectId") ?? readString(project, "id");
+    const projectSlug = readString(input, "projectSlug") ??
+        readString(input, "slug") ??
+        readString(project, "slug") ??
+        (typeof fallbackProjectSlug === "string" ? fallbackProjectSlug : null);
+    const controlPlaneUrl = readString(input, "controlPlaneUrl") ?? fallbackControlPlaneUrl;
+    const previewOrigin = readString(input, "previewOrigin") ??
+        readString(input, "launchUrl") ??
+        readString(input, "staticAssetsBaseUrl") ??
+        readString(input, "url");
+    const deviceSecret = readString(input, "deviceSecret") ??
+        readString(input, "deviceToken") ??
+        readString(input, "deployToken") ??
+        readString(input, "token");
+    const localPort = readNumber(input, "localPort") ??
+        (typeof fallbackLocalPort === "number" ? fallbackLocalPort : 3000);
+    if (projectId === null ||
+        projectSlug === null ||
+        previewOrigin === null ||
+        deviceSecret === null) {
+        return null;
+    }
+    return {
+        projectId,
+        projectSlug,
+        controlPlaneUrl,
+        previewOrigin,
+        deviceSecret,
+        localPort,
+    };
+};
+const readNumber = (input, key) => {
+    const value = input[key];
+    return typeof value === "number" ? value : null;
+};
+const readString = (input, key) => {
+    const value = input[key];
+    return typeof value === "string" ? value : null;
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isNodeError = (error) => error instanceof Error;
+const toError = (cause) => cause instanceof Error ? cause : new Error(String(cause));
+const copyOverlayTreeSync = (sourceDir, targetDir) => {
+    const entries = readdirSync(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(sourceDir, entry.name);
+        const targetPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            mkdirSync(targetPath, { recursive: true });
+            copyOverlayTreeSync(sourcePath, targetPath);
+            continue;
+        }
+        const content = readFileSync(sourcePath, "utf8");
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, content, "utf8");
+    }
+};

package/packages/app/dist/src/shell/cli.js

@@ -0,0 +1,72 @@
+import { Effect } from "effect";
+import { DEFAULT_CLAIM_PATH, DEFAULT_CONTROL_PLANE_URL, DEFAULT_PROJECT_DIR, DEFAULT_TEMPLATE_BRANCH, DEFAULT_TEMPLATE_REPO, } from "../core/bootstrap.js";
+export const formatUsage = (invocation = "npx @spawn-dock/create --token <pairing-token> [project-dir]") => `Usage: ${invocation}`;
+export const parseArgs = (argv, env = process.env) => {
+    const result = {
+        token: "",
+        controlPlaneUrl: env["SPAWNDOCK_CONTROL_PLANE_URL"] ?? DEFAULT_CONTROL_PLANE_URL,
+        claimPath: env["SPAWNDOCK_CLAIM_PATH"] ?? DEFAULT_CLAIM_PATH,
+        projectDir: DEFAULT_PROJECT_DIR,
+        templateRepo: env["SPAWNDOCK_TEMPLATE_REPO"] ?? DEFAULT_TEMPLATE_REPO,
+        templateBranch: env["SPAWNDOCK_TEMPLATE_BRANCH"] ?? DEFAULT_TEMPLATE_BRANCH,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (value === undefined) {
+            continue;
+        }
+        if (value === "--token") {
+            result.token = argv[index + 1] ?? "";
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--token=")) {
+            result.token = value.slice("--token=".length);
+            continue;
+        }
+        if (value === "--control-plane-url") {
+            result.controlPlaneUrl = argv[index + 1] ?? DEFAULT_CONTROL_PLANE_URL;
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--control-plane-url=")) {
+            result.controlPlaneUrl = value.slice("--control-plane-url=".length);
+            continue;
+        }
+        if (value === "--claim-path") {
+            result.claimPath = argv[index + 1] ?? DEFAULT_CLAIM_PATH;
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--claim-path=")) {
+            result.claimPath = value.slice("--claim-path=".length);
+            continue;
+        }
+        if (value === "--template-repo") {
+            result.templateRepo = argv[index + 1] ?? DEFAULT_TEMPLATE_REPO;
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--template-repo=")) {
+            result.templateRepo = value.slice("--template-repo=".length);
+            continue;
+        }
+        if (value === "--template-branch") {
+            result.templateBranch = argv[index + 1] ?? DEFAULT_TEMPLATE_BRANCH;
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--template-branch=")) {
+            result.templateBranch = value.slice("--template-branch=".length);
+            continue;
+        }
+        if (value.startsWith("--")) {
+            continue;
+        }
+        if (result.projectDir === DEFAULT_PROJECT_DIR) {
+            result.projectDir = value;
+        }
+    }
+    return result;
+};
+export const readCliOptions = Effect.sync(() => parseArgs(process.argv.slice(2), process.env));

package/packages/app/template-nextjs-overlay/next.config.ts

@@ -0,0 +1,35 @@
+import type { NextConfig } from "next"
+import createNextIntlPlugin from "next-intl/plugin"
+
+const withNextIntl = createNextIntlPlugin("./src/core/i18n/i18n.ts")
+
+const parseAllowedOrigins = (value: string | undefined): Array<string> =>
+  value
+    ? value
+        .split(",")
+        .map((origin) => origin.trim())
+        .filter(Boolean)
+    : []
+
+const allowedDevOrigins = parseAllowedOrigins(
+  process.env.SPAWNDOCK_ALLOWED_DEV_ORIGINS,
+)
+const previewPath = process.env.SPAWNDOCK_PREVIEW_PATH
+const serverActionOrigins = parseAllowedOrigins(
+  process.env.SPAWNDOCK_SERVER_ACTIONS_ALLOWED_ORIGINS,
+)
+const normalizedPreviewPath =
+  previewPath && previewPath.length > 0 ? previewPath : undefined
+
+const nextConfig: NextConfig = {
+  allowedDevOrigins,
+  assetPrefix: normalizedPreviewPath,
+  basePath: normalizedPreviewPath,
+  experimental: {
+    serverActions: {
+      allowedOrigins: serverActionOrigins,
+    },
+  },
+}
+
+export default withNextIntl(nextConfig)

package/packages/app/template-nextjs-overlay/public/tonconnect-manifest.json

@@ -0,0 +1,5 @@
+{
+  "url": "__SPAWNDOCK_PREVIEW_ORIGIN__",
+  "name": "__SPAWNDOCK_PROJECT_NAME__",
+  "iconUrl": "__SPAWNDOCK_PREVIEW_ORIGIN__/favicon.ico"
+}

package/packages/app/template-nextjs-overlay/spawndock/config.mjs

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+export const readSpawndockConfig = (cwd = process.cwd()) =>
+  JSON.parse(readFileSync(resolve(cwd, "spawndock.config.json"), "utf8"))
+
+export const resolveLocalOrigin = (config) =>
+  `http://127.0.0.1:${config.localPort ?? 3000}`
+
+export const resolvePreviewOrigin = (config) =>
+  config.previewOrigin ?? ""
+
+export const resolveAllowedDevOrigins = (config) =>
+  [config.previewOrigin].filter(Boolean)

package/packages/app/template-nextjs-overlay/spawndock/dev.mjs

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process"
+import { setTimeout } from "node:timers"
+
+const scripts = [
+  ["node", ["spawndock/next.mjs"]],
+  ["node", ["spawndock/tunnel.mjs"]],
+]
+
+const children = []
+
+const stopChildren = (signal) => {
+  for (const child of children) {
+    if (!child.killed) {
+      child.kill(signal ?? "SIGTERM")
+    }
+  }
+}
+
+process.on("SIGINT", () => {
+  stopChildren("SIGINT")
+  process.exit(0)
+})
+
+process.on("SIGTERM", () => {
+  stopChildren("SIGTERM")
+  process.exit(0)
+})
+
+for (const [command, args] of scripts) {
+  const child = spawn(command, args, {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: "inherit",
+  })
+
+  children.push(child)
+
+  child.on("exit", (code) => {
+    if (typeof code === "number" && code !== 0) {
+      stopChildren()
+      process.exit(code)
+    }
+  })
+}
+
+setTimeout(() => {
+  console.log("SpawnDock dev session is ready.")
+}, 0)

package/packages/app/template-nextjs-overlay/spawndock/next.mjs

@@ -0,0 +1,69 @@
+import { spawn } from "node:child_process"
+import readline from "node:readline"
+
+import { readSpawndockConfig, resolveAllowedDevOrigins } from "./config.mjs"
+
+const config = readSpawndockConfig()
+const localPort = Number(config.localPort ?? 3000)
+const allowedOrigins = resolveAllowedDevOrigins(config)
+const previewOrigin = config.previewOrigin ?? ""
+
+const child = spawn("pnpm", ["exec", "next", "dev", "-p", String(localPort)], {
+  cwd: process.cwd(),
+  env: {
+    ...process.env,
+    SPAWNDOCK_ALLOWED_DEV_ORIGINS: allowedOrigins.join(","),
+    SPAWNDOCK_PREVIEW_PATH: config.previewPath ?? "",
+    SPAWNDOCK_ASSET_PREFIX: config.previewPath ?? "",
+    SPAWNDOCK_SERVER_ACTIONS_ALLOWED_ORIGINS: config.previewHost ?? "",
+  },
+  stdio: ["inherit", "pipe", "pipe"],
+})
+
+const exitWithChild = (code) => {
+  process.exit(typeof code === "number" ? code : 1)
+}
+
+const rewriteNextLine = (line) => {
+  if (previewOrigin.length === 0) {
+    return line
+  }
+
+  if (line.includes("Local:")) {
+    return `   - Local:         ${previewOrigin}`
+  }
+
+  if (line.includes("Network:")) {
+    return `   - Network:       ${previewOrigin}`
+  }
+
+  return line
+}
+
+const forwardStream = (stream, writer) => {
+  if (!stream) {
+    return
+  }
+
+  const interfaceHandle = readline.createInterface({
+    input: stream,
+  })
+
+  interfaceHandle.on("line", (line) => {
+    writer(`${rewriteNextLine(line)}\n`)
+  })
+}
+
+forwardStream(child.stdout, (chunk) => {
+  process.stdout.write(chunk)
+})
+
+forwardStream(child.stderr, (chunk) => {
+  process.stderr.write(chunk)
+})
+
+child.on("exit", exitWithChild)
+child.on("error", (error) => {
+  console.error(error)
+  process.exit(1)
+})

package/packages/app/template-nextjs-overlay/spawndock/tunnel.mjs

@@ -0,0 +1,16 @@
+import { spawn } from "node:child_process"
+
+const child = spawn("pnpm", ["exec", "spawn-dock-tunnel"], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: "inherit",
+})
+
+child.on("exit", (code) => {
+  process.exit(typeof code === "number" ? code : 1)
+})
+
+child.on("error", (error) => {
+  console.error(error)
+  process.exit(1)
+})