@hajimism/dek 0.1.0

package/src/cli/files.ts

@@ -0,0 +1,309 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { bundledTheme } from "../core/bundled-theme.ts";
+import { deckPaths } from "../core/deck-paths.ts";
+import { DekError } from "../core/error.ts";
+import { walkUp } from "../core/optional.ts";
+import { PLAYWRIGHT_INSTALL } from "../core/playwright.ts";
+import { readSourceIfExists, writeInside } from "../core/safe-fs.ts";
+import { formatVoiceToml } from "../core/voice.ts";
+
+export function defaultTheme(): string {
+  return bundledTheme();
+}
+
+export function defaultToml(): string {
+  return "# dek project\n";
+}
+
+/**
+ * What dek keeps for itself under .dek/ while it runs: the dev server's lock, and the marks left
+ * while rehearsing. Neither belongs in the repository.
+ */
+const LOCAL_STATE = [".dek/server.json", ".dek/marks.json"];
+
+export function defaultGitignore(): string {
+  return `# dek
+dist/
+.cache/
+${LOCAL_STATE.join("\n")}
+node_modules/
+refs/
+`;
+}
+
+/** The lines that ignore `entry` whole or through .dek/, with or without a leading slash. */
+const ignores = (entry: string): string[] =>
+  [entry, ".dek", ".dek/", ".dek/*", ".dek/**"].flatMap((line) => [line, `/${line}`]);
+
+/**
+ * Add what dek keeps for itself to the project's .gitignore, for a project made before dek kept
+ * it; whether the file changed. A project with no .gitignore is left without one.
+ */
+export function ignoreLocalState(root: string): boolean {
+  const path = join(root, ".gitignore");
+  const current = readSourceIfExists(path, root);
+  if (current === undefined) {
+    return false;
+  }
+  const lines = new Set(current.split("\n").map((line) => line.trim()));
+  const missing = LOCAL_STATE.filter((entry) => !ignores(entry).some((line) => lines.has(line)));
+  if (missing.length === 0) {
+    return false;
+  }
+  const separator = current === "" || current.endsWith("\n") ? "" : "\n";
+  writeInside(path, `${current}${separator}${missing.join("\n")}\n`, root);
+  return true;
+}
+
+export function defaultRumdl(): string {
+  return `# Markdown rules for script.md
+# ## is a slide. Frontmatter is allowed. Keep heading skips, line length, and broken links.
+[global]
+disable = ["MD041"]
+`;
+}
+
+/** How to install dek into a project. The package is `@hajimism/dek`; its command is `dekc`. */
+const INSTALL_DEK = "bun add -d @hajimism/dek";
+
+/**
+ * The starter script: short, but a real talk, so the first `dekc ls` already
+ * shows sections, beats, and an estimate against the budget. A deck with a
+ * voice starts in Japanese, the language dek's voice reads; any other in English.
+ */
+export function defaultScript(title: string, lang: "en" | "ja" = "en"): string {
+  return `---
+# yaml-language-server: $schema=../../.dek/schema.json
+title: ${JSON.stringify(title)}
+duration: 1m
+---
+${STARTER_BODY[lang]}`;
+}
+
+const STARTER_BODY = {
+  en: `
+## intro
+
+Hello, and thank you for coming.
+This is a starter script: read it, then make it your own talk.
+
+> A blockquote is a note to yourself. It is neither spoken nor timed.
+
+## How this file becomes slides {#how-it-works}
+
+Every paragraph you write here is something you will say out loud.
+
+### One heading, one slide {#slides}
+
+Each level-two heading is one slide,
+and the paragraphs under it are what you say while it is on screen.
+
+### One beat, one pause {#beats}
+
+Each level-three heading is a beat:
+a pause in the speaking, and a moment where the screen can move on.
+
+## The clock {#timing}
+
+dek estimates how long the talk takes from these words,
+and checks the estimate against the duration at the top of this file.
+Run \`dekc ls\` to see the budget and the estimate side by side.
+
+## Your turn {#next}
+
+Rewrite these sections as your own talk.
+The dev server keeps the slides in step every time you save.
+`,
+  // No Latin words in what is spoken: the voice would need a reading for each one.
+  ja: `
+## intro
+
+こんにちは、今日は来てくださってありがとうございます。
+これは最初の台本です。読んだら、自分の話に書き換えてください。
+
+> 引用は自分へのメモです。読み上げられず、時間にも数えません。
+
+## 台本がスライドになるまで {#how-it-works}
+
+ここに書く段落は、どれも声に出して話す言葉です。
+
+### 見出しひとつで一枚 {#slides}
+
+二階層目の見出しがスライド一枚になり、
+その下の段落は、そのスライドを映している間に話す内容です。
+
+### ビートひとつで一呼吸 {#beats}
+
+三階層目の見出しはビートです。
+話の区切りであり、画面が次へ進める瞬間でもあります。
+
+## 時間 {#timing}
+
+話にかかる時間は、ここに書いた言葉から見積もられます。
+その見積もりを、ファイルの先頭にある持ち時間と照らし合わせます。
+
+> \`dekc ls\` で持ち時間と見積もりを並べて見る。
+
+## あなたの番です {#next}
+
+これらのセクションを、自分の話に書き換えてください。
+開発サーバーは、保存するたびにスライドを台本に合わせます。
+`,
+};
+
+/** A path init or new writes: a directory, or a file with what goes in it. */
+export type PlannedPath = { path: string; contents?: string };
+
+/** What applying a plan did: paths it wrote, and files it left because they were already there. */
+export type Applied = { created: string[]; kept: string[] };
+
+/**
+ * Writes what the plan has and the disk lacks, and never overwrites. A file
+ * that is already there is kept as it is, and listed when it differs from
+ * what the plan would write. Every path is checked before the first write,
+ * so a plan that cannot land leaves nothing behind.
+ */
+export function applyPlan(plan: PlannedPath[]): Applied {
+  const steps = plan.map((entry) => ({ entry, state: pathState(entry) }));
+  const created: string[] = [];
+  const kept: string[] = [];
+  for (const { entry, state } of steps) {
+    if (state === "kept") {
+      kept.push(entry.path);
+    }
+    if (state !== "missing") {
+      continue;
+    }
+    if (entry.contents === undefined) {
+      mkdirSync(entry.path, { recursive: true });
+    } else {
+      mkdirSync(dirname(entry.path), { recursive: true });
+      // Exclusive: a file, or a dangling link a repository planted, is never written through.
+      writeFileSync(entry.path, entry.contents, { flag: "wx" });
+    }
+    created.push(entry.path);
+  }
+  return { created, kept };
+}
+
+function pathState(entry: PlannedPath): "missing" | "same" | "kept" {
+  const kind = entry.contents === undefined ? "directory" : "file";
+  if (!placeable(entry.path, kind)) {
+    return "missing";
+  }
+  if (entry.contents === undefined) {
+    return "same";
+  }
+  return readFileSync(entry.path, "utf8") === entry.contents ? "same" : "kept";
+}
+
+/**
+ * Checks that each file can be written where it goes, before anything is: for
+ * files dek refreshes on every run, which a plan does not hold.
+ */
+export function checkFileSlots(paths: string[]): void {
+  for (const path of paths) {
+    placeable(path, "file");
+  }
+}
+
+/** Whether something is already at the path; throws when it is the wrong kind of thing. */
+function placeable(path: string, kind: "file" | "directory"): boolean {
+  if (!existsSync(path)) {
+    return false;
+  }
+  const isDir = statSync(path).isDirectory();
+  if (kind === "directory" && !isDir) {
+    throw new DekError("a file is in the way of a directory", {
+      path,
+      hint: "move the file aside and run again",
+    });
+  }
+  if (kind === "file" && isDir) {
+    throw new DekError("a directory is in the way of a file", {
+      path,
+      hint: "move the directory aside and run again",
+    });
+  }
+  return true;
+}
+
+/**
+ * A deck's files: its directories, the starter script, the theme it starts
+ * from, and voice settings when the project has a voice. The skeleton slides
+ * are sync's to write, once the theme they are drawn in is in place.
+ */
+export function deckPlan(
+  root: string,
+  name: string,
+  theme: string,
+  voice?: { engine: string; speaker: string; speed?: number },
+): PlannedPath[] {
+  const paths = deckPaths(join(root, "decks", name));
+  const script = defaultScript(name, voice ? "ja" : "en");
+  const plan: PlannedPath[] = [
+    { path: paths.slides },
+    { path: paths.assets },
+    { path: paths.script, contents: script },
+    { path: paths.theme, contents: theme },
+  ];
+  if (voice) {
+    plan.push(
+      { path: paths.voiceToml, contents: formatVoiceToml(voice) },
+      { path: paths.voiceDict, contents: "# voice dictionary\n" },
+    );
+  }
+  return plan;
+}
+
+/**
+ * The commands to run next, from `cwd`, exactly as they can be pasted: dek
+ * installed into the project unless it already resolves there, then into the
+ * deck to write the script and start the dev server, or a first deck to add.
+ */
+export function nextSteps(cwd: string, root: string, deckDir?: string): string[] {
+  const steps: string[] = [];
+  let at = cwd;
+  const go = (dir: string): void => {
+    const path = relative(at, dir);
+    if (path) {
+      steps.push(`cd ${shellQuote(path.length <= dir.length ? path : dir)}`);
+    }
+    at = dir;
+  };
+  if (!hasLocalDek(root)) {
+    go(root);
+    steps.push(INSTALL_DEK);
+  }
+  if (!deckDir) {
+    return [...steps, "bunx dekc new <name>"];
+  }
+  go(deckDir);
+  return [...steps, "$EDITOR script.md", "bunx dekc"];
+}
+
+/** Whether `bunx dekc` in the project runs this dek: bunx looks in node_modules/.bin up the tree. */
+function hasLocalDek(root: string): boolean {
+  return inNodeModules(root, ".bin", "dekc");
+}
+
+/**
+ * The Playwright install, until the project has it: shots, the PDF, and the rendered lint rules
+ * need it, and dek does not bring it along.
+ */
+export function playwrightStep(root: string): string | undefined {
+  return inNodeModules(root, "playwright", "package.json") ? undefined : PLAYWRIGHT_INSTALL;
+}
+
+/** Whether node_modules holds `path` in `root` or a directory above it, as Bun resolves it. */
+function inNodeModules(root: string, ...path: string[]): boolean {
+  return (
+    walkUp(root, (dir) => existsSync(join(dir, "node_modules", ...path)) || undefined) === true
+  );
+}
+
+/** `word` as one shell word: as it is when that is safe, else single-quoted. */
+export function shellQuote(word: string): string {
+  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
+}

