@half-built/tooling 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Curt Henrichs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @half-built/tooling
+
+Lint presets and the test kit for half-built sites.
+
+## Test kit
+
+`test-kit/browser-server.ts` type-imports and dynamically imports
+`puppeteer-core` for `launchChrome`; it is an optional peer dependency,
+so consumers of the test kit install `puppeteer-core` themselves.
+
+## Provenance
+
+Extracted from the private `half-built-robots-blog` repository, where
+this configuration was built and used in production. The extraction
+review that checked it for blog-specific assumptions before the move is
+the design record for this package.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@half-built/tooling",
+  "version": "0.1.0",
+  "description": "Lint presets and the test kit for half-built sites.",
+  "license": "MIT",
+  "type": "module",
+  "files": ["src"],
+  "exports": {
+    "./eslint": "./src/eslint.config.mjs",
+    "./stylelint": "./src/stylelintrc.json",
+    "./htmlvalidate": "./src/htmlvalidate.json",
+    "./test-kit/*": "./src/test-kit/*"
+  },
+  "dependencies": {
+    "@eslint/js": "^10.0.1",
+    "typescript-eslint": "^8.65.0",
+    "eslint-plugin-astro": "^1.7.0",
+    "globals": "^17.8.0"
+  },
+  "peerDependencies": {
+    "eslint": "^10.8.0",
+    "stylelint": "^17.14.1",
+    "html-validate": "^9.7.1",
+    "vitest": "^2.1.9",
+    "puppeteer-core": "^25.8.0"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer-core": { "optional": true }
+  },
+  "publishConfig": { "access": "public" }
+}

package/src/eslint.config.mjs

@@ -0,0 +1,77 @@
+// Flat ESLint config: JS/TS plus Astro component linting, shared across
+// half-built packages and any site that consumes them. Adapted from the
+// half-built-robots-blog repo's eslint.config.mjs (step 11.3 task 5):
+// the blog-only ignores (.superpowers/, .claude/, .visual-check/, the
+// vendored fluid-sim.js exemption) are gone, since none of that exists
+// outside the blog, and the file-scoped overrides below are widened from
+// root-anchored globs to "**/"-prefixed ones so they still find
+// scripts/, test/, and src/pages/ wherever a package or site nests them
+// in this monorepo, not only at repo root.
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+import eslintPluginAstro from "eslint-plugin-astro";
+import globals from "globals";
+
+export default tseslint.config(
+  { ignores: ["**/dist/", "**/node_modules/", "**/.astro/", "**/public/"] },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    // Type-checked strict tier for real TypeScript (libs, tests, config).
+    // Astro virtual scripts and .mjs tooling stay on recommended: typed
+    // linting needs the project service, which does not cover them.
+    files: ["**/*.ts"],
+    extends: [
+      ...tseslint.configs.strictTypeChecked,
+      ...tseslint.configs.stylisticTypeChecked,
+    ],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        // Not import.meta.dirname: the blog's original pinned this to
+        // wherever eslint.config.mjs itself lived, which was correct for
+        // a single-repo config at the repo root but breaks the moment
+        // this config ships in a package. import.meta.dirname would then
+        // resolve inside node_modules/@half-built/tooling/src, and
+        // TypeScript's project service treats that as an upper bound: it
+        // will not walk up past it looking for a consumer's tsconfig.json,
+        // so every consumer's typed linting would silently fail (and, in
+        // this repo, so does packages/tooling's own test-kit, since
+        // its tsconfig.json sits one directory above this file). cwd is
+        // wherever eslint was invoked from, which for a shared preset is
+        // the actual project root every time.
+        tsconfigRootDir: process.cwd(),
+      },
+    },
+    rules: {
+      // Numbers interpolate into template literals losslessly; forbidding
+      // them buys String() noise, not safety.
+      "@typescript-eslint/restrict-template-expressions": ["error", { allowNumber: true }],
+    },
+  },
+  ...eslintPluginAstro.configs.recommended,
+  {
+    files: ["**/scripts/**/*.mjs"],
+    languageOptions: { globals: { ...globals.node } },
+  },
+  {
+    // This file itself: it reads process.cwd() above, and any consumer's
+    // eslint.config.mjs that imports this preset runs in Node too.
+    files: ["**/eslint.config.mjs"],
+    languageOptions: { globals: { ...globals.node } },
+  },
+  {
+    files: ["**/test/**/*.ts"],
+    languageOptions: { globals: { ...globals.node } },
+  },
+  {
+    // Astro endpoints run at build time in Node with the web Response global.
+    files: ["**/src/pages/**/*.js"],
+    languageOptions: { globals: { ...globals.node, Response: "readonly" } },
+  },
+  {
+    // Client-side <script> blocks inside Astro components run in the browser.
+    files: ["**/*.astro/*.js", "**/*.astro/*.ts", "**/src/pages/**/*.astro"],
+    languageOptions: { globals: { ...globals.browser } },
+  }
+);

