@olomonhelpdesk2/helpdesk 0.1.3 → 0.1.4

package/helpdesk-capture.mjs

@@ -21,6 +21,16 @@ var CAPTURE_CONTRACT = {
   maxClipBytes: 2 * 1024 * 1024,
   /** Everything renders as though it were this instant. */
   pinnedClock: "2026-01-15T09:00:00.000Z",
+  /**
+   * And in this locale and this zone, set on the browser rather than inherited
+   * from whoever runs it, so a date on a screen reads the same from any machine.
+   *
+   * American English, because the products this documents are read in it: a
+   * frame showing "15/01/2026" beside an article written for an American
+   * reader is a screenshot of a product nobody uses.
+   */
+  locale: "en-US",
+  timezone: "UTC",
   /**
    * Injected before every shot. Necessary, not sufficient — see above.
    */
@@ -87,6 +97,108 @@ function captureReport(outcomes) {
   return { ready: ready.length, needData: actionable.length, lines };
 }
 
+// core/capture/examples.ts
+var CI_EXAMPLES_OUT_ENV = "HELPDESK_EXAMPLES_OUT";
+var EXAMPLES_SCHEMA = "helpdesk.examples/1";
+var MAX_PATH = 2048;
+var MAX_ROUTES = 500;
+function segmentsOf(path3) {
+  return path3.split("/").filter((part) => part !== "");
+}
+function patternOf(route) {
+  return segmentsOf(route).map((part) => {
+    const optional = /^\[\[\.\.\.([^\]]+)\]\]$/.exec(part);
+    if (optional) return { kind: "any", name: optional[1] };
+    const catchAll = /^\[\.\.\.([^\]]+)\]$/.exec(part);
+    if (catchAll) return { kind: "many", name: catchAll[1] };
+    const one = /^\[([^\]]+)\]$/.exec(part);
+    if (one) return { kind: "one", name: one[1] };
+    return { kind: "static", text: part };
+  });
+}
+function dynamicSegments(route) {
+  return patternOf(route).filter((segment) => segment.kind !== "static").map((segment) => segment.name);
+}
+function fillsPattern(pattern, path3) {
+  const want = patternOf(pattern);
+  const have = segmentsOf(path3);
+  const match = (w, h) => {
+    if (w === want.length) return h === have.length;
+    const segment = want[w];
+    if (segment.kind === "static") return have[h] === segment.text && match(w + 1, h + 1);
+    if (segment.kind === "one") return h < have.length && match(w + 1, h + 1);
+    const least = segment.kind === "many" ? 1 : 0;
+    for (let take = have.length - h; take >= least; take -= 1) {
+      if (match(w + 1, h + take)) return true;
+    }
+    return false;
+  };
+  return match(0, 0);
+}
+function unusablePath(path3) {
+  if (path3.length > MAX_PATH) return "the path is longer than any screen's";
+  if (!path3.startsWith("/") || path3.startsWith("//")) return "the path is not a path inside the product";
+  if (/[?#\\]/.test(path3)) return "the path carries a query, a fragment or a backslash";
+  if (/\s/.test(path3) || [...path3].some((character) => character.charCodeAt(0) < 32)) {
+    return "the path carries whitespace or a control character";
+  }
+  const segments = segmentsOf(path3);
+  if (segments.some((segment) => segment === "." || segment === ".." || /%2e%2e|%2f|%5c/i.test(segment))) {
+    return "the path climbs out of its position";
+  }
+  if (/\[|\]/.test(path3)) return "the path still holds a dynamic segment rather than a record";
+  return void 0;
+}
+function readExampleRoutes(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, because: "the file is not a JSON object" };
+  }
+  const body = raw;
+  if (body["schema"] !== EXAMPLES_SCHEMA) {
+    return { ok: false, because: `the file does not say "schema": "${EXAMPLES_SCHEMA}"` };
+  }
+  const routes = body["routes"];
+  if (typeof routes !== "object" || routes === null || Array.isArray(routes)) {
+    return { ok: false, because: 'the file has no "routes" object' };
+  }
+  const entries = Object.entries(routes);
+  if (entries.length > MAX_ROUTES) return { ok: false, because: `the file names more than ${MAX_ROUTES} routes` };
+  const paths = /* @__PURE__ */ new Map();
+  const refused = [];
+  for (const [route, value] of entries) {
+    if (!route.startsWith("/") || dynamicSegments(route).length === 0) {
+      refused.push({ route, because: "it is not a route with a dynamic segment" });
+      continue;
+    }
+    if (typeof value !== "string") {
+      refused.push({ route, because: "its example is not a path" });
+      continue;
+    }
+    const path3 = value.trim();
+    const unusable = unusablePath(path3);
+    if (unusable) {
+      refused.push({ route, because: unusable });
+      continue;
+    }
+    if (!fillsPattern(route, path3)) {
+      refused.push({ route, because: `${path3} is not ${route} with its dynamic segments filled in` });
+      continue;
+    }
+    paths.set(route, path3);
+  }
+  return { ok: true, examples: { paths, refused } };
+}
+function resolveVisit(route, examples) {
+  const needs = dynamicSegments(route);
+  if (needs.length === 0) return { visit: route };
+  const path3 = examples.paths.get(route);
+  return path3 ? { visit: path3 } : { needs };
+}
+function describeMissingExample(route, needs) {
+  const named = needs.map((name) => `[${name}]`).join(" and ");
+  return `the seed command named no record for ${named} on ${route}, so there is nothing real to open. Add one to the file it writes at ${CI_EXAMPLES_OUT_ENV}`;
+}
+
 // core/cli-package.ts
 var HELPDESK_CLI_PACKAGE = "@olomonhelpdesk2/helpdesk";
 function helpdeskCommand(command, args = []) {
@@ -1438,10 +1550,14 @@ async function runCapture(options) {
   };
 }
 async function captureOne(options, shot, build) {
+  if (shot.unvisitable) {
+    return { outcome: { shotId: shot.id, route: shot.route, status: "skipped", reason: shot.unvisitable } };
+  }
+  const visit = shot.visit ?? shot.route;
   let page;
   try {
     page = await options.browser.page();
-    await page.goto(new URL(shot.route, options.baseUrl).toString());
+    await page.goto(new URL(visit, options.baseUrl).toString());
     if (await page.isSignIn()) {
       return {
         outcome: {
@@ -1478,7 +1594,7 @@ async function captureOne(options, shot, build) {
       };
     }
     const seen = await page.observe?.() ?? {};
-    const observed = classifyRoute({ ...seen, route: shot.route, text: pageText });
+    const observed = { ...classifyRoute({ ...seen, route: visit, text: pageText }), route: shot.route };
     if (!isPublishable(observed.result)) {
       return {
         outcome: {
@@ -1491,7 +1607,7 @@ async function captureOne(options, shot, build) {
         observed
       };
     }
-    const evidence = await readEvidence(settledPage, shot.route, options, build);
+    const evidence = await readEvidence(settledPage, shot.route, options, build, visit);
     const reading = options.clearance ? await readScreen(settledPage, options.clearance) : void 0;
     if (options.clearance && !reading) {
       return {
@@ -1660,9 +1776,9 @@ async function captureOne(options, shot, build) {
     await page?.close().catch(() => void 0);
   }
 }
-async function readEvidence(page, route, options, build) {
+async function readEvidence(page, route, options, build, visited = route) {
   if (!options.commit || !options.repository || !options.session || !build) return void 0;
-  const url = new URL(route, options.baseUrl).toString();
+  const url = new URL(visited, options.baseUrl).toString();
   const html = await page.html?.().catch(() => "");
   const aria = await page.aria?.().catch(() => "");
   if (!html && !aria) return void 0;
@@ -1734,8 +1850,8 @@ async function playwrightBrowser(options = {}) {
     // Pinned as well as the clock. A date formatted in the runner's own zone
     // renders differently in London and in Denver, which makes a frame depend
     // on who took it.
-    timezoneId: "UTC",
-    locale: "en-GB",
+    timezoneId: CAPTURE_CONTRACT.timezone,
+    locale: CAPTURE_CONTRACT.locale,
     /**
      * A session, when one is supplied — and only ever from a file on the
      * machine running this.
@@ -2351,15 +2467,21 @@ Something else is already answering on ${options.appUrl}. That is almost always
   };
 }
 var SESSION_OUT_ENV = CI_SESSION_OUT_ENV;
+var EXAMPLES_OUT_ENV = CI_EXAMPLES_OUT_ENV;
 async function stageSeeded(options) {
   const onLog = options.onLog;
   const { access, unlink } = await import("node:fs/promises");
   await unlink(options.sessionOut).catch(() => void 0);
+  if (options.examplesOut) await unlink(options.examplesOut).catch(() => void 0);
   onLog?.(`Seeding a demo tenant with ${options.seedCommand}`);
   const seeded = await runToCompletion(
     options.seedCommand,
     options.seedMs ?? 6e5,
-    { [CI_SESSION_OUT_ENV]: options.sessionOut, [CI_BASE_URL_ENV]: options.appUrl },
+    {
+      [CI_SESSION_OUT_ENV]: options.sessionOut,
+      [CI_BASE_URL_ENV]: options.appUrl,
+      ...options.examplesOut ? { [CI_EXAMPLES_OUT_ENV]: options.examplesOut } : {}
+    },
     onLog
   );
   if (!seeded.ok) {
@@ -2377,6 +2499,7 @@ Nothing has been photographed. A run that carried on from here would sign in to
   onLog?.(
     sessionPath ? `The seed command left a session at ${sessionPath}, so the screens behind your login can be photographed.` : `The seed command wrote no session to ${SESSION_OUT_ENV}. Only the screens a signed-out visitor can reach will be photographed.`
   );
+  const examples = options.examplesOut ? await examplesFrom(options.examplesOut, onLog) : void 0;
   let app;
   let died;
   if (options.appCommand) {
@@ -2413,11 +2536,38 @@ Something else is already answering on ${options.appUrl}, which is almost always
   return {
     appUrl: options.appUrl,
     ...sessionPath ? { sessionPath } : {},
+    ...examples ? { examples } : {},
     close: async () => {
       stop(app);
     }
   };
 }
+async function examplesFrom(path3, onLog) {
+  const { readFile: readFile2 } = await import("node:fs/promises");
+  let text2;
+  try {
+    text2 = await readFile2(path3, "utf8");
+  } catch {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text2);
+  } catch {
+    onLog?.(`The seed command wrote ${EXAMPLES_OUT_ENV}, but it is not JSON, so no screen with an id in its address will be opened.`);
+    return void 0;
+  }
+  const reading = readExampleRoutes(parsed);
+  if (!reading.ok) {
+    onLog?.(`The seed command wrote ${EXAMPLES_OUT_ENV}, but ${reading.because}, so no screen with an id in its address will be opened.`);
+    return void 0;
+  }
+  onLog?.(
+    `The seed command named a record for ${reading.examples.paths.size} screen(s) with an id in the address.`
+  );
+  for (const refused of reading.examples.refused) onLog?.(`  not using ${refused.route}: ${refused.because}`);
+  return reading.examples;
+}
 async function runToCompletion(command, timeoutMs, env, onLog) {
   return new Promise((resolve) => {
     const child = spawn(command, {
@@ -2920,6 +3070,13 @@ function shotsFromRepo(repo, previous) {
     ...previous.has(step.shotId) ? { sha256: previous.get(step.shotId) } : {}
   }));
 }
+function withExamples(shots, examples) {
+  return shots.map((shot) => {
+    const resolved = resolveVisit(shot.route, examples);
+    if ("needs" in resolved) return { ...shot, unvisitable: describeMissingExample(shot.route, resolved.needs) };
+    return resolved.visit === shot.route ? shot : { ...shot, visit: resolved.visit };
+  });
+}
 async function previousFrames(out) {
   try {
     const manifest = JSON.parse(await readFile(path2.join(out, "manifest.json"), "utf8"));
@@ -2988,6 +3145,7 @@ Approve one on the plan page, then run this again.`
         seedCommand: parsed.seedCommand,
         ...parsed.appCommand ? { appCommand: parsed.appCommand } : {},
         sessionOut: parsed.session ?? path2.join(process.cwd(), "helpdesk-demo-session.json"),
+        examplesOut: path2.join(process.cwd(), "helpdesk-examples.json"),
         onLog: (line) => console.log(line)
       });
       if (seeded.sessionPath) parsed.session = seeded.sessionPath;
@@ -2998,6 +3156,7 @@ Approve one on the plan page, then run this again.`
       return 1;
     }
   }
+  const planned = seeded?.examples ? withExamples(shots, seeded.examples) : shots;
   if (parsed.cassette) {
     try {
       stage = await stageAgainstRecording({
@@ -3022,8 +3181,8 @@ Approve one on the plan page, then run this again.`
     baseUrl,
     browser: await browser.build?.().catch(() => void 0),
     clockPinned: !parsed.liveClock,
-    locale: "en-GB",
-    timezone: "UTC",
+    locale: CAPTURE_CONTRACT.locale,
+    timezone: CAPTURE_CONTRACT.timezone,
     session: Boolean(parsed.session),
     ...stage ? { replaying: parsed.cassette } : {},
     ...parsed.allowProduction ? { productionGranted: true } : {},
@@ -3054,7 +3213,7 @@ Approve one on the plan page, then run this again.`
   try {
     const report = await runCapture({
       baseUrl,
-      shots,
+      shots: planned,
       browser,
       ...orders.capture ? {
         clearance: {
@@ -3310,5 +3469,6 @@ if (runningAsCommand(import.meta.url)) {
   );
 }
 export {
-  main
+  main,
+  withExamples
 };

package/helpdesk-seed.mjs

@@ -981,6 +981,16 @@ var CAPTURE_CONTRACT = {
   maxClipBytes: 2 * 1024 * 1024,
   /** Everything renders as though it were this instant. */
   pinnedClock: "2026-01-15T09:00:00.000Z",
+  /**
+   * And in this locale and this zone, set on the browser rather than inherited
+   * from whoever runs it, so a date on a screen reads the same from any machine.
+   *
+   * American English, because the products this documents are read in it: a
+   * frame showing "15/01/2026" beside an article written for an American
+   * reader is a screenshot of a product nobody uses.
+   */
+  locale: "en-US",
+  timezone: "UTC",
   /**
    * Injected before every shot. Necessary, not sufficient — see above.
    */

package/helpdesk.mjs

@@ -519,8 +519,17 @@ function baseUrlFromTsconfig(tsconfig) {
 }
 
 // core/discovery/screen-facts.ts
-function noScreenFacts() {
-  return { headings: [], actions: [], links: [], fields: [], notices: [], warnings: [], readFrom: [] };
+function noScreenFacts(read) {
+  return {
+    headings: [],
+    actions: [],
+    links: [],
+    fields: [],
+    notices: [],
+    warnings: [],
+    readFrom: [],
+    ...read ? { read } : {}
+  };
 }
 var LIMITS = {
   headings: 12,

package/package.json

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