@olomonhelpdesk2/helpdesk 0.1.4 → 0.1.9

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,13 +784,14 @@ 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",
     regex: /\b[A-Z]{1,2}\d{6,9}\b/g,
-    because: "the shape of a passport or licence number",
+    because: "the shape of a passport or license number",
     replace: (match) => `${match.slice(0, 1)}${"0".repeat(match.length - 1)}`
   },
   {
@@ -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.",
       "",
@@ -1270,7 +1278,7 @@ ${carriedReport(sealed.carried, args.cassette).join("\n")}`);
     console.log(`
 ${describeScrub({ scrubbed: "", findings: sealed.findings, needsReview: true })}`);
     console.log(
-      "\nThese survived the field pass, which means they were in free text or under a key nothing\nrecognised. Read them before you commit this."
+      "\nThese survived the field pass, which means they were in free text or under a key nothing\nrecognized. Read them before you commit this."
     );
     return 1;
   }
@@ -1278,7 +1286,7 @@ ${describeScrub({ scrubbed: "", findings: sealed.findings, needsReview: true })}
   return 0;
 }
 function carriedReport(carried, cassette) {
-  if (!carried.length) return ["Every key in the recording was recognised and rewritten."];
+  if (!carried.length) return ["Every key in the recording was recognized and rewritten."];
   const ranked = [...carried].sort((a, b) => score(b) - score(a) || b.count - a.count);
   const width = Math.max(...ranked.map((field) => field.key.length));
   const worth = ranked.filter((field) => score(field) > 0);
@@ -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."
     ] : []
   ];
@@ -1380,7 +1388,7 @@ async function routes(args) {
   const cassette = parseCassette(await readFile(args.cassette, "utf8"));
   const found = exampleRoutes(cassette);
   if (!found.length) {
-    console.log("The recording holds no parameterised routes, so there are no example ids to offer.");
+    console.log("The recording holds no parameterized routes, so there are no example ids to offer.");
     return 0;
   }
   console.log("Routes the recording can answer, with an identifier it has already served:\n");

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`;
@@ -793,6 +933,7 @@ function readProduct(routes, options) {
   };
   const documentable = routes.filter((route) => !route.skipped);
   const total = Math.min(documentable.length, maxScreens);
+  const reading = { how: "source", commit: options.commit ?? null };
   let done = 0;
   let withFacts = 0;
   const out = routes.map((route) => {
@@ -803,18 +944,23 @@ function readProduct(routes, options) {
       const source = read(reached.path);
       if (source !== void 0) files.push({ path: reached.path, contents: source, depth: reached.depth });
     }
-    const facts = readScreenFacts(files);
     done += 1;
     options.onScreen?.(route, done, total);
-    if (!hasAnything(facts)) return route;
+    if (files.length === 0) return route;
+    const facts = readScreenFacts(files);
+    if (!hasAnything(facts)) {
+      return { ...route, facts: noScreenFacts(reading) };
+    }
     withFacts += 1;
-    return { ...route, facts };
+    return { ...route, facts: { ...facts, read: reading } };
   });
   return { routes: out, read: withFacts, filesOpened: opened.size };
 }
 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) {
@@ -823,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");
@@ -937,7 +1111,7 @@ function markersPullRequestBody(result) {
   const lines = [
     "This adds one-line comments that link screens in this repository to the help articles that describe them.",
     "",
-    "**Nothing here changes behaviour.** Each line is a comment. Once merged, a change to one of these files tells our help desk which article may now be out of date, so somebody can check it before a customer does.",
+    "**Nothing here changes behavior.** Each line is a comment. Once merged, a change to one of these files tells our help desk which article may now be out of date, so somebody can check it before a customer does.",
     "",
     `${result.proposals.length} marker${result.proposals.length === 1 ? "" : "s"} proposed.`
   ];
@@ -946,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(
@@ -1000,7 +1174,10 @@ async function runMap(options) {
         }
       },
       aliases: aliasesFromTsconfig(tsconfig),
-      baseUrl: baseUrlFromTsconfig(tsconfig)
+      baseUrl: baseUrlFromTsconfig(tsconfig),
+      // Stamped onto every reading, so a map carries the commit its labels and
+      // controls were read at and a later one can tell fresh from stale.
+      commit: headCommit(options.cwd)
     });
     routes = read.routes;
     const reading = describeReading(routes);
@@ -1024,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;
@@ -1047,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.");
   }
@@ -1070,11 +1247,28 @@ 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;
   }
 }
+function headCommit(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim() || null;
+  } catch {
+    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.4",
+  "version": "0.1.9",
   "description": "Reads a product's screens, plans its help articles, and photographs them.",
   "type": "module",
   "engines": {