@napplet/conformance-cli 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @napplet/conformance-cli
+
+The headless `napplet-conformance` runner. It drives the
+[`@napplet/conformance`](../conformance) engine against a napplet in real headless
+Chromium (via Playwright), so a napplet can prove it conforms to the NAP protocol
+**before** publishing — locally and in CI.
+
+```bash
+# Build your napplet first, then:
+npx napplet-conformance ./dist
+# or point at a directory containing index.html / a dist/ subdir:
+npx napplet-conformance .
+# or a remotely-served napplet:
+npx napplet-conformance --url https://my.napplet.example/
+```
+
+Wire it into any package manager as `test:conformance`:
+
+```jsonc
+{
+  "scripts": {
+    "test:conformance": "napplet-conformance ./dist",
+    "test:conformance:ui": "napplet-conformance --ui . --exec \"vite build --watch\""
+  }
+}
+```
+
+```bash
+pnpm test:conformance   # npm / yarn / bun all work — the bin is PM-agnostic
+```
+
+## UI / watch mode (`--ui`) — like `vitest --ui`
+
+```bash
+napplet-conformance --ui . --exec "vite build --watch"
+```
+
+`--ui` serves the standalone conformance web runtime (bundled with this package) plus
+the napplet, opens your browser, and **re-runs conformance live every time the napplet
+changes**. The optional `--exec` runs your build in watch mode so source edits rebuild
+the served `./dist`; the CLI's file watcher then triggers a fresh run — edit, save, see
+the verdict update. Useful flags: `--port <n>`, `--no-open`. (Headless mode is
+unchanged — `--ui` is purely additive.)
+
+## How it works
+
+1. Serves your built napplet on loopback alongside a host harness page and the
+   bundled engine. Every response sends `Access-Control-Allow-Origin: *` so the
+   sandboxed napplet's module scripts load across its opaque origin.
+2. Launches headless Chromium, loads the napplet into a `sandbox="allow-scripts"`
+   iframe (no `allow-same-origin`), attaches a reference shell, and records every
+   envelope the napplet emits — plus a second no-capability pass to prove graceful
+   degradation.
+3. Assembles the conformance context (manifest + static `window.nostr` scan), runs
+   the check catalog, prints the report, and exits non-zero on any error-severity
+   failure.
+
+## Options
+
+```
+--url <url>            Test a remotely-served napplet instead of a local dir
+--reporter <fmt>       pretty | json | junit            (default: pretty)
+--out <file>           Write the report to a file instead of stdout
+--ready-timeout <ms>   Boot timeout waiting for shell.ready (default: 5000)
+--settle <ms>          Envelope-collection window after boot (default: 600)
+--no-degraded          Skip the graceful-degradation pass
+--allow-same-origin    Debug only (a conformant napplet must not need it)
+-h, --help             Show help
+```
+
+Exit codes: `0` conformant, `1` non-conformant, `2` usage/runtime error.
+
+> Requires Playwright's Chromium. In CI, run `npx playwright install --with-deps chromium`
+> once before invoking the CLI. This package is npm-only (Playwright is not
+> JSR-friendly); the pure engine `@napplet/conformance` is published to both.

package/dist/cli.js

@@ -0,0 +1,526 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFile as readFile4, writeFile, stat as stat4 } from "fs/promises";
+import { join as join4, dirname, resolve as resolve3 } from "path";
+import { fileURLToPath } from "url";
+import { spawn } from "child_process";
+import { chromium } from "playwright";
+import {
+  buildContext,
+  runConformance,
+  report
+} from "@napplet/conformance";
+
+// src/server.ts
+import { createServer } from "http";
+import { readFile as readFile2, stat as stat2 } from "fs/promises";
+import { join, normalize, extname as extname2, resolve } from "path";
+
+// src/static.ts
+import { readFile, stat } from "fs/promises";
+import { extname } from "path";
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".wasm": "application/wasm",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".map": "application/json; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8"
+};
+function setCors(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+}
+async function sendFile(res, absPath) {
+  const info = await stat(absPath).catch(() => null);
+  if (!info?.isFile()) return false;
+  res.writeHead(200, { "Content-Type": MIME[extname(absPath).toLowerCase()] ?? "application/octet-stream" });
+  res.end(await readFile(absPath));
+  return true;
+}
+
+// src/server.ts
+var HOST_HTML_ROUTE = "/__conformance__/host.html";
+var HOST_BUNDLE_ROUTE = "/__conformance__/host-bundle.js";
+function renderHostPage(boot) {
+  const cfg = JSON.stringify(boot);
+  return `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>napplet conformance host</title></head>
+<body>
+<script src="${HOST_BUNDLE_ROUTE}"></script>
+<script>
+  (function () {
+    var cfg = ${cfg};
+    window.NappletConformanceHost.run(cfg).then(function (boot) {
+      window.__conformanceBoot__ = boot;
+    }).catch(function (err) {
+      window.__conformanceError__ = String((err && err.stack) || err);
+    });
+  })();
+</script>
+</body>
+</html>`;
+}
+async function startHarnessServer(options) {
+  const dir = options.nappletDir ? resolve(options.nappletDir) : null;
+  const hostHtml = renderHostPage(options.bootConfig);
+  const server = createServer((req, res) => {
+    void serve(req.url ?? "/", res);
+  });
+  async function serve(rawUrl, res) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    const path = decodeURIComponent(rawUrl.split("?")[0]);
+    if (path === HOST_HTML_ROUTE) {
+      res.writeHead(200, { "Content-Type": MIME[".html"] });
+      res.end(hostHtml);
+      return;
+    }
+    if (path === HOST_BUNDLE_ROUTE) {
+      res.writeHead(200, { "Content-Type": MIME[".js"] });
+      res.end(options.hostBundle);
+      return;
+    }
+    if (!dir) {
+      res.writeHead(404).end("not found");
+      return;
+    }
+    const relative = normalize(path).replace(/^(\.\.[/\\])+/, "").replace(/^[/\\]+/, "");
+    let filePath = join(dir, relative);
+    if (!filePath.startsWith(dir)) {
+      res.writeHead(403).end("forbidden");
+      return;
+    }
+    try {
+      let info = await stat2(filePath).catch(() => null);
+      if (info?.isDirectory()) {
+        filePath = join(filePath, "index.html");
+        info = await stat2(filePath).catch(() => null);
+      }
+      if (path === "/" && !info) {
+        filePath = join(dir, "index.html");
+        info = await stat2(filePath).catch(() => null);
+      }
+      if (!info?.isFile()) {
+        res.writeHead(404).end("not found");
+        return;
+      }
+      const body = await readFile2(filePath);
+      res.writeHead(200, { "Content-Type": MIME[extname2(filePath).toLowerCase()] ?? "application/octet-stream" });
+      res.end(body);
+    } catch {
+      res.writeHead(500).end("server error");
+    }
+  }
+  await new Promise((resolveListen) => server.listen(0, "127.0.0.1", resolveListen));
+  const address = server.address();
+  const origin = `http://127.0.0.1:${address.port}`;
+  return {
+    origin,
+    hostUrl: `${origin}${HOST_HTML_ROUTE}`,
+    close: () => new Promise((res, rej) => server.close((err) => err ? rej(err) : res()))
+  };
+}
+
+// src/ui-server.ts
+import { createServer as createServer2 } from "http";
+import { watch } from "fs";
+import { join as join2, normalize as normalize2, resolve as resolve2 } from "path";
+var NAPPLET_PREFIX = "/__napplet__/";
+var EVENTS_ROUTE = "/__conformance__/events";
+function safeJoin(dir, urlPath) {
+  const relative = normalize2(urlPath).replace(/^(\.\.[/\\])+/, "").replace(/^[/\\]+/, "");
+  const full = join2(dir, relative);
+  return full.startsWith(dir) ? full : null;
+}
+function handleSse(res, clients) {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive"
+  });
+  res.write("retry: 1000\n\n");
+  clients.add(res);
+  res.on("close", () => clients.delete(res));
+}
+async function handleNapplet(res, nappletDir, path) {
+  const rel = path.slice(NAPPLET_PREFIX.length) || "index.html";
+  const abs = safeJoin(nappletDir, rel);
+  if (abs && await sendFile(res, abs)) return;
+  res.writeHead(404).end("napplet asset not found");
+}
+async function handleApp(res, appDir, path) {
+  const abs = safeJoin(appDir, path === "/" ? "index.html" : path);
+  if (abs && await sendFile(res, abs)) return;
+  if (await sendFile(res, join2(appDir, "index.html"))) return;
+  res.writeHead(404).end("not found");
+}
+function startWatcher(dir, debounceMs, fire) {
+  let timer = null;
+  const onEvent = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(fire, debounceMs);
+  };
+  let watcher;
+  try {
+    watcher = watch(dir, { recursive: true }, onEvent);
+  } catch {
+    watcher = watch(dir, onEvent);
+  }
+  return {
+    close() {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+async function startUiServer(options) {
+  const appDir = resolve2(options.appDir);
+  const nappletDir = resolve2(options.nappletDir);
+  const clients = /* @__PURE__ */ new Set();
+  const broadcast = () => {
+    for (const res of clients) res.write(`event: rerun
+data: ${Date.now()}
+
+`);
+  };
+  const server = createServer2((req, res) => {
+    setCors(res);
+    res.setHeader("Cache-Control", "no-store");
+    const path = decodeURIComponent((req.url ?? "/").split("?")[0]);
+    if (path === EVENTS_ROUTE) {
+      handleSse(res, clients);
+    } else if (path === NAPPLET_PREFIX.slice(0, -1) || path.startsWith(NAPPLET_PREFIX)) {
+      void handleNapplet(res, nappletDir, path);
+    } else {
+      void handleApp(res, appDir, path);
+    }
+  });
+  await new Promise((r) => server.listen(options.port ?? 0, "127.0.0.1", r));
+  const { port } = server.address();
+  const origin = `http://127.0.0.1:${port}`;
+  const appUrl = `${origin}/?url=${encodeURIComponent(NAPPLET_PREFIX)}&live=1`;
+  const watcher = startWatcher(nappletDir, options.debounceMs ?? 120, broadcast);
+  return {
+    origin,
+    appUrl,
+    notify: broadcast,
+    close: () => new Promise((res, rej) => {
+      watcher.close();
+      for (const c of clients) c.end();
+      clients.clear();
+      server.close((err) => err ? rej(err) : res());
+    })
+  };
+}
+
+// src/scan.ts
+import { readdir, readFile as readFile3, stat as stat3 } from "fs/promises";
+import { join as join3, extname as extname3 } from "path";
+var FORBIDDEN = [
+  { label: "window.nostr", re: /\bwindow\s*\.\s*nostr\b/ },
+  { label: "globalThis.nostr", re: /\bglobalThis\s*\.\s*nostr\b/ }
+];
+var SCANNABLE = /* @__PURE__ */ new Set([".js", ".mjs", ".cjs", ".html", ".htm"]);
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".turbo", "coverage"]);
+async function collectFiles(dir, acc) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await collectFiles(join3(dir, entry.name), acc);
+    } else if (entry.isFile() && SCANNABLE.has(extname3(entry.name).toLowerCase())) {
+      acc.push(join3(dir, entry.name));
+    }
+  }
+}
+async function scanForbiddenGlobals(dir) {
+  const info = await stat3(dir).catch(() => null);
+  if (!info?.isDirectory()) return [];
+  const files = [];
+  await collectFiles(dir, files);
+  const found = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const text = await readFile3(file, "utf8").catch(() => "");
+    for (const { label, re } of FORBIDDEN) {
+      if (re.test(text)) found.add(label);
+    }
+  }
+  return [...found];
+}
+
+// src/cli.ts
+var HELP = `napplet-conformance \u2014 run NAP protocol conformance against a napplet
+
+Usage:
+  napplet-conformance [dir] [options]            # headless, one-shot, CI exit code
+  napplet-conformance --ui [dir] [options]       # open the live web runtime (like vitest --ui)
+  napplet-conformance --url https://my.napplet/ [options]
+
+Arguments:
+  dir                      Built napplet directory (looks for ./index.html or ./dist/index.html)
+
+Options:
+  --url <url>              Test a remotely-served napplet instead of a local dir (headless)
+  --reporter <fmt>         pretty | json | junit            (default: pretty)
+  --out <file>             Write the report to a file instead of stdout
+  --ready-timeout <ms>     Boot timeout waiting for shell.ready (default: 5000)
+  --settle <ms>            Envelope-collection window after boot (default: 600)
+  --no-degraded            Skip the no-capability graceful-degradation pass
+  --allow-same-origin      Debug: also grant allow-same-origin (a conformant napplet must not need it)
+
+UI / watch mode (--ui):
+  --port <n>               Port for the UI server (default: random)
+  --no-open                Do not open a browser automatically
+  --exec <cmd>             Run a command (e.g. "vite build --watch") so edits rebuild the served dir;
+                           the watcher then re-runs conformance live on every change
+  -h, --help               Show this help
+
+Exit codes (headless): 0 conformant, 1 non-conformant, 2 usage/runtime error.
+`;
+function parseArgs(argv) {
+  const opts = {
+    reporter: "pretty",
+    readyTimeoutMs: 5e3,
+    settleMs: 600,
+    runDegraded: true,
+    allowSameOrigin: false,
+    ui: false,
+    open: true,
+    help: false
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const value = () => {
+      const v = argv[i + 1];
+      if (v === void 0 || v.startsWith("--")) throw new Error(`Missing value for ${arg}`);
+      i += 1;
+      return v;
+    };
+    switch (arg) {
+      case "-h":
+      case "--help":
+        opts.help = true;
+        break;
+      case "--url":
+        opts.url = value();
+        break;
+      case "--reporter": {
+        const r = value();
+        if (r !== "pretty" && r !== "json" && r !== "junit") throw new Error(`Invalid reporter: ${r}`);
+        opts.reporter = r;
+        break;
+      }
+      case "--out":
+        opts.out = value();
+        break;
+      case "--ready-timeout":
+        opts.readyTimeoutMs = Number(value());
+        break;
+      case "--settle":
+        opts.settleMs = Number(value());
+        break;
+      case "--no-degraded":
+        opts.runDegraded = false;
+        break;
+      case "--allow-same-origin":
+        opts.allowSameOrigin = true;
+        break;
+      case "--ui":
+        opts.ui = true;
+        break;
+      case "--port":
+        opts.port = Number(value());
+        break;
+      case "--no-open":
+        opts.open = false;
+        break;
+      case "--exec":
+        opts.exec = value();
+        break;
+      default:
+        if (arg.startsWith("--")) throw new Error(`Unknown option: ${arg}`);
+        if (opts.target) throw new Error(`Unexpected extra argument: ${arg}`);
+        opts.target = arg;
+    }
+  }
+  return opts;
+}
+async function isFile(path) {
+  return (await stat4(path).catch(() => null))?.isFile() ?? false;
+}
+async function resolveNappletDir(target) {
+  const base = resolve3(target);
+  if (await isFile(join4(base, "index.html"))) return { dir: base, indexHtml: join4(base, "index.html") };
+  const dist = join4(base, "dist");
+  if (await isFile(join4(dist, "index.html"))) return { dir: dist, indexHtml: join4(dist, "index.html") };
+  throw new Error(`No index.html found in ${base} or ${dist}. Build the napplet first.`);
+}
+async function collectBoot(hostUrl, allowSameOrigin, totalTimeoutMs) {
+  const browser = await chromium.launch({ args: ["--no-sandbox"] });
+  try {
+    const page = await browser.newPage();
+    page.on("pageerror", (e) => process.stderr.write(`[host page error] ${e.message}
+`));
+    await page.goto(hostUrl, { waitUntil: "load" });
+    await page.waitForFunction(
+      () => window.__conformanceBoot__ !== void 0 || window.__conformanceError__ !== void 0,
+      void 0,
+      { timeout: totalTimeoutMs }
+    );
+    const error = await page.evaluate(() => window.__conformanceError__);
+    if (error) throw new Error(`Host harness failed: ${error}`);
+    const boot = await page.evaluate(() => window.__conformanceBoot__);
+    if (!boot) throw new Error("Host harness produced no result");
+    void allowSameOrigin;
+    return boot;
+  } finally {
+    await browser.close();
+  }
+}
+async function isDir(path) {
+  return (await stat4(path).catch(() => null))?.isDirectory() ?? false;
+}
+function openBrowser(url) {
+  try {
+    if (process.platform === "darwin") {
+      spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+    } else if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
+    } else {
+      spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+    }
+  } catch {
+  }
+}
+async function runUiMode(opts) {
+  if (opts.url) {
+    process.stderr.write("--ui serves a local napplet directory; --url is not supported in UI mode.\n");
+    return 2;
+  }
+  if (!opts.target) {
+    process.stderr.write(`Provide a napplet directory.
+
+${HELP}`);
+    return 2;
+  }
+  const resolved = await resolveNappletDir(opts.target);
+  const here = dirname(fileURLToPath(import.meta.url));
+  const appDir = join4(here, "ui");
+  if (!await isDir(appDir)) {
+    process.stderr.write(`Conformance UI assets are missing at ${appDir}. Rebuild @napplet/conformance-cli.
+`);
+    return 2;
+  }
+  const server = await startUiServer({ appDir, nappletDir: resolved.dir, port: opts.port });
+  const child = opts.exec ? spawn(opts.exec, { cwd: resolve3(opts.target), shell: true, stdio: "inherit" }) : null;
+  process.stdout.write(
+    `
+  napplet conformance UI  \u2192  ${server.appUrl}
+  watching  ${resolved.dir}${opts.exec ? `  (running: ${opts.exec})` : ""}
+  Ctrl-C to stop
+
+`
+  );
+  if (opts.open) openBrowser(server.appUrl);
+  await new Promise((resolveWait) => {
+    let closing = false;
+    const shutdown = () => {
+      if (closing) return;
+      closing = true;
+      child?.kill();
+      void server.close().finally(resolveWait);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
+  return 0;
+}
+async function main(argv) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+
+${HELP}`);
+    return 2;
+  }
+  if (opts.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (opts.ui) {
+    return runUiMode(opts);
+  }
+  let nappletDir = null;
+  let manifestHtml;
+  let forbiddenGlobals = [];
+  let bootUrl;
+  if (opts.url) {
+    bootUrl = opts.url;
+    manifestHtml = await (await fetch(opts.url)).text();
+  } else {
+    if (!opts.target) {
+      process.stderr.write(`Provide a napplet directory or --url.
+
+${HELP}`);
+      return 2;
+    }
+    const resolved = await resolveNappletDir(opts.target);
+    nappletDir = resolved.dir;
+    manifestHtml = await readFile4(resolved.indexHtml, "utf8");
+    forbiddenGlobals = await scanForbiddenGlobals(resolved.dir);
+    bootUrl = "/";
+  }
+  const here = dirname(fileURLToPath(import.meta.url));
+  const hostBundle = await readFile4(join4(here, "host-bundle.global.js"), "utf8");
+  const server = await startHarnessServer({
+    nappletDir,
+    hostBundle,
+    bootConfig: {
+      url: bootUrl,
+      readyTimeoutMs: opts.readyTimeoutMs,
+      settleMs: opts.settleMs,
+      runDegraded: opts.runDegraded
+    }
+  });
+  let boot;
+  try {
+    const totalTimeout = (opts.readyTimeoutMs + opts.settleMs) * 2 + 3e4;
+    boot = await collectBoot(server.hostUrl, opts.allowSameOrigin, totalTimeout);
+  } finally {
+    await server.close();
+  }
+  const context = buildContext({ manifestHtml, boot, forbiddenGlobals });
+  const run = runConformance(context);
+  const output = report(run, opts.reporter);
+  if (opts.out) {
+    await writeFile(opts.out, `${output}
+`, "utf8");
+    process.stdout.write(`Report written to ${opts.out}
+`);
+  } else {
+    process.stdout.write(`${output}
+`);
+  }
+  return run.ok ? 0 : 1;
+}
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  process.stderr.write(`napplet-conformance: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`);
+  process.exitCode = 2;
+});
+//# sourceMappingURL=cli.js.map