package/src/cli/flags.ts

@@ -0,0 +1,295 @@
+import { parseArgs } from "node:util";
+import { DekError } from "../core/error.ts";
+import { acceptedFlags, isTypedCommand, subcommandAt } from "./commands.ts";
+
+/** A flag's shape: a switch, a string, or a value dek checks before any command runs. */
+type FlagSpec = { text: string } & (
+  | { type: "boolean"; short?: string }
+  | { type: "string"; value: string }
+  | { type: "int"; value: string; min: number; max?: number; example: string }
+  | { type: "number"; value: string; above: number; example: string }
+  | { type: "enum"; choices: readonly string[]; example: string; note?: string }
+);
+
+/**
+ * Every flag dek has: its type, the placeholder for its value, and what it means. Each command
+ * names the ones it takes; help, parsing, and the checks on a value all read this one table.
+ */
+export const FLAGS = {
+  json: { type: "boolean", text: "print the result, or the error, as JSON" },
+  help: { type: "boolean", short: "h", text: "show help; dekc help <command> for one command" },
+  version: { type: "boolean", short: "v", text: "print the dek version" },
+  agent: { type: "boolean", text: "the compact reference for agents" },
+  deck: { type: "string", value: "NAME", text: "target a deck by name from the project root" },
+  "theme-from": {
+    type: "string",
+    value: "DECK",
+    text: "copy that deck's theme.css instead of the project's",
+  },
+  remote: {
+    type: "boolean",
+    text: "serve on the LAN; the presenter view needs the password dek prints",
+  },
+  port: {
+    type: "int",
+    value: "N",
+    min: 1,
+    max: 65_535,
+    example: "dekc --port 3030",
+    text: "listen on this port (the OS picks one when omitted)",
+  },
+  fix: { type: "boolean", text: "create missing skeleton slides before linting" },
+  visual: {
+    type: "boolean",
+    text: "add the rendered rules: overflow and contrast (needs Playwright)",
+  },
+  shot: { type: "boolean", text: "also write a screenshot and return its path" },
+  voice: { type: "boolean", text: "also return each sentence's reading and duration" },
+  format: {
+    type: "enum",
+    choices: ["sarif"],
+    example: "dekc lint --format sarif",
+    note: "for JSON, pass --json",
+    text: "print diagnostics as SARIF",
+  },
+  before: { type: "string", value: "SLUG", text: "move the section before this one" },
+  after: { type: "string", value: "SLUG", text: "move the section after this one" },
+  step: { type: "string", value: "ID|N", text: "the beat to capture (default: the last)" },
+  to: { type: "string", value: "SLUG", text: "capture the transition into this slide" },
+  // A string: core/shot.ts reads and checks it, as the one place that knows the range.
+  at: {
+    type: "string",
+    value: "0..1",
+    text: "how far into the view transition (default 0.5); the slide's own entrance can run on past 1",
+  },
+  sheet: { type: "boolean", text: "tile every slide on contact sheets an agent reads in one look" },
+  motion: {
+    type: "boolean",
+    text: "a row for the arrival and each beat, held at moments through all it moves, ending as shot does",
+  },
+  accent: {
+    type: "int",
+    value: "N",
+    min: 0,
+    example: "dekc voice dict add dek デック --accent 1",
+    text: "the accent position of the reading",
+  },
+  fps: {
+    type: "number",
+    value: "N",
+    above: 0,
+    example: "dekc video --fps 30",
+    text: "frames per second",
+  },
+  "root-dist": { type: "boolean", text: "write to <root>/dist/ instead of the deck's dist/" },
+  url: {
+    type: "string",
+    value: "<url>",
+    text: "the URL dist/ is served from, over url in dek.toml",
+  },
+  public: {
+    type: "boolean",
+    text: "a page for anyone with the link, without the script's stage directions and comments",
+  },
+} as const satisfies Record<string, FlagSpec>;
+
+export type FlagName = keyof typeof FLAGS;
+
+type ValueOf<F> = F extends { type: "boolean" }
+  ? true
+  : F extends { type: "int" | "number" }
+    ? number
+    : F extends { choices: readonly (infer C)[] }
+      ? C
+      : string;
+
+/** What the command line said, each value already of its flag's type. */
+export type FlagValues = { -readonly [K in FlagName]?: ValueOf<(typeof FLAGS)[K]> };
+
+/**
+ * Taken by every invocation: --json also shapes an error, and --help and --version turn any
+ * command line into help or the version.
+ */
+const GLOBAL_FLAGS: readonly FlagName[] = ["json", "help", "version"];
+
+/** The placeholder help prints after a flag, or nothing for a switch. */
+export function flagValue(name: FlagName): string | undefined {
+  const flag: FlagSpec = FLAGS[name];
+  if (flag.type === "boolean") {
+    return undefined;
+  }
+  return flag.type === "enum" ? flag.choices.join("|") : flag.value;
+}
+
+type ParseOptions = Record<string, { type: "boolean" | "string"; short?: string }>;
+
+function parseOptions(names: readonly FlagName[]): ParseOptions {
+  return Object.fromEntries(
+    names.map((name) => {
+      const flag: FlagSpec = FLAGS[name];
+      const type = flag.type === "boolean" ? "boolean" : "string";
+      return [name, flag.type === "boolean" && flag.short ? { type, short: flag.short } : { type }];
+    }),
+  );
+}
+
+const ALL_FLAGS = Object.keys(FLAGS) as FlagName[];
+
+export type CommandLine = {
+  /** The first word: a command, a deck name, or nothing for the bare `dekc`. */
+  command?: string;
+  /** The subcommand named, such as `dict add` for `dekc voice dict add`. */
+  subcommand?: string;
+  /** Every word that is no flag, the command word first. */
+  positionals: string[];
+  values: FlagValues;
+  /**
+   * argv as typed with the command word moved first, which runs the same: what a hint retypes
+   * when it only needs to add a word after the command.
+   */
+  typed: string[];
+};
+
+function lenientParse(argv: string[]) {
+  return parseArgs({
+    args: argv,
+    options: parseOptions(ALL_FLAGS),
+    strict: false,
+    allowPositionals: true,
+  });
+}
+
+/**
+ * Whether argv asks for JSON, read even from a command line too broken to parse: from the words
+ * themselves, since a value flag in front, as in `--port --json`, would take it for its value.
+ */
+export function wantsJson(argv: string[]): boolean {
+  const end = argv.indexOf("--");
+  return (end < 0 ? argv : argv.slice(0, end)).some(
+    (word) => word === "--json" || word.startsWith("--json="),
+  );
+}
+
+/**
+ * argv after `dekc`, checked against the flags its command takes. Two passes:
+ * a lenient one only to find the command word (value flags must consume their
+ * value first, or `--deck talk ls` would read `talk` as the command), then a
+ * strict one with that command's flags, so a typo or a flag from another
+ * command is an error instead of a silent no-op. A value that does not fit its
+ * flag is refused here too, before any command runs.
+ */
+export function parseCommandLine(argv: string[]): CommandLine {
+  const lenient = lenientParse(argv);
+  const command = lenient.positionals[0];
+  // An unknown word, `serve` included, is parsed as the bare `dekc [deck]` and judged later.
+  const name =
+    lenient.values.help === true && !isTypedCommand(command)
+      ? "help"
+      : isTypedCommand(command)
+        ? command
+        : "serve";
+  const sub = subcommandAt(name, lenient.positionals);
+  const names = [...acceptedFlags(name, sub?.name), ...GLOBAL_FLAGS];
+  const label = [command === undefined ? "dekc" : `dekc ${command}`, sub?.name]
+    .filter(Boolean)
+    .join(" ");
+  const hint = `${label} takes ${names.map((flag) => `--${flag}`).join(", ")}; run \`dekc help ${name}\``;
+
+  let parsed: ReturnType<typeof parseArgs>;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: parseOptions(names),
+      strict: true,
+      allowPositionals: true,
+      tokens: true,
+    });
+  } catch (error) {
+    throw describeParseError(error, { argv, label, hint });
+  }
+  return {
+    command,
+    ...(sub ? { subcommand: sub.name } : {}),
+    positionals: parsed.positionals,
+    values: typedValues(parsed.values as Record<string, string | boolean>),
+    typed: commandFirst(argv, parsed.tokens?.find((token) => token.kind === "positional")?.index),
+  };
+}
+
+function commandFirst(argv: string[], at: number | undefined): string[] {
+  const word = at === undefined ? undefined : argv[at];
+  return word === undefined ? argv : [word, ...argv.slice(0, at), ...argv.slice((at ?? 0) + 1)];
+}
+
+function typedValues(raw: Record<string, string | boolean>): FlagValues {
+  const values: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    values[name] = typeof value === "string" ? typedValue(name as FlagName, value) : value;
+  }
+  return values as FlagValues;
+}
+
+/** A flag's value as its type, or the error that says what it may be. */
+function typedValue(name: FlagName, value: string): string | number {
+  const flag: FlagSpec = FLAGS[name];
+  switch (flag.type) {
+    case "boolean":
+    case "string":
+      return value;
+    case "int": {
+      const n = /^-?\d+$/.test(value) ? Number(value) : Number.NaN;
+      if (Number.isInteger(n) && n >= flag.min && (flag.max === undefined || n <= flag.max)) {
+        return n;
+      }
+      const range =
+        flag.max === undefined ? `of ${flag.min} or more` : `from ${flag.min} to ${flag.max}`;
+      throw invalid(name, value, `a whole number ${range}, e.g. \`${flag.example}\``);
+    }
+    case "number": {
+      // Number("") is 0, so an empty value is refused before it can pass as one.
+      const n = value.trim() === "" ? Number.NaN : Number(value);
+      if (Number.isFinite(n) && n > flag.above) {
+        return n;
+      }
+      throw invalid(name, value, `a number above ${flag.above}, e.g. \`${flag.example}\``);
+    }
+    case "enum": {
+      if (flag.choices.includes(value)) {
+        return value;
+      }
+      const note = flag.note ? `; ${flag.note}` : "";
+      throw invalid(name, value, `${flag.choices.join(" or ")}, e.g. \`${flag.example}\`${note}`);
+    }
+  }
+}
+
+function invalid(name: FlagName, value: string, takes: string): DekError {
+  return new DekError(`invalid --${name} "${value}"`, { hint: `--${name} takes ${takes}` });
+}
+
+/** parseArgs' own messages, reworded around what the user typed. */
+function describeParseError(
+  error: unknown,
+  { argv, label, hint }: { argv: string[]; label: string; hint: string },
+): DekError {
+  const message = error instanceof Error ? error.message : String(error);
+  const unknown = message.match(/^Unknown option '([^']+)'/);
+  if (unknown) {
+    return new DekError(`unknown flag ${unknown[1]} for ${label}`, { hint });
+  }
+  const missing = message.match(/^Option '(--[^ ']+)(?: <value>)?' argument missing/);
+  if (missing) {
+    return new DekError(`${missing[1]} needs a value`, { hint });
+  }
+  // `--to --deck`: parseArgs refuses to guess; say what it saw instead of a value.
+  const ambiguous = message.match(/^Option '(--[^']+)' argument is ambiguous/);
+  if (ambiguous) {
+    const next = argv[argv.indexOf(ambiguous[1] ?? "") + 1];
+    return new DekError(`${ambiguous[1]} needs a value, got ${next}`, { hint });
+  }
+  const extra = message.match(/^Option '(--[^']+)' does not take an argument/);
+  if (extra) {
+    return new DekError(`${extra[1]} takes no value`, { hint });
+  }
+  return new DekError(message, { hint });
+}