npm - @pixel-point/toolcraft - Versions diffs - 0.0.8 → 0.0.11 - Mend

@pixel-point/toolcraft 0.0.8 → 0.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (88) hide show

package/templates/starter/gitignore CHANGED Viewed

@@ -19,6 +19,7 @@ playwright-report
 .env
 .env.*
 !.env.example
+.toolcraft
 # Logs
 logs

package/templates/starter/index.html CHANGED Viewed

@@ -2,6 +2,7 @@
 <html lang="en" class="dark">
   <head>
     <meta charset="UTF-8" />
+    <meta name="toolcraft-app-title" content="Toolcraft Starter" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Toolcraft Starter</title>
   </head>

package/templates/starter/package.json CHANGED Viewed

@@ -6,8 +6,10 @@
   "scripts": {
     "ai:check": "node scripts/check-ai-skills.mjs",
     "dev": "node scripts/run-vite-on-free-port.mjs dev",
+    "dev:restart": "node scripts/run-vite-on-free-port.mjs dev --toolcraft-restart",
     "build": "tsc -p tsconfig.json --noEmit && vite build",
     "preview": "node scripts/run-vite-on-free-port.mjs preview",
+    "preview:restart": "node scripts/run-vite-on-free-port.mjs preview --toolcraft-restart",
     "docs:check": "node scripts/check-toolcraft-docs.mjs",
     "test": "node scripts/check-toolcraft-docs.mjs && node scripts/check-toolcraft-integrity.mjs && node --test scripts/*.test.mjs && vitest run src --passWithNoTests",
     "test:browser": "playwright install chromium && playwright test",
@@ -16,6 +18,7 @@
     "verify:quick": "pnpm ai:check && pnpm test",
     "verify:ui": "pnpm test:browser",
     "verify:perf": "pnpm test:browser:perf",
+    "verify:perf:playwright": "pnpm test:browser:perf",
     "verify:final": "pnpm ai:check && pnpm test && pnpm build && pnpm test:browser"
   },
   "dependencies": {

package/templates/starter/playwright.config.ts CHANGED Viewed

@@ -35,7 +35,7 @@ export default defineConfig({
     trace: "retain-on-failure",
   },
   webServer: {
-    command: `pnpm exec vite dev --port ${testPort}`,
+    command: `pnpm exec vite dev --host 127.0.0.1 --port ${testPort} --strictPort`,
     reuseExistingServer: false,
     timeout: 60_000,
     url: testBaseUrl,

package/templates/starter/scripts/check-toolcraft-docs.mjs CHANGED Viewed

@@ -35,6 +35,7 @@ const requiredRuleIds = [
   "output-export-required",
   "controls-layout-heuristics",
   "renderer-technique-inventory",
+  "video-reference-analysis",
   "reference-clone-source-of-truth",
   "acceptance-product-observable",
   "performance-coverage-levels",

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

@@ -2,47 +2,148 @@
 import { spawn } from "node:child_process";
-import { findAvailablePort, readPreferredPort } from "./toolcraft-port.mjs";
+import {
+  findAvailablePort,
+  isPortAvailableOnLoopback,
+  killListeningProcessesOnPort,
+  readPreferredPort,
+  readSavedToolcraftPort,
+  waitForToolcraftAppOnPort,
+  waitForPortAvailable,
+  writeSavedToolcraftPort,
+} from "./toolcraft-port.mjs";
 const viteCommand = process.argv[2] ?? "dev";
-const passthroughArgs = process.argv.slice(3).filter((arg) => arg !== "--");
+const restartArg = "--toolcraft-restart";
+const rawPassthroughArgs = process.argv.slice(3).filter((arg) => arg !== "--");
+const restartSamePort =
+  process.env.TOOLCRAFT_RESTART === "1" || rawPassthroughArgs.includes(restartArg);
+const passthroughArgs = rawPassthroughArgs.filter((arg) => arg !== restartArg);
 const preferredPort = readPreferredPort([
   "TOOLCRAFT_DEV_PORT",
   "TOOLCRAFT_PORT",
   "PORT",
 ]);
-const port = await findAvailablePort(preferredPort);
+const savedPort = await readSavedToolcraftPort();
+let port = savedPort;
-if (port !== preferredPort) {
-  console.log(`[toolcraft] Port ${preferredPort} is busy; using ${port} instead.`);
+if (savedPort) {
+  console.log(`[toolcraft] Using saved port ${savedPort}.`);
+  if (restartSamePort && !(await isPortAvailableOnLoopback(savedPort))) {
+    console.log(`[toolcraft] Port ${savedPort} is busy; stopping the existing listener first.`);
+    await killListeningProcessesOnPort(savedPort);
+    if (!(await waitForPortAvailable(savedPort))) {
+      console.log(`[toolcraft] Port ${savedPort} is still busy; forcing listener shutdown.`);
+      await killListeningProcessesOnPort(savedPort, { signal: "SIGKILL" });
+      if (!(await waitForPortAvailable(savedPort, { timeoutMs: 1_000 }))) {
+        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 (!port) {
+  port = await findAvailablePort(preferredPort);
+  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 CHANGED Viewed

@@ -1,7 +1,16 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
 import net from "node:net";
+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";
+const PORT_STATE_FILE = "server-port.json";
 export function readPreferredPort(names, fallback = DEFAULT_TOOLCRAFT_PORT, env = process.env) {
   for (const name of names) {
@@ -52,3 +61,274 @@ export async function findAvailablePort(startPort = DEFAULT_TOOLCRAFT_PORT) {
   throw new Error(`No free port found at or above ${startPort}.`);
 }
+function isValidPort(port) {
+  return Number.isInteger(port) && port > 0 && port <= 65_535;
+}
+export function getToolcraftPortStatePath(cwd = process.cwd()) {
+  return path.join(cwd, PORT_STATE_DIR, PORT_STATE_FILE);
+}
+export async function readSavedToolcraftPort(cwd = process.cwd()) {
+  try {
+    const source = await fs.readFile(getToolcraftPortStatePath(cwd), "utf8");
+    const state = JSON.parse(source);
+    return isValidPort(state.port) ? state.port : null;
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) {
+      return null;
+    }
+    throw error;
+  }
+}
+export async function writeSavedToolcraftPort(port, cwd = process.cwd()) {
+  if (!isValidPort(port)) {
+    throw new Error(`Cannot save invalid Toolcraft port: ${port}.`);
+  }
+  const statePath = getToolcraftPortStatePath(cwd);
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await fs.writeFile(
+    statePath,
+    `${JSON.stringify({ port, updatedAt: new Date().toISOString() }, null, 2)}\n`,
+  );
+}
+export async function getListeningProcessIds(port, execFileImpl = execFileAsync) {
+  if (!isValidPort(port)) {
+    return [];
+  }
+  try {
+    const { stdout } =
+      process.platform === "win32"
+        ? await execFileImpl("powershell", [
+            "-NoProfile",
+            "-Command",
+            `Get-NetTCPConnection -LocalPort ${port} -State Listen | Select-Object -ExpandProperty OwningProcess -Unique`,
+          ])
+        : await execFileImpl("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"]);
+    return [...new Set(String(stdout).split(/\s+/).map(Number).filter(Number.isInteger))].filter(
+      (pid) => pid > 0 && pid !== process.pid,
+    );
+  } catch {
+    return [];
+  }
+}
+export async function killListeningProcessesOnPort(port, options = {}) {
+  const {
+    execFileImpl = execFileAsync,
+    killProcess = process.kill,
+    signal = "SIGTERM",
+  } = options;
+  const pids = await getListeningProcessIds(port, execFileImpl);
+  for (const pid of pids) {
+    try {
+      killProcess(pid, signal);
+    } catch (error) {
+      if (error?.code !== "ESRCH") {
+        throw error;
+      }
+    }
+  }
+  return pids;
+}
+export async function waitForPortAvailable(port, options = {}) {
+  const { intervalMs = 100, timeoutMs = 3_000 } = options;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    if (await isPortAvailableOnLoopback(port)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  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"
+    }`,
+  );
+}