@pixel-point/toolcraft 0.0.9 → 0.0.11

package/templates/starter/scripts/run-vite-on-free-port.mjs

@@ -8,6 +8,7 @@ import {
   killListeningProcessesOnPort,
   readPreferredPort,
   readSavedToolcraftPort,
+  waitForToolcraftAppOnPort,
   waitForPortAvailable,
   writeSavedToolcraftPort,
 } from "./toolcraft-port.mjs";
@@ -23,13 +24,13 @@ const preferredPort = readPreferredPort([
   "TOOLCRAFT_PORT",
   "PORT",
 ]);
-const savedPort = restartSamePort ? await readSavedToolcraftPort() : null;
-const port = savedPort ?? (await findAvailablePort(preferredPort));
+const savedPort = await readSavedToolcraftPort();
+let port = savedPort;
 
 if (savedPort) {
-  console.log(`[toolcraft] Restart mode: reusing port ${savedPort}.`);
+  console.log(`[toolcraft] Using saved port ${savedPort}.`);
 
-  if (!(await isPortAvailableOnLoopback(savedPort))) {
+  if (restartSamePort && !(await isPortAvailableOnLoopback(savedPort))) {
     console.log(`[toolcraft] Port ${savedPort} is busy; stopping the existing listener first.`);
     await killListeningProcessesOnPort(savedPort);
 
@@ -41,43 +42,108 @@ if (savedPort) {
         throw new Error(`Port ${savedPort} is still busy after forced restart cleanup.`);
       }
     }
+  } else if (!restartSamePort && !(await isPortAvailableOnLoopback(savedPort))) {
+    try {
+      const existingApp = await waitForToolcraftAppOnPort(savedPort, { timeoutMs: 1_200 });
+      console.log(`[toolcraft] This app is already running on ${existingApp.url}`);
+      process.exit(0);
+    } catch (error) {
+      console.error(
+        `Saved Toolcraft port ${savedPort} is busy, but it is not serving this app. Use pnpm dev:restart or pnpm preview:restart to reclaim the saved port, or remove .toolcraft/server-port.json to assign a new port. ${error?.message ?? ""}`.trim(),
+      );
+      process.exit(1);
+    }
   }
 } else if (restartSamePort) {
   console.log("[toolcraft] Restart mode requested, but no saved port exists yet.");
 }
 
-if (!savedPort && port !== preferredPort) {
-  console.log(`[toolcraft] Port ${preferredPort} is busy; using ${port} instead.`);
-}
+if (!port) {
+  port = await findAvailablePort(preferredPort);
 
-await writeSavedToolcraftPort(port);
+  if (port !== preferredPort) {
+    console.log(`[toolcraft] Port ${preferredPort} is busy; using ${port} instead.`);
+  }
+}
 
 const pnpmCommand = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
