@hajimism/dek 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.3.0](https://github.com/hajimism/dek/compare/v0.2.2...v0.3.0) (2026-10-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* a DEK_ variable kept in a project's .env, such as DEK_VOICE_URL, no longer applies; set it in the shell, or use `engine` in voice.toml.
+* reading a private ref needs GITHUB_TOKEN or GH_TOKEN; being signed in to gh is not enough, and DEK_GH is gone. `GITHUB_TOKEN=$(gh auth token) dekc ref ...` does what dek did before. No token is sent to DEK_GITHUB_API.
+
+### Bug Fixes
+
+* draw pages in Chromium's sandbox with the network off ([550cc3a](https://github.com/hajimism/dek/commit/550cc3ab1c44005d4ef89420d3bb92a44a7da3a9))
+* ignore what the .env.*.local files set, and NODE_TLS_REJECT_UNAUTHORIZED from any .env ([da02b7c](https://github.com/hajimism/dek/commit/da02b7c4375b41ddd9ea2d879714950e5017cbc2))
+* keep a ref's title to one line of AGENTS.md ([c1b0b60](https://github.com/hajimism/dek/commit/c1b0b609a8710985c32988cff19b8cb65a0e6bc6))
+* run dekc, and every bun it starts, without the working directory's bunfig.toml ([0418909](https://github.com/hajimism/dek/commit/04189098b6975ba37506f039e865388205c5817b))
+* ship tsconfig.json, so a project's paths cannot take over dek's imports ([3eed8f0](https://github.com/hajimism/dek/commit/3eed8f0961a232a48be1cb06cd08dc03e121d026))
+* stop asking gh for a token, and send one only to api.github.com ([62c896b](https://github.com/hajimism/dek/commit/62c896ba1b69424e5426534040a087a2d42bef1a))
+* take DEK_ variables only from the environment, never from a .env ([7f4629b](https://github.com/hajimism/dek/commit/7f4629b3099e23a4c46b6261fa95627659fbfe51))
+
+
+### Documentation
+
+* **adr:** number the GHSA-mj6q-67q7-q923 decision after the ones on main ([4a888b0](https://github.com/hajimism/dek/commit/4a888b06594c188bf0efa88fb9111f48f70263e9))
+* **adr:** take GitHub tokens and DEK_ variables only from what the user sets ([c07fa4c](https://github.com/hajimism/dek/commit/c07fa4ceb7e1df69fb184ee8955f1819ee58a069))
+* record the ref title and shot fixes in ADR 12 and the architecture guide ([a6bfb93](https://github.com/hajimism/dek/commit/a6bfb9383c9c614c5c39f0e2f6817db24dc83e06))
+* say what a project cannot set for the Bun that runs dek, and what stays out of scope ([632efbb](https://github.com/hajimism/dek/commit/632efbbe4697a2175bf9cd0c8b5db77e53dbfa17))
+
 ## [0.2.2](https://github.com/hajimism/dek/compare/v0.2.1...v0.2.2) (2026-10-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",
@@ -11,6 +11,7 @@
   "files": [
     "src",
     "skills",
+    "tsconfig.json",
     "LICENSE",
     "README.md",
     "README.ja.md",

package/src/cli/env-file.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ansi, shouldColor, terminalSafe } from "./tty.ts";
+
+/**
+ * The files Bun may read into process.env from the working directory before dek starts: `.env`,
+ * `.env.local`, and the two for NODE_ENV, plain and `.local`. All of them are read whatever
+ * NODE_ENV is, so a change in which ones Bun picks cannot let a variable through.
+ */
+const ENV_FILES = [
+  ".env",
+  ".env.local",
+  ...["development", "production", "test"].flatMap((mode) => [
+    `.env.${mode}`,
+    `.env.${mode}.local`,
+  ]),
+];
+
+/**
+ * Every name dek takes only from the environment that a file holds, however the line around it is
+ * written: `K=v`, `export K=v`, `K: v`. Besides DEK_ variables, NODE_TLS_REJECT_UNAUTHORIZED: Bun
+ * reads it on each request, and with it a proxy that a `.env` named could read the token `dekc ref`
+ * sends. Other variables Bun acts on, such as HTTPS_PROXY, take effect before dek starts, and
+ * deleting them changes nothing.
+ */
+const NAME_RE = /DEK_[A-Z0-9_]*|NODE_TLS_REJECT_UNAUTHORIZED/gi;
+
+/**
+ * Takes out of `env` every variable in NAME_RE that a `.env` file in `cwd` may have set, and
+ * returns their names. Bun loads those files before dek runs, so a repository someone else wrote
+ * could otherwise choose the programs dek runs and the host `dekc ref` calls. These variables come
+ * only from the environment dek was started in. Under `--no-env-file`, which the dekc bin passes,
+ * Bun loaded nothing, so every one there is the user's own.
+ */
+export function dropEnvFileVariables(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  execArgv: readonly string[] = process.execArgv,
+): string[] {
+  if (execArgv.includes("--no-env-file")) {
+    return [];
+  }
+  const names = new Set<string>();
+  for (const file of ENV_FILES) {
+    let text: string;
+    try {
+      text = readFileSync(join(cwd, file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const [name] of text.matchAll(NAME_RE)) {
+      names.add(name.toUpperCase());
+    }
+  }
+  const dropped = [...names].filter((name) => env[name] !== undefined).sort();
+  for (const name of dropped) {
+    delete env[name];
+  }
+  return dropped;
+}
+
+/** What dek says on stderr about the variables `dropEnvFileVariables` took out. */
+export function envFileWarning(names: readonly string[], color = false): string {
+  const c = ansi(color);
+  const list = names.join(", ");
+  return [
+    `${c.yellow("warning:")} ignored ${list}: a .env file in this directory sets it, and dek takes it only from the environment`,
+    `  ${c.yellow("help:")} set it in the shell that runs dekc instead`,
+  ].join("\n");
+}
+
+/** The bin's first step: drop what a `.env` set, and say so. */
+export function ignoreEnvFileVariables(cwd: string): void {
+  const dropped = dropEnvFileVariables(cwd);
+  if (dropped.length > 0) {
+    process.stderr.write(`${terminalSafe(envFileWarning(dropped, shouldColor(process.stderr)))}\n`);
+  }
+}

package/src/cli.ts

@@ -1,4 +1,8 @@
-#!/usr/bin/env bun
+#!/usr/bin/env -S bun --no-env-file --config=/dev/null
+import { ignoreEnvFileVariables } from "./cli/env-file.ts";
 import { main } from "./cli/main.ts";
 
+// `bun ./node_modules/.bin/dekc` skips the line above and loads `.env` anyway. It reads
+// `bunfig.toml` too, and nothing here can undo a preload that has already run.
+ignoreEnvFileVariables(process.cwd());
 await main(Bun.argv.slice(2), process.cwd());

package/src/core/github.ts

@@ -3,7 +3,7 @@ import { DekError } from "./error.ts";
 /**
  * The two GitHub calls dekc ref needs: pin a rev to a commit, and download
  * that commit. DEK_GITHUB_API points them elsewhere, the way DEK_VOICE_URL
- * does for the voice engine.
+ * does for the voice engine, but a token only ever goes here.
  */
 const DEFAULT_API = "https://api.github.com";
 
@@ -16,9 +16,6 @@ const COMMIT_TIMEOUT_MS = 30 * 1000;
 /** A tarball near the size cap on a slow line still fits well inside this. */
 const TARBALL_TIMEOUT_MS = 10 * 60 * 1000;
 
-const SIGN_IN_HINT =
-  "if the repository is private, set GITHUB_TOKEN or run `gh auth login`, then run the command again";
-
 export type GithubOptions = {
   /** Covers the whole call, from connecting to the last byte of the body. */
   timeoutMs?: number;
@@ -32,22 +29,27 @@ function apiBase(): string {
   return (process.env.DEK_GITHUB_API ?? DEFAULT_API).replace(/\/+$/, "");
 }
 
-/** GITHUB_TOKEN, else what `gh auth token` prints, else nothing: public repositories need no token. */
-function token(): string | undefined {
-  const fromEnv = process.env.GITHUB_TOKEN?.trim();
-  if (fromEnv) {
-    return fromEnv;
-  }
-  try {
-    const result = Bun.spawnSync([process.env.DEK_GH ?? "gh", "auth", "token"], {
-      stdout: "pipe",
-      stderr: "ignore",
-    });
-    const printed = result.exitCode === 0 ? result.stdout.toString().trim() : "";
-    return printed || undefined;
-  } catch {
+/**
+ * The Authorization header for a call to `base`: the token the user set in GITHUB_TOKEN, else
+ * GH_TOKEN, and only for api.github.com. Public repositories need none. dek never asks `gh` for
+ * one: that token can write to every repository its owner can, and a tool that takes it unasked
+ * reads as credential theft to the machine's security software.
+ */
+export function authorization(
+  base: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  if (base !== DEFAULT_API) {
     return undefined;
   }
+  const token = env.GITHUB_TOKEN?.trim() || env.GH_TOKEN?.trim();
+  return token ? `Bearer ${token}` : undefined;
+}
+
+function signInHint(base: string): string {
+  return base === DEFAULT_API
+    ? "if the repository is private, set GITHUB_TOKEN to a token that can read it (`gh auth token` prints yours), then run the command again"
+    : "DEK_GITHUB_API points dek away from api.github.com, and a token goes only there; unset it to read a private repository";
 }
 
 /**
@@ -78,7 +80,7 @@ function deadline(what: string, timeoutMs: number): Deadline {
 
 function rateLimitHint(retryAfter: string | null): string {
   const wait = retryAfter ? `wait ${retryAfter}s, and ` : "";
-  return `${wait}set GITHUB_TOKEN or run \`gh auth login\` to raise the limit, then run the command again`;
+  return `${wait}set GITHUB_TOKEN to raise the limit, then run the command again`;
 }
 
 async function request(
@@ -87,14 +89,15 @@ async function request(
   accept: string,
   { signal, timeout, expired }: Deadline,
 ): Promise<Response> {
-  const auth = token();
+  const base = apiBase();
+  const auth = authorization(base);
   let response: Response;
   try {
-    response = await fetch(`${apiBase()}${path}`, {
+    response = await fetch(`${base}${path}`, {
       headers: {
         accept,
         "user-agent": "dek",
-        ...(auth ? { authorization: `Bearer ${auth}` } : {}),
+        ...(auth ? { authorization: auth } : {}),
       },
       redirect: "follow",
       signal,
@@ -112,7 +115,7 @@ async function request(
     return response;
   }
   if (response.status === 404) {
-    throw new DekError(`${what} not found on GitHub`, { hint: SIGN_IN_HINT });
+    throw new DekError(`${what} not found on GitHub`, { hint: signInHint(base) });
   }
   const retryAfter = response.headers.get("retry-after");
   if (
@@ -125,7 +128,7 @@ async function request(
   }
   if (response.status === 401 || response.status === 403) {
     throw new DekError(`GitHub refused access to ${what} (${response.status})`, {
-      hint: SIGN_IN_HINT,
+      hint: signInHint(base),
     });
   }
   throw new DekError(`GitHub answered ${response.status} for ${what}`, {

package/src/core/playwright-module.d.ts

@@ -33,14 +33,15 @@ declare module "playwright" {
     close(): Promise<void>;
   };
   export type Browser = {
-    newPage(options?: { viewport?: Viewport }): Promise<Page>;
+    newPage(options?: { viewport?: Viewport; offline?: boolean }): Promise<Page>;
     newContext(options?: {
       viewport?: Viewport;
       deviceScaleFactor?: number;
+      offline?: boolean;
     }): Promise<BrowserContext>;
     close(): Promise<void>;
   };
   export const chromium: {
-    launch(options?: { headless?: boolean }): Promise<Browser>;
+    launch(options?: { headless?: boolean; chromiumSandbox?: boolean }): Promise<Browser>;
   };
 }

package/src/core/playwright-visual.ts

@@ -50,9 +50,11 @@ export async function runVisualRequest<R extends VisualRequest>(
   browser: Browser,
   request: R,
 ): Promise<ResponseTo<R>> {
-  // A PPTX's pictures are shown full screen, so they are drawn at twice the slide's size.
+  // A PPTX's pictures are shown full screen, so they are drawn at twice the slide's size. A deck is
+  // self-contained (DEK020), so the page needs no network, and a ref's slide scripts get none.
   const context = await browser.newContext({
     viewport: request.viewport,
+    offline: true,
     ...(request.kind === "pptx" ? { deviceScaleFactor: 2 } : {}),
   });
   try {

package/src/core/playwright.ts

@@ -260,7 +260,7 @@ export async function runPlaywrightWorker<Request, Response>(
   }
   const request = await readWorkerRequest<Request>();
   try {
-    const browser = await playwright.chromium.launch({ headless: true });
+    const browser = await launchChromium(playwright.chromium);
     try {
       const response = await handle(browser, request);
       process.stdout.write(`${JSON.stringify(response)}\n`);
@@ -272,6 +272,19 @@ export async function runPlaywrightWorker<Request, Response>(
   }
 }
 
+/**
+ * Headless Chromium with its sandbox, which Playwright leaves off by default: slide scripts run in
+ * it, a ref's included. Where the sandbox cannot start, as in a container running as root, it
+ * runs without one rather than not at all.
+ */
+async function launchChromium(chromium: typeof import("playwright").chromium): Promise<Browser> {
+  try {
+    return await chromium.launch({ headless: true, chromiumSandbox: true });
+  } catch {
+    return await chromium.launch({ headless: true });
+  }
+}
+
 export async function defaultPlaywrightRunner(
   request: VisualRequest,
   options: SpawnTimeoutOptions = {},

package/src/core/slide-script-eval.ts

@@ -7,6 +7,7 @@ import {
   type SlideScriptProblem,
   staticProblems,
 } from "./slide-script.ts";
+import { BUN_FLAGS } from "./spawn.ts";
 import { suggest } from "./suggest.ts";
 
 /** One slide script as lint checks it: its source, and the slide's step keys to check `motion` by. */
@@ -149,7 +150,7 @@ const EVALUATOR_OPTIONS = { stdout: "pipe", stderr: "ignore", env: {} } as const
 
 function evaluatorCommand(): string[] {
   const worker = moduleFilePath(new URL("./slide-eval-worker.ts", import.meta.url));
-  return [process.execPath, "--no-install", worker];
+  return [process.execPath, ...BUN_FLAGS, worker];
 }
 
 /** A worker that was killed still wrote a line for every script it finished. */

package/src/core/spawn.ts

@@ -13,9 +13,16 @@ export async function awaitPiped(proc: {
   return { stdout, stderr, exitCode };
 }
 
+/**
+ * How dek runs bun: with no auto install, and without the working directory's `.env` or
+ * `bunfig.toml`, which a repository someone else wrote can commit to set variables or preload code.
+ * The dekc bin's shebang passes the last two to dek itself; a child does not inherit them.
+ */
+export const BUN_FLAGS = ["--no-install", "--no-env-file", "--config=/dev/null"];
+
 /** `bin` as a command line: a .ts worker runs under bun, anything else as is. */
 export function workerCommand(bin: string, args: string[] = []): string[] {
-  return bin.endsWith(".ts") ? ["bun", "--no-install", bin, ...args] : [bin, ...args];
+  return bin.endsWith(".ts") ? ["bun", ...BUN_FLAGS, bin, ...args] : [bin, ...args];
 }
 
 /** A browser that hangs must not hang dek; a whole visual run or capture fits well inside this. */

package/src/core/sync.ts

@@ -293,6 +293,25 @@ For commands, run \`dekc help --agent\`.
 `;
 }
 
+/** The longest ref title AGENTS.md shows: a title names a deck, it does not describe one. */
+const REF_TITLE_MAX = 80;
+
+/**
+ * A ref's title as it goes into AGENTS.md. Someone else wrote it, and agents read dek's block as
+ * dek's own guidance, so a title must not start a line of its own there, such as a heading or an
+ * instruction: line breaks and control characters become one space, and it is cut to
+ * REF_TITLE_MAX characters.
+ */
+function refTitleLine(title: string | undefined): string | undefined {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+  const line = title?.replace(/[\s\x00-\x1f\x7f-\x9f]+/gu, " ").trim();
+  if (!line) {
+    return undefined;
+  }
+  const chars = [...line];
+  return chars.length > REF_TITLE_MAX ? `${chars.slice(0, REF_TITLE_MAX - 1).join("")}…` : line;
+}
+
 /**
  * The refs dek.toml pins, one line each, so an agent knows which decks it may
  * read as models. Empty when there are none, leaving AGENTS.md as before. A
@@ -311,7 +330,7 @@ function referencesSection(root: string): string {
     return "";
   }
   const lines = refs.map((name) => {
-    const title = refTitle(refDir(root, name), parseRefSource(name).deck)?.title;
+    const title = refTitleLine(refTitle(refDir(root, name), parseRefSource(name).deck)?.title);
     return title ? `- \`${name}\`: ${title}` : `- \`${name}\``;
   });
   return `

package/src/video/worker.ts

@@ -21,8 +21,10 @@ async function capture(
   request: VideoCaptureRequest,
 ): Promise<VideoCaptureResponse> {
   mkdirSync(request.outDir, { recursive: true });
+  // A deck is self-contained (DEK020), so the page needs no network.
   const page = await browser.newPage({
     viewport: { width: request.viewport.width, height: request.viewport.height },
+    offline: true,
   });
   await loadVideoDoc(page, request.html);
 

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "allowJs": true,
+    "types": ["bun"],
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src", "tests"]
+}