@olomonhelpdesk2/helpdesk 0.1.5 → 0.1.9

package/helpdesk-capture.mjs

@@ -51,6 +51,18 @@ function unusablePath(path3) {
   if (/\[|\]/.test(path3)) return "the path still holds a dynamic segment rather than a record";
   return void 0;
 }
+var PLAIN_QUERY = /^[\w.~%:+,-]+=[\w.~%:+,-]*(?:&[\w.~%:+,-]+=[\w.~%:+,-]*)*$/;
+function queryFor(route, named) {
+  const mark = named.indexOf("?");
+  const path3 = mark < 0 ? named : named.slice(0, mark);
+  const query = mark < 0 ? "" : named.slice(mark + 1);
+  if (!query) return { because: "it has no dynamic segment, so the only thing to name for it is the query it opens with" };
+  if (path3 !== route) return { because: `${named} is not ${route} with a query` };
+  const unusable = unusablePath(route);
+  if (unusable) return { because: unusable };
+  if (named.length > MAX_PATH || !PLAIN_QUERY.test(query)) return { because: "the query is not a plain list of names and values" };
+  return { visit: named };
+}
 function readExampleRoutes(raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     return { ok: false, because: "the file is not a JSON object" };
@@ -68,14 +80,20 @@ function readExampleRoutes(raw) {
   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" });
+    if (!route.startsWith("/")) {
+      refused.push({ route, because: "it is not a route" });
       continue;
     }
     if (typeof value !== "string") {
       refused.push({ route, because: "its example is not a path" });
       continue;
     }
+    if (dynamicSegments(route).length === 0) {
+      const opened = queryFor(route, value.trim());
+      if ("because" in opened) refused.push({ route, because: opened.because });
+      else paths.set(route, opened.visit);
+      continue;
+    }
     const path3 = value.trim();
     const unusable = unusablePath(path3);
     if (unusable) {
@@ -92,8 +110,8 @@ function readExampleRoutes(raw) {
 }
 function resolveVisit(route, examples) {
   const needs = dynamicSegments(route);
-  if (needs.length === 0) return { visit: route };
   const path3 = examples.paths.get(route);
+  if (needs.length === 0) return { visit: path3 ?? route };
   return path3 ? { visit: path3 } : { needs };
 }
 function describeMissingExample(route, needs) {
@@ -165,7 +183,7 @@ function actionFor(outcome) {
       return void 0;
     case "not-found": {
       if ((!outcome.missingEndpoint || outcome.missingEndpoint === outcome.route) && !outcome.route.includes("[")) {
-        return `${outcome.route} answered Not Found here, and its address names no record to create. If it is behind a feature flag, turn the flag on where the run happens; if it is gone, it will drop out of the plan.`;
+        return `${outcome.route} answered Not Found here, and its address names no record to create. If it is behind a feature flag, turn the flag on where the run happens. If it opens only from a record, as a form started from one does, name the address it opens at in the file the seed command writes at ${CI_EXAMPLES_OUT_ENV}. If it is gone, it will drop out of the plan.`;
       }
       const asked = outcome.missingEndpoint ?? outcome.route;
       const noun = subjectOf(fillsPattern(outcome.route, asked) ? outcome.route : asked);
@@ -340,40 +358,40 @@ function preflight(facts) {
       name: "target",
       ok: true,
       blocking: false,
-      detail: `${facts.baseUrl}, reading from ${facts.replaying} \u2014 no live backend is reachable from this run, so nothing on these screens can be a real person's`
+      detail: `${facts.baseUrl}, reading from ${facts.replaying}. No live backend is reachable from this run, so nothing on these screens can be a real person's`
     });
   } else if (facts.session && live && !facts.productionGranted) {
     checks.push({
       name: "target",
       ok: false,
       blocking: true,
-      detail: `${facts.baseUrl} does not look like a demo or staging address, and this run has a session. A help article shows the typical state of a screen, not somebody's data \u2014 point this at a demo tenant, or pass --allow-production if that address really is the seeded one.`
+      detail: `${facts.baseUrl} does not look like a demo or staging address, and this run has a session. A help article shows the typical state of a screen, not somebody's data. Point this at a demo tenant, or pass --allow-production if that address really is the seeded one.`
     });
   } else {
     checks.push({
       name: "target",
       ok: true,
       blocking: false,
-      detail: facts.session ? `${facts.baseUrl}, signed in${live ? " \u2014 accepted as seeded by --allow-production" : " as a demo tenant"}` : `${facts.baseUrl}, signed in as nobody`
+      detail: facts.session ? `${facts.baseUrl}, signed in${live ? ", accepted as seeded by --allow-production" : " as a demo tenant"}` : `${facts.baseUrl}, signed in as nobody`
     });
   }
   checks.push({
     name: "browser",
     ok: Boolean(facts.browser),
     blocking: false,
-    detail: facts.browser ? `${facts.browser}, recorded on every frame` : "not identified \u2014 a browser upgrade will look like the product changing"
+    detail: facts.browser ? `${facts.browser}, recorded on every frame` : "not identified. A browser upgrade will look like the product changing"
   });
   checks.push({
     name: "clock",
     ok: facts.clockPinned,
     blocking: false,
-    detail: facts.clockPinned ? "pinned, with randomness and generated ids seeded from it" : "running live (--live-clock) \u2014 screens showing a date will differ every run, so nothing here can tell you whether they changed"
+    detail: facts.clockPinned ? "pinned, with randomness and generated ids seeded from it" : "running live (--live-clock). Screens showing a date will differ every run, so nothing here can tell you whether they changed"
   });
   checks.push({
     name: "locale",
     ok: true,
     blocking: false,
-    detail: `${facts.locale}, ${facts.timezone} \u2014 set explicitly rather than inherited from this machine`
+    detail: `${facts.locale}, ${facts.timezone}, set explicitly rather than inherited from this machine`
   });
   checks.push({
     name: "isolation",
@@ -398,7 +416,7 @@ function preflight(facts) {
       name: "rebaseline",
       ok: true,
       blocking: false,
-      detail: `replacing every stored frame \u2014 "${facts.rebaselineReason}"`
+      detail: `replacing every stored frame: "${facts.rebaselineReason}"`
     });
   }
   const blocked = checks.filter((check) => check.blocking && !check.ok);
@@ -425,11 +443,30 @@ function attestation(run) {
   ].filter(Boolean).join("\n");
 }
 
+// core/capture/run-record.ts
+function runIdentityFromEnv(env) {
+  if (env["GITHUB_ACTIONS"] !== "true" || !env["GITHUB_RUN_NUMBER"]) return void 0;
+  const said = { number: env["GITHUB_RUN_NUMBER"] };
+  for (const [key, name] of [
+    ["id", "GITHUB_RUN_ID"],
+    ["attempt", "GITHUB_RUN_ATTEMPT"],
+    ["repository", "GITHUB_REPOSITORY"],
+    ["server", "GITHUB_SERVER_URL"]
+  ]) {
+    const value = env[name];
+    if (value) said[key] = value;
+  }
+  return said;
+}
+
 // core/capture/run-verdict.ts
+function runCounts(run) {
+  return `${run.captured} photographed, ${run.unchanged} unchanged, ${run.skipped} skipped, ${run.refused} refused, ${run.failed} failed`;
+}
 function runVerdict(run) {
   const delivered = run.captured + run.unchanged;
   const missed = run.skipped + run.refused + run.failed;
-  const counts = `${run.captured} photographed, ${run.unchanged} unchanged, ${run.skipped} skipped, ${run.refused} refused, ${run.failed} failed`;
+  const counts = runCounts(run);
   if (run.screens > 0 && delivered === 0) {
     return {
       exit: 1,
@@ -580,6 +617,8 @@ var ALREADY_SAFE = [
 function alreadySafe(kind, value) {
   return ALREADY_SAFE.some((entry) => entry.kind === kind && entry.regex.test(value));
 }
+var BIRTH_LABEL = /(?:\bdate[\s_-]*of[\s_-]*birth|\bbirth[\s_-]*(?:date|day)|\bdob\b|\bd\.o\.b\b|\bborn\b)/i;
+var LABEL_REACH = 48;
 var PATTERNS = [
   {
     kind: "email",
@@ -629,8 +668,9 @@ var PATTERNS = [
   {
     kind: "date-of-birth",
     regex: /\b(19|20)\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])\b/g,
-    because: "a full date \u2014 if it is a birth date it identifies somebody",
-    replace: () => "1970-01-01"
+    because: "a date labeled as a birth date, which identifies somebody",
+    replace: () => "1970-01-01",
+    labelled: BIRTH_LABEL
   },
   {
     kind: "passport",
@@ -651,8 +691,13 @@ function scrub(text2, options = {}) {
   let output = text2;
   for (const pattern of PATTERNS) {
     const seen = /* @__PURE__ */ new Map();
-    output = output.replace(pattern.regex, (match) => {
+    output = output.replace(pattern.regex, (...args) => {
+      const match = args[0];
+      const named = typeof args[args.length - 1] === "object";
+      const offset = args[args.length - (named ? 3 : 2)];
+      const whole = args[args.length - (named ? 2 : 1)];
       if (alreadySafe(pattern.kind, match)) return match;
+      if (pattern.labelled && !pattern.labelled.test(whole.slice(Math.max(0, offset - LABEL_REACH), offset))) return match;
       const already = seen.get(match);
       if (already) return already;
       const replacement = pattern.replace(match, seen.size);
@@ -669,7 +714,7 @@ function scrub(text2, options = {}) {
         found: brand,
         replacement: brand,
         where,
-        because: "a real institution in a published screenshot implies a partnership \u2014 a legal review item, not a design nit"
+        because: "a real institution in a published screenshot implies a partnership: a legal review item, not a design nit"
       });
     }
   }
@@ -697,7 +742,7 @@ function gateFrame(pageText, options = {}) {
   return {
     safe: false,
     findings,
-    reason: onlyBrands ? `Not photographed${where}: the screen names ${named.join(", ")}. A real company in a published screenshot implies a partnership, which is a legal review item rather than a design nit \u2014 so somebody has to say whether it belongs there. If these names are on this screen on purpose, list them on the capture approval and this screen is photographed as it is.` : `Not photographed${where}: the screen showed ${kinds.join(", ")} that looks real. A screenshot cannot be redacted afterwards, so it is refused rather than cleaned \u2014 point the capture at a demo tenant, or fix the seed that produced this.`
+    reason: onlyBrands ? `Not photographed${where}: the screen names ${named.join(", ")}. A real company in a published screenshot implies a partnership, which is a legal review item rather than a design nit, so somebody has to say whether it belongs there. If these names are on this screen on purpose, list them on the capture approval and this screen is photographed as it is.` : `Not photographed${where}: the screen showed ${kinds.join(", ")} that looks real. A screenshot cannot be redacted afterwards, so it is refused rather than cleaned. Point the capture at a demo tenant, or fix the seed that produced this.`
   };
 }
 
@@ -1037,11 +1082,22 @@ var LIMITS = {
   fields: 24,
   notices: 20,
   warnings: 12,
+  disabled: 24,
+  empty: 12,
+  gatedBy: 8,
   choices: 12,
   /** Longer than this is a paragraph of copy, not a label. */
   label: 120,
   sentence: 300
 };
+var EMPTY_STATE = /^(?:no\s+(?!(?:longer|need|problem|worries|matter|one|way|thanks)\b)[a-z]|nothing\b|none\s|you (?:have|haven't|don't have|do not have)\s+(?:no|any|not)\b|there(?:'s| (?:are|is|were))\s+(?:no|nothing)\b|there aren't any\b|(?:you|we) haven't\b.*\byet\b)/i;
+function isEmptyState(text2) {
+  const sentence = text2.replace(/[\u2018\u2019]/g, "'").replace(/\s+/g, " ").trim();
+  if (!sentence || sentence.length > LIMITS.sentence || sentence.includes("?")) return false;
+  if (/\b(?:until|unless)\b/i.test(sentence)) return false;
+  if (sentence.split(" ").length < 2) return false;
+  return EMPTY_STATE.test(sentence);
+}
 
 // core/discovery/aria-facts.ts
 var LANDMARK = {
@@ -1092,6 +1148,12 @@ function readAriaFactRecords(snapshot, options = {}) {
     const state = controlState(node);
     if (node.role === "heading") {
       add("heading", node.name || node.text, node);
+      if (isEmptyState(node.name || node.text)) add("empty", node.name || node.text, node);
+      continue;
+    }
+    if (node.role === "paragraph" || node.role === "text") {
+      const said = node.text || node.name;
+      if (isEmptyState(said)) add("empty", trim(said, LIMITS.sentence), node);
       continue;
     }
     if (node.role === "link") {
@@ -1115,7 +1177,9 @@ function readAriaFactRecords(snapshot, options = {}) {
       continue;
     }
     if (NOTICE.has(node.role)) {
-      add("notice", trim(node.text || node.name, LIMITS.sentence), node);
+      const said = trim(node.text || node.name, LIMITS.sentence);
+      add("notice", said, node);
+      if (isEmptyState(said)) add("empty", said, node);
     }
   }
   return facts;
@@ -1152,7 +1216,7 @@ function parse(snapshot) {
       if (node.name || node.text) parent.choices.push(node.name || node.text);
       continue;
     }
-    if (role !== "text") out.push(node);
+    out.push(node);
     stack.push({ depth: depth2, node });
   }
   return out;
@@ -1235,6 +1299,7 @@ function readRenderedFactRecords(html, options = {}) {
     const label = accessibleName(element);
     if (HEADING.test(tag) || role === "heading") {
       add("heading", label, landmark);
+      if (isEmptyState(label)) add("empty", label, landmark);
       continue;
     }
     if (tag === "button" || PRESSABLE.has(role) || submitLike(element)) {
@@ -1260,11 +1325,20 @@ function readRenderedFactRecords(html, options = {}) {
       continue;
     }
     if (ANNOUNCEMENT.has(role) || attributes["aria-live"]) {
-      add("notice", trim2(text(inner), LIMITS.sentence), landmark);
+      const said = trim2(text(inner), LIMITS.sentence);
+      add("notice", said, landmark);
+      if (isEmptyState(said)) add("empty", said, landmark);
+      continue;
+    }
+    if (TEXT_HOLDER.has(tag) && !BLOCK_INSIDE.test(inner)) {
+      const said = trim2(text(inner).replace(/\s+([.,;:!])/g, "$1"), LIMITS.sentence);
+      if (isEmptyState(said)) add("empty", said, landmark);
     }
   }
   return facts;
 }
+var TEXT_HOLDER = /* @__PURE__ */ new Set(["p", "span", "small", "td", "li", "div"]);
+var BLOCK_INSIDE = /<(?!\/?(?:strong|em|b|i|a|code|br|span|small)\b)[a-z]/i;
 var OVERLAY_ROLE = {
   dialog: "dialog",
   alertdialog: "dialog",
@@ -1616,7 +1690,7 @@ function requireDeployment(producer, input) {
   const value = deployment.value.trim();
   if (BROWSER_SHAPED.test(value) || value === input.captureEnvironment?.trim()) {
     throw new UnstampedObservation(
-      `A ${producer} observation gives "${value}" as the deployment that answered it. That names the browser that did the reading, which belongs in captureEnvironment. What is wanted here is what the application was running \u2014 a deployment id, a build id, a release SHA \u2014 or unknownDeployment("why not").`
+      `A ${producer} observation gives "${value}" as the deployment that answered it. That names the browser that did the reading, which belongs in captureEnvironment. What is wanted here is what the application was running (a deployment id, a build id, a release SHA) or unknownDeployment("why not").`
     );
   }
 }
@@ -1665,7 +1739,7 @@ async function captureOne(options, shot, build) {
           status: "skipped",
           result: "bounced",
           needsAccount: true,
-          reason: "a signed-out visitor is shown a sign-in here, so this screen needs a demo tenant \u2014 never a real account"
+          reason: "a signed-out visitor is shown a sign-in here, so this screen needs a demo tenant, never a real account"
         },
         observed: { route: shot.route, result: "bounced" }
       };
@@ -1853,7 +1927,7 @@ async function captureOne(options, shot, build) {
         sha256,
         settled: frame.settled,
         ...frame.settled ? observed.landed ? { reason: `followed its redirect to ${observed.landed}` } : {} : {
-          reason: "photographed, but this screen never stopped moving \u2014 its hash will differ every run, so drift on it means nothing"
+          reason: "photographed, but this screen never stopped moving. Its hash will differ every run, so drift on it means nothing"
         }
       } : {
         shotId: shot.id,
@@ -2546,7 +2620,7 @@ async function stageAgainstRecording(options) {
       died = code ?? 1;
     });
   } else {
-    options.onLog?.(`The recording is at ${replay.url} \u2014 start your product with ${variable} set to it.`);
+    options.onLog?.(`The recording is at ${replay.url}. Start your product with ${variable} set to it.`);
   }
   const up = await waitForApp(options.appUrl, Date.now() + (options.waitMs ?? 6e4), options.onLog, () => died !== void 0);
   if (app) await new Promise((resolve) => setTimeout(resolve, 250));
@@ -2557,7 +2631,7 @@ async function stageAgainstRecording(options) {
     throw new Error(
       `The start command exited (${died}) before the product was ready. Its output is above.` + (up ? `
 
-Something else is already answering on ${options.appUrl}. That is almost always a server left behind by an earlier run \u2014 this will not photograph it, because it is not the product this run started.` : "")
+Something else is already answering on ${options.appUrl}. That is almost always a server left behind by an earlier run. This will not photograph it, because it is not the product this run started.` : "")
     );
   }
   if (!up) {
@@ -2748,7 +2822,7 @@ function gapReport(gaps) {
     ""
   ];
   for (const gap of gaps) {
-    const broke = gap.broke.length ? ` \u2014 breaks ${gap.broke.join(", ")}` : "";
+    const broke = gap.broke.length ? ` (breaks ${gap.broke.join(", ")})` : "";
     lines.push(`  ${gap.method} ${gap.path}${broke}`);
     if (gap.path !== gap.example) lines.push(`      for example ${gap.example}`);
   }
@@ -2795,7 +2869,7 @@ function coverageReport(found, total) {
     ...found.missing.map((route) => `  ${route}`),
     "",
     "They will not be photographed. Record again and visit them, or they stay out of the",
-    "plan \u2014 an empty screen photographed from a gap in the recording looks exactly like an",
+    "plan: an empty screen photographed from a gap in the recording looks exactly like an",
     "empty screen belonging to a customer with nothing, which is how a help article ends up",
     "showing a product with no content in it."
   ];
@@ -2991,7 +3065,7 @@ function score(route, signals) {
   }
   if (hasSegment(route.path, MONEY_OR_ACCESS)) {
     total += 18;
-    because.push("money or access \u2014 asked about out of proportion to its traffic");
+    because.push("money or access: asked about out of proportion to its traffic");
   }
   if (hasSegment(route.path, ENTRY_POINT)) {
     total += 16;
@@ -3087,6 +3161,16 @@ function buildArticlePlan(options) {
 function repositoryFiles(cwd) {
   return execFileSync("git", ["ls-files"], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }).split("\n").filter(Boolean);
 }
+var WORKFLOW_ACTIONS = {
+  checkout: "actions/checkout@v7",
+  setupNode: "actions/setup-node@v7"
+};
+var SETUP_STEPS = `      - uses: ${WORKFLOW_ACTIONS.checkout}
+      - uses: ${WORKFLOW_ACTIONS.setupNode}
+        with:
+          node-version: "22"
+          package-manager-cache: false
+`;
 
 // core/discovery/storyboard.ts
 function shotIdFor(route) {
@@ -3322,6 +3406,10 @@ Approve one on the plan page, then run this again.`
 `
   );
   const runId = local ? void 0 : await openRun(parsed.to, headers, shots.length);
+  let told = Promise.resolve();
+  const tell = (body) => {
+    told = told.then(() => tellHelpDesk(parsed.to, headers, body));
+  };
   try {
     const report = await runCapture({
       baseUrl,
@@ -3354,13 +3442,16 @@ Approve one on the plan page, then run this again.`
       role: parsed.session ? unknownRole() : noRole("this run was signed out"),
       onProgress: (outcome, index, total) => {
         const mark = { captured: "\u2713", unchanged: "=", skipped: "\u2013", refused: "\u2717", failed: "!" }[outcome.status];
-        console.log(`${mark} ${index}/${total} ${outcome.route}${outcome.reason ? ` \u2014 ${outcome.reason}` : ""}`);
+        console.log(`${mark} ${index}/${total} ${outcome.route}${outcome.reason ? `: ${outcome.reason}` : ""}`);
         if (runId) {
-          void tellHelpDesk(parsed.to, headers, {
+          tell({
             action: "progress",
             jobId: runId,
             item: outcome.route,
+            // Kept for a help desk that predates `outcome`, which folds the
+            // five into three and cannot tell a refusal from a skip.
             status: outcome.status === "captured" || outcome.status === "unchanged" ? "ok" : outcome.status === "failed" ? "failed" : "skipped",
+            outcome: outcome.status,
             ...outcome.reason ? { note: outcome.reason } : {},
             // So Setup can ask about them, once each. See `core/capture/unclassified.ts`.
             ...outcome.unaccounted?.length ? { unaccounted: outcome.unaccounted } : {}
@@ -3413,10 +3504,8 @@ Approve one on the plan page, then run this again.`
         return { ok: false, error: body.error ?? `the help desk answered ${response.status}` };
       }
     });
-    console.log(
-      `
-${report.captured} photographed, ${report.unchanged} unchanged, ${report.skipped} skipped, ${report.refused} refused, ${report.failed} failed.`
-    );
+    console.log(`
+${runCounts(report)}.`);
     const unclassified = unclassifiedLines(
       groupUnclassified(
         report.outcomes.flatMap((outcome) => outcome.unaccounted?.length ? [{ route: outcome.route, values: outcome.unaccounted }] : [])
@@ -3481,7 +3570,7 @@ whether they changed. Usually a spinner that never resolves or a looping animati
     const gated = report.outcomes.filter((outcome) => outcome.needsAccount);
     if (gated.length) {
       console.log(
-        stage ? "\nSome screens still showed a sign-in. A recording answers the backend, but it cannot\ngive the product a session \u2014 record the sign-in itself, or save one against the replayed\nproduct and pass it with --session." : parsed.session ? "\nSome screens still showed a sign-in. The saved session may have expired \u2014 run `sign-in` again." : `
+        stage ? "\nSome screens still showed a sign-in. A recording answers the backend, but it cannot\ngive the product a session: record the sign-in itself, or save one against the replayed\nproduct and pass it with --session." : parsed.session ? "\nSome screens still showed a sign-in. The saved session may have expired. Run `sign-in` again." : `
 Some screens are behind your sign-in. To photograph them, save a session against a
 DEMO tenant and pass it back:
 
@@ -3508,27 +3597,32 @@ ${attestation({
       console.log(`
 ${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
     }
+    const counts = {
+      screens: shots.length,
+      captured: report.captured,
+      unchanged: report.unchanged,
+      skipped: report.skipped,
+      refused: report.refused,
+      failed: report.failed
+    };
     if (runId) {
+      await told;
       await tellHelpDesk(parsed.to, headers, {
         action: "finish",
         jobId: runId,
+        // What the verdict below prints, so Setup can say what this log says.
+        counts,
         ...report.survey.length ? { survey: report.survey } : {}
       });
     }
-    const verdict = runVerdict({
-      screens: shots.length,
-      captured: report.captured,
-      unchanged: report.unchanged,
-      skipped: report.skipped,
-      refused: report.refused,
-      failed: report.failed
-    });
+    const verdict = runVerdict(counts);
     if (verdict.sentence) console.log(`
 ${verdict.sentence}`);
     if (verdict.annotation && process.env["GITHUB_ACTIONS"] === "true") console.log(verdict.annotation);
     return verdict.exit;
   } catch (error) {
     if (runId) {
+      await told;
       await tellHelpDesk(parsed.to, headers, {
         action: "finish",
         jobId: runId,
@@ -3543,11 +3637,12 @@ ${verdict.sentence}`);
   }
 }
 async function openRun(to, headers, total) {
+  const run = runIdentityFromEnv(process.env);
   try {
     const response = await fetch(`${to}/api/helpdesk/captures`, {
       method: "POST",
       headers: { ...headers, "content-type": "application/json" },
-      body: JSON.stringify({ action: "start", total })
+      body: JSON.stringify({ action: "start", total, ...run ? { run } : {} })
     });
     if (!response.ok) return void 0;
     const body = await response.json();
@@ -3577,7 +3672,7 @@ async function signIn(argv) {
     return 2;
   }
   console.log(
-    `Opening ${baseUrl}. Sign in as your DEMO tenant \u2014 never a real customer.
+    `Opening ${baseUrl}. Sign in as your DEMO tenant, never as a real customer.
 This window is yours: use SSO, a one-time code, whatever you normally do.
 The session will be saved to ${sessionPath} and sent nowhere.
 `

package/helpdesk-seed.mjs

@@ -219,7 +219,7 @@ function gapReport(gaps2) {
     ""
   ];
   for (const gap of gaps2) {
-    const broke = gap.broke.length ? ` \u2014 breaks ${gap.broke.join(", ")}` : "";
+    const broke = gap.broke.length ? ` (breaks ${gap.broke.join(", ")})` : "";
     lines.push(`  ${gap.method} ${gap.path}${broke}`);
     if (gap.path !== gap.example) lines.push(`      for example ${gap.example}`);
   }
@@ -733,6 +733,8 @@ var ALREADY_SAFE = [
 function alreadySafe(kind, value) {
   return ALREADY_SAFE.some((entry) => entry.kind === kind && entry.regex.test(value));
 }
+var BIRTH_LABEL = /(?:\bdate[\s_-]*of[\s_-]*birth|\bbirth[\s_-]*(?:date|day)|\bdob\b|\bd\.o\.b\b|\bborn\b)/i;
+var LABEL_REACH = 48;
 var PATTERNS = [
   {
     kind: "email",
@@ -782,8 +784,9 @@ var PATTERNS = [
   {
     kind: "date-of-birth",
     regex: /\b(19|20)\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])\b/g,
-    because: "a full date \u2014 if it is a birth date it identifies somebody",
-    replace: () => "1970-01-01"
+    because: "a date labeled as a birth date, which identifies somebody",
+    replace: () => "1970-01-01",
+    labelled: BIRTH_LABEL
   },
   {
     kind: "passport",
@@ -804,8 +807,13 @@ function scrub(text, options = {}) {
   let output = text;
   for (const pattern of PATTERNS) {
     const seen = /* @__PURE__ */ new Map();
-    output = output.replace(pattern.regex, (match) => {
+    output = output.replace(pattern.regex, (...args) => {
+      const match = args[0];
+      const named = typeof args[args.length - 1] === "object";
+      const offset = args[args.length - (named ? 3 : 2)];
+      const whole = args[args.length - (named ? 2 : 1)];
       if (alreadySafe(pattern.kind, match)) return match;
+      if (pattern.labelled && !pattern.labelled.test(whole.slice(Math.max(0, offset - LABEL_REACH), offset))) return match;
       const already = seen.get(match);
       if (already) return already;
       const replacement = pattern.replace(match, seen.size);
@@ -822,7 +830,7 @@ function scrub(text, options = {}) {
         found: brand,
         replacement: brand,
         where,
-        because: "a real institution in a published screenshot implies a partnership \u2014 a legal review item, not a design nit"
+        because: "a real institution in a published screenshot implies a partnership: a legal review item, not a design nit"
       });
     }
   }
@@ -838,7 +846,7 @@ function describeScrub(result) {
   }
   const lines = [`${result.findings.length} thing(s) found. Nothing publishes until you confirm.`, ""];
   for (const [kind, group] of byKind) {
-    lines.push(`  ${kind.toUpperCase().replace(/-/g, " ")} \u2014 ${group[0].because}`);
+    lines.push(`  ${kind.toUpperCase().replace(/-/g, " ")}: ${group[0].because}`);
     for (const finding of group.slice(0, 5)) {
       lines.push(
         kind === "brand" ? `    ${finding.found}  (left as-is: decide whether this frame can ship)` : `    ${finding.found}  \u2192  ${finding.replacement}`
@@ -1217,7 +1225,7 @@ async function record(args) {
     [
       `Recording everything sent to ${args.upstream}.`,
       "",
-      "Point your product's backend address at this and use it \u2014 sign in, open the screens",
+      "Point your product's backend address at this and use it: sign in, open the screens",
       "you want documented, and make the errors happen if you can. What you visit is what",
       "the recording will be able to replay.",
       "",
@@ -1289,7 +1297,7 @@ function carriedReport(carried, cassette) {
       (field) => `  ${field.key.padEnd(width)}  ${String(field.count).padStart(4)}\xD7  ${field.example}`
     ),
     "",
-    "That is not automatically wrong \u2014 an id, a status or a currency is meant to survive.",
+    "That is not automatically wrong: an id, a status or a currency is meant to survive.",
     "But this package only knows the words every product shares: people, their contact",
     "details, their address, and the role each one is playing. Whatever your product holds",
     "that no other product does is on the list above, and it was not touched.",
@@ -1304,7 +1312,7 @@ function carriedReport(carried, cassette) {
       "         company, note, amount",
       "",
       "  note invents a sentence of about the same length, for anything free-text.",
-      "  amount invents a different figure of the same size, for a salary or a balance \u2014",
+      "  amount invents a different figure of the same size, for a salary or a balance:",
       "  a number is never detectable by shape, so naming it is the only way it is caught."
     ] : []
   ];

package/helpdesk.mjs

@@ -188,7 +188,7 @@ function score(route, signals) {
   }
   if (hasSegment(route.path, MONEY_OR_ACCESS)) {
     total += 18;
-    because.push("money or access \u2014 asked about out of proportion to its traffic");
+    because.push("money or access: asked about out of proportion to its traffic");
   }
   if (hasSegment(route.path, ENTRY_POINT)) {
     total += 16;
@@ -538,11 +538,22 @@ var LIMITS = {
   fields: 24,
   notices: 20,
   warnings: 12,
+  disabled: 24,
+  empty: 12,
+  gatedBy: 8,
   choices: 12,
   /** Longer than this is a paragraph of copy, not a label. */
   label: 120,
   sentence: 300
 };
+var EMPTY_STATE = /^(?:no\s+(?!(?:longer|need|problem|worries|matter|one|way|thanks)\b)[a-z]|nothing\b|none\s|you (?:have|haven't|don't have|do not have)\s+(?:no|any|not)\b|there(?:'s| (?:are|is|were))\s+(?:no|nothing)\b|there aren't any\b|(?:you|we) haven't\b.*\byet\b)/i;
+function isEmptyState(text) {
+  const sentence = text.replace(/[\u2018\u2019]/g, "'").replace(/\s+/g, " ").trim();
+  if (!sentence || sentence.length > LIMITS.sentence || sentence.includes("?")) return false;
+  if (/\b(?:until|unless)\b/i.test(sentence)) return false;
+  if (sentence.split(" ").length < 2) return false;
+  return EMPTY_STATE.test(sentence);
+}
 var IRREVERSIBLE = /\b(cannot be undone|can't be undone|permanently|permanent|irreversible|no way back|cannot be recovered|unrecoverable|this cannot be reversed)\b/i;
 var DESTRUCTIVE = /\b(delete|deletes|deleting|remove|removes|revoke|revokes|erase|wipe|discard|destroy|overwrite|overwrites|reset|disconnect|unpublish|cancel subscription)\b/i;
 var PERMISSION = /\b(only (?:an?\s+)?(?:owner|admin|administrator)s?\b|your role|not allowed|do(?:es)? not have permission|don't have permission|permission to|requires? (?:an? )?(?:owner|admin|editing|editor)|admins? only|read[- ]only)\b/i;
@@ -553,18 +564,24 @@ function readScreenFacts(files, options = {}) {
   const links = [];
   const fields = [];
   const notices = [];
-  const warnings = [];
+  const disabled = [];
+  const empty = [];
   const messageDepth = options.messageDepth ?? 2;
+  const read = files.filter((file) => !options.skip?.(file.path));
+  const gatedBy = flagsGating(read, messageDepth);
   for (const file of files) {
     if (options.skip?.(file.path)) continue;
     const source = withoutComments(file.contents);
-    const before = headings.length + actions.length + links.length + fields.length + notices.length;
-    readElements(source, { headings, actions, links, fields });
-    if ((file.depth ?? 0) <= messageDepth) readMessages(source, notices);
-    const after = headings.length + actions.length + links.length + fields.length + notices.length;
+    const before = headings.length + actions.length + links.length + fields.length + notices.length + empty.length;
+    readElements(source, { headings, actions, links, fields, disabled, empty });
+    if ((file.depth ?? 0) <= messageDepth) {
+      readMessages(source, notices);
+      readEmptyMessages(source, empty);
+    }
+    const after = headings.length + actions.length + links.length + fields.length + notices.length + empty.length;
     if (after > before) facts.readFrom.push(file.path);
   }
-  return finishScreenFacts({ headings, actions, links, fields, notices, readFrom: facts.readFrom });
+  return finishScreenFacts({ headings, actions, links, fields, notices, readFrom: facts.readFrom, disabled, empty, gatedBy });
 }
 function finishScreenFacts(parts) {
   const warnings = [];
@@ -581,23 +598,48 @@ function finishScreenFacts(parts) {
     fields: cappedBy(parts.fields, (field) => `${field.label}|${field.kind}`, LIMITS.fields),
     notices: capped(parts.notices, LIMITS.notices),
     warnings: capped(warnings, LIMITS.warnings),
-    readFrom: parts.readFrom
+    readFrom: parts.readFrom,
+    ...states({ disabled: parts.disabled, empty: parts.empty, gatedBy: parts.gatedBy })
+  };
+}
+function states(parts) {
+  const disabled = capped(parts.disabled ?? [], LIMITS.disabled);
+  const empty = capped(parts.empty ?? [], LIMITS.empty);
+  const gatedBy = capped(parts.gatedBy ?? [], LIMITS.gatedBy);
+  return {
+    ...disabled.length ? { disabled } : {},
+    ...empty.length ? { empty } : {},
+    ...gatedBy.length ? { gatedBy } : {}
   };
 }
 var HEADING_TAG = /^h[1-4]$/;
 var BUTTON_TAG = /^(button|Button|MenuItem|Tab)$/;
 var LINK_TAG = /^(a|Link|NavLink)$/;
 var FIELD_TAG = /^(input|Input|textarea|Textarea|select|Select|Checkbox|Radio|Switch|Toggle)$/;
+var TEXT_TAG = /^(p|span|small|td|li|div)$/;
+var NOT_INLINE = /<(?!\/?(?:strong|em|b|i|code|br)\b)[A-Za-z]/;
+var EMPTY_TAG = /^(EmptyState|Empty|EmptyMessage|EmptyPanel|NoResults|ZeroState|BlankState)$/;
+var EMPTY_PROPS = ["emptyState", "emptyText", "emptyMessage", "emptyLabel", "emptyTitle", "emptyDescription"];
+var DISABLED_PROP = /(?:^|\s)(?:disabled|aria-disabled)(?=\s|=|\/|$)(?!\s*=\s*\{\s*false\s*\})(?!\s*=\s*["']false["'])/;
 function readElements(source, into) {
   for (const tag of tagsIn(source)) {
     const attributes = readAttributes(tag.attributes);
     if (HEADING_TAG.test(tag.name)) {
-      push(into.headings, visibleText(childrenOf(source, tag)));
+      const children = childrenOf(source, tag);
+      const heading = visibleText(children);
+      push(into.headings, heading);
+      for (const said of [heading, ...chosenIn(children)]) if (isEmptyState(said)) push(into.empty, said, LIMITS.sentence);
       continue;
     }
     push(into.headings, attributes["heading"]);
+    for (const prop of EMPTY_PROPS) pushWords(into.empty, attributes[prop]);
+    if (EMPTY_TAG.test(tag.name)) {
+      for (const prop of ["title", "description", "message"]) pushWords(into.empty, attributes[prop]);
+    }
     if (BUTTON_TAG.test(tag.name)) {
-      push(into.actions, visibleText(childrenOf(source, tag)) || attributes["label"] || attributes["aria-label"]);
+      const label = visibleText(childrenOf(source, tag)) || attributes["label"] || attributes["aria-label"];
+      push(into.actions, label);
+      if (DISABLED_PROP.test(tag.attributes)) push(into.disabled, label);
       continue;
     }
     if (LINK_TAG.test(tag.name)) {
@@ -611,6 +653,16 @@ function readElements(source, into) {
     if (FIELD_TAG.test(tag.name)) {
       const field = fieldFrom(tag.name, attributes, source, tag);
       if (field) into.fields.push(field);
+      if (field && DISABLED_PROP.test(tag.attributes)) push(into.disabled, field.label);
+      continue;
+    }
+    if (TEXT_TAG.test(tag.name)) {
+      const children = childrenOf(source, tag);
+      if (NOT_INLINE.test(children)) continue;
+      const written = visibleText(children, LIMITS.sentence).replace(/\s+([.,;:!])/g, "$1");
+      for (const said of [written, ...chosenIn(children)]) {
+        if (isEmptyState(said)) push(into.empty, said, LIMITS.sentence);
+      }
     }
   }
   for (const tag of tagsIn(source)) {
@@ -723,7 +775,7 @@ function childrenOf(source, tag) {
 function escapeName(name) {
   return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function visibleText(fragment) {
+function visibleText(fragment, limit = LIMITS.label) {
   if (!fragment) return "";
   let text = fragment;
   let previous = "";
@@ -732,7 +784,26 @@ function visibleText(fragment) {
     text = text.replace(/\{[^{}]*\}/g, " ");
   }
   text = text.replace(/<[^>]*>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&mdash;/g, "\u2014").replace(/&ndash;/g, "\u2013").replace(/&(?:l|r)squo;/g, "'").replace(/&(?:l|r)dquo;/g, '"').replace(/&#\d+;/g, " ").replace(/\s+/g, " ").trim();
-  return /[A-Za-z]/.test(text) ? trim(text, LIMITS.label) : "";
+  return /[A-Za-z]/.test(text) ? trim(text, limit) : "";
+}
+function chosenIn(fragment) {
+  const chosen = [];
+  let depth2 = 0;
+  let start = 0;
+  for (let index = 0; index < fragment.length; index += 1) {
+    if (fragment[index] === "{") {
+      if (depth2 === 0) start = index + 1;
+      depth2 += 1;
+    } else if (fragment[index] === "}" && depth2 > 0) {
+      depth2 -= 1;
+      if (depth2 > 0) continue;
+      for (const literal of fragment.slice(start, index).matchAll(/"([^"\\]*)"|'([^'\\]*)'|`([^`\\$]*)`/g)) {
+        const text = (literal[1] ?? literal[2] ?? literal[3] ?? "").replace(/\s+/g, " ").trim();
+        if (text) chosen.push(text);
+      }
+    }
+  }
+  return chosen;
 }
 function readAttributes(raw) {
   const attributes = {};
@@ -752,11 +823,80 @@ function humanise(name) {
 function scrubExpressions(value) {
   return value.replace(/\$\{[^}]*\}/g, "\u2026").replace(/\s+/g, " ").trim();
 }
-function push(into, value) {
+function push(into, value, limit = LIMITS.label) {
   const text = value === void 0 ? "" : scrubExpressions(value);
   if (!text || !/[A-Za-z]/.test(text)) return;
   if ((text.match(/…/g)?.length ?? 0) > 1) return;
-  into.push(trim(text, LIMITS.label));
+  into.push(trim(text, limit));
+}
+function pushWords(into, value) {
+  if (value && value.trim().split(/\s+/).length >= 2) push(into, value, LIMITS.sentence);
+}
+var EMPTY_PROPERTY = /(?:^|[\s,{(])(?:emptyState|emptyText|emptyMessage|emptyLabel|emptyTitle|emptyDescription)\s*:\s*(["'`])((?:(?!\1)[\s\S]){4,}?)\1/g;
+function readEmptyMessages(source, into) {
+  for (const match of source.matchAll(EMPTY_PROPERTY)) pushWords(into, match[2].replace(/\s+/g, " ").trim());
+}
+var FLAG_NAME = /\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*_(?:ENABLED|ENABLE|FLAG|FEATURE)|(?:ENABLE|FEATURE|FLAG)_[A-Z0-9]+(?:_[A-Z0-9]+)*)\b/g;
+var FLAG_NAME_ONLY = /^[A-Za-z0-9_.:-]{1,80}$/;
+var DECLARATION = /^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)|^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^=\n]+)?=>/gm;
+var NOT_THERE = /\b(?:notFound|redirect)\s*\(/g;
+function flagsIn(text) {
+  return [...new Set([...text.matchAll(FLAG_NAME)].map((match) => match[1]))];
+}
+function flagsGating(files, messageDepth) {
+  const named = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    if ((file.depth ?? 0) > messageDepth) continue;
+    const source = withoutComments(file.contents);
+    const declarations = [...source.matchAll(DECLARATION)];
+    declarations.forEach((declaration, index) => {
+      const name = declaration[1] ?? declaration[2];
+      const body = source.slice(declaration.index, declarations[index + 1]?.index ?? source.length);
+      const flags = flagsIn(body);
+      if (flags.length) named.set(name, /* @__PURE__ */ new Set([...named.get(name) ?? [], ...flags]));
+    });
+  }
+  const gating = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    if ((file.depth ?? 0) > 0) continue;
+    const source = withoutComments(file.contents);
+    for (const call of source.matchAll(NOT_THERE)) {
+      const condition = guardOf(source, call.index);
+      if (condition === void 0) continue;
+      for (const flag of flagsIn(condition)) gating.add(flag);
+      for (const [, dotted, bracketed] of condition.matchAll(
+        /process\.env(?:\.([A-Z][A-Z0-9_]*)|\[\s*["']([A-Z][A-Z0-9_]*)["']\s*\])/g
+      )) {
+        gating.add(dotted ?? bracketed);
+      }
+      for (const [, args] of condition.matchAll(/\b\w*(?:[Ff]lag|[Ff]eature|[Ee]nabled)\w*\s*\(([^()]*)\)/g)) {
+        for (const [, literal] of args.matchAll(/["'`]([^"'`]+)["'`]/g)) {
+          if (FLAG_NAME_ONLY.test(literal)) gating.add(literal);
+        }
+      }
+      for (const [, callee] of condition.matchAll(/([A-Za-z_$][\w$]*)\s*\(/g)) {
+        for (const flag of named.get(callee) ?? []) gating.add(flag);
+      }
+    }
+  }
+  return [...gating];
+}
+function guardOf(source, callAt) {
+  const before = source.slice(Math.max(0, callAt - 400), callAt);
+  const opened = [...before.matchAll(/\bif\s*\(/g)].at(-1);
+  if (!opened) return void 0;
+  const start = opened.index + opened[0].length;
+  let depth2 = 1;
+  let cursor = start;
+  while (cursor < before.length && depth2 > 0) {
+    const character = before[cursor];
+    if (character === "(") depth2 += 1;
+    else if (character === ")") depth2 -= 1;
+    cursor += 1;
+  }
+  if (depth2 !== 0) return void 0;
+  if (!/^\s*(?:\{\s*)?(?:return\s+)?$/.test(before.slice(cursor))) return void 0;
+  return before.slice(start, cursor - 1);
 }
 function trim(value, limit) {
   return value.length <= limit ? value : `${value.slice(0, limit - 1).trimEnd()}\u2026`;
@@ -818,7 +958,9 @@ function readProduct(routes, options) {
 }
 function hasAnything(facts) {
   return Boolean(
-    facts.headings.length || facts.actions.length || facts.links.length || facts.fields.length || facts.notices.length
+    facts.headings.length || facts.actions.length || facts.links.length || facts.fields.length || facts.notices.length || // A flagged page whose screen is all in a component the reader cannot
+    // follow still says it is behind a flag, and an empty state is still words.
+    facts.gatedBy?.length || facts.empty?.length
   );
 }
 function describeReading(routes) {
@@ -827,6 +969,34 @@ function describeReading(routes) {
   return { screens: documentable.length, read, pathsOnly: read === 0 };
 }
 
+// core/github/remote.ts
+function repositoryFromRemote(remote) {
+  const raw = remote?.trim();
+  if (!raw) return void 0;
+  if (OWNER_NAME.test(raw)) return withoutGit(raw);
+  const scp = SCP.exec(raw);
+  const at = scp ? { host: scp[1], hostname: scp[1], path: scp[2] } : located(raw);
+  if (!at) return void 0;
+  const parts = withoutGit(at.path.replace(/^\/+|\/+$/g, "")).split("/").filter(Boolean);
+  if (!parts.length) return void 0;
+  if (GITHUB.test(at.hostname)) return parts.length === 2 ? `${parts[0]}/${parts[1]}` : void 0;
+  return `${at.host}/${parts.join("/")}`;
+}
+var OWNER_NAME = /^[A-Za-z0-9][\w-]*\/(?!\.\.?$)[\w.-]+$/;
+var SCP = /^(?:[^@\s/]+@)?([^:\s/]{2,}):(?!\/)(\S+)$/;
+var GITHUB = /^(www\.)?github\.com$/i;
+function withoutGit(path) {
+  return path.replace(/\.git$/, "");
+}
+function located(raw) {
+  try {
+    const url = new URL(raw);
+    return url.hostname && /^(https?|ssh|git):$/.test(url.protocol) ? { host: url.host, hostname: url.hostname, path: url.pathname } : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
 // core/markers/propose.ts
 function toLines(contents) {
   const lines = contents.split("\n");
@@ -950,7 +1120,7 @@ function markersPullRequestBody(result) {
   }
   lines.push(
     "",
-    "**A wrong one costs nothing.** Delete the line and the article stops being linked to that file. If we missed one, the screen is still matched by its route \u2014 this only makes the match more precise."
+    "**A wrong one costs nothing.** Delete the line and the article stops being linked to that file. If we missed one, the screen is still matched by its route. This only makes the match more precise."
   );
   if (result.unmatchedSlugs.length > 0) {
     lines.push(
@@ -1031,7 +1201,7 @@ async function runMap(options) {
     lines.push(
       "",
       proposed.proposals.length ? `Wrote ${proposed.proposals.length} marker(s) to ${options.markersOut}. Apply with:
-  git apply ${options.markersOut}` : "Every file already carries its marker \u2014 nothing to propose."
+  git apply ${options.markersOut}` : "Every file already carries its marker: nothing to propose."
     );
   }
   let sent = false;
@@ -1054,7 +1224,7 @@ async function runMap(options) {
       throw new Error(`The help desk refused the map (${response.status}). ${body}`);
     }
     sent = true;
-    lines.push("", "Sent. Whoever asked you to run this can see it now \u2014 you are done.");
+    lines.push("", "Sent. Whoever asked you to run this can see it now. You are done.");
   } else if (options.token) {
     lines.push("", "No destination given. Pass --to https://your-helpdesk.example to send this.");
   }
@@ -1077,7 +1247,7 @@ function readTsconfig(cwd) {
 }
 function originOf(cwd) {
   try {
-    return execFileSync("git", ["remote", "get-url", "origin"], { cwd, encoding: "utf8" }).trim();
+    return repositoryFromRemote(execFileSync("git", ["remote", "get-url", "origin"], { cwd, encoding: "utf8" }));
   } catch {
     return void 0;
   }
@@ -1089,6 +1259,16 @@ function headCommit(cwd) {
     return null;
   }
 }
+var WORKFLOW_ACTIONS = {
+  checkout: "actions/checkout@v7",
+  setupNode: "actions/setup-node@v7"
+};
+var SETUP_STEPS = `      - uses: ${WORKFLOW_ACTIONS.checkout}
+      - uses: ${WORKFLOW_ACTIONS.setupNode}
+        with:
+          node-version: "22"
+          package-manager-cache: false
+`;
 
 // adapters/invoked-as-command.ts
 import { realpathSync } from "node:fs";

package/package.json

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