@hajimism/dek 0.1.0

package/src/cli/result.ts

@@ -0,0 +1,161 @@
+import type { Diagnostic, SkippedCheck } from "../core/diagnostic.ts";
+import { DekError } from "../core/error.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 { displayPath, formatError, formatErrorText } from "./format.ts";
+import { shouldColor, terminalSafe } from "./tty.ts";
+
+export type { CliResult, SkippedCheck };
+
+/** `{ skipped }` when any check was skipped, nothing otherwise: the field is present only when it matters. */
+export function skippedChecks(skipped: SkippedCheck[]): { skipped?: SkippedCheck[] } {
+  return skipped.length > 0 ? { skipped } : {};
+}
+
+/**
+ * The overflow and contrast rules, when a run leaves them out: why, and `rerun`, the command that
+ * measures them. Without Playwright, installing it comes first, whatever the reason was.
+ */
+export function visualSkipped(
+  rerun: string,
+  options: { reason: string; runner?: PlaywrightRunner },
+): SkippedCheck {
+  const measure = `run \`${rerun}\` to measure overflow and contrast`;
+  return playwrightReady(options.runner)
+    ? { check: "visual", reason: options.reason, hint: measure }
+    : {
+        check: "visual",
+        reason: "Playwright is not installed",
+        hint: `${PLAYWRIGHT_INSTALL}, then ${measure}`,
+      };
+}
+
+export type WriteSuccessOptions = {
+  json: boolean;
+  format?: string;
+  /** Print diagnostic paths relative to this directory. SARIF keeps absolute URIs. */
+  cwd?: string;
+  /** The one deck the command worked on, which hints that name no path are about. */
+  deck?: HintDeck;
+};
+
+/** Where a run's hints are read: the directory it ran in, and the deck it worked on, if one. */
+export type HintSite = { cwd: string; deck?: HintDeck };
+
+/**
+ * A result whose hints run as written from where the command ran: see `addressHint`. A diagnostic
+ * is about the deck its path is in; a skipped check, about the deck the command worked on.
+ */
+export function addressResult(result: CliResult, site: HintSite): CliResult {
+  const data = result.data as { diagnostics?: Diagnostic[]; skipped?: SkippedCheck[] };
+  if (data.diagnostics === undefined && data.skipped === undefined) {
+    return result;
+  }
+  const address = <T extends { hint?: string }>(entry: T, deck: HintDeck | undefined): T =>
+    entry.hint === undefined ? entry : { ...entry, hint: addressHint(entry.hint, deck, site.cwd) };
+  return {
+    ...result,
+    data: {
+      ...data,
+      ...(data.diagnostics && {
+        diagnostics: data.diagnostics.map((diagnostic) =>
+          address(diagnostic, diagnosticDeck(diagnostic) ?? site.deck),
+        ),
+      }),
+      ...(data.skipped && { skipped: data.skipped.map((entry) => address(entry, site.deck)) }),
+    },
+  } as CliResult;
+}
+
+function diagnosticDeck(diagnostic: Diagnostic): HintDeck | undefined {
+  return diagnostic.path === undefined ? undefined : deckAround(diagnostic.path);
+}
+
+/**
+ * Print a result: SARIF, the `--json` envelope, or text with what did not run on stderr.
+ * Only lint and check fail on an error diagnostic; a build or a listing reports what lint
+ * would say but still did its job: at the venue, a deck that shows is better than none. The
+ * error has the shape a thrown one has, so `--json` readers branch on `ok` and read `error` alike.
+ */
+export function writeSuccess(original: CliResult, options: WriteSuccessOptions): void {
+  const output = outputOf(original.command);
+  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 failure =
+    failed?.hint === undefined || cwd === undefined
+      ? failed
+      : { ...failed, hint: addressHint(failed.hint, options.deck, cwd) };
+  if (options.format === "sarif" && output.sarif) {
+    process.stdout.write(`${JSON.stringify(output.sarif(addressed.data))}\n`);
+  } else if (options.json) {
+    const envelope = failure ? { ok: false, error: failure } : { ok: true };
+    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));
+    process.stdout.write(`${terminalSafe(text)}\n`);
+    const notes = output.notes?.(result.data, shouldColor(process.stderr));
+    if (notes) {
+      process.stderr.write(`${terminalSafe(notes)}\n`);
+    }
+  }
+
+  if (failure) {
+    // Not process.exit: a pipe still holds the output, and exit would cut it at 64 KB.
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * Paths into the source tree (diagnostics, files dek created) relative to
+ * `cwd`, so an agent reads `slides/intro.html` instead of the same long
+ * absolute prefix on every line. Artifacts dek writes, such as `shot` or a
+ * build, stay absolute: they are meant to be opened as-is.
+ */
+export function displayPaths(result: CliResult, cwd: string): CliResult {
+  const paths = outputOf(result.command).paths;
+  if (!paths) {
+    return result;
+  }
+  return { ...result, data: paths(result.data, (path) => displayPath(path, cwd)) } as CliResult;
+}
+
+/** 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);
+}
+
+/**
+ * Print why a command line failed, in the shape a failed result has: `--json` readers get
+ * `{ ok: false, error }` on stdout, everyone else the error and its hint on stderr.
+ */
+export function writeFailure(error: unknown, options: { json: boolean; cwd: string }): void {
+  error = addressError(error, options.cwd);
+  if (options.json) {
+    const formatted = formatError(error, { cwd: options.cwd });
+    process.stdout.write(`${JSON.stringify({ ok: false, error: formatted })}\n`);
+  } else {
+    const color = shouldColor(process.stderr);
+    process.stderr.write(`${terminalSafe(formatErrorText(error, { color, cwd: options.cwd }))}\n`);
+  }
+  process.exitCode = 1;
+}
+
+/** A DekError whose hint runs as written from `cwd`, about the deck its path is in. */
+function addressError(error: unknown, cwd: string): unknown {
+  if (!(error instanceof DekError) || error.path === undefined || error.hint === undefined) {
+    return error;
+  }
+  const hint = addressHint(error.hint, deckAround(error.path), cwd);
+  return hint === error.hint
+    ? error
+    : new DekError(error.message, {
+        path: error.path,
+        hint,
+        ...(error.line !== undefined ? { line: error.line } : {}),
+        cause: error.cause,
+      });
+}

package/src/cli/scope.ts

@@ -0,0 +1,308 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DekError } from "../core/error.ts";
+import {
+  isRefName,
+  parseRefSource,
+  REF_MARKER,
+  readRefMeta,
+  refLicense,
+  refState,
+} from "../core/ref.ts";
+import {
+  locateDeck,
+  type Project,
+  type ProjectDeck,
+  requireSection,
+  resolveProject,
+} from "../core/resolve.ts";
+import { suggest } from "../core/suggest.ts";
+
+export { requireSection };
+
+export type Scope = {
+  project: Project;
+  deck?: ProjectDeck;
+};
+
+/** A deck whose script.md cannot be read, and why. */
+type UnreadableDeck = Project["failed"][number];
+
+/**
+ * What a command works on, which the CLI resolves before it runs: one deck, or every deck in
+ * scope (the project's, or the one named).
+ */
+export type DeckScope = "deck" | "decks";
+
+/** One deck of a project. */
+export type DeckTarget = { project: Project; deck: ProjectDeck };
+
+/** The decks in scope; `deck` is set when one was named or the command runs inside it. */
+export type DecksTarget = {
+  project: Project;
+  decks: ProjectDeck[];
+  deck?: ProjectDeck;
+  /**
+   * The decks in scope whose script.md cannot be read. Only a command that declares `unreadable`
+   * is handed one it named; any other is refused with its error, as before.
+   */
+  failed?: UnreadableDeck[];
+  /** Set when the deck is a ref. */
+  ref?: RefInfo;
+};
+
+export function requireProject(cwd: string): Project {
+  const project = resolveProject(cwd);
+  if (existsSync(join(project.root, REF_MARKER))) {
+    const name = readRefMeta(project.root)?.name ?? "<ref>";
+    throw new DekError("this directory is inside a ref; refs are read-only", {
+      path: project.root,
+      hint: `run dek from your own project instead: \`dekc show ${name} <slug>\``,
+    });
+  }
+  return project;
+}
+
+export function inferDeckName(project: Project, cwd: string): string | undefined {
+  const located = locateDeck(project.root, cwd);
+  if (!located) {
+    return undefined;
+  }
+  if (!isKnownDeckName(project, located.name)) {
+    return undefined;
+  }
+  return located.name;
+}
+
+function isKnownDeckName(project: Project, name: string): boolean {
+  return (
+    project.decks.some((deck) => deck.name === name) ||
+    project.failed.some((entry) => entry.name === name)
+  );
+}
+
+/**
+ * The deck a command's words name first, and the words left for the command. `max` is how many
+ * words the command takes without a deck. A ref name is always a deck. More words than the
+ * command takes make the first one a deck, found or not, so a typo in it is reported as a deck
+ * not found. Otherwise the first word is a deck when it names one of the project's and dek does
+ * not run inside a deck, where it names something in that deck instead. A command with
+ * subcommands takes a word that is no deck as a mistyped subcommand, never as a deck.
+ */
+export function peelDeckArg(
+  cwd: string,
+  words: string[],
+  grammar: { max: number; subcommands?: boolean },
+): { deck?: string; rest: string[] } {
+  const [first, ...rest] = words;
+  if (first === undefined) {
+    return { rest: words };
+  }
+  if (isRefName(first)) {
+    return { deck: first, rest };
+  }
+  const extra = words.length > grammar.max;
+  if (extra && grammar.subcommands !== true) {
+    return { deck: first, rest };
+  }
+  let project: Project;
+  try {
+    project = requireProject(cwd);
+  } catch {
+    return { rest: words };
+  }
+  if (!isKnownDeckName(project, first)) {
+    return { rest: words };
+  }
+  return extra || inferDeckName(project, cwd) === undefined
+    ? { deck: first, rest }
+    : { rest: words };
+}
+
+/** Whether a word names a deck of the project dek runs in, or a ref. */
+export function namesDeck(cwd: string, word: string): boolean {
+  if (isRefName(word)) {
+    return true;
+  }
+  try {
+    return isKnownDeckName(requireProject(cwd), word);
+  } catch {
+    return false;
+  }
+}
+
+export function resolveScope(cwd: string, options: { deck?: string } = {}): Scope {
+  const project = requireProject(cwd);
+  const name = options.deck ?? inferDeckName(project, cwd);
+  if (name === undefined) {
+    return { project };
+  }
+  if (isRefName(name)) {
+    throw new DekError(`"${name}" is a ref; refs are read-only`, {
+      hint: `read it with \`dekc show ${name} <slug>\`, then copy what you need into your own deck and rewrite it in your theme`,
+    });
+  }
+  const deck = project.decks.find((entry) => entry.name === name);
+  if (!deck) {
+    const failed = project.failed.find((entry) => entry.name === name);
+    if (failed) {
+      throw failed.error;
+    }
+    const guess = suggest(name, [
+      ...project.decks.map((entry) => entry.name),
+      ...project.failed.map((entry) => entry.name),
+    ]);
+    throw new DekError(`deck "${name}" not found`, {
+      path: join(project.root, "decks", name),
+      hint: guess ? `did you mean \`${guess}\`? run \`dekc ls\` for every deck` : "run `dekc ls`",
+    });
+  }
+  return { project, deck };
+}
+
+export function resolveDecks(
+  cwd: string,
+  options: { deck?: string; unreadable?: boolean } = {},
+): DecksTarget {
+  if (options.unreadable) {
+    const unreadable = unreadableInScope(cwd, options.deck);
+    if (unreadable) {
+      return { project: unreadable.project, decks: [], failed: [unreadable.failed] };
+    }
+  }
+  const scope = resolveScope(cwd, options);
+  if (scope.deck) {
+    return { project: scope.project, decks: [scope.deck], deck: scope.deck };
+  }
+  const { failed } = scope.project;
+  return {
+    project: scope.project,
+    decks: scope.project.decks,
+    ...(failed.length > 0 && { failed }),
+  };
+}
+
+/** The one deck in scope, named or around `cwd`, when its script.md cannot be read. */
+function unreadableInScope(
+  cwd: string,
+  deck: string | undefined,
+): { project: Project; failed: UnreadableDeck } | undefined {
+  const project = requireProject(cwd);
+  const name = deck ?? inferDeckName(project, cwd);
+  const failed = project.failed.find((entry) => entry.name === name);
+  return failed ? { project, failed } : undefined;
+}
+
+/**
+ * A deck command run where no deck is in scope. It carries the project's decks, so the CLI, which
+ * knows the command line, can hint that line with each one named.
+ */
+export class DeckRequiredError extends DekError {
+  readonly decks: ProjectDeck[];
+
+  constructor(cwd: string, decks: ProjectDeck[]) {
+    super("not inside a deck directory; pass a deck name", {
+      path: cwd,
+      hint: "pass a deck name or --deck <name>",
+    });
+    this.decks = decks;
+  }
+}
+
+function requireDeck(scope: Scope, cwd: string): ProjectDeck {
+  if (scope.deck) {
+    return scope.deck;
+  }
+  throw new DeckRequiredError(cwd, scope.project.decks);
+}
+
+export function requireDeckFromCwd(cwd: string, deck?: string): DeckTarget {
+  const scope = resolveScope(cwd, { deck });
+  return { project: scope.project, deck: requireDeck(scope, cwd) };
+}
+
+/** Where a ref came from, returned by the commands that read one. */
+export type RefInfo = {
+  name: string;
+  rev: string;
+  /** The snapshot directory. */
+  dir: string;
+  /** The snapshot's license file, or null when the source had none. */
+  license: string | null;
+};
+
+/** One deck to read: the project's own, or a ref. */
+export type ReadableDeck = DeckTarget & { ref?: RefInfo };
+
+/**
+ * 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
+ * would change it. For every other command resolveScope refuses a ref.
+ */
+export function resolveTarget(cwd: string, scope: "deck", options?: TargetOptions): ReadableDeck;
+export function resolveTarget(cwd: string, scope: "decks", options?: TargetOptions): DecksTarget;
+export function resolveTarget(
+  cwd: string,
+  scope: DeckScope,
+  options?: TargetOptions,
+): ReadableDeck | DecksTarget;
+export function resolveTarget(
+  cwd: string,
+  scope: DeckScope,
+  options: TargetOptions = {},
+): ReadableDeck | DecksTarget {
+  const ref =
+    options.refs === true && options.deck !== undefined && isRefName(options.deck)
+      ? resolveRef(cwd, options.deck)
+      : undefined;
+  if (scope === "deck") {
+    return ref ?? requireDeckFromCwd(cwd, options.deck);
+  }
+  return ref
+    ? { project: ref.project, decks: [ref.deck], deck: ref.deck, ref: ref.ref }
+    : resolveDecks(cwd, { deck: options.deck, unreadable: options.unreadable === true });
+}
+
+/** How a command's spec asks for its decks; see `refs` and `unreadable` there. */
+type TargetOptions = { deck?: string; refs?: boolean; unreadable?: boolean };
+
+function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
+  const source = parseRefSource(arg);
+  const project = requireProject(cwd);
+  const { pinned, dir, fetched } = refState(project, source.name);
+  if (pinned === undefined) {
+    throw new DekError(`ref "${source.name}" is not added`, {
+      path: project.configPath,
+      hint: `run \`dekc ref ${arg}\``,
+    });
+  }
+  if (source.rev !== undefined && source.rev !== pinned) {
+    throw new DekError(`"${arg}" is not the pinned version, ${pinned.slice(0, 7)}`, {
+      path: project.configPath,
+      hint: `run \`dekc ref ${arg}\` to pin that version, or drop @${source.rev}`,
+    });
+  }
+  if (!fetched) {
+    throw new DekError(`ref "${source.name}" is not fetched`, {
+      path: dir,
+      hint: `run \`dekc ref ${source.name}@${pinned}\``,
+    });
+  }
+  const snapshot = resolveProject(dir);
+  const found = snapshot.decks.find((entry) => entry.name === source.deck);
+  if (!found) {
+    const failed = snapshot.failed.find((entry) => entry.name === source.deck);
+    if (failed) {
+      throw failed.error;
+    }
+    throw new DekError(`ref "${source.name}" has no deck "${source.deck}"`, {
+      path: dir,
+      hint: `run \`dekc ref ${source.name}@${pinned}\` to fetch it again`,
+    });
+  }
+  return {
+    project: snapshot,
+    deck: found,
+    ref: { name: source.name, rev: pinned, dir, license: refLicense(dir) },
+  };
+}