package/src/htmlvalidate.json

@@ -0,0 +1,32 @@
+{
+  "extends": [
+    "html-validate:recommended"
+  ],
+  "rules": {
+    "no-inline-style": [
+      "error",
+      {
+        "allowedProperties": [
+          "height",
+          "background-image",
+          "--gallery-cols",
+          "object-position",
+          "color",
+          "background-color",
+          "overflow-x",
+          "font-style"
+        ]
+      }
+    ],
+    "void-style": "off",
+    "no-trailing-whitespace": "off",
+    "prefer-button": "off",
+    "long-title": "off",
+    "valid-id": [
+      "error",
+      {
+        "relaxed": true
+      }
+    ]
+  }
+}

package/src/stylelintrc.json

@@ -0,0 +1,70 @@
+{
+  "extends": [
+    "stylelint-config-standard"
+  ],
+  "ignoreFiles": [
+    "**/dist/**",
+    "**/node_modules/**",
+    "**/public/**"
+  ],
+  "rules": {
+    "color-no-hex": [
+      true,
+      {
+        "message": "Hex colors live in tokens.css only; use var(--...) (docs/css-architecture.md)"
+      }
+    ],
+    "media-feature-range-notation": null,
+    "alpha-value-notation": null,
+    "color-function-notation": null,
+    "no-descending-specificity": null,
+    "custom-property-empty-line-before": null,
+    "declaration-empty-line-before": null,
+    "comment-empty-line-before": null,
+    "rule-empty-line-before": null,
+    "value-keyword-case": null,
+    "selector-class-pattern": null,
+    "font-family-name-quotes": null,
+    "shorthand-property-no-redundant-values": null,
+    "declaration-block-no-redundant-longhand-properties": null,
+    "number-max-precision": null,
+    "declaration-block-single-line-max-declarations": null,
+    "selector-pseudo-class-no-unknown": [
+      true,
+      {
+        "ignorePseudoClasses": [
+          "global"
+        ]
+      }
+    ],
+    "at-rule-empty-line-before": null,
+    "color-hex-length": null,
+    "color-function-alias-notation": null,
+    "import-notation": null,
+    "declaration-property-value-disallowed-list": [
+      {
+        "/^(width|min-width|max-width)$/": ["/ch$/"]
+      },
+      {
+        "message": "never-cap-prose (step 11.1): a ch measure exists to cap prose width and has no legitimate non-prose use, so this half of the guard is safe as a blanket, selector-blind rule. The other half, that a prose stylesheet's only max-width is the 100% image-fit exception, needs to know which selectors are prose and which are not; stylelint's property/value rules cannot see selector context, so that half stays a consumer's own test (see half-built-robots-blog/test/tokens.test.ts, \"prose never caps width\", which reads the prose stylesheet directly and asserts its max-width declarations are exactly [\"max-width: 100%;\"])."
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": [
+        "**/*.astro"
+      ],
+      "customSyntax": "postcss-html"
+    },
+    {
+      "files": [
+        "**/tokens.css",
+        "**/tokens/*.css"
+      ],
+      "rules": {
+        "color-no-hex": null
+      }
+    }
+  ]
+}

package/src/test-kit/browser-server.ts

