feat: add toolbox contract shell and testkit

packages/testkit/LICENSE

@@ -0,0 +1,192 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      Copyright 2026 ADD Ideas
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

packages/testkit/README.md

@@ -0,0 +1,17 @@
+# @add-ideas/toolbox-testkit
+
+Validate and smoke-check a built toolbox application:
+
+```sh
+toolbox-check dist
+```
+
+The checker validates `toolbox-app.json`, its id and SemVer version, verifies
+the entry, icon, and declared assets, rejects unsafe local paths, serves the
+build under a deep nested prefix, and fetches it both standalone and with
+`?toolbox=/toolbox.catalog.json`. It also fetches local scripts, stylesheets,
+images, icons, linked web manifests, and their icons from the entry HTML, so
+root-absolute references fail the nested-deployment check. It does not launch a
+browser.
+
+The same behavior is available programmatically as `checkToolboxDist()`.

packages/testkit/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@add-ideas/toolbox-testkit",
+  "version": "0.1.0",
+  "description": "Manifest, asset, and nested-deployment smoke checks for built toolbox applications.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.add-ideas.de/zemion/toolbox-sdk.git",
+    "directory": "packages/testkit"
+  },
+  "homepage": "https://git.add-ideas.de/zemion/toolbox-sdk",
+  "keywords": [
+    "toolbox",
+    "manifest",
+    "smoke-test",
+    "cli"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "toolbox-check": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@add-ideas/toolbox-contract": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');fs.chmodSync('dist/cli.js',0o755);fs.copyFileSync('../../LICENSE','LICENSE')\"",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://git.add-ideas.de/api/packages/zemion/npm/"
+  }
+}

packages/testkit/src/check.ts