package/src/cli/serve.ts

@@ -0,0 +1,125 @@
+import { type DevServer, startDevServer } from "../server/dev.ts";
+import { generateRemotePassword, remoteBanner } from "../server/lan.ts";
+import { PAIRING_TTL_MS } from "../server/pairing.ts";
+import { keepDevServer } from "./keep-alive.ts";
+import { qrMatrix, renderQr } from "./qr.ts";
+import { shouldColor } from "./tty.ts";
+
+export async function serveCommand(options: {
+  cwd: string;
+  deck?: string;
+  remote?: boolean;
+  visual?: boolean;
+  port?: number;
+}): Promise<void> {
+  await runDevSession(
+    {
+      cwd: options.cwd,
+      deck: options.deck,
+      remote: options.remote === true,
+      visual: options.visual === true,
+      ...(options.port !== undefined ? { port: options.port } : {}),
+    },
+    devSessionView,
+  );
+}
+
+type SessionView = { banner: string; pairPath: string };
+
+/** What `dekc` prints once up, and which presenter view a phone pairs into. */
+export function devSessionView(
+  server: Pick<DevServer, "url" | "remoteUrls" | "deckDir" | "decks">,
+  password: string | undefined,
+): SessionView {
+  const presenterPaths = server.deckDir
+    ? ["presenter"]
+    : server.decks.map((name) => `decks/${name}/presenter`);
+  return {
+    banner: devBanner(server.url, server.remoteUrls, { password, presenterPaths }),
+    // One deck pairs straight into its presenter view; several, into the list to pick from.
+    pairPath: presenterPaths.length === 1 ? (presenterPaths[0] as string) : "",
+  };
+}
+
+/**
+ * Start the dev server, print where to open it, offer a phone the presenter view, and serve until
+ * stopped. `show` says what to print once the server is up, and which path a QR code opens.
+ */
+export async function runDevSession(
+  options: Omit<Parameters<typeof startDevServer>[0], "password">,
+  show: (server: DevServer, password: string | undefined) => SessionView,
+): Promise<void> {
+  const password = options.remote === true ? generateRemotePassword() : undefined;
+  const server = await startDevServer({ ...options, password });
+  const { banner, pairPath } = show(server, password);
+  process.stdout.write(`${banner}\n`);
+  offerPairing(server, pairPath);
+  await keepDevServer(server);
+}
+
+type Terminal = {
+  out: { isTTY?: boolean; write(text: string): unknown };
+  input: { isTTY?: boolean; on(event: "data", listener: (chunk: Buffer) => void): unknown };
+  color: boolean;
+};
+
+/**
+ * With --remote, a QR code a phone scans to open `path` as the presenter, and a new one each
+ * time Enter is pressed, for the next device. Only on a terminal: in a pipe or a log nobody can
+ * scan it, and the code in it would only sit there.
+ */
+export function offerPairing(
+  server: Pick<DevServer, "remoteUrls" | "pair">,
+  path: string,
+  terminal: Terminal = {
+    out: process.stdout,
+    input: process.stdin,
+    color: shouldColor(process.stdout),
+  },
+): void {
+  const pair = server.pair;
+  if (!pair || terminal.out.isTTY !== true) {
+    return;
+  }
+  const host = server.remoteUrls.find((url) => !url.includes("127.0.0.1"));
+  if (!host) {
+    terminal.out.write("\nno LAN address, so no QR code; connect to the network the phone is on\n");
+    return;
+  }
+  const print = (): void => {
+    terminal.out.write(`\n${pairingBlock({ host, path, code: pair(), color: terminal.color })}\n`);
+  };
+  print();
+  if (terminal.input.isTTY === true) {
+    terminal.input.on("data", (chunk) => {
+      if (/[\r\n]/.test(chunk.toString())) {
+        print();
+      }
+    });
+  }
+}
+
+/** The QR code for one pairing, and what it does; the code is never printed as text. */
+export function pairingBlock(options: {
+  host: string;
+  path: string;
+  code: string;
+  color: boolean;
+}): string {
+  const url = new URL(options.path, options.host);
+  url.searchParams.set("pair", options.code);
+  const what = options.path
+    ? "scan to open the presenter view on a phone"
+    : "scan to pick a deck as the presenter on a phone";
+  const minutes = PAIRING_TTL_MS / 60_000;
+  return `${renderQr(qrMatrix(url.href), { color: options.color })}\n${what} · works once, within ${minutes} minutes · Enter makes a new code`;
+}
+
+/** What the dev server prints on start: where to open it, then the keys nobody can see. */
+export function devBanner(
+  url: string,
+  remoteUrls: string[],
+  options: Parameters<typeof remoteBanner>[2],
+): string {
+  return `${remoteBanner(url, remoteUrls, options)}\n\np presenter view · s slide rail · Ctrl-C stops the server`;
+}