-const child = spawn(pnpmCommand, ["exec", "vite", viteCommand, "--port", String(port), ...passthroughArgs], {
-  env: {
-    ...process.env,
-    TOOLCRAFT_ACTIVE_PORT: String(port),
-    PORT: String(port),
+const child = spawn(
+  pnpmCommand,
+  [
+    "exec",
+    "vite",
+    viteCommand,
+    "--host",
+    "127.0.0.1",
+    "--port",
+    String(port),
+    "--strictPort",
+    ...passthroughArgs,
+  ],
+  {
+    env: {
+      ...process.env,
+      TOOLCRAFT_ACTIVE_PORT: String(port),
+      PORT: String(port),
+    },
+    stdio: "inherit",
   },
-  stdio: "inherit",
-});
+);
 
 const signalExitCodes = {
   SIGINT: 130,
   SIGTERM: 143,
 };
 
+let childExit = null;
+const childExitPromise = new Promise((resolve) => {
+  child.on("exit", (code, signal) => {
+    childExit = { code, signal };
+    resolve(childExit);
+  });
+});
+
 for (const signal of ["SIGINT", "SIGTERM"]) {
   process.on(signal, () => {
     child.kill(signal);
   });
 }
 
-child.on("exit", (code, signal) => {
+function exitFromChild(code, signal) {
   if (signal) {
     process.exit(signalExitCodes[signal] ?? 1);
     return;
   }
 
   process.exit(code ?? 0);
+}
+
+try {
+  const startupResult = await Promise.race([
+    waitForToolcraftAppOnPort(port),
+    childExitPromise.then(() => "exited"),
+  ]);
+
+  if (startupResult === "exited") {
+    throw new Error(`Vite exited before serving this Toolcraft app on port ${port}.`);
+  }
+
+  await writeSavedToolcraftPort(port);
+  console.log(`[toolcraft] Verified this app on ${startupResult.url}`);
+} catch (error) {
+  console.error(`[toolcraft] ${error?.message ?? error}`);
+
+  if (!childExit) {
+    child.kill("SIGTERM");
+  }
+
+  process.exit(1);
+}
+
+if (childExit) {
+  exitFromChild(childExit.code, childExit.signal);
+}
+
+childExitPromise.then(({ code, signal }) => {
+  exitFromChild(code, signal);
 });

package/templates/starter/scripts/toolcraft-port.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import { promisify } from "node:util";
 
 export const DEFAULT_TOOLCRAFT_PORT = 3002;
+export const TOOLCRAFT_APP_TITLE_META_NAME = "toolcraft-app-title";
+export const TOOLCRAFT_SERVER_IDENTITY_PATH = "/.toolcraft/server-identity.json";
 const LOOPBACK_HOSTS = ["127.0.0.1", "::1"];
 const execFileAsync = promisify(execFile);
 const PORT_STATE_DIR = ".toolcraft";
@@ -154,3 +156,179 @@ export async function waitForPortAvailable(port, options = {}) {
 
   return false;
 }
+
+function extractAttribute(tag, name) {
+  const pattern = new RegExp(`${name}\\s*=\\s*["']([^"']*)["']`, "i");
+  return tag.match(pattern)?.[1] ?? null;
+}
+
+export function readToolcraftAppIdentityFromHtml(source) {
+  const html = String(source ?? "");
+  const title = html.match(/<title>(.*?)<\/title>/is)?.[1]?.trim() ?? null;
+  const metaTags = html.match(/<meta\b[^>]*>/gi) ?? [];
+  const appTitleMeta = metaTags.find(
+    (tag) => extractAttribute(tag, "name")?.toLowerCase() === TOOLCRAFT_APP_TITLE_META_NAME,
+  );
+  const appTitle = appTitleMeta ? extractAttribute(appTitleMeta, "content") : null;
+
+  return {
+    appTitle,
+    title,
+  };
+}
+
+async function getRealPath(filePath) {
+  try {
+    return await fs.realpath(filePath);
+  } catch {
+    return path.resolve(filePath);
+  }
+}
+
+export async function readExpectedToolcraftAppIdentity(cwd = process.cwd()) {
+  const indexPath = path.join(cwd, "index.html");
+  const source = await fs.readFile(indexPath, "utf8");
+  const identity = readToolcraftAppIdentityFromHtml(source);
+  const expectedLabel = identity.appTitle ?? identity.title;
+
+  if (!expectedLabel) {
+    throw new Error(
+      `Cannot verify the Toolcraft server for ${cwd}: index.html has no ${TOOLCRAFT_APP_TITLE_META_NAME} meta tag or title.`,
+    );
+  }
+
+  return {
+    ...identity,
+    root: await getRealPath(cwd),
+  };
+}
+
+export function toolcraftAppIdentityMatches(actual, expected) {
+  if (actual.root && expected.root) {
+    return actual.root === expected.root;
+  }
+
+  if (expected.appTitle) {
+    return actual.appTitle === expected.appTitle;
+  }
+
+  return actual.title === expected.title;
+}
+
+function getToolcraftIdentityLabel(identity) {
+  return identity.appTitle ?? identity.title ?? "unknown app";
+}
+
+function getToolcraftIdentityDescription(identity) {
+  const label = getToolcraftIdentityLabel(identity);
+
+  return identity.root ? `${label} at ${identity.root}` : label;
+}
+
+async function fetchTextWithTimeout(url, options = {}) {
+  const { fetchImpl = globalThis.fetch, timeoutMs = 1_000 } = options;
+
+  if (typeof fetchImpl !== "function") {
+    throw new Error("Cannot verify Toolcraft server identity because fetch is unavailable.");
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchImpl(url, {
+      cache: "no-store",
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    return await response.text();
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function fetchToolcraftServerIdentity(baseUrl, options = {}) {
+  const source = await fetchTextWithTimeout(
+    `${baseUrl}${TOOLCRAFT_SERVER_IDENTITY_PATH}?toolcraft-port-check=${Date.now()}`,
+    options,
+  );
+  const parsed = JSON.parse(source);
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Toolcraft server identity endpoint returned invalid JSON.");
+  }
+
+  if (typeof parsed.root !== "string" || parsed.root.trim() === "") {
+    throw new Error("Toolcraft server identity endpoint did not return a project root.");
+  }
+
+  return {
+    appTitle: typeof parsed.appTitle === "string" ? parsed.appTitle : null,
+    root: await getRealPath(parsed.root),
+    title: null,
+  };
+}
+
+function createHttpBaseUrl(host, port) {
+  const formattedHost = host.includes(":") ? `[${host}]` : host;
+
+  return `http://${formattedHost}:${port}`;
+}
+
+export async function waitForToolcraftAppOnPort(port, options = {}) {
+  const {
+    cwd = process.cwd(),
+    fetchImpl = globalThis.fetch,
+    host = "127.0.0.1",
+    hosts = [host, "::1"],
+    intervalMs = 150,
+    timeoutMs = 10_000,
+  } = options;
+  const expected = await readExpectedToolcraftAppIdentity(cwd);
+  const expectedDescription = getToolcraftIdentityDescription(expected);
+  const deadline = Date.now() + timeoutMs;
+  const candidateHosts = [...new Set(hosts)];
+  let lastError = null;
+
+  while (Date.now() <= deadline) {
+    for (const candidateHost of candidateHosts) {
+      const baseUrl = createHttpBaseUrl(candidateHost, port);
+      const url = `${baseUrl}/`;
+
+      try {
+        const actual = await fetchToolcraftServerIdentity(baseUrl, { fetchImpl });
+
+        if (!toolcraftAppIdentityMatches(actual, expected)) {
+          throw new Error(
+            `Port ${port} is serving ${getToolcraftIdentityDescription(
+              actual,
+            )} instead of this app ${expectedDescription}.`,
+          );
+        }
+
+        return {
+          expected,
+          url,
+        };
+      } catch (error) {
+        lastError = error;
+
+        if (/is serving/.test(String(error?.message))) {
+          throw error;
+        }
+      }
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  throw new Error(
+    `Timed out waiting for this Toolcraft app ${expectedDescription} on port ${port}. Last error: ${
+      lastError?.message ?? "none"
+    }`,
+  );
+}

package/templates/starter/scripts/toolcraft-port.test.mjs

@@ -9,7 +9,9 @@ import {
   findAvailablePort,
   getListeningProcessIds,
   killListeningProcessesOnPort,
+  readToolcraftAppIdentityFromHtml,
   readSavedToolcraftPort,
+  waitForToolcraftAppOnPort,
   writeSavedToolcraftPort,
 } from "./toolcraft-port.mjs";
 
@@ -130,3 +132,148 @@ test("killListeningProcessesOnPort supports forced restart cleanup", async () =>
   assert.deepEqual(pids, [789]);
   assert.deepEqual(killed, [{ pid: 789, signal: "SIGKILL" }]);
 });
+
+test("readToolcraftAppIdentityFromHtml prefers the app title meta marker", () => {
+  assert.deepEqual(
+    readToolcraftAppIdentityFromHtml(`
+      <html>
+        <head>
+          <meta name="toolcraft-app-title" content="Generated App" />
+          <title>Other Title</title>
+        </head>
+      </html>
+    `),
+    {
+      appTitle: "Generated App",
+      title: "Other Title",
+    },
+  );
+});
+
+test("waitForToolcraftAppOnPort accepts the current app identity", async (t) => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-identity-"));
+  t.after(() => fs.rm(cwd, { force: true, recursive: true }));
+  await fs.writeFile(
+    path.join(cwd, "index.html"),
+    '<meta name="toolcraft-app-title" content="Current App" /><title>Current App</title>',
+  );
+  const currentRoot = await fs.realpath(cwd);
+
+  const result = await waitForToolcraftAppOnPort(4321, {
+    cwd,
+    fetchImpl: async () => ({
+      ok: true,
+      text: async () => JSON.stringify({ appTitle: "Current App", root: currentRoot }),
+    }),
+    timeoutMs: 1,
+  });
+
+  assert.equal(result.url, "http://127.0.0.1:4321/");
+});
+
+test("waitForToolcraftAppOnPort verifies the current project root when the server identity endpoint exists", async (t) => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-root-"));
+  t.after(() => fs.rm(cwd, { force: true, recursive: true }));
+  await fs.writeFile(
+    path.join(cwd, "index.html"),
+    '<meta name="toolcraft-app-title" content="Current App" /><title>Current App</title>',
+  );
+  const currentRoot = await fs.realpath(cwd);
+
+  const result = await waitForToolcraftAppOnPort(4321, {
+    cwd,
+    fetchImpl: async (url) => ({
+      ok: true,
+      text: async () =>
+        String(url).includes("/.toolcraft/server-identity.json")
+          ? JSON.stringify({ appTitle: "Current App", root: currentRoot })
+          : '<meta name="toolcraft-app-title" content="Different App" /><title>Different App</title>',
+    }),
+    timeoutMs: 1,
+  });
+
+  assert.equal(result.url, "http://127.0.0.1:4321/");
+});
+
+test("waitForToolcraftAppOnPort checks IPv6 localhost when IPv4 does not respond", async (t) => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-ipv6-"));
+  t.after(() => fs.rm(cwd, { force: true, recursive: true }));
+  await fs.writeFile(
+    path.join(cwd, "index.html"),
+    '<meta name="toolcraft-app-title" content="Current App" /><title>Current App</title>',
+  );
+  const currentRoot = await fs.realpath(cwd);
+
+  const result = await waitForToolcraftAppOnPort(4321, {
+    cwd,
+    fetchImpl: async (url) => {
+      if (String(url).startsWith("http://127.0.0.1:4321")) {
+        throw new Error("fetch failed");
+      }
+
+      return {
+        ok: true,
+        text: async () =>
+          String(url).includes("/.toolcraft/server-identity.json")
+            ? JSON.stringify({ appTitle: "Current App", root: currentRoot })
+            : '<meta name="toolcraft-app-title" content="Current App" /><title>Current App</title>',
+      };
+    },
+    timeoutMs: 1,
+  });
+
+  assert.equal(result.url, "http://[::1]:4321/");
+});
+
+test("waitForToolcraftAppOnPort rejects a port serving another app", async (t) => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-foreign-"));
+  t.after(() => fs.rm(cwd, { force: true, recursive: true }));
+  await fs.writeFile(
+    path.join(cwd, "index.html"),
+    '<meta name="toolcraft-app-title" content="Current App" /><title>Current App</title>',
+  );
+  const otherRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-foreign-root-"));
+  t.after(() => fs.rm(otherRoot, { force: true, recursive: true }));
+  const otherRealRoot = await fs.realpath(otherRoot);
+
+  await assert.rejects(
+    () =>
+      waitForToolcraftAppOnPort(4321, {
+        cwd,
+        fetchImpl: async () => ({
+          ok: true,
+          text: async () => JSON.stringify({ appTitle: "Different App", root: otherRealRoot }),
+        }),
+        timeoutMs: 1,
+      }),
+    /Port 4321 is serving Different App at .* instead of this app Current App at /,
+  );
+});
+
+test("waitForToolcraftAppOnPort rejects a matching title from a different project root", async (t) => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-root-current-"));
+  const otherRoot = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-root-other-"));
+  t.after(() => fs.rm(cwd, { force: true, recursive: true }));
+  t.after(() => fs.rm(otherRoot, { force: true, recursive: true }));
+  await fs.writeFile(
+    path.join(cwd, "index.html"),
+    '<meta name="toolcraft-app-title" content="Current App" /><title>Current App</title>',
+  );
+  const otherRealRoot = await fs.realpath(otherRoot);
+
+  await assert.rejects(
+    () =>
+      waitForToolcraftAppOnPort(4321, {
+        cwd,
+        fetchImpl: async (url) => ({
+          ok: true,
+          text: async () =>
+            String(url).includes("/.toolcraft/server-identity.json")
+              ? JSON.stringify({ appTitle: "Current App", root: otherRealRoot })
+              : '<meta name="toolcraft-app-title" content="Current App" /><title>Current App</title>',
+        }),
+        timeoutMs: 1,
+      }),
+    /Port 4321 is serving Current App at .* instead of this app Current App at /,
+  );
+});