@hajimism/dek 0.3.3 → 0.4.0

package/src/cli/pptx.ts

@@ -1,20 +1,25 @@
-import { pptxDeck } from "../core/pptx.ts";
+import { type PptxLifted, pptxDeck } from "../core/pptx.ts";
 import type { DecksTarget } from "./scope.ts";
 
-/** One file per deck, a single deck included, as `dekc pdf` answers. */
-export type PptxCliResult = { outs: string[] };
+/**
+ * One file per deck, a single deck included, as `dekc pdf` answers, and what each file laid
+ * over its pictures, for the text output alone (`--json` is `outs`).
+ */
+export type PptxCliResult = { outs: string[]; lifted?: PptxLifted[] };
 
 export async function pptxCommand(
   { project, decks }: DecksTarget,
   options: { rootDist?: boolean; public?: boolean } = {},
 ): Promise<PptxCliResult> {
   const outs: string[] = [];
+  const lifted: PptxLifted[] = [];
   for (const entry of decks) {
     const done = await pptxDeck(
       { project, deck: entry },
       { rootDist: options.rootDist, public: options.public },
     );
     outs.push(done.outPath);
+    lifted.push(done.lifted);
   }
-  return { outs };
+  return { outs, lifted };
 }

package/src/cli/ref.ts