@@ -0,0 +1,153 @@
+/* One preview server and one headless Chrome for a consumer's browser
+   suites. Adapted from half-built-robots-blog's test/browser-server.ts
+   (step 11.3 task 5): that file imported findChrome from a sibling
+   ../scripts/find-chrome.mjs, which existed because the blog keeps a
+   repo-wide scripts/ directory (visual-check.mjs used the same finder).
+   The tooling package has no such directory of its own to point at, so
+   findChrome is inlined below instead of adding a sixth file outside the
+   brief's five; its CHROME_CANDIDATES search order is preserved verbatim.
+   Everything else here is the blog's original: one definition of spawn,
+   wait, launch, and kill, so a consumer's suites do not each carry their
+   own drifted copy. */
+import { existsSync } from "node:fs";
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import type { Browser, Page } from "puppeteer-core";
+
+const CHROME_CANDIDATES = [
+  /* CHROME_PATH wins when set, for environments this list cannot know. */
+  process.env.CHROME_PATH ?? "",
+  "C:/Program Files/Google/Chrome/Application/chrome.exe",
+  "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+  `${process.env.LOCALAPPDATA ?? ""}/Google/Chrome/Application/chrome.exe`,
+  /* ubuntu-latest CI runners ship Chrome here. */
+  "/usr/bin/google-chrome",
+  "/usr/bin/chromium-browser",
+  "/usr/bin/chromium",
+];
+
+/** Absolute path to a local Chrome; throws naming every path checked. */
+export function findChrome(): string {
+  const chrome = CHROME_CANDIDATES.find((p) => p && existsSync(p));
+  if (chrome == null || chrome === "") {
+    throw new Error(`Chrome not found; checked: ${CHROME_CANDIDATES.filter(Boolean).join(", ")}`);
+  }
+  return chrome;
+}
+
+async function answers(url: string): Promise<boolean> {
+  try {
+    await fetch(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForServer(url: string, proc: ChildProcess, tries = 60): Promise<void> {
+  for (let i = 0; i < tries; i++) {
+    if (proc.exitCode != null) {
+      throw new Error(`preview server exited with code ${proc.exitCode} (see stderr above)`);
+    }
+    let res: Response | undefined;
+    try {
+      res = await fetch(url);
+    } catch {
+      /* not up yet */
+    }
+    if (res?.status === 404) {
+      /* The server is up but the page is not where the suite thinks:
+         fail now and name the likely cause instead of timing out. */
+      throw new Error(`server is up but ${url} is 404; did the route or slug change?`);
+    }
+    if (res?.ok) return;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error(`preview server never answered at ${url}`);
+}
+
+/* Serves dist on `port` and resolves once `readyPath` answers 200.
+   The port must be OURS: a stale preview (a suite's own leak, or some
+   other tooling session) would answer the wait and the tests would
+   validate a server this run does not control. Chrome is located
+   before the spawn so a machine without one fails before it has a
+   server to clean up. */
+export async function startPreview(port: number, readyPath: string): Promise<ChildProcess> {
+  findChrome();
+  const origin = `http://localhost:${port}`;
+  if (await answers(`${origin}/`)) {
+    throw new Error(`something already serves ${origin}; kill it before running the browser suites`);
+  }
+  /* stderr inherited so a failed spawn (missing dist, bad flag) is
+     loud instead of a silent 30 s timeout. detached on POSIX so the
+     shell wrapper gets its own process group we can kill whole. */
+  const server = spawn("npx", ["astro", "preview", "--port", String(port)], {
+    shell: true,
+    stdio: ["ignore", "ignore", "inherit"],
+    detached: process.platform !== "win32",
+  });
+  await waitForServer(`${origin}${readyPath}`, server);
+  return server;
+}
+
+/* shell: true wraps the server in a shell; kill the whole tree. Safe
+   to call when the spawn itself failed, so no orphan keeps the port. */
+export function stopPreview(server: ChildProcess | undefined): void {
+  if (server?.pid == null) return;
+  if (process.platform === "win32") {
+    spawnSync("taskkill", ["/pid", String(server.pid), "/T", "/F"], { stdio: "ignore" });
+  } else {
+    try {
+      process.kill(-server.pid, "SIGTERM"); // negative pid: the detached group
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/* CI runners restrict the user namespaces Chrome's sandbox needs; the
+   runner is already a throwaway VM. It also has no GPU, so WebGL there
+   is SwiftShader on a couple of vCPUs; a canvas- or WebGL-driven
+   consumer should account for that fallback path the way the blog's own
+   fluid player does, or a timeout there usually means the lighter path
+   stopped engaging, not that the assertion is slow. */
+export async function launchChrome(): Promise<Browser> {
+  const puppeteer = await import("puppeteer-core");
+  return puppeteer.launch({
+    executablePath: findChrome(),
+    headless: true,
+    args: [
+      /* A desktop pointer, stated at launch. Headless Chrome on a CI
+         runner with no input devices reports (hover: none) and
+         (pointer: none); anything gated on a hover/pointer media query
+         (the blog's link-tip.ts is one example) then correctly declines
+         to mount, which can pass locally and fail on the runner. CDP's
+         Emulation.setEmulatedMedia hover/pointer features are ignored
+         by Chrome (probed both directions), so the only lever is
+         Blink's own settings: hover type 2 = hover, pointer type 4 =
+         fine. Launching with the "none" values (1) reproduces the
+         runner failure exactly on a laptop. Touch emulation from
+         setViewport({ hasTouch }) still flips these per page, so
+         phonePage below keeps proving the no-hover path. */
+      "--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4",
+      ...(process.env.CI ? ["--no-sandbox", "--disable-setuid-sandbox"] : []),
+    ],
+  });
+}
+
+/* A desktop-class page. The pointer itself is a launch setting (see
+   launchChrome); this is the viewport, and the one place desktop pages
+   are opened so a consumer's suites cannot drift. */
+export async function desktopPage(browser: Browser, width = 1280, height = 900): Promise<Page> {
+  const p = await browser.newPage();
+  await p.setViewport({ width, height });
+  return p;
+}
+
+/* A phone-class page: iPhone width and touch. hasTouch is what flips
+   (hover: none) and (pointer: coarse) on, per page, over the launch
+   setting; it is the reason a touch test proves the no-hover path. */
+export async function phonePage(browser: Browser, width = 390, height = 664): Promise<Page> {
+  const p = await browser.newPage();
+  await p.setViewport({ width, height, deviceScaleFactor: 2, isMobile: true, hasTouch: true });
+  return p;
+}

package/src/test-kit/helpers.ts

@@ -0,0 +1,87 @@
+/* Shared test utilities for consumers of @half-built/tooling. Adapted from
+   half-built-robots-blog's test/helpers.ts (step 11.3 task 5): the two
+   blog-content exports are dropped since neither means anything outside
+   that repo. FLUID_ART_POST was a post slug shared by three of the blog's
+   own suites; allHtml() walked a built dist/ tree looking for that blog's
+   post pages. What is left is generic: DOM and canvas test scaffolding
+   any consumer's suite can use. (packages/astro/test/helpers.ts made the
+   same two drops independently for the package's own tests; this file
+   serves outside consumers instead, so the overlap is expected, not
+   duplication to dedupe.) */
+import { vi } from "vitest";
+
+/* rAF driven by the fake-timer clock, for suites under vi.useFakeTimers.
+   Self-advancing frame stamp: do not lean on performance.now or Date.now
+   here, fake timers do not reliably advance them across environments.
+   Call after vi.useFakeTimers(); undone by vi.unstubAllGlobals(). */
+export function stubRafOnFakeTimers(): void {
+  let frameNow = 0;
+  vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) =>
+    setTimeout(() => { frameNow += 16; cb(frameNow); }, 16) as unknown as number);
+  vi.stubGlobal("cancelAnimationFrame", (id: number) => { clearTimeout(id); });
+}
+
+/* jsdom's <dialog> support has lagged the platform; polyfill the members
+   modal decorators use so tests exercise your logic, not jsdom's. Touches
+   HTMLDialogElement only when called, so node-env tests importing this
+   module are unaffected. */
+export function polyfillDialog(): void {
+  const p = HTMLDialogElement.prototype;
+  if (typeof p.showModal !== "function") {
+    p.showModal = function (this: HTMLDialogElement) { this.setAttribute("open", ""); };
+  }
+  if (typeof p.close !== "function") {
+    p.close = function (this: HTMLDialogElement) {
+      this.removeAttribute("open");
+      this.dispatchEvent(new Event("close"));
+    };
+  }
+}
+
+/* Canvas call recorder for canvas-painting code under test (it should be
+   pure over the 2D context it is handed). Every recorded method pushes
+   {op, args} plus the style fields as they stood at call time, so a test
+   can ask what color a given rect was painted in. measureText answers 5px
+   per character. */
+export interface CanvasCall {
+  op: string;
+  args: unknown[];
+  fillStyle: string;
+  strokeStyle: string;
+  lineWidth: number;
+  font: string;
+  textAlign: string;
+}
+export interface RecordingContext {
+  calls: CanvasCall[];
+  ops: (op: string) => CanvasCall[];
+  ctx: CanvasRenderingContext2D;
+}
+export function recordingContext(): RecordingContext {
+  const calls: CanvasCall[] = [];
+  const ctx: Record<string, unknown> = {
+    fillStyle: "", strokeStyle: "", lineWidth: 1, font: "", textAlign: "start",
+  };
+  const snap = (op: string, args: unknown[]): void => {
+    calls.push({
+      op, args,
+      fillStyle: String(ctx.fillStyle), strokeStyle: String(ctx.strokeStyle),
+      lineWidth: Number(ctx.lineWidth), font: String(ctx.font), textAlign: String(ctx.textAlign),
+    });
+  };
+  for (const op of [
+    "fillRect", "strokeRect", "beginPath", "moveTo", "lineTo", "stroke",
+    "fillText", "scale", "clearRect", "drawImage", "save", "restore",
+  ]) {
+    ctx[op] = (...args: unknown[]): void => { snap(op, args); };
+  }
+  ctx.measureText = (text: string): { width: number } => {
+    snap("measureText", [text]);
+    return { width: text.length * 5 };
+  };
+  return {
+    calls,
+    ops: (op) => calls.filter((c) => c.op === op),
+    ctx: ctx as unknown as CanvasRenderingContext2D,
+  };
+}