@hajimism/dek 0.3.2 → 0.3.3

package/src/core/pack.ts

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { loadConfig } from "./config.ts";
+import { DekError } from "./error.ts";
+import { licenseText } from "./licenses.ts";
+import { type DistOptions, distFile } from "./path.ts";
+import { keepsInDeck, LICENSE_NAMES, MAX_SNAPSHOT_BYTES } from "./ref.ts";
+import { isRefDeckName } from "./ref-name.ts";
+import { followInside, requireInside, writeInside } from "./safe-fs.ts";
+
+/**
+ * A deck handed over as a file, to be read as a ref by someone who cannot reach it on GitHub:
+ * a gzipped tar of a project that holds only that deck, under a folder named for it. The deck
+ * keeps what `dekc ref` keeps of a repository; the project's dek.toml goes empty, so the
+ * sender's refs and voice settings stay home. Its LICENSE is the one `packLicense` picks.
+ */
+export async function packDeck(
+  project: { root: string },
+  deck: { name: string; dir: string },
+  options: { maxBytes?: number } = {},
+): Promise<Uint8Array> {
+  if (!isRefDeckName(deck.name)) {
+    throw new DekError(`deck "${deck.name}" cannot be read as a ref by that name`, {
+      path: deck.dir,
+      hint: "a ref names its deck with no space or @; rename the deck's folder, e.g. to 2026-10-talk, and pack it again",
+    });
+  }
+  // Each file by its path in the pack and where it really is, measured before any is read.
+  const sources: Array<readonly [string, string]> = deckFiles(deck.dir, project.root).map(
+    (path) =>
+      [`decks/${deck.name}/${path}`, requireInside(join(deck.dir, path), project.root)] as const,
+  );
+  const license = packLicense(project.root);
+  if (license?.path) {
+    sources.push([license.name, license.path]);
+  }
+  const maxBytes = options.maxBytes ?? MAX_SNAPSHOT_BYTES;
+  const size = sources.reduce((sum, [, real]) => sum + statSync(real).size, 0);
+  if (size > maxBytes) {
+    throw new DekError(
+      `deck "${deck.name}" is larger than a ref keeps, ${maxBytes / 1024 / 1024} MB`,
+      {
+        path: deck.dir,
+        hint: "a deck to read as a model should be far smaller; check its assets",
+      },
+    );
+  }
+  const files = new Map<string, Uint8Array>([["dek.toml", new Uint8Array()]]);
+  for (const [path, real] of sources) {
+    files.set(path, readFileSync(real));
+  }
+  if (license?.text !== undefined) {
+    files.set(license.name, new TextEncoder().encode(license.text));
+  }
+  const entries: Record<string, Uint8Array> = {};
+  for (const [path, bytes] of files) {
+    entries[`${deck.name}/${path}`] = bytes;
+  }
+  return new Bun.Archive(entries, { compress: "gzip" }).bytes();
+}
+
+/**
+ * The LICENSE a pack carries: the legal code `[pack] license` names, which says what the reader
+ * may do with a deck handed over on purpose; else the project's own LICENSE file; else none.
+ */
+function packLicense(
+  root: string,
+):
+  | { name: string; text: string; path?: undefined }
+  | { name: string; path: string; text?: undefined }
+  | undefined {
+  const id = loadConfig(join(root, "dek.toml")).pack?.license;
+  if (id) {
+    return { name: "LICENSE", text: licenseText(id) };
+  }
+  const name = LICENSE_NAMES.find((file) => isFile(join(root, file), root));
+  return name ? { name, path: requireInside(join(root, name), root) } : undefined;
+}
+
+/** Said to the sender, who can fix it, when a pack would go out with no license. */
+const NO_PACK_LICENSE =
+  'the pack carries no license, so its reader is told to ask you before reusing it; add `[pack] license = "CC0-1.0"` to dek.toml to let them reuse it freely, or put a LICENSE at the project root';
+
+/** `dekc pack`: write the deck's pack as dist/<deck>.tgz. */
+export async function writePack(
+  project: { root: string },
+  deck: { name: string; dir: string },
+  options: DistOptions = {},
+): Promise<{ outPath: string; warnings: string[] }> {
+  const bytes = await packDeck(project, deck);
+  const outPath = distFile(project, deck, "tgz", options);
+  writeInside(outPath, bytes, project.root);
+  return { outPath, warnings: packLicense(project.root) ? [] : [NO_PACK_LICENSE] };
+}
+
+/** What `deckFiles` looks at in the deck's own folder; dist/, .cache/, and voice/ are not read. */
+const DECK_TOP = new Set(["script.md", "theme.css", "slides", "assets"]);
+
+/**
+ * The deck's files a ref keeps, relative to the deck, in a stable order. A file or folder whose
+ * name starts with a dot stays behind; a link dek would not follow anywhere else is an error.
+ */
+function deckFiles(deckDir: string, root: string): string[] {
+  const found: string[] = [];
+  const walk = (rel: string) => {
+    const dir = requireInside(join(deckDir, rel), root);
+    for (const name of readdirSync(dir).sort()) {
+      if (name.startsWith(".") || (rel === "" && !DECK_TOP.has(name))) {
+        continue;
+      }
+      const path = rel === "" ? name : `${rel}/${name}`;
+      const real = requireInside(join(deckDir, path), root);
+      if (!existsSync(real)) {
+        throw new DekError(`${relative(root, join(deckDir, path))} is missing`, {
+          path: join(deckDir, path),
+          hint: "it is a symlink to nothing; remove it, or copy the file it meant in its place",
+        });
+      }
+      if (statSync(real).isDirectory()) {
+        walk(path);
+      } else if (keepsInDeck(path)) {
+        found.push(path);
+      }
+    }
+  };
+  walk("");
+  return found;
+}
+
+function isFile(path: string, root: string): boolean {
+  const real = followInside(path, root);
+  try {
+    return real !== undefined && statSync(real).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/core/ref-name.ts

@@ -2,11 +2,13 @@ import { DekError } from "./error.ts";
 
 /**
  * A ref is someone else's deck, kept as a read-only snapshot to read as a
- * model. dek.toml `[refs]` pins each one to a commit; the snapshot under
- * `refs/owner/repo/deck` is only a copy of that commit and can be fetched again.
+ * model. dek.toml `[refs]` pins each one: a deck on GitHub to a commit, a pack
+ * to a digest of its files. The snapshot under `refs/` is only a copy of what
+ * the pin names, fetched or unpacked again whenever it is missing.
  * This module only names refs; `ref.ts` fetches and stores them.
  */
-export type RefSource = {
+export type GithubRefSource = {
+  kind: "github";
   /** `owner/repo/deck`, the key in dek.toml `[refs]`. */
   name: string;
   owner: string;
@@ -18,13 +20,32 @@ export type RefSource = {
   path?: string;
 };
 
+/** A deck handed over as a file by `dekc pack`, committed as `packs/<deck>.tgz`. */
+export type FileRefSource = {
+  kind: "file";
+  /** `file/<deck>`, the key in dek.toml `[refs]`. */
+  name: string;
+  deck: string;
+};
+
+export type RefSource = GithubRefSource | FileRefSource;
+
+/** The first segment of a pack's ref name; no GitHub owner may take it, so refs/ never overlaps. */
+const PACK_OWNER = "file";
+
 const OWNER_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
 const REPO_RE = /^[A-Za-z0-9._-]+$/;
 const DECK_RE = /^[^/\\\s@]+$/;
 const SHA_RE = /^[0-9a-f]{40}$/;
+const DIGEST_RE = /^[0-9a-f]{64}$/;
 
 const REF_HINT =
-  "name a ref as owner/repo/deck, e.g. hajimism/dek/why-dek or hajimism/dek/why-dek@v1";
+  "name a ref as owner/repo/deck, e.g. hajimism/dek/why-dek or hajimism/dek/why-dek@v1, or a pack's as file/<deck>";
+
+/** Where a pack's ref keeps its pack, relative to the project root: committed, never ignored. */
+export function packFile(deck: string): string {
+  return `packs/${deck}.tgz`;
+}
 
 /** True for `owner/repo/deck[@rev]` or a GitHub link, which a deck name never is. */
 export function isRefName(arg: string): boolean {
@@ -34,14 +55,15 @@ export function isRefName(arg: string): boolean {
   if (arg.startsWith(".") || arg.startsWith("/") || arg.startsWith("~")) {
     return false;
   }
-  return arg.split("@")[0]?.split("/").length === 3;
+  const segments = arg.split("@")[0]?.split("/") ?? [];
+  return segments.length === 3 || (segments.length === 2 && segments[0] === PACK_OWNER);
 }
 
-/** A valid `owner/repo/deck` with no rev: the form dek.toml `[refs]` keys take. */
+/** A valid `owner/repo/deck` with no rev, or a pack's `file/<deck>`: the form dek.toml `[refs]` keys take. */
 export function isPlainRefName(name: string): boolean {
   try {
     const source = parseRefSource(name);
-    return source.rev === undefined && source.name === name;
+    return (source.kind === "file" || source.rev === undefined) && source.name === name;
   } catch {
     return false;
   }
@@ -51,6 +73,16 @@ export function isPinnedRev(rev: string): boolean {
   return SHA_RE.test(rev);
 }
 
+/** True when `pin` has the form a ref of this kind is pinned with: a commit, or a pack's digest. */
+export function isPinFor(source: RefSource, pin: string): boolean {
+  return source.kind === "file" ? DIGEST_RE.test(pin) : SHA_RE.test(pin);
+}
+
+/** True for a deck name a ref can carry: no slash, space, or @, and not . or .. */
+export function isRefDeckName(deck: string | undefined): deck is string {
+  return deck !== undefined && DECK_RE.test(deck) && deck !== "." && deck !== "..";
+}
+
 export function parseRefSource(input: string): RefSource {
   const trimmed = input.trim();
   if (/^https?:\/\//i.test(trimmed)) {
@@ -60,6 +92,17 @@ export function parseRefSource(input: string): RefSource {
   const path = at === -1 ? trimmed : trimmed.slice(0, at);
   const rev = at === -1 ? undefined : trimmed.slice(at + 1);
   const [owner, repo, deck, ...extra] = path.split("/");
+  if (owner === PACK_OWNER && deck === undefined) {
+    if (rev !== undefined || !isRefDeckName(repo)) {
+      throw new DekError(`"${input}" is not a ref name`, { hint: REF_HINT });
+    }
+    return { kind: "file", name: `${PACK_OWNER}/${repo}`, deck: repo };
+  }
+  if (owner?.toLowerCase() === PACK_OWNER && deck !== undefined) {
+    throw new DekError(`"${input}" is not a ref name`, {
+      hint: "file is kept for packs, so no GitHub owner of that name can be pinned; name a pack's ref as file/<deck>",
+    });
+  }
   const valid =
     extra.length === 0 &&
     owner !== undefined &&
@@ -68,15 +111,13 @@ export function parseRefSource(input: string): RefSource {
     REPO_RE.test(repo) &&
     repo !== "." &&
     repo !== ".." &&
-    deck !== undefined &&
-    DECK_RE.test(deck) &&
-    deck !== "." &&
-    deck !== ".." &&
+    isRefDeckName(deck) &&
     (rev === undefined || /^[^\s@]+$/.test(rev));
   if (!valid) {
     throw new DekError(`"${input}" is not a ref name`, { hint: REF_HINT });
   }
   return {
+    kind: "github",
     name: `${owner}/${repo}/${deck}`,
     owner,
     repo,
@@ -90,7 +131,7 @@ export function parseRefSource(input: string): RefSource {
  * link people copy from a browser. A branch name with a slash cannot be told
  * apart from the path, so such a branch goes after `@` instead.
  */
-function parseGithubUrl(input: string): RefSource {
+function parseGithubUrl(input: string): GithubRefSource {
   const url = new URL(input);
   const [owner = "", repo = "", kind, rev, ...rest] = url.pathname.split("/").filter(Boolean);
   const decks = rest.indexOf("decks");
@@ -106,5 +147,8 @@ function parseGithubUrl(input: string): RefSource {
     });
   }
   const source = parseRefSource(`${owner}/${repo.replace(/\.git$/, "")}/${deck}@${rev}`);
+  if (source.kind !== "github") {
+    throw new DekError(`"${input}" is not a link to a deck on GitHub`, { hint: REF_HINT });
+  }
   return { ...source, path: rest.slice(0, decks + 2).join("/") };
 }

package/src/core/ref.ts

@@ -11,6 +11,7 @@ import { outputDir } from "./safe-fs.ts";
 export {
   isPinnedRev,
   isRefName,
+  packFile,
   parseRefSource,
   type RefSource,
 } from "./ref-name.ts";
@@ -35,8 +36,10 @@ export const RefMeta = z.object({
 export type RefMeta = z.infer<typeof RefMeta>;
 
 export function refDir(root: string, name: string): string {
-  const { owner, repo, deck } = parseRefSource(name);
-  return join(root, "refs", owner, repo, deck);
+  const source = parseRefSource(name);
+  return source.kind === "file"
+    ? join(root, "refs", "file", source.deck)
+    : join(root, "refs", source.owner, source.repo, source.deck);
 }
 
 /** The marker of a snapshot, or nothing when it is missing or not one dek wrote. */
@@ -53,7 +56,7 @@ export function readRefMeta(dir: string): RefMeta | undefined {
   }
 }
 
-const LICENSE_NAMES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"];
+export const LICENSE_NAMES = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"];
 
 /** The snapshot's license file, relative to the snapshot, when the source had one. */
 export function refLicense(dir: string): string | null {
@@ -86,7 +89,12 @@ export function refState(project: { root: string; configPath: string }, name: st
 export type RepoFiles = Map<string, Blob>;
 
 /** Beyond this, a snapshot is refused: a deck to read is a few hundred kilobytes. */
-const MAX_SNAPSHOT_BYTES = 50 * 1024 * 1024;
+export const MAX_SNAPSHOT_BYTES = 50 * 1024 * 1024;
+
+/** A pack's tar, unzipped, may hold its files and their headers, not much more. */
+const MAX_PACK_TAR_BYTES = 2 * MAX_SNAPSHOT_BYTES;
+
+const PACK_HINT = "ask for a pack its author made with `dekc pack <deck>`";
 
 /**
  * Reads a GitHub tarball. Bun leaves out links; a path that is absolute, has
@@ -108,6 +116,64 @@ export async function readTarball(bytes: Uint8Array): Promise<RepoFiles> {
   return files;
 }
 
+/**
+ * Reads a pack from someone else. It is gunzipped through a count that stops at `maxTarBytes`
+ * before Bun takes any of it apart, so a small file that inflates without end is refused rather
+ * than held in memory; the tar is then read as a GitHub tarball is.
+ */
+export async function readPack(
+  bytes: Uint8Array,
+  limits: { maxBytes?: number; maxTarBytes?: number } = {},
+): Promise<RepoFiles> {
+  const maxBytes = limits.maxBytes ?? MAX_SNAPSHOT_BYTES;
+  const maxTarBytes = limits.maxTarBytes ?? MAX_PACK_TAR_BYTES;
+  if (bytes.byteLength > maxBytes) {
+    throw new DekError(`the pack is larger than ${formatMb(maxBytes)}`, { hint: PACK_HINT });
+  }
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    const reader = new Blob([new Uint8Array(bytes)])
+      .stream()
+      .pipeThrough(new DecompressionStream("gzip"))
+      .getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      size += value.byteLength;
+      if (size > maxTarBytes) {
+        await reader.cancel();
+        throw new DekError(`the pack unpacks to more than ${formatMb(maxTarBytes)}`, {
+          hint: PACK_HINT,
+        });
+      }
+      chunks.push(value);
+    }
+  } catch (error) {
+    if (error instanceof DekError) {
+      throw error;
+    }
+    throw new DekError("the file is not a pack: a pack is a gzipped tar", { hint: PACK_HINT });
+  }
+  const tar = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    tar.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return await readTarball(tar);
+  } catch {
+    throw new DekError("the file is not a pack: a pack is a gzipped tar", { hint: PACK_HINT });
+  }
+}
+
+function formatMb(bytes: number): string {
+  return bytes >= 1024 * 1024 ? `${bytes / 1024 / 1024} MB` : `${bytes} bytes`;
+}
+
 const DECK_SCRIPT_RE = /^(?:(.*)\/)?decks\/([^/]+)\/script\.md$/;
 
 /** The decks in a repository: each `decks/<name>/script.md` beside its project's dek.toml. */
@@ -119,14 +185,32 @@ function repoDecks(files: RepoFiles): Array<{ name: string; prefix: string }> {
   });
 }
 
+/** The name of the one deck a pack holds; a pack of none, or of more, is refused. */
+export function deckOfPack(files: RepoFiles): string {
+  const names = [...new Set(repoDecks(files).map((deck) => deck.name))].sort();
+  const [name, ...others] = names;
+  if (name === undefined) {
+    throw new DekError("the pack holds no deck", {
+      hint: `a pack is one deck beside a dek.toml; ${PACK_HINT}`,
+    });
+  }
+  if (others.length > 0) {
+    throw new DekError(`the pack holds more than one deck: ${names.join(", ")}`, {
+      hint: `a pack is one deck; ${PACK_HINT}`,
+    });
+  }
+  return name;
+}
+
 /** The directory of the project that holds the deck, as a prefix: "" or "sample/". */
 export function findDeckInRepo(files: RepoFiles, source: RefSource): string {
-  const repo = `${source.owner}/${source.repo}`;
+  const repo = source.kind === "file" ? "the pack" : `${source.owner}/${source.repo}`;
+  const path = source.kind === "github" ? source.path : undefined;
   const decks = repoDecks(files);
   const matches = decks.filter(
     (deck) =>
       deck.name === source.deck &&
-      (source.path === undefined || `${deck.prefix}decks/${deck.name}` === source.path),
+      (path === undefined || `${deck.prefix}decks/${deck.name}` === path),
   );
   const [match, ...others] = matches;
   if (!match) {
@@ -148,7 +232,7 @@ export function findDeckInRepo(files: RepoFiles, source: RefSource): string {
 }
 
 /** Inside the deck, only what reading it needs: not dist/, .cache/, or voice/. */
-function keepsInDeck(path: string): boolean {
+export function keepsInDeck(path: string): boolean {
   return (
     path === "script.md" ||
     path === "theme.css" ||
@@ -157,17 +241,19 @@ function keepsInDeck(path: string): boolean {
   );
 }
 
+/** The files a snapshot keeps, by their paths in it, and where the deck was in its source. */
+export type Snapshot = {
+  files: Map<string, Blob>;
+  license: string | undefined;
+  /** The deck's directory in the source repository or pack. */
+  path: string;
+};
+
 /**
- * Writes the snapshot of one deck at one commit under refs/, laid out as the
- * project it came from so it resolves like any dek project. It is written
- * beside the old one and swapped in, so a failure leaves the old one whole.
+ * What a snapshot keeps of a repository or a pack: its project's dek.toml, the deck's files that
+ * reading needs, and its license, laid out as the project it came from.
  */
-export async function installSnapshot(
-  root: string,
-  source: RefSource,
-  sha: string,
-  files: RepoFiles,
-): Promise<{ dir: string; license: string | null; path: string }> {
+export function pickSnapshot(files: RepoFiles, source: RefSource): Snapshot {
   const prefix = findDeckInRepo(files, source);
   const deckPrefix = `${prefix}decks/${source.deck}/`;
   const license =
@@ -190,10 +276,52 @@ export async function installSnapshot(
       hint: "a deck to read as a model should be far smaller; check its assets",
     });
   }
+  return { files: picked, license, path: `${prefix}decks/${source.deck}` };
+}
+
+/**
+ * What a pack's ref is pinned to: the sha256 of every file the snapshot keeps, in byte order of
+ * their paths, each as its path, a NUL, its size in decimal digits, a NUL, and its bytes. It
+ * follows the files, not the tarball, whose headers carry the time it was made.
+ */
+export async function snapshotDigest(snapshot: Snapshot): Promise<string> {
+  const hasher = new Bun.CryptoHasher("sha256");
+  const encoder = new TextEncoder();
+  const paths = [...snapshot.files.keys()].sort((a, b) =>
+    Buffer.compare(encoder.encode(a), encoder.encode(b)),
+  );
+  for (const path of paths) {
+    const blob = snapshot.files.get(path) ?? new Blob([]);
+    hasher.update(`${path}\0${blob.size}\0`);
+    hasher.update(new Uint8Array(await blob.arrayBuffer()));
+  }
+  return hasher.digest("hex");
+}
 
+/** Writes the snapshot of one deck at one commit under refs/; see writeSnapshot. */
+export async function installSnapshot(
+  root: string,
+  source: RefSource,
+  sha: string,
+  files: RepoFiles,
+): Promise<{ dir: string; license: string | null; path: string }> {
+  return writeSnapshot(root, source.name, sha, pickSnapshot(files, source));
+}
+
+/**
+ * Writes a snapshot under refs/, laid out as the project it came from so it resolves like any
+ * dek project, and marks it with what it is pinned to. It is written beside the old one and
+ * swapped in, so a failure leaves the old one whole.
+ */
+export async function writeSnapshot(
+  root: string,
+  name: string,
+  pin: string,
+  snapshot: Snapshot,
+): Promise<{ dir: string; license: string | null; path: string }> {
   // refs/ is dek's; a link on the way would aim the swap below, and its delete, elsewhere.
   const refsDir = join(root, "refs");
-  const dir = refDir(root, source.name);
+  const dir = refDir(root, name);
   outputDir(dirname(dir), root);
   if (isLink(dir)) {
     await rm(dir);
@@ -201,9 +329,9 @@ export async function installSnapshot(
   const suffix = `${process.pid}-${Date.now().toString(36)}`;
   const temp = join(refsDir, `.tmp-${suffix}`);
   const old = join(refsDir, `.old-${suffix}`);
-  const meta: RefMeta = { name: source.name, rev: sha, path: `${prefix}decks/${source.deck}` };
+  const meta: RefMeta = { name, rev: pin, path: snapshot.path };
   try {
-    for (const [path, blob] of picked) {
+    for (const [path, blob] of snapshot.files) {
       await mkdir(dirname(join(temp, path)), { recursive: true });
       await writeFile(join(temp, path), new Uint8Array(await blob.arrayBuffer()));
     }
@@ -224,7 +352,7 @@ export async function installSnapshot(
       await rm(old, { recursive: true, force: true });
     }
   }
-  return { dir, license: license ?? null, path: meta.path };
+  return { dir, license: snapshot.license ?? null, path: meta.path };
 }
 
 /** The snapshot deck's title and slide count, or nothing when it does not parse. */

package/src/core/sync.ts

@@ -336,7 +336,7 @@ function referencesSection(root: string): string {
   return `
 ## References
 
-Other people's decks, pinned in \`dek.toml\` \`[refs]\`, to read as models. They are read-only: read a slide with \`dekc show <ref> <slug>\`, then write your own in this deck's theme.
+Other people's decks, pinned in \`dek.toml\` \`[refs]\`, to read as models. They are read-only. To build a deck on a ref's layouts, start it with \`dekc new <name> --theme-from <ref>\`, which copies the ref's theme into it. Otherwise read a slide with \`dekc show <ref> <slug>\`, then write your own in this deck's theme.
 
 ${lines.join("\n")}
 `;

package/src/runtime/annotate-view.ts

@@ -671,10 +671,12 @@ export function createAnnotateView(options: {
       return;
     }
     event.stopPropagation();
-    if (event.target !== field) {
+    // Safari sends the key that commits or cancels a conversion after compositionend, with
+    // isComposing false; keyCode 229 still marks it as the input method's.
+    if (event.target !== field || event.isComposing || event.keyCode === 229) {
       return;
     }
-    if (event.key === "Enter" && !event.shiftKey && !event.isComposing) {
+    if (event.key === "Enter" && !event.shiftKey) {
       event.preventDefault();
       submit();
     } else if (event.key === "Escape") {