@@ -1,7 +1,8 @@
-import { existsSync, lstatSync, readdirSync, readFileSync, rmdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+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";
 import { DekError } from "../core/error.ts";
+import { isPlainWord, shellQuote } from "../core/escape.ts";
 import { downloadTarball, resolveRev } from "../core/github.ts";
 import {
   deckOfPack,
@@ -12,15 +13,17 @@ import {
   pickSnapshot,
   readPack,
   readTarball,
+  refDir,
   refLicense,
   refState,
   refTitle,
+  refuseLinkUnderPacks,
+  refuseLinkUnderRefs,
   type Snapshot,
   snapshotDigest,
   writeSnapshot,
 } from "../core/ref.ts";
-import type { FileRefSource, GithubRefSource } from "../core/ref-name.ts";
-import { readTextIfExists } from "../core/resolve.ts";
+import type { FileRefSource, GithubRefSource, RefSource } from "../core/ref-name.ts";
 import { readSourceIfExists, removeInside, requireInside, writeInside } from "../core/safe-fs.ts";
 import { writeAgentsMd } from "../core/sync.ts";
 import { setTableKey } from "../core/toml-keys.ts";
@@ -58,10 +61,12 @@ export type RefCliResult = RefAddResult | RefListResult | RefRmResult;
 export async function restoreRef(cwd: string, arg: string): Promise<void> {
   const source = parseRefSource(arg);
   const project = requireProject(cwd);
-  const { pinned, fetched } = refState(project, source.name);
+  const { pinned, dir, fetched } = refState(project, source.name);
   if (pinned === undefined || fetched) {
     return;
   }
+  // Said before a download that the write would refuse anyway.
+  refuseLinkUnderRefs(project.root, dir);
   if (source.kind === "file") {
     await unpackSnapshot(project.root, source, pinned);
     return;
@@ -88,7 +93,7 @@ async function unpackSnapshot(root: string, source: FileRefSource, pin: string):
   if ((await snapshotDigest(snapshot)) !== pin) {
     throw new DekError(`${rel} is not the pack ${source.name} is pinned to`, {
       path,
-      hint: `run \`dekc ref ${rel}\` to pin the pack that is there, or put back the one dek.toml pins`,
+      hint: `run \`dekc ref ${shellQuote(rel)}\` to pin the pack that is there, or put back the one dek.toml pins`,
     });
   }
   await writeSnapshot(root, source.name, pin, snapshot);
@@ -128,7 +133,10 @@ export async function addRef(cwd: string, arg: string): Promise<RefAddResult> {
     });
   }
   const project = requireProject(cwd);
+  refuseSharedFolders(project, source);
   const { pinned: from, dir, fetched } = refState(project, source.name);
+  // Said before a download that the write would refuse anyway.
+  refuseLinkUnderRefs(project.root, dir);
   const rev =
     source.rev !== undefined && isPinnedRev(source.rev)
       ? source.rev
@@ -141,7 +149,7 @@ export async function addRef(cwd: string, arg: string): Promise<RefAddResult> {
     changed = true;
   }
   if (from !== rev) {
-    const toml = readTextIfExists(project.configPath) ?? "";
+    const toml = readSourceIfExists(project.configPath, project.root) ?? "";
     writeInside(project.configPath, setTableKey(toml, "refs", source.name, rev), project.root);
     changed = true;
   }
@@ -166,6 +174,72 @@ export async function addRef(cwd: string, arg: string): Promise<RefAddResult> {
   };
 }
 
+/**
+ * Refuses a pin whose folders another pin, or a folder already on disk, takes. refs/ and packs/
+ * are named by the ref, and macOS and Windows read a name without its case, so `file/Talk` and
+ * `file/talk` would share one snapshot and one pack, and adding the second would replace the
+ * first's.
+ */
+function refuseSharedFolders(
+  project: { root: string; configPath: string },
+  source: RefSource,
+): void {
+  const { name } = source;
+  const other = Object.keys(loadConfig(project.configPath).refs ?? {}).find(
+    (pinned) => pinned !== name && folded(pinned) === folded(name),
+  );
+  if (other !== undefined) {
+    throw new DekError(`${name} would share its folders with ${other}, which dek.toml pins`, {
+      path: project.configPath,
+      hint: `a ref's folders are named without their case on macOS and Windows; to pin ${name} in its place, run \`dekc ref rm ${shellQuote(other)}\` first`,
+    });
+  }
+  const paths = [relative(project.root, refDir(project.root, name))];
+  if (source.kind === "file") {
+    paths.push(packFile(source.deck));
+  }
+  const left = paths
+    .map((path) => spelledOtherwise(project.root, path))
+    .find((path) => path !== undefined);
+  if (left !== undefined) {
+    const shown = isPlainWord(left) ? left : "another folder";
+    throw new DekError(
+      `${name} would share a folder with ${shown}, which is already in the project`,
+      {
+        path: join(project.root, left),
+        hint: "no ref in dek.toml pins it, so a ref removed by hand left it; delete it and add the ref again",
+      },
+    );
+  }
+}
+
+/** A name as a file system blind to case and form reads it: APFS folds ς as σ, and fi as fi. */
+function folded(name: string): string {
+  return name.normalize("NFKC").toUpperCase().toLowerCase();
+}
+
+/**
+ * The path, under `root`, of a folder or file a file system blind to case and form would read as
+ * `path` though it is spelled otherwise, found segment by segment.
+ */
+function spelledOtherwise(root: string, path: string): string | undefined {
+  let dir = root;
+  const walked: string[] = [];
+  for (const segment of path.split(sep)) {
+    const entries = existsSync(dir) && statSync(dir).isDirectory() ? readdirSync(dir) : [];
+    const other = entries.find((entry) => entry !== segment && folded(entry) === folded(segment));
+    if (other !== undefined) {
+      return join(...walked, other);
+    }
+    if (!entries.includes(segment)) {
+      return undefined;
+    }
+    walked.push(segment);
+    dir = join(dir, segment);
+  }
+  return undefined;
+}
+
 /** An argument that ends in .tgz or .tar.gz is a pack's path, never a ref name. */
 function isPackPath(arg: string): boolean {
   return /\.(tgz|tar\.gz)$/i.test(arg);
@@ -187,9 +261,12 @@ async function addPack(cwd: string, arg: string): Promise<RefAddResult> {
   }
   const read = await readPackFile(given, undefined);
   const { source, bytes } = read;
+  refuseSharedFolders(project, source);
   const rev = await snapshotDigest(read);
   const { pinned: from, dir, fetched } = refState(project, source.name);
   const stored = join(project.root, packFile(source.deck));
+  // Before the first write: the copy below is written by name.
+  refuseLinkUnderPacks(project.root, source.deck);
 
   let changed = false;
   if (!(fetched && from === rev)) {
@@ -201,7 +278,7 @@ async function addPack(cwd: string, arg: string): Promise<RefAddResult> {
     changed = true;
   }
   if (from !== rev) {
-    const toml = readTextIfExists(project.configPath) ?? "";
+    const toml = readSourceIfExists(project.configPath, project.root) ?? "";
     writeInside(project.configPath, setTableKey(toml, "refs", source.name, rev), project.root);
     changed = true;
   }
@@ -264,8 +341,13 @@ export function removeRef(cwd: string, arg: string): RefRmResult {
       hint: "run `dekc ref` to list refs",
     });
   }
+  // Before anything changes: the deletes below must not reach what a link there points to.
+  refuseLinkUnderRefs(project.root, dir);
+  if (source.kind === "file") {
+    refuseLinkUnderPacks(project.root, source.deck);
+  }
   if (pinned !== undefined) {
-    const toml = readFileSync(project.configPath, "utf8");
+    const toml = readSourceIfExists(project.configPath, project.root) ?? "";
     writeInside(
       project.configPath,
       setTableKey(toml, "refs", source.name, undefined),

package/src/cli/result.ts

@@ -13,15 +13,18 @@ export function skippedChecks(skipped: SkippedCheck[]): { skipped?: SkippedCheck
   return skipped.length > 0 ? { skipped } : {};
 }
 
+/** What `--visual` measures in a browser, as a hint or a reason names it. */
+export const RENDERED_RULES = "overflow, contrast, line breaks, and alignment";
+
 /**
- * The overflow and contrast rules, when a run leaves them out: why, and `rerun`, the command that
+ * The rules a browser measures, 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`;
+  const measure = `run \`${rerun}\` to measure ${RENDERED_RULES}`;
   return playwrightReady(options.runner)
     ? { check: "visual", reason: options.reason, hint: measure }
     : {

package/src/cli/scope.ts

@@ -1,14 +1,14 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { DekError } from "../core/error.ts";
+import { shellName, shellQuote } from "../core/escape.ts";
 import {
   isRefName,
   packFile,
   parseRefSource,
-  REF_MARKER,
-  readRefMeta,
   refLicense,
+  refReadOnlyError,
   refState,
+  requireProject,
 } from "../core/ref.ts";
 import {
   locateDeck,
@@ -19,7 +19,7 @@ import {
 } from "../core/resolve.ts";
 import { suggest } from "../core/suggest.ts";
 
-export { requireSection };
+export { requireProject, requireSection };
 
 export type Scope = {
   project: Project;
@@ -52,18 +52,6 @@ export type DecksTarget = {
   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) {
@@ -139,9 +127,7 @@ export function resolveScope(cwd: string, options: { deck?: string } = {}): Scop
     return { project };
   }
   if (isRefName(name)) {
-    throw new DekError(`"${name}" is a ref; refs are read-only`, {
-      hint: `start a deck on its theme with \`dekc new <name> --theme-from ${name}\`, or read it with \`dekc show ${name} <slug>\` and write what you need in your own deck's theme`,
-    });
+    throw refReadOnlyError(name);
   }
   const deck = project.decks.find((entry) => entry.name === name);
   if (!deck) {
@@ -149,10 +135,11 @@ export function resolveScope(cwd: string, options: { deck?: string } = {}): Scop
     if (failed) {
       throw failed.error;
     }
-    const guess = suggest(name, [
+    const near = suggest(name, [
       ...project.decks.map((entry) => entry.name),
       ...project.failed.map((entry) => entry.name),
     ]);
+    const guess = near === undefined ? undefined : shellName(near);
     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`",
@@ -277,18 +264,16 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
       hint:
         source.kind === "file"
           ? "add it from the pack you were sent: `dekc ref <file>.tgz`"
-          : `run \`dekc ref ${arg}\``,
+          : `run \`dekc ref ${shellQuote(arg)}\``,
     });
   }
   // What adds the ref again: a pack's ref from its file, any other from its name.
-  const again =
-    source.kind === "file"
-      ? `dekc ref ${packFile(source.deck)}`
-      : `dekc ref ${source.name}@${pinned}`;
+  const added = source.kind === "file" ? packFile(source.deck) : `${source.name}@${pinned}`;
+  const again = `dekc ref ${shellQuote(added)}`;
   if (source.kind === "github" && 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}`,
+      hint: `run \`dekc ref ${shellQuote(arg)}\` to pin that version, or drop @${source.rev}`,
     });
   }
   if (!fetched) {
@@ -311,7 +296,11 @@ function resolveRef(cwd: string, arg: string): ReadableDeck & { ref: RefInfo } {
   }
   return {
     project: snapshot,
-    deck: found,
+    // Read where it is, but cached in this project: nothing is written in a snapshot.
+    deck: {
+      ...found,
+      cache: { dir: join(project.root, ".cache", relative(project.root, dir)), root: project.root },
+    },
     ref: { name: source.name, rev: pinned, dir, license: refLicense(dir) },
   };
 }

package/src/cli/shot.ts

@@ -1,4 +1,5 @@
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import { parseMorphAt, shotMorph } from "../core/shot/morph.ts";
 import { type ShotMotion, shotMotion } from "../core/shot/motion.ts";
 import { type ShotFile, shotDeck, shotSheet } from "../core/shot/still.ts";
@@ -91,7 +92,7 @@ export function parseShotMode(options: ShotCommandOptions): ShotMode {
     if (slug) {
       refuse(
         "--sheet with a slug",
-        `--sheet tiles every slide; for one slide's beats, run \`dekc shot ${slug} --motion\``,
+        `--sheet tiles every slide; for one slide's beats, run \`dekc shot ${shellQuote(slug)} --motion\``,
       );
     }
     return { kind: "sheet" };

package/src/cli/text.ts

@@ -1,6 +1,8 @@
 // How each command's result reads as text; commands.ts says which command prints which.
 // The pieces the dev server's log shares, such as diagnostics and tables, are in format.ts.
 import type { Diagnostic, SkippedCheck } from "../core/diagnostic.ts";
+import { shellQuote } from "../core/escape.ts";
+import { unprinted } from "../core/prose.ts";
 import { packFile, parseRefSource } from "../core/ref-name.ts";
 import { formatClock } from "../core/timing.ts";
 import type { AnnotationsCliResult } from "./annotations.ts";
@@ -16,6 +18,7 @@ import type { MvResult } from "./mv.ts";
 import type { NewResult } from "./new.ts";
 import type { PackCliResult } from "./pack.ts";
 import type { PdfCliResult } from "./pdf.ts";
+import type { PptxCliResult } from "./pptx.ts";
 import type { RefCliResult } from "./ref.ts";
 import type { ShotCliResult } from "./shot.ts";
 import type { ShowResult } from "./show.ts";
@@ -230,6 +233,27 @@ export function formatPdf(data: PdfCliResult): string {
   return data.outs.map((path) => `wrote ${path}`).join("\n");
 }
 
+/**
+ * Each file written, and what it laid over its pictures, naming the slides that kept everything
+ * in the picture, which are the ones to rewrite toward shapes.
+ */
+export function formatPptx(data: PptxCliResult): string {
+  return data.outs
+    .flatMap((path, index) => {
+      const lifted = data.lifted?.[index];
+      if (!lifted) {
+        return [`wrote ${path}`];
+      }
+      const none = lifted.untouched.length > 0 ? `; nothing on ${lifted.untouched.join(", ")}` : "";
+      const count = (n: number, one: string) => `${n} ${one}${n === 1 ? "" : "s"}`;
+      return [
+        `wrote ${path}`,
+        `  laid ${count(lifted.shapes, "shape")} and ${count(lifted.pictures, "picture")} over the picture${none}`,
+      ];
+    })
+    .join("\n");
+}
+
 export function formatPack(data: PackCliResult): string {
   return [formatPdf(data), ...data.warnings.map((warning) => `warning: ${warning}`)].join("\n");
 }
@@ -346,6 +370,7 @@ export function formatTheme(data: ThemeResult): string {
     ...data.layouts.map(
       (layout) => `  ${layout.name}${layout.example === undefined ? "  (no example)" : ""}`,
     ),
+    ...(data.unprintedLayouts ? [`  and ${unprinted(data.unprintedLayouts)}`] : []),
     "",
     "CLASSES",
     `  ${data.classes.join(" ")}`,
@@ -360,7 +385,7 @@ export function formatTheme(data: ThemeResult): string {
     "TOKENS",
     ...data.tokens.map((token) => `  ${token.name.padEnd(width)}  ${token.value}`),
     "",
-    "Markup for a layout: dekc theme <layout>",
+    `Markup for a layout: dekc theme ${data.ref ? `${shellQuote(data.ref.name)} ` : ""}<layout>`,
   ].join("\n");
 }
 
@@ -437,7 +462,7 @@ export function formatRef(data: RefCliResult): string {
         head,
         ...data.warnings.map((warning) => `warning: ${warning}`),
         ...(data.pack ? [`commit ${data.pack}: a clone unpacks the ref from it`] : []),
-        `read it with \`dekc ls ${data.name}\` and \`dekc show ${data.name} <slug>\``,
+        `read it with \`dekc ls ${shellQuote(data.name)}\` and \`dekc show ${shellQuote(data.name)} <slug>\``,
       ].join("\n");
     }
     case "list":

package/src/cli/theme.ts

@@ -2,6 +2,8 @@ import { existsSync } from "node:fs";
 import { type CssToken, parseCss } from "../core/css.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
+import { isPlainWord } from "../core/escape.ts";
+import { listShown, unprinted } from "../core/prose.ts";
 import { readDeckFile } from "../core/resolve.ts";
 import { type ThemeLayout, themeFacts } from "../core/theme-facts.ts";
 import type { ReadableDeck, RefInfo } from "./scope.ts";
@@ -15,7 +17,10 @@ export type ThemeResult = {
   stateClasses: string[];
   /** The tokens every slide can `var()`. */
   tokens: CssToken[];
+  /** The layouts whose names are plain words. A name is the theme's text, maybe a pack's. */
   layouts: ThemeLayout[];
+  /** How many layouts the theme has whose names are no plain word, left out of `layouts`. */
+  unprintedLayouts?: number;
   /** Set when one layout was asked for; text output prints its example alone. */
   layout?: { name: string; example: string };
   /** Set when the deck is a ref. */
@@ -34,12 +39,15 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
   const { classes, stateClasses, layouts, tokens } = themeFacts(
     parseCss(readDeckFile(deck.dir, path) ?? ""),
   );
+  const printed = layouts.filter((layout) => isPlainWord(layout.name));
+  const left = layouts.length - printed.length;
   const result: ThemeResult = {
     path,
     classes: [...classes].sort(),
     stateClasses: [...stateClasses].sort(),
     tokens,
-    layouts,
+    layouts: printed,
+    ...(left > 0 ? { unprintedLayouts: left } : {}),
     ...(ref ? { ref } : {}),
   };
   if (!name) {
@@ -49,7 +57,13 @@ export function themeCommand({ deck, ref }: ReadableDeck, name?: string): ThemeR
   if (!layout) {
     throw new DekError(`layout "${name}" is not defined in theme.css`, {
       path,
-      hint: `use one of: ${layouts.map((entry) => entry.name).join(", ") || "(none)"}`,
+      hint: `use one of: ${
+        listShown(
+          layouts.map((entry) => entry.name),
+          isPlainWord,
+          unprinted,
+        ) || "(none)"
+      }`,
     });
   }
   if (layout.example === undefined) {

package/src/cli/voice.ts

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { DekError } from "../core/error.ts";
 import { deckProjectRoot } from "../core/path.ts";
-import { isCachedFile, writeInside } from "../core/safe-fs.ts";
+import { isCachedFile, requireInside, writeInside } from "../core/safe-fs.ts";
 import { loadVoiceDict, loadVoiceSettings, voiceCacheFile, writeVoiceDict } from "../core/voice.ts";
 import {
   engineBaseUrl,
@@ -91,8 +91,9 @@ export function pinVoice({ deck }: DeckTarget): VoiceCliResult {
   const pinDir = join(deck.dir, "voice", "pin");
   const pinTimeline = join(pinDir, "timeline.json");
   const pinAudio = join(pinDir, "master.wav");
-  writeInside(pinTimeline, readFileSync(timelinePath), root);
-  writeInside(pinAudio, readFileSync(audioPath), root);
+  // The folders on the way may be links too; what is pinned comes from inside the project.
+  writeInside(pinTimeline, readFileSync(requireInside(timelinePath, root)), root);
+  writeInside(pinAudio, readFileSync(requireInside(audioPath, root)), root);
   return { action: "pin", timelinePath: pinTimeline, audioPath: pinAudio };
 }