@@ -0,0 +1,482 @@
+import {
+  loadToolboxContext,
+  parseToolboxApp,
+  type ToolboxAppManifest,
+} from "@add-ideas/toolbox-contract";
+import { createReadStream } from "node:fs";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { createServer, type Server } from "node:http";
+import { extname, relative, resolve, sep } from "node:path";
+
+const DEEP_PREFIX = "/__toolbox-check__/deep/nested/app/";
+const CATALOG_PATH = "/toolbox.catalog.json";
+const SEMVER_PATTERN =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export class ToolboxCheckError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ToolboxCheckError";
+  }
+}
+
+export interface ToolboxCheckOptions {
+  manifestName?: string;
+}
+
+export interface ToolboxCheckReport {
+  root: string;
+  manifestPath: string;
+  app: ToolboxAppManifest;
+  checkedFiles: readonly string[];
+  smoke: {
+    standaloneUrl: string;
+    contextualUrl: string;
+    fetchedUrls: readonly string[];
+  };
+}
+
+interface CheckedReference {
+  reference: string;
+  path: string;
+}
+
+function decodedReference(reference: string, label: string): string {
+  let decoded = reference;
+  try {
+    for (let count = 0; count < 3; count += 1) {
+      const next = decodeURIComponent(decoded);
+      if (next === decoded) break;
+      decoded = next;
+    }
+  } catch (cause) {
+    throw new ToolboxCheckError(`${label} contains invalid URL encoding`, {
+      cause,
+    });
+  }
+  return decoded;
+}
+
+function localReference(
+  root: string,
+  reference: string,
+  label: string,
+): CheckedReference {
+  const decoded = decodedReference(reference, label);
+  const pathPart = decoded.split(/[?#]/u, 1)[0] ?? "";
+  if (
+    pathPart.startsWith("/") ||
+    pathPart.includes("\\") ||
+    /^[a-z][a-z\d+.-]*:/iu.test(pathPart) ||
+    pathPart.split("/").includes("..") ||
+    pathPart.includes("\0")
+  ) {
+    throw new ToolboxCheckError(`${label} uses an unsafe path: ${reference}`);
+  }
+
+  let filePath = resolve(root, pathPart || ".");
+  if (pathPart.endsWith("/") || pathPart === "." || pathPart === "./") {
+    filePath = resolve(filePath, "index.html");
+  }
+  const fromRoot = relative(root, filePath);
+  if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) {
+    throw new ToolboxCheckError(`${label} escapes the distribution directory`);
+  }
+  return { reference, path: filePath };
+}
+
+async function assertRegularContainedFile(
+  root: string,
+  item: CheckedReference,
+  label: string,
+): Promise<string> {
+  try {
+    await lstat(item.path);
+  } catch (cause) {
+    throw new ToolboxCheckError(`${label} does not exist: ${item.reference}`, {
+      cause,
+    });
+  }
+  const [realRoot, realFile] = await Promise.all([
+    realpath(root),
+    realpath(item.path),
+  ]);
+  const fromRealRoot = relative(realRoot, realFile);
+  if (fromRealRoot === ".." || fromRealRoot.startsWith(`..${sep}`)) {
+    throw new ToolboxCheckError(`${label} resolves outside the distribution`);
+  }
+  const info = await stat(realFile);
+  if (!info.isFile()) {
+    throw new ToolboxCheckError(`${label} is not a file: ${item.reference}`);
+  }
+  return item.path;
+}
+
+function contentType(path: string): string {
+  switch (extname(path).toLowerCase()) {
+    case ".html":
+      return "text/html; charset=utf-8";
+    case ".json":
+      return "application/json; charset=utf-8";
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".js":
+    case ".mjs":
+      return "text/javascript; charset=utf-8";
+    case ".svg":
+      return "image/svg+xml";
+    case ".png":
+      return "image/png";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+function encodedPath(path: string): string {
+  return path.split("/").map(encodeURIComponent).join("/");
+}
+
+function catalogDocument(manifestName: string): object {
+  return {
+    schemaVersion: 1,
+    id: "de.add-ideas.toolbox-check",
+    name: "Toolbox check",
+    home: "/",
+    theme: { mode: "system", brand: "Toolbox check" },
+    apps: [
+      {
+        manifest: `${DEEP_PREFIX}${encodedPath(manifestName)}`,
+        enabled: true,
+      },
+    ],
+  };
+}
+
+function staticServer(root: string, manifestName: string): Server {
+  return createServer((request, response) => {
+    void (async () => {
+      const requestUrl = new URL(request.url ?? "/", "http://localhost");
+      if (requestUrl.pathname === CATALOG_PATH) {
+        response.writeHead(200, {
+          "content-type": "application/json; charset=utf-8",
+        });
+        response.end(JSON.stringify(catalogDocument(manifestName)));
+        return;
+      }
+      if (!requestUrl.pathname.startsWith(DEEP_PREFIX)) {
+        response.writeHead(404).end("Not found");
+        return;
+      }
+      let relativePath: string;
+      try {
+        relativePath = decodeURIComponent(
+          requestUrl.pathname.slice(DEEP_PREFIX.length),
+        );
+      } catch {
+        response.writeHead(400).end("Bad path");
+        return;
+      }
+      const checked = localReference(
+        root,
+        relativePath || "./",
+        "Request path",
+      );
+      try {
+        await assertRegularContainedFile(root, checked, "Requested file");
+      } catch {
+        response.writeHead(404).end("Not found");
+        return;
+      }
+      response.writeHead(200, { "content-type": contentType(checked.path) });
+      createReadStream(checked.path).pipe(response);
+    })().catch(() => {
+      if (!response.headersSent) response.writeHead(500);
+      response.end("Server error");
+    });
+  });
+}
+
+async function listen(server: Server): Promise<number> {
+  await new Promise<void>((resolvePromise, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolvePromise());
+  });
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    throw new ToolboxCheckError("Could not determine smoke-test server port");
+  }
+  return address.port;
+}
+
+async function close(server: Server): Promise<void> {
+  await new Promise<void>((resolvePromise, reject) => {
+    server.close((error) => (error ? reject(error) : resolvePromise()));
+  });
+}
+
+async function requireOk(url: URL, label: string): Promise<Response> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new ToolboxCheckError(`${label} returned HTTP ${response.status}`);
+  }
+  return response;
+}
+
+interface HtmlResource {
+  kind: "icon" | "image" | "manifest" | "script" | "stylesheet";
+  reference: string;
+}
+
+function attributes(source: string): Map<string, string> {
+  const result = new Map<string, string>();
+  const pattern = /([:\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/gu;
+  for (const match of source.matchAll(pattern)) {
+    const name = match[1]?.toLowerCase();
+    const value = match[2] ?? match[3] ?? match[4];
+    if (name !== undefined && value !== undefined) result.set(name, value);
+  }
+  return result;
+}
+
+function htmlResources(html: string): readonly HtmlResource[] {
+  const resources: HtmlResource[] = [];
+  const tagPattern = /<(script|link|img)\b([^>]*)>/giu;
+  for (const match of html.matchAll(tagPattern)) {
+    const tag = match[1]?.toLowerCase();
+    const values = attributes(match[2] ?? "");
+    if (tag === "script") {
+      const reference = values.get("src");
+      if (reference) resources.push({ kind: "script", reference });
+    } else if (tag === "img") {
+      const reference = values.get("src");
+      if (reference) resources.push({ kind: "image", reference });
+    } else if (tag === "link") {
+      const reference = values.get("href");
+      const relationships = new Set(
+        (values.get("rel") ?? "").toLowerCase().split(/\s+/u).filter(Boolean),
+      );
+      if (!reference) continue;
+      if (relationships.has("manifest")) {
+        resources.push({ kind: "manifest", reference });
+      } else if (relationships.has("stylesheet")) {
+        resources.push({ kind: "stylesheet", reference });
+      } else if (
+        relationships.has("icon") ||
+        relationships.has("apple-touch-icon")
+      ) {
+        resources.push({ kind: "icon", reference });
+      } else if (
+        relationships.has("modulepreload") ||
+        relationships.has("preload")
+      ) {
+        resources.push({ kind: "script", reference });
+      }
+    }
+  }
+  return resources;
+}
+
+function nestedLocalUrl(
+  reference: string,
+  base: URL,
+  label: string,
+): URL | undefined {
+  let url: URL;
+  try {
+    url = new URL(reference, base);
+  } catch (cause) {
+    throw new ToolboxCheckError(`${label} has an invalid URL: ${reference}`, {
+      cause,
+    });
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+  if (url.origin !== base.origin) return undefined;
+  if (!url.pathname.startsWith(DEEP_PREFIX)) {
+    throw new ToolboxCheckError(
+      `${label} is not relocatable under the nested prefix: ${reference}`,
+    );
+  }
+  return url;
+}
+
+async function inspectWebManifest(
+  response: Response,
+  manifestUrl: URL,
+): Promise<readonly string[]> {
+  let document: unknown;
+  try {
+    document = await response.json();
+  } catch (cause) {
+    throw new ToolboxCheckError("Linked web manifest is not valid JSON", {
+      cause,
+    });
+  }
+  if (typeof document !== "object" || document === null) return [];
+  const icons = (document as { icons?: unknown }).icons;
+  if (icons === undefined) return [];
+  if (!Array.isArray(icons)) {
+    throw new ToolboxCheckError("Linked web manifest icons must be an array");
+  }
+  const fetched: string[] = [];
+  for (const [index, icon] of icons.entries()) {
+    if (typeof icon !== "object" || icon === null) {
+      throw new ToolboxCheckError(
+        `Web manifest icon ${index} must be an object`,
+      );
+    }
+    const source = (icon as { src?: unknown }).src;
+    if (typeof source !== "string" || source.length === 0) {
+      throw new ToolboxCheckError(`Web manifest icon ${index} needs a src`);
+    }
+    const iconUrl = nestedLocalUrl(source, manifestUrl, "Web manifest icon");
+    if (iconUrl !== undefined) {
+      await requireOk(iconUrl, "Web manifest icon");
+      fetched.push(iconUrl.href);
+    }
+  }
+  return fetched;
+}
+
+async function inspectEntryHtml(
+  html: string,
+  entryUrl: URL,
+): Promise<readonly string[]> {
+  const fetched: string[] = [];
+  for (const resource of htmlResources(html)) {
+    const label = `HTML ${resource.kind}`;
+    const url = nestedLocalUrl(resource.reference, entryUrl, label);
+    if (url === undefined) continue;
+    const response = await requireOk(url, label);
+    fetched.push(url.href);
+    if (resource.kind === "manifest") {
+      fetched.push(...(await inspectWebManifest(response, url)));
+    }
+  }
+  return fetched;
+}
+
+async function smokeCheck(
+  root: string,
+  manifest: ToolboxAppManifest,
+  manifestName: string,
+): Promise<ToolboxCheckReport["smoke"]> {
+  const server = staticServer(root, manifestName);
+  const port = await listen(server);
+  try {
+    const appBase = new URL(DEEP_PREFIX, `http://127.0.0.1:${port}/`);
+    const standaloneUrl = new URL(manifest.entry, appBase);
+    const standaloneResponse = await requireOk(
+      standaloneUrl,
+      "Standalone entry",
+    );
+    const fetchedUrls = await inspectEntryHtml(
+      await standaloneResponse.text(),
+      standaloneUrl,
+    );
+    const standalone = await loadToolboxContext({ location: standaloneUrl });
+    if (standalone.status !== "standalone") {
+      throw new ToolboxCheckError(
+        "The standalone smoke URL discovered a toolbox",
+      );
+    }
+
+    const contextualUrl = new URL(standaloneUrl);
+    contextualUrl.searchParams.set("toolbox", CATALOG_PATH);
+    await requireOk(contextualUrl, "Contextual entry");
+    const contextual = await loadToolboxContext({ location: contextualUrl });
+    if (contextual.status !== "ready") {
+      const reason =
+        contextual.status === "error" ? `: ${contextual.error.message}` : "";
+      throw new ToolboxCheckError(
+        `Toolbox context smoke check failed${reason}`,
+      );
+    }
+    const loaded = contextual.context.catalog.apps.find(
+      (entry) => entry.kind === "manifest",
+    );
+    if (loaded?.kind !== "manifest" || loaded.app.manifest.id !== manifest.id) {
+      throw new ToolboxCheckError(
+        "Smoke catalog did not resolve the built app",
+      );
+    }
+    return {
+      standaloneUrl: standaloneUrl.href,
+      contextualUrl: contextualUrl.href,
+      fetchedUrls,
+    };
+  } finally {
+    await close(server);
+  }
+}
+
+export async function checkToolboxDist(
+  dist: string,
+  options: ToolboxCheckOptions = {},
+): Promise<ToolboxCheckReport> {
+  const root = resolve(dist);
+  let rootInfo;
+  try {
+    rootInfo = await stat(root);
+  } catch (cause) {
+    throw new ToolboxCheckError(
+      `Distribution directory does not exist: ${root}`,
+      {
+        cause,
+      },
+    );
+  }
+  if (!rootInfo.isDirectory()) {
+    throw new ToolboxCheckError(
+      `Distribution path is not a directory: ${root}`,
+    );
+  }
+
+  const manifestName = options.manifestName ?? "toolbox-app.json";
+  const manifestReference = localReference(root, manifestName, "Manifest");
+  const manifestPath = await assertRegularContainedFile(
+    root,
+    manifestReference,
+    "Manifest",
+  );
+  let document: unknown;
+  try {
+    document = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (cause) {
+    throw new ToolboxCheckError(`Manifest is not valid JSON: ${manifestPath}`, {
+      cause,
+    });
+  }
+  let app: ToolboxAppManifest;
+  try {
+    app = parseToolboxApp(document);
+  } catch (cause) {
+    throw new ToolboxCheckError("Manifest does not satisfy toolbox app v1", {
+      cause,
+    });
+  }
+  if (!SEMVER_PATTERN.test(app.version)) {
+    throw new ToolboxCheckError(
+      `Manifest version is not SemVer: ${app.version}`,
+    );
+  }
+
+  const references: Array<[string, string]> = [
+    [app.entry, "Application entry"],
+    [app.icon, "Application icon"],
+    ...(app.assets ?? []).map((asset): [string, string] => [
+      asset,
+      "Application asset",
+    ]),
+  ];
+  const checkedFiles = await Promise.all(
+    references.map(([reference, label]) =>
+      assertRegularContainedFile(
+        root,
+        localReference(root, reference, label),
+        label,
+      ),
+    ),
+  );
+  const smoke = await smokeCheck(root, app, manifestName);
+  return { root, manifestPath, app, checkedFiles, smoke };
+}

packages/testkit/src/cli.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { checkToolboxDist } from "./check.js";
+
+function usage(): void {
+  console.log("Usage: toolbox-check <dist>");
+}
+
+const arguments_ = process.argv.slice(2);
+if (arguments_.includes("--help") || arguments_.includes("-h")) {
+  usage();
+} else if (arguments_.length !== 1) {
+  usage();
+  process.exitCode = 2;
+} else {
+  checkToolboxDist(arguments_[0] as string)
+    .then((report) => {
+      console.log(
+        `toolbox-check: ${report.app.id}@${report.app.version} passed (${report.checkedFiles.length} files, standalone + contextual smoke checks)`,
+      );
+    })
+    .catch((error: unknown) => {
+      console.error(
+        `toolbox-check: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      process.exitCode = 1;
+    });
+}

packages/testkit/src/index.ts

@@ -0,0 +1,2 @@
+export { checkToolboxDist, ToolboxCheckError } from "./check.js";
+export type { ToolboxCheckOptions, ToolboxCheckReport } from "./check.js";

packages/testkit/test/check.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment node
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { checkToolboxDist } from "../src/index.js";
+
+const temporaryDirectories: string[] = [];
+
+const manifest = (overrides: Record<string, unknown> = {}) => ({
+  schemaVersion: 1,
+  id: "de.add-ideas.example",
+  name: "Example",
+  version: "1.2.3",
+  description: "Example app",
+  entry: "./",
+  icon: "./icon.svg",
+  categories: ["example"],
+  tags: ["test"],
+  integration: {
+    contextVersion: 1,
+    launchModes: ["navigate"],
+    embedding: "unsupported",
+  },
+  requirements: {
+    secureContext: false,
+    workers: false,
+    indexedDb: false,
+    crossOriginIsolated: false,
+  },
+  privacy: {
+    processing: "local",
+    fileUploads: false,
+    telemetry: false,
+  },
+  source: {
+    repository: "https://git.example.test/example",
+    license: "MIT",
+  },
+  assets: ["./app.js"],
+  ...overrides,
+});
+
+async function fixture(document = manifest()): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "toolbox-check-"));
+  temporaryDirectories.push(root);
+  await Promise.all([
+    writeFile(join(root, "toolbox-app.json"), JSON.stringify(document)),
+    writeFile(
+      join(root, "index.html"),
+      '<!doctype html><link rel="manifest" href="./site.webmanifest"><link rel="icon" href="./icon.svg"><link rel="stylesheet" href="./style.css"><img src="./image.png" alt=""><script type="module" src="./app.js"></script><title>Example</title>',
+    ),
+    writeFile(
+      join(root, "icon.svg"),
+      '<svg xmlns="http://www.w3.org/2000/svg"/>',
+    ),
+    writeFile(join(root, "app.js"), "console.log('ok')"),
+    writeFile(join(root, "style.css"), "body { color: black; }"),
+    writeFile(join(root, "image.png"), "not-a-real-png"),
+    writeFile(
+      join(root, "site.webmanifest"),
+      JSON.stringify({ icons: [{ src: "./icon.svg" }] }),
+    ),
+  ]);
+  return root;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+
+describe("toolbox-check", () => {
+  it("validates files and smoke-fetches nested standalone and context URLs", async () => {
+    const report = await checkToolboxDist(await fixture());
+
+    expect(report.app.id).toBe("de.add-ideas.example");
+    expect(report.checkedFiles).toHaveLength(3);
+    expect(new URL(report.smoke.standaloneUrl).pathname).toBe(
+      "/__toolbox-check__/deep/nested/app/",
+    );
+    expect(
+      new URL(report.smoke.contextualUrl).searchParams.get("toolbox"),
+    ).toBe("/toolbox.catalog.json");
+    expect(report.smoke.fetchedUrls).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("/site.webmanifest"),
+        expect.stringContaining("/style.css"),
+        expect.stringContaining("/app.js"),
+      ]),
+    );
+  });
+
+  it("rejects traversal in declared assets", async () => {
+    const root = await fixture(manifest({ assets: ["../secret.txt"] }));
+    await expect(checkToolboxDist(root)).rejects.toThrow(/unsafe path/u);
+  });
+
+  it("rejects a non-SemVer manifest version", async () => {
+    const root = await fixture(manifest({ version: "next" }));
+    await expect(checkToolboxDist(root)).rejects.toThrow(/not SemVer/u);
+  });
+
+  it("rejects root-absolute HTML assets that break nested deployment", async () => {
+    const root = await fixture();
+    await writeFile(
+      join(root, "index.html"),
+      '<!doctype html><script src="/app.js"></script>',
+    );
+    await expect(checkToolboxDist(root)).rejects.toThrow(/not relocatable/u);
+  });
+});

packages/testkit/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

packages/testkit/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"],
+    "paths": {
+      "@add-ideas/toolbox-contract": ["../contract/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}