@pixel-point/toolcraft 0.0.7 → 0.0.9

package/templates/starter/e2e/performance-helpers.ts

@@ -21,6 +21,26 @@ export type ToolcraftInteractionOptions = {
   settleMs?: number;
 };
 
+export type ToolcraftStressFixtureApplyContext = {
+  config: ToolcraftPerformanceConfig;
+  fixture: Record<string, unknown>;
+  key: string;
+  page: Page;
+  scenarioId: string;
+};
+
+export type ToolcraftStressFixtureAppliers = Record<
+  string,
+  (
+    value: unknown,
+    context: ToolcraftStressFixtureApplyContext,
+  ) => Promise<void> | void
+>;
+
+function isToolcraftStressFixtureObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 export async function startToolcraftFrameProbe(
   page: Page,
 ): Promise<() => Promise<ToolcraftFrameProbeResult>> {
@@ -371,6 +391,161 @@ export async function dragToolcraftSliderByLabel(
   await page.mouse.up();
 }
 
+export async function dragToolcraftSliderToValue(
+  page: Page,
+  label: string,
+  value: number,
+): Promise<void> {
+  const field = await getToolcraftFieldByLabel(page, label);
+  const slider = field.locator('[data-slot="slider"], [role="slider"]').first();
+
+  await expect(slider, `Toolcraft slider "${label}" should be visible`).toBeVisible();
+
+  const range = await slider.evaluate((element) => {
+    const htmlElement = element as HTMLElement;
+    const min = Number(
+      htmlElement.getAttribute("aria-valuemin") ??
+        (htmlElement as HTMLInputElement).min ??
+        "0",
+    );
+    const max = Number(
+      htmlElement.getAttribute("aria-valuemax") ??
+        (htmlElement as HTMLInputElement).max ??
+        "100",
+    );
+
+    return {
+      max: Number.isFinite(max) ? max : 100,
+      min: Number.isFinite(min) ? min : 0,
+    };
+  });
+  const denominator = range.max - range.min;
+  const ratio = denominator === 0 ? 0 : (value - range.min) / denominator;
+
+  await dragToolcraftSliderByLabel(page, label, Math.min(1, Math.max(0, ratio)));
+}
+
+export async function dragToolcraftSliderToPerformanceStressValue(
+  page: Page,
+  label: string,
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+): Promise<void> {
+  const value = getToolcraftPerformanceStressValue(config, scenarioId);
+
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" must provide a numeric stressFixture.value for slider "${label}".`,
+    );
+  }
+
+  await dragToolcraftSliderToValue(page, label, value);
+}
+
+export async function applyToolcraftPerformanceStressFixture(
+  page: Page,
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  appliers: ToolcraftStressFixtureAppliers,
+): Promise<Record<string, unknown>> {
+  const fixture = getToolcraftPerformanceStressValue(config, scenarioId);
+
+  if (!isToolcraftStressFixtureObject(fixture)) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" must provide an object stressFixture.value for combined fixture application.`,
+    );
+  }
+
+  const fixtureKeys = Object.keys(fixture);
+  if (fixtureKeys.length === 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" stressFixture.value must contain at least one key.`,
+    );
+  }
+
+  const missingKeys = fixtureKeys.filter((key) => !appliers[key]);
+  if (missingKeys.length > 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" is missing fixture appliers for: ${missingKeys.join(
+        ", ",
+      )}.`,
+    );
+  }
+
+  const extraKeys = Object.keys(appliers).filter((key) => !fixtureKeys.includes(key));
+  if (extraKeys.length > 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" declares fixture appliers not present in stressFixture.value: ${extraKeys.join(
+        ", ",
+      )}.`,
+    );
+  }
+
+  for (const key of fixtureKeys) {
+    await appliers[key]!(fixture[key], {
+      config,
+      fixture,
+      key,
+      page,
+      scenarioId,
+    });
+  }
+
+  return fixture;
+}
+
+export async function applyToolcraftPerformanceWorkloadFixture(
+  page: Page,
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+  appliers: ToolcraftStressFixtureAppliers,
+): Promise<Record<string, unknown>> {
+  const fixture = getToolcraftPerformanceWorkloadValue(config, scenarioId);
+
+  if (!isToolcraftStressFixtureObject(fixture)) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" must provide an object workloadFixture.value for baseline fixture application.`,
+    );
+  }
+
+  const fixtureKeys = Object.keys(fixture);
+  if (fixtureKeys.length === 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" workloadFixture.value must contain at least one key.`,
+    );
+  }
+
+  const missingKeys = fixtureKeys.filter((key) => !appliers[key]);
+  if (missingKeys.length > 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" is missing workload fixture appliers for: ${missingKeys.join(
+        ", ",
+      )}.`,
+    );
+  }
+
+  const extraKeys = Object.keys(appliers).filter((key) => !fixtureKeys.includes(key));
+  if (extraKeys.length > 0) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" declares workload fixture appliers not present in workloadFixture.value: ${extraKeys.join(
+        ", ",
+      )}.`,
+    );
+  }
+
+  for (const key of fixtureKeys) {
+    await appliers[key]!(fixture[key], {
+      config,
+      fixture,
+      key,
+      page,
+      scenarioId,
+    });
+  }
+
+  return fixture;
+}
+
 export async function dragToolcraftCanvasViewport(
   page: Page,
   delta: { x: number; y: number } = { x: 96, y: -64 },
@@ -553,6 +728,28 @@ export function getToolcraftPerformanceStressValue<TValue = unknown>(
   return scenario.stressFixture.value as TValue;
 }
 
+export function getToolcraftPerformanceWorkloadValue<TValue = unknown>(
+  config: ToolcraftPerformanceConfig,
+  scenarioId: string,
+): TValue {
+  const scenario = config.scenarios.find((item) => item.id === scenarioId);
+
+  if (!scenario) {
+    throw new Error(`Toolcraft performance scenario "${scenarioId}" was not found.`);
+  }
+
+  if (
+    !scenario.workloadFixture ||
+    !Object.prototype.hasOwnProperty.call(scenario.workloadFixture, "value")
+  ) {
+    throw new Error(
+      `Toolcraft performance scenario "${scenarioId}" does not declare workloadFixture.value.`,
+    );
+  }
+
+  return scenario.workloadFixture.value as TValue;
+}
+
 export function expectToolcraftScenarioPerformanceBudget(
   result: ToolcraftPerformanceBudgetResult,
   config: ToolcraftPerformanceConfig,

package/templates/starter/gitignore

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

package/templates/starter/package.json

@@ -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",
@@ -20,6 +22,9 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.4.1",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@fontsource-variable/inter": "^5.2.8",
     "@phosphor-icons/react": "^2.1.10",
     "@repo/toolcraft-runtime": "workspace:*",

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

@@ -2,21 +2,56 @@
 
 import { spawn } from "node:child_process";
 
-import { findAvailablePort, readPreferredPort } from "./toolcraft-port.mjs";
+import {
+  findAvailablePort,
+  isPortAvailableOnLoopback,
+  killListeningProcessesOnPort,
+  readPreferredPort,
+  readSavedToolcraftPort,
+  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 = restartSamePort ? await readSavedToolcraftPort() : null;
+const port = savedPort ?? (await findAvailablePort(preferredPort));
 
-if (port !== preferredPort) {
+if (savedPort) {
+  console.log(`[toolcraft] Restart mode: reusing port ${savedPort}.`);
+
+  if (!(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) {
+  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.`);
 }
 
+await writeSavedToolcraftPort(port);
+
 const pnpmCommand = process.platform === "win32" ? "pnpm.cmd" : "pnpm";
 const child = spawn(pnpmCommand, ["exec", "vite", viteCommand, "--port", String(port), ...passthroughArgs], {
   env: {

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

@@ -1,7 +1,14 @@
+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;
 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 +59,98 @@ 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;
+}

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

@@ -1,8 +1,17 @@
 import assert from "node:assert/strict";
+import fs from "node:fs/promises";
 import net from "node:net";
+import os from "node:os";
+import path from "node:path";
 import test from "node:test";
 
-import { findAvailablePort } from "./toolcraft-port.mjs";
+import {
+  findAvailablePort,
+  getListeningProcessIds,
+  killListeningProcessesOnPort,
+  readSavedToolcraftPort,
+  writeSavedToolcraftPort,
+} from "./toolcraft-port.mjs";
 
 function listen(host) {
   return new Promise((resolve, reject) => {
@@ -71,3 +80,53 @@ test("findAvailablePort skips ports occupied on IPv4 localhost", async (t) => {
     "A port occupied on 127.0.0.1 must be treated as unavailable for localhost URLs.",
   );
 });
+
+test("saved Toolcraft port round-trips through local project state", async (t) => {
+  const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "toolcraft-port-"));
+  t.after(() => fs.rm(cwd, { force: true, recursive: true }));
+
+  assert.equal(await readSavedToolcraftPort(cwd), null);
+
+  await writeSavedToolcraftPort(4123, cwd);
+
+  assert.equal(await readSavedToolcraftPort(cwd), 4123);
+});
+
+test("getListeningProcessIds parses unique listening process ids", async () => {
+  const pids = await getListeningProcessIds(4123, async () => ({
+    stderr: "",
+    stdout: "123\n456\n123\nnot-a-pid\n",
+  }));
+
+  assert.deepEqual(pids, [123, 456]);
+});
+
+test("killListeningProcessesOnPort targets listeners found on the port", async () => {
+  const killed = [];
+  const pids = await killListeningProcessesOnPort(4123, {
+    execFileImpl: async () => ({ stderr: "", stdout: "123\n456\n" }),
+    killProcess: (pid, signal) => {
+      killed.push({ pid, signal });
+    },
+  });
+
+  assert.deepEqual(pids, [123, 456]);
+  assert.deepEqual(killed, [
+    { pid: 123, signal: "SIGTERM" },
+    { pid: 456, signal: "SIGTERM" },
+  ]);
+});
+
+test("killListeningProcessesOnPort supports forced restart cleanup", async () => {
+  const killed = [];
+  const pids = await killListeningProcessesOnPort(4123, {
+    execFileImpl: async () => ({ stderr: "", stdout: "789\n" }),
+    killProcess: (pid, signal) => {
+      killed.push({ pid, signal });
+    },
+    signal: "SIGKILL",
+  });
+
+  assert.deepEqual(pids, [789]);
+  assert.deepEqual(killed, [{ pid: 789, signal: "SIGKILL" }]);
+});