@hajimism/dek 0.4.0 → 0.5.1

package/src/cli/goto.ts

@@ -13,22 +13,42 @@ export type NavResult = {
   viewers: number;
 };
 
-export async function gotoCommand(target: DeckTarget, slug: string): Promise<NavResult> {
+type NavOptions = {
+  /** Covers the whole request, from connecting to the last byte of the answer. */
+  timeoutMs?: number;
+};
+
+/** The dev server answers a nav request at once; a stall this long is a server that is stuck. */
+const NAV_TIMEOUT_MS = 10 * 1000;
+
+export async function gotoCommand(
+  target: DeckTarget,
+  slug: string,
+  options: NavOptions = {},
+): Promise<NavResult> {
   requireSection(target.deck, slug);
-  return requestDevServer(target, {
-    method: "POST",
-    path: "goto",
-    body: { slug },
-  });
+  return requestDevServer(
+    target,
+    { method: "POST", path: "goto", body: { slug } },
+    options.timeoutMs ?? NAV_TIMEOUT_MS,
+  );
 }
 
-export async function currentCommand(target: DeckTarget): Promise<NavResult> {
-  return requestDevServer(target, { method: "GET", path: "current" });
+export async function currentCommand(
+  target: DeckTarget,
+  options: NavOptions = {},
+): Promise<NavResult> {
+  return requestDevServer(
+    target,
+    { method: "GET", path: "current" },
+    options.timeoutMs ?? NAV_TIMEOUT_MS,
+  );
 }
 
 async function requestDevServer(
   { project, deck }: DeckTarget,
   request: { method: "GET" | "POST"; path: "goto" | "current"; body?: { slug: string } },
+  timeoutMs: number,
 ): Promise<NavResult> {
   const deckName = deck.name;
   const lock = readDevServerLock(project.root);
@@ -45,16 +65,27 @@ async function requestDevServer(
   if (lock.password) {
     headers.authorization = `Basic ${btoa(`:${lock.password}`)}`;
   }
+  // A server that takes the connection but never answers is stuck; say so instead of waiting.
+  const signal = AbortSignal.timeout(timeoutMs);
+  const unlessStuck = (error: unknown): never => {
+    throw signal.aborted
+      ? new DekError(`the dev server at ${lock.url} did not answer within ${timeoutMs / 1000}s`, {
+          hint: "restart it: stop `dekc` and run it again",
+        })
+      : error;
+  };
+  // biome-ignore lint/style/noRestrictedGlobals: signal, an AbortSignal.timeout, bounds the request and the read of its answer.
   const response = await fetch(url, {
     method: request.method,
     headers: Object.keys(headers).length > 0 ? headers : undefined,
     body: request.body ? JSON.stringify(request.body) : undefined,
-  });
+    signal,
+  }).catch(unlessStuck);
   // Only the nav routes answer JSON; a 404, 401, or 405 from the server itself is plain text.
   if (!response.headers.get("content-type")?.includes("application/json")) {
     throw refusal(response.status, lock, deckName, request.path);
   }
-  const json = (await response.json()) as {
+  const json = (await response.json().catch(unlessStuck)) as {
     ok?: boolean;
     slug?: string;
     slideIndex?: number;

package/src/cli/keep-alive.ts

@@ -7,6 +7,13 @@ const PARENT_POLL_MS = 1_000;
 /** How long a stop waits for the server to close before the process exits anyway. */
 const SHUTDOWN_GRACE_MS = 2_000;
 
+/**
+ * The process that started this one, read as the CLI loads. A parent read once the server is up
+ * would come too late: whoever waits for the URL can be killed before the next line runs, and the
+ * parent read then is already init, which never goes away.
+ */
+const startedBy = process.ppid;
+
 /**
  * Serve until told to stop: Ctrl-C, a kill, a closed terminal, or the process that started the
  * server going away, so a test run or an editor that dies without cleaning up leaves no server
@@ -51,16 +58,15 @@ export function stopOnce(
 }
 
 /**
- * Call `fn` once this process is reparented, which is how Unix says the parent died: a SIGKILL
- * leaves it no chance to stop its children. A process started with no parent of its own to lose
- * (already under init) is never orphaned.
+ * Call `fn` once this process is no longer under `parent`, the one that started it, which is how
+ * Unix says the parent died: a SIGKILL leaves it no chance to stop its children. A process started
+ * with no parent of its own to lose (already under init) is never orphaned.
  */
 export function onOrphaned(
   fn: () => void,
-  options: { ppid?: () => number; intervalMs?: number } = {},
+  options: { parent?: number; ppid?: () => number; intervalMs?: number } = {},
 ): () => void {
-  const ppid = options.ppid ?? (() => process.ppid);
-  const parent = ppid();
+  const { parent = startedBy, ppid = () => process.ppid } = options;
   const timer = setInterval(() => {
     if (ppid() !== parent) {
       clearInterval(timer);

package/src/cli/lint.ts

@@ -4,7 +4,7 @@ import type { Diagnostic } from "../core/diagnostic.ts";
 import { shellQuote } from "../core/escape.ts";
 import { lintDeck, lintProject, unreadableScriptDiagnostics } from "../core/lint.ts";
 import { playwrightMissingError } from "../core/playwright.ts";
-import { resolveRumdlBin, runRumdl } from "../core/rumdl.ts";
+import { type RumdlRunner, type RumdlSkip, resolveRumdlBin, runRumdl } from "../core/rumdl.ts";
 import { mergeSarif, type SarifLog } from "../core/sarif.ts";
 import { syncDeck } from "../core/sync.ts";
 import { lintVisualDeck } from "../core/visual.ts";
@@ -18,10 +18,10 @@ export type LintCliResult = {
   rumdlSarif?: SarifLog;
 };
 
-/** `cwd` is where a skipped rumdl's hint says to run it from. */
+/** `cwd` is where a skipped rumdl's hint says to run it from; `rumdl` runs it, dek's by default. */
 export async function lintCommand(
   { project, decks, failed = [] }: DecksTarget,
-  options: { cwd: string; fix?: boolean; visual?: boolean },
+  options: { cwd: string; fix?: boolean; visual?: boolean; rumdl?: RumdlRunner },
 ): Promise<LintCliResult> {
   // dek.toml's findings once, then each deck's.
   const diagnostics: Diagnostic[] = [
@@ -30,19 +30,25 @@ export async function lintCommand(
   ];
   let rumdlSkip: SkippedCheck | undefined;
   let rumdlSarif: SarifLog | undefined;
+  // A rumdl that hung on one deck would hang on each, half a minute apiece.
+  let rumdlHung = false;
 
   for (const deck of decks) {
     if (options.fix) {
       syncDeck({ project, deck });
     }
     diagnostics.push(...lintDeck({ project, deck }));
-    const markdown = await runRumdl(deck.scriptPath);
-    diagnostics.push(...markdown.diagnostics);
-    if (markdown.skipped) {
-      rumdlSkip ??= rumdlSkipped(deck.scriptPath, options.cwd);
-    }
-    if (markdown.sarif) {
-      rumdlSarif = rumdlSarif ? mergeSarif(rumdlSarif, markdown.sarif) : markdown.sarif;
+    if (!rumdlHung) {
+      const markdown = await runRumdl(deck.scriptPath, options.rumdl);
+      diagnostics.push(...markdown.diagnostics);
+      // One entry for the run: the first reason, unless rumdl hung, which covers every deck after.
+      if (markdown.skipped && (!rumdlSkip || markdown.skipped.hung)) {
+        rumdlSkip = rumdlSkipped(deck.scriptPath, options.cwd, markdown.skipped);
+      }
+      rumdlHung = markdown.skipped?.hung === true;
+      if (markdown.sarif) {
+        rumdlSarif = rumdlSarif ? mergeSarif(rumdlSarif, markdown.sarif) : markdown.sarif;
+      }
     }
     if (options.visual) {
       const visual = await lintVisualDeck({ project, deck });
@@ -71,15 +77,28 @@ export async function lintCommand(
 
 const RUMDL_INSTALL = "bun add -d rumdl; or put rumdl on PATH, or set DEK_RUMDL to its path";
 
-/** Why rumdl gave no result: dek looks for it on PATH, in node_modules/.bin, and at DEK_RUMDL. */
-function rumdlSkipped(scriptPath: string, cwd: string): SkippedCheck {
+const RUMDL_HUNG =
+  "update or reinstall rumdl (`bun add -d rumdl@latest`), or set DEK_RUMDL to a rumdl that finishes; lint skips it for every deck after one it hangs on";
+
+/**
+ * Why rumdl gave no result: whether dek found it, on PATH, in node_modules/.bin, or at DEK_RUMDL,
+ * and the reason when dek knows it. One that hung would hang again, so its hint is not to rerun.
+ */
+function rumdlSkipped(scriptPath: string, cwd: string, skip: RumdlSkip): SkippedCheck {
   const bin = resolveRumdlBin();
   if (bin === undefined || !existsSync(bin)) {
     return { check: "rumdl", reason: "rumdl is not installed", hint: RUMDL_INSTALL };
   }
+  if (skip.hung) {
+    return {
+      check: "rumdl",
+      reason: skip.reason ?? "rumdl hung and was stopped",
+      hint: RUMDL_HUNG,
+    };
+  }
   return {
     check: "rumdl",
-    reason: "rumdl ran but gave no result",
+    reason: skip.reason ?? "rumdl ran but gave no result",
     hint: `run \`${shellQuote(bin)} check ${shellQuote(relative(cwd, scriptPath) || scriptPath)}\` to see why`,
   };
 }

package/src/cli/ls.ts

@@ -1,11 +1,12 @@
 import type { Diagnostic } from "../core/diagnostic.ts";
+import type { HiddenText } from "../core/foreign-text.ts";
 import { lintDeck, lintProject } from "../core/lint.ts";
 import { listSlides, type Project, type ProjectDeck } from "../core/resolve.ts";
 import { slideVideoSeconds, timelineSeconds } from "../core/timeline.ts";
 import { sectionTiming } from "../core/timing.ts";
 import { tryLoadCachedTimeline } from "../core/voice.ts";
 import { type SkippedCheck, skippedChecks } from "./result.ts";
-import type { DecksTarget, RefInfo } from "./scope.ts";
+import { type DecksTarget, hiddenField, hiddenInFiles, type RefInfo } from "./scope.ts";
 
 export type LsListResult = {
   kind: "list";
@@ -46,6 +47,8 @@ export type LsDeckResult = {
   skipped?: SkippedCheck[];
   /** Set when the deck is a ref. */
   ref?: RefInfo;
+  /** A ref's lines of script.md that hold characters a person cannot see. */
+  hidden?: HiddenText[];
 };
 
 /** The one deck in scope, a ref included, or else every deck of the project. */
@@ -58,6 +61,7 @@ export function lsCommand(target: DecksTarget): LsListResult | LsDeckResult {
         { check: "lint", reason: "a ref is read-only; its problems are not yours to fix" },
       ]),
       ref,
+      ...hiddenField(ref, hiddenInFiles(deck.dir, [deck.scriptPath])),
     };
   }
   if (deck) {

package/src/cli/main.ts

@@ -1,9 +1,13 @@
+import { parseCss } from "../core/css.ts";
+import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
 import { shellQuote } from "../core/escape.ts";
 import { either } from "../core/prose.ts";
 import { isRefName } from "../core/ref-name.ts";
-import { resolveProject } from "../core/resolve.ts";
-import { addressHint, deckWord, type HintDeck, withPlaceholderNote } from "./address.ts";
+import { type ProjectDeck, readDeckFile, resolveProject } from "../core/resolve.ts";
+import { takeUnsandboxed } from "../core/sandbox.ts";
+import { themeFacts } from "../core/theme-facts.ts";
+import { addressCommands, deckWord, type HintDeck, withPlaceholderNote } from "./address.ts";
 import {
   type AnySpec,
   type CliResult,
@@ -158,7 +162,7 @@ async function run(cwd: string, line: CommandLine): Promise<void> {
   }
   const scope = spec.scope;
   const target = scope
-    ? retypedWithDeck(line, cwd, () =>
+    ? retypedWithDeck(line, cwd, call, () =>
         resolveTarget(cwd, scope, {
           deck: call.deck,
           refs: spec.refs === true,
@@ -170,10 +174,13 @@ async function run(cwd: string, line: CommandLine): Promise<void> {
   const ctx = { cwd, flags: line.values, args: call.args, target };
   const data = await form.run?.(ctx);
   if (spec.kind === "result") {
-    writeSuccess({ command: call.name, data } as CliResult, {
+    // Said on stderr as Chromium drew without its sandbox, and kept here for --json.
+    const drawn = { ...(data as object), ...takeUnsandboxed() };
+    writeSuccess({ command: call.name, data: drawn } as CliResult, {
       json: line.values.json === true,
       format: line.values.format,
       cwd,
+      flags: line.values,
       ...(target?.deck && {
         deck: { name: target.ref?.name ?? target.deck.name, dir: target.deck.dir },
       }),
@@ -186,9 +193,10 @@ const NAMED_DECKS = 3;
 
 /**
  * `resolve`, with a missing deck hinted as the line that was typed, the deck named where the
- * command takes it: one command per deck of the project, so the hint runs as written.
+ * command takes it: one command per deck of the project that has what the line names, so the
+ * hint runs as written.
  */
-function retypedWithDeck<T>(line: CommandLine, cwd: string, resolve: () => T): T {
+function retypedWithDeck<T>(line: CommandLine, cwd: string, call: Call, resolve: () => T): T {
   try {
     return resolve();
   } catch (error) {
@@ -196,18 +204,43 @@ function retypedWithDeck<T>(line: CommandLine, cwd: string, resolve: () => T): T
       throw error;
     }
     const typed = `\`dekc ${line.typed.map(shellQuote).join(" ")}\``;
-    const [first] = error.decks;
+    const decks = error.decks.filter((deck) => runsIn(call, deck));
+    const [first] = decks;
     // Each command is retyped for one deck; where to find a name left as <deck> is said once.
-    const retyped = (deck: HintDeck) => addressHint(typed, deck, cwd, { note: false });
-    const hint = !first
-      ? "run `dekc new <name>` to make a deck"
-      : error.decks.length > NAMED_DECKS
-        ? `run ${retyped(first)}, or name another deck in place of ${deckWord(first.name)}; \`dekc ls\` lists them`
-        : `run ${either(error.decks.map(retyped))}`;
+    const retyped = (deck: HintDeck) => addressCommands(typed, deck, cwd, { note: false });
+    const hint =
+      error.decks.length === 0
+        ? "run `dekc new <name>` to make a deck"
+        : !first
+          ? "run `dekc ls`"
+          : decks.length > NAMED_DECKS
+            ? `run ${retyped(first)}, or name another deck in place of ${deckWord(first.name)}; \`dekc ls\` lists them`
+            : `run ${either(decks.map(retyped))}`;
     throw new DekError(error.message, { hint: withPlaceholderNote(hint), cause: error });
   }
 }
 
+/**
+ * Whether `call` finds in `deck` what it names: a section, the one `dekc mv` renames or the name
+ * script.md already gives it, and a layout of the deck's theme.
+ */
+function runsIn(call: Call, deck: ProjectDeck): boolean {
+  const { slug, old, layout } = call.args;
+  const has = (name: string | undefined) =>
+    deck.deck.sections.some((section) => section.slug === name);
+  return (
+    (slug === undefined || has(slug)) &&
+    (old === undefined || has(old) || has(call.args.new)) &&
+    (layout === undefined || themeLayouts(deck).includes(layout))
+  );
+}
+
+/** The layouts a deck's theme defines; none when it has no theme.css. */
+function themeLayouts(deck: ProjectDeck): string[] {
+  const css = readDeckFile(deck.dir, deckPaths(deck.dir).theme) ?? "";
+  return themeFacts(parseCss(css)).layouts.map((entry) => entry.name);
+}
+
 /** A session prints no result, so --json has nothing to shape, and a reader would wait forever. */
 function sessionJsonError(name: string): DekError {
   return new DekError(`${name} keeps running until stopped and prints no JSON`, {
@@ -220,6 +253,8 @@ function sessionJsonError(name: string): DekError {
  * prints once, here: as JSON when the line asks for it, even a line too broken to parse.
  */
 export async function main(argv: string[], cwd: string): Promise<void> {
+  // What a run before this one in the process drew is its own, even one that failed.
+  takeUnsandboxed();
   let json = wantsJson(argv);
   try {
     const line = parseCommandLine(argv);

package/src/cli/new.ts

@@ -3,13 +3,20 @@ import { join } from "node:path";
 import { loadConfig } from "../core/config.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
+import { type HiddenText, hiddenText } from "../core/foreign-text.ts";
 import { DECK_NAME_HINT, isDeckName } from "../core/path.ts";
 import { isRefName } from "../core/ref-name.ts";
 import { readDeckFile } from "../core/resolve.ts";
 import { readSourceIfExists } from "../core/safe-fs.ts";
 import { syncDeck } from "../core/sync.ts";
 import { applyPlan, deckPlan, nextSteps } from "./files.ts";
-import { type RefInfo, requireDeckFromCwd, requireProject, resolveTarget } from "./scope.ts";
+import {
+  hiddenField,
+  type RefInfo,
+  requireDeckFromCwd,
+  requireProject,
+  resolveTarget,
+} from "./scope.ts";
 
 export type NewResult = {
   name: string;
@@ -21,6 +28,11 @@ export type NewResult = {
   next: string[];
   /** Set when the theme came from a ref with no license. */
   warnings: string[];
+  /**
+   * A ref's theme's lines, now the new deck's theme.css, that hold characters a person cannot
+   * see: the copy is the deck's own, so they are its author's to remove.
+   */
+  hidden?: HiddenText[];
 };
 
 export function newCommand(options: { cwd: string; name: string; themeFrom?: string }): NewResult {
@@ -87,6 +99,7 @@ export function newCommand(options: { cwd: string; name: string; themeFrom?: str
             `${ref.name} has no license; ask its author before you present or share a deck built on its theme`,
           ]
         : [],
+    ...hiddenField(ref, ref ? hiddenText(theme, deckPaths(dir).theme) : []),
   };
 }
 

package/src/cli/ref.ts

@@ -1,3 +1,4 @@
+// biome-ignore lint/style/noRestrictedImports: rmdirSync, which takes packs/ and refs/ folders only while empty; removeInside would take what is in them.
 import { existsSync, lstatSync, readdirSync, readFileSync, rmdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { loadConfig } from "../core/config.ts";

package/src/cli/result.ts

@@ -1,10 +1,12 @@
 import type { Diagnostic, SkippedCheck } from "../core/diagnostic.ts";
 import { DekError } from "../core/error.ts";
+import { revealHidden } from "../core/foreign-text.ts";
 import { PLAYWRIGHT_INSTALL, type PlaywrightRunner, playwrightReady } from "../core/playwright.ts";
 import { addressHint, deckAround, type HintDeck } from "./address.ts";
 import { type CliResult, outputOf } from "./commands.ts";
+import type { FlagValues } from "./flags.ts";
 import { displayPath, formatError, formatErrorText } from "./format.ts";
-import { shouldColor, terminalSafe } from "./tty.ts";
+import { plainText, shouldColor, terminalSafe } from "./tty.ts";
 
 export type { CliResult, SkippedCheck };
 
@@ -41,6 +43,8 @@ export type WriteSuccessOptions = {
   cwd?: string;
   /** The one deck the command worked on, which hints that name no path are about. */
   deck?: HintDeck;
+  /** The flags it ran with, which a failure's rerun repeats where they change what is checked. */
+  flags?: FlagValues;
 };
 
 /** Where a run's hints are read: the directory it ran in, and the deck it worked on, if one. */
@@ -86,7 +90,7 @@ export function writeSuccess(original: CliResult, options: WriteSuccessOptions):
   const { cwd } = options;
   const addressed = cwd === undefined ? original : addressResult(original, { cwd, ...options });
   const result = cwd === undefined ? addressed : displayPaths(addressed, cwd);
-  const failed = output.failure?.(result.data);
+  const failed = output.failure?.(result.data, options.flags ?? {});
   const failure =
     failed?.hint === undefined || cwd === undefined
       ? failed
@@ -98,9 +102,13 @@ export function writeSuccess(original: CliResult, options: WriteSuccessOptions):
     const data = output.json ? output.json(result.data) : (result.data as object);
     process.stdout.write(`${JSON.stringify({ ...envelope, ...data })}\n`);
   } else {
-    const text = formatText(result, shouldColor(process.stdout));
+    const plain = {
+      ...result,
+      data: plainStrings(result.data, isAboutRef(result.data)),
+    } as CliResult;
+    const text = formatText(plain, shouldColor(process.stdout));
     process.stdout.write(`${terminalSafe(text)}\n`);
-    const notes = output.notes?.(result.data, shouldColor(process.stderr));
+    const notes = output.notes?.(plain.data, shouldColor(process.stderr));
     if (notes) {
       process.stderr.write(`${terminalSafe(notes)}\n`);
     }
@@ -126,6 +134,36 @@ export function displayPaths(result: CliResult, cwd: string): CliResult {
   return { ...result, data: paths(result.data, (path) => displayPath(path, cwd)) } as CliResult;
 }
 
+/** A result that read a ref, as `ls`, `show`, and `theme` mark theirs. */
+function isAboutRef(data: unknown): boolean {
+  return typeof data === "object" && data !== null && "ref" in data && data.ref !== undefined;
+}
+
+/**
+ * Every string in a result as plainText, so the text a deck or a ref wrote reaches the terminal
+ * with no escape of its own; the text formatters paint dek's colors after. In a result about a
+ * ref, each character a person cannot see shows as `⟨U+XXXX⟩` too.
+ */
+function plainStrings<T>(value: T, reveal: boolean): T {
+  if (typeof value === "string") {
+    const plain = plainText(value);
+    return (reveal ? revealHidden(plain) : plain) as T;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => plainStrings(entry, reveal)) as T;
+  }
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, plainStrings(entry, reveal)]),
+    ) as T;
+  }
+  return value;
+}
+
 /** A result as text, without what did not run; see writeSuccess. */
 export function formatText(result: CliResult, color = false): string {
   return outputOf(result.command).text(result.data, color);

package/src/cli/scope.ts

@@ -1,10 +1,12 @@
 import { join, relative } from "node:path";
 import { DekError } from "../core/error.ts";
 import { shellName, shellQuote } from "../core/escape.ts";
+import { foreignLine, type HiddenText, hiddenText, MESSAGE_MAX } from "../core/foreign-text.ts";
 import {
   isRefName,
   packFile,
   parseRefSource,
+  type RefSource,
   refLicense,
   refReadOnlyError,
   refState,
@@ -14,6 +16,7 @@ import {
   locateDeck,
   type Project,
   type ProjectDeck,
+  readDeckFile,
   requireSection,
   resolveProject,
 } from "../core/resolve.ts";
@@ -222,6 +225,25 @@ export type RefInfo = {
 /** One deck to read: the project's own, or a ref. */
 export type ReadableDeck = DeckTarget & { ref?: RefInfo };
 
+/**
+ * `{ hidden }` when a ref's files hold characters a person cannot see, nothing otherwise. Only a
+ * ref's are reported: a deck of the project's own is its author's, emoji joiners and all.
+ */
+export function hiddenField(
+  ref: RefInfo | undefined,
+  found: HiddenText[],
+): { hidden?: HiddenText[] } {
+  return ref && found.length > 0 ? { hidden: found } : {};
+}
+
+/** What the files at `paths` in the deck hold that a person cannot see, file by file. */
+export function hiddenInFiles(deckDir: string, paths: string[]): HiddenText[] {
+  return paths.flatMap((path) => {
+    const text = readDeckFile(deckDir, path);
+    return text === undefined ? [] : hiddenText(text, path);
+  });
+}
+
 /**
  * What a command declares it works on, resolved: one deck or the decks in scope. Only a command
  * whose spec says `refs` reads a ref; it never writes, so a ref cannot reach a command that
@@ -287,7 +309,7 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
   if (!found) {
     const failed = snapshot.failed.find((entry) => entry.name === source.deck);
     if (failed) {
-      throw failed.error;
+      throw unreadableRef(failed.error, source);
     }
     throw new DekError(`ref "${source.name}" has no deck "${source.deck}"`, {
       path: dir,
@@ -304,3 +326,20 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
     ref: { name: source.name, rev: pinned, dir, license: refLicense(dir) },
   };
 }
+
+/**
+ * A ref whose script.md cannot be read. The error's hint would say how to fix the file, quoting
+ * it, and a ref is not the reader's to fix: the message stays, on one line, and the hint is dek's.
+ */
+function unreadableRef(error: Error, source: RefSource): DekError {
+  const fields = error instanceof DekError ? error : undefined;
+  return new DekError(foreignLine(error.message, MESSAGE_MAX), {
+    ...(fields?.path !== undefined ? { path: fields.path } : {}),
+    ...(fields?.line !== undefined ? { line: fields.line } : {}),
+    hint:
+      source.kind === "file"
+        ? "a ref is read-only, so its script.md is its author's to fix; ask them for a pack that reads, and add it with `dekc ref <file>.tgz`"
+        : `a ref is read-only, so its script.md is its author's to fix; pin a commit where it reads with \`dekc ref ${source.name}@<rev>\``,
+    cause: error,
+  });
+}