@olomonhelpdesk2/helpdesk 0.1.0 → 0.1.2

package/helpdesk-capture.mjs

@@ -65,8 +65,8 @@ function actionFor(outcome) {
       return `${outcome.route} asked for ${outcome.missingEndpoint ?? "data"}, which is not in the recording. Visit this screen while recording, then run this again.`;
   }
 }
-function subjectOf(path2) {
-  const segments = path2.split("/").filter(Boolean).filter((segment) => !/^(api|v\d+)$/.test(segment));
+function subjectOf(path3) {
+  const segments = path3.split("/").filter(Boolean).filter((segment) => !/^(api|v\d+)$/.test(segment));
   while (segments.length > 1 && looksLikeAnId(segments[segments.length - 1])) segments.pop();
   const last = segments[segments.length - 1] ?? "record";
   return last.replace(/[-_]/g, " ").replace(/s$/, "");
@@ -172,11 +172,11 @@ function canonicalisation(asked, landed) {
 function samePlace(asked, landed) {
   return stripQuery(asked) === stripQuery(landed);
 }
-function stripQuery(path2) {
-  return path2.split(/[?#]/)[0] ?? path2;
+function stripQuery(path3) {
+  return path3.split(/[?#]/)[0] ?? path3;
 }
-function normalise(path2) {
-  return stripQuery(path2).toLowerCase().replace(/\/index(\.html?)?$/, "/").replace(/\/+$/, "").replace(/^$/, "/");
+function normalise(path3) {
+  return stripQuery(path3).toLowerCase().replace(/\/index(\.html?)?$/, "/").replace(/\/+$/, "").replace(/^$/, "/");
 }
 function firstSentence(text2) {
   const sentence = text2.trim().split(/(?<=[.!?])\s|\n/)[0] ?? text2;
@@ -304,6 +304,11 @@ function attestation(run) {
   ].filter(Boolean).join("\n");
 }
 
+// adapters/capture-cli.ts
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
 // core/capture/scrub.ts
 var BRANDS = [
   "Chase",
@@ -1991,17 +1996,51 @@ async function captureSignIn(options) {
     await browser.close();
   }
 }
+async function resolveFrom(directory, specifier) {
+  const resolve = createRequire(path.join(directory, "package.json"));
+  return import(
+    /* webpackIgnore: true */
+    pathToFileURL(resolve.resolve(specifier)).href
+  );
+}
 async function loadPlaywright() {
   const specifier = "playwright-core";
-  try {
-    return await import(
+  const given = process.env["CAPTURE_PLAYWRIGHT"];
+  const sources = [
+    ...given ? [() => resolveFrom(given, specifier)] : [],
+    // Beside this file, which covers a local devDependency and a bundled copy.
+    () => import(
       /* webpackIgnore: true */
       specifier
-    );
+    ),
+    // From the repository being photographed, which covers an npx invocation
+    // in a project that already has Playwright. Many do: the capture rig
+    // detector exists because so many repositories already drive a browser.
+    () => resolveFrom(process.cwd(), specifier)
+  ];
+  for (const source of sources) {
+    try {
+      const loaded = await source();
+      const chromium = loaded.chromium ?? loaded.default?.chromium;
+      if (chromium) return { chromium };
+    } catch {
+    }
+  }
+  throw new Error(
+    "Capture needs Playwright. Install it in the repository you are photographing with `npm i -D playwright-core`, or point CAPTURE_PLAYWRIGHT at a copy, and make sure a Chrome is available (set CAPTURE_CHROME to its path if it is not on the default one)."
+  );
+}
+
+// adapters/invoked-as-command.ts
+import { realpathSync } from "node:fs";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
+function runningAsCommand(moduleUrl) {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return moduleUrl === pathToFileURL2(realpathSync(invoked)).href;
   } catch {
-    throw new Error(
-      "Capture needs Playwright. Install it beside this command with `npm i -D playwright-core` and make sure a Chrome is available (set CAPTURE_CHROME to its path if it is not on the default one)."
-    );
+    return false;
   }
 }
 
@@ -2032,7 +2071,7 @@ function looksLikeIdentifier(segment) {
   return /\d/.test(segment) && segment.length >= 3;
 }
 function templatise(paths) {
-  const split = paths.map((path2) => path2.split("/").filter(Boolean));
+  const split = paths.map((path3) => path3.split("/").filter(Boolean));
   const depth2 = Math.max(0, ...split.map((segments) => segments.length));
   const parameters = /* @__PURE__ */ new Set();
   const prefixOf = (segments, upTo) => {
@@ -2135,9 +2174,9 @@ var CassetteIndex = class {
     return void 0;
   }
 };
-function matchesTemplate(template, path2) {
+function matchesTemplate(template, path3) {
   const wanted = template.split("/").filter(Boolean);
-  const actual = path2.split("/").filter(Boolean);
+  const actual = path3.split("/").filter(Boolean);
   if (wanted.length !== actual.length) return false;
   return wanted.every((segment, index) => segment.startsWith(":") || segment === actual[index]);
 }
@@ -2168,10 +2207,10 @@ function shut(server) {
   });
 }
 function splitUrl(url) {
-  const [path2, search] = url.split("?");
+  const [path3, search] = url.split("?");
   const query = {};
   for (const [name, value] of new URLSearchParams(search ?? "")) query[name] = value;
-  return { path: path2 ?? "/", query };
+  return { path: path3 ?? "/", query };
 }
 async function replayFrom(options) {
   const index = new CassetteIndex(options.cassette);
@@ -2179,14 +2218,14 @@ async function replayFrom(options) {
   const served = /* @__PURE__ */ new Set();
   const server = createServer((incoming, outgoing) => {
     void (async () => {
-      const { path: path2, query } = splitUrl(incoming.url ?? "/");
+      const { path: path3, query } = splitUrl(incoming.url ?? "/");
       await bodyOf(incoming);
-      const found = index.find({ method: incoming.method ?? "GET", path: path2, query });
+      const found = index.find({ method: incoming.method ?? "GET", path: path3, query });
       if (!found) {
         const from = incoming.headers["referer"] ?? incoming.headers["x-seed-page"];
         const miss = {
           method: incoming.method ?? "GET",
-          path: path2,
+          path: path3,
           ...Object.keys(query).length ? { query } : {},
           ...typeof from === "string" ? { from: pageOf(from) } : {}
         };
@@ -2422,8 +2461,8 @@ function gapsFrom(misses, cassette) {
   const templates = templatise([...known, ...misses.map((miss) => miss.path)]);
   const grouped = /* @__PURE__ */ new Map();
   for (const miss of misses) {
-    const path2 = templates.get(miss.path) ?? miss.path;
-    const key = interactionKey({ method: miss.method, path: path2, ...miss.query ? { query: miss.query } : {} });
+    const path3 = templates.get(miss.path) ?? miss.path;
+    const key = interactionKey({ method: miss.method, path: path3, ...miss.query ? { query: miss.query } : {} });
     const existing = grouped.get(key);
     if (existing) {
       existing.asked += 1;
@@ -2432,7 +2471,7 @@ function gapsFrom(misses, cassette) {
     }
     grouped.set(key, {
       method: miss.method.toUpperCase(),
-      path: path2,
+      path: path3,
       asked: 1,
       broke: miss.from ? [miss.from] : [],
       example: miss.path
@@ -2502,7 +2541,7 @@ function coverageReport(found, total) {
 
 // adapters/capture-bin.ts
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
+import path2 from "node:path";
 
 // adapters/map-cli.ts
 import { execFileSync } from "node:child_process";
@@ -2515,14 +2554,14 @@ var ROUTE_GROUP = /^\((.+)\)$/;
 var DYNAMIC = /^\[{1,2}(\.{3})?(.+?)\]{1,2}$/;
 var PARALLEL = /^@/;
 var INTERCEPTING = /^\(\.+\)/;
-function classify(path2) {
-  if (path2 === "/api" || path2.startsWith("/api/")) {
+function classify(path3) {
+  if (path3 === "/api" || path3.startsWith("/api/")) {
     return { skipped: "not-html", note: "an API route, not a screen" };
   }
-  if (/(^|\/)(admin|internal|debug|_dev)(\/|$)/.test(path2)) {
+  if (/(^|\/)(admin|internal|debug|_dev)(\/|$)/.test(path3)) {
     return { skipped: "internal-tooling", note: "internal tooling" };
   }
-  if (/(^|\/)(login|logout|signin|sign-in|signup|sign-up|auth|verify|reset-password)(\/|$)/.test(path2)) {
+  if (/(^|\/)(login|logout|signin|sign-in|signup|sign-up|auth|verify|reset-password)(\/|$)/.test(path3)) {
     return { skipped: "unauthenticated-flow", note: "an authentication step" };
   }
   return void 0;
@@ -2626,8 +2665,8 @@ function enclosingLayouts(pageFile, layouts) {
   const dir = pageFile.slice(0, pageFile.lastIndexOf("/"));
   return layouts.filter((layout) => dir.startsWith(layout.slice(0, layout.lastIndexOf("/")))).sort((a, b) => a.length - b.length);
 }
-function depth(path2) {
-  return path2 === "/" ? 0 : path2.split("/").filter(Boolean).length;
+function depth(path3) {
+  return path3 === "/" ? 0 : path3.split("/").filter(Boolean).length;
 }
 
 // core/discovery/article-plan.ts
@@ -2664,8 +2703,8 @@ var ENTRY_POINT = /* @__PURE__ */ new Set([
   "integration",
   "integrations"
 ]);
-function hasSegment(path2, vocabulary) {
-  return path2.split("/").filter(Boolean).some((segment) => vocabulary.has(segment.toLowerCase()));
+function hasSegment(path3, vocabulary) {
+  return path3.split("/").filter(Boolean).some((segment) => vocabulary.has(segment.toLowerCase()));
 }
 function score(route, signals) {
   const because = [];
@@ -2704,8 +2743,8 @@ function tierFor(rank, count) {
   if (rank <= Math.max(16, Math.ceil(count * 0.6))) return "supporting";
   return "minor";
 }
-function slugFor(path2) {
-  const segments = path2.split("/").filter(Boolean).filter((segment) => !segment.startsWith("["));
+function slugFor(path3) {
+  const segments = path3.split("/").filter(Boolean).filter((segment) => !segment.startsWith("["));
   return segments.length ? segments.join("/") : "overview";
 }
 function titleFor(route) {
@@ -2764,7 +2803,7 @@ function buildArticlePlan(options) {
   let covered = 0;
   const needs = [...merged.entries()].map(([slug, group], index) => {
     const rank = index + 1;
-    const claimed = [group.entry.route.path, ...group.routes.slice(1) ?? []].map((path2) => options.documented?.[path2]).find(Boolean);
+    const claimed = [group.entry.route.path, ...group.routes.slice(1) ?? []].map((path3) => options.documented?.[path3]).find(Boolean);
     const already = existing.has(slug) || Boolean(claimed);
     if (already) covered += 1;
     return {
@@ -2808,7 +2847,7 @@ function buildStoryboard(options) {
   const beneath = options.routes.filter(
     (route) => !covered.has(route.path) && !route.skipped && [...covered].some((base) => base !== "/" && route.path.startsWith(`${base}/`))
   );
-  const ordered = [...covered].map((path2) => byPath.get(path2)).filter((route) => Boolean(route) && !route.skipped).sort((a, b) => a.path.length - b.path.length).concat(beneath.sort((a, b) => a.path.length - b.path.length));
+  const ordered = [...covered].map((path3) => byPath.get(path3)).filter((route) => Boolean(route) && !route.skipped).sort((a, b) => a.path.length - b.path.length).concat(beneath.sort((a, b) => a.path.length - b.path.length));
   const limit = options.maxSteps ?? 5;
   const steps = ordered.slice(0, limit).map((route, index) => ({
     route: route.path,
@@ -2883,7 +2922,7 @@ function shotsFromRepo(repo, previous) {
 }
 async function previousFrames(out) {
   try {
-    const manifest = JSON.parse(await readFile(path.join(out, "manifest.json"), "utf8"));
+    const manifest = JSON.parse(await readFile(path2.join(out, "manifest.json"), "utf8"));
     return new Map((manifest.frames ?? []).map((frame) => [frame.id, frame.sha256]));
   } catch {
     return /* @__PURE__ */ new Map();
@@ -2948,7 +2987,7 @@ Approve one on the plan page, then run this again.`
         appUrl: baseUrl,
         seedCommand: parsed.seedCommand,
         ...parsed.appCommand ? { appCommand: parsed.appCommand } : {},
-        sessionOut: parsed.session ?? path.join(process.cwd(), "helpdesk-demo-session.json"),
+        sessionOut: parsed.session ?? path2.join(process.cwd(), "helpdesk-demo-session.json"),
         onLog: (line) => console.log(line)
       });
       if (seeded.sessionPath) parsed.session = seeded.sessionPath;
@@ -3058,7 +3097,7 @@ Approve one on the plan page, then run this again.`
       async send(frame) {
         if (local) {
           const file = `${frame.shot.id}.png`;
-          await writeFile(path.join(local, file), frame.image);
+          await writeFile(path2.join(local, file), frame.image);
           frames.push({
             id: frame.shot.id,
             route: frame.shot.route,
@@ -3121,7 +3160,7 @@ ${report.captured} photographed, ${report.unchanged} unchanged, ${report.skipped
         });
       }
       await writeFile(
-        path.join(local, "manifest.json"),
+        path2.join(local, "manifest.json"),
         `${JSON.stringify(
           {
             schema: "olomon.capture-manifest/1",
@@ -3261,7 +3300,7 @@ The session will be saved to ${sessionPath} and sent nowhere.
 Saved ${sessionPath}. Pass it to a capture run with --session ${sessionPath}.`);
   return 0;
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (runningAsCommand(import.meta.url)) {
   main(process.argv.slice(2)).then(
     (code) => process.exit(code),
     (error) => {

package/helpdesk-seed.mjs

@@ -10,6 +10,19 @@ function helpdeskCommand(command, args = []) {
   return parts.join(" ");
 }
 
+// adapters/invoked-as-command.ts
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+function runningAsCommand(moduleUrl) {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return moduleUrl === pathToFileURL(realpathSync(invoked)).href;
+  } catch {
+    return false;
+  }
+}
+
 // core/seed/cassette.ts
 var CASSETTE_SCHEMA = "olomon.seed-cassette/1";
 var DROP_HEADERS = /* @__PURE__ */ new Set([
@@ -1367,6 +1380,15 @@ async function routes(args) {
 function missFile(cassette) {
   return cassette.replace(/\.json$/, "") + ".misses.json";
 }
+if (runningAsCommand(import.meta.url)) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  );
+}
 export {
   carriedReport,
   main

package/helpdesk.mjs

@@ -1067,6 +1067,19 @@ function originOf(cwd) {
   }
 }
 
+// adapters/invoked-as-command.ts
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+function runningAsCommand(moduleUrl) {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return moduleUrl === pathToFileURL(realpathSync(invoked)).href;
+  } catch {
+    return false;
+  }
+}
+
 // adapters/map-bin.ts
 function arg(name) {
   const index = process.argv.indexOf(`--${name}`);
@@ -1091,7 +1104,9 @@ async function main() {
   });
   console.log(result.report);
 }
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+if (runningAsCommand(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olomonhelpdesk2/helpdesk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Reads a product's screens, plans its help articles, and photographs them.",
   "type": "module",
   "engines": {