svg-terminal 1.0.0

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+import {
+  BlockConfigError,
+  ConfigError,
+  generate,
+  generateStatic,
+  getBlock,
+  inspectCache,
+  listBlocks,
+  loadConfig,
+  mergeConfig,
+  setStrictBlockConfig,
+  themes
+} from "./chunk-IVINEQLU.js";
+
+// src/cli.ts
+import { writeFileSync, watch as fsWatch } from "fs";
+import { basename, dirname, resolve } from "path";
+
+// src/core/cli-helpers.ts
+function formatModeTag(opts) {
+  const parts = [
+    opts.isStatic && "static",
+    opts.minify && "minified",
+    opts.cacheMode !== "normal" && `cache:${opts.cacheMode}`
+  ].filter(Boolean);
+  return parts.length ? ` (${parts.join(", ")})` : "";
+}
+function humanAge(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0) return "0s";
+  if (seconds < 60) return `${Math.floor(seconds)}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h`;
+  return `${Math.floor(seconds / 86400)}d`;
+}
+function minifySvg(svg) {
+  return svg.replace(/>\s+</g, "><").replace(/\n\s+/g, "\n").replace(/^\s+|\s+$/g, "");
+}
+function resolveCacheMode(args2) {
+  const seen = [];
+  if (args2.includes("--no-cache")) seen.push({ flag: "--no-cache", mode: "off" });
+  if (args2.includes("--refresh-cache")) seen.push({ flag: "--refresh-cache", mode: "refresh" });
+  if (args2.includes("--frozen-cache")) seen.push({ flag: "--frozen-cache", mode: "frozen" });
+  const modeIdx = args2.indexOf("--cache-mode");
+  if (modeIdx !== -1) {
+    const value = args2[modeIdx + 1];
+    if (value === void 0 || value.startsWith("--")) {
+      throw new Error("--cache-mode requires a value (normal | refresh | frozen | off)");
+    }
+    if (!isCacheMode(value)) {
+      throw new Error(`Invalid --cache-mode value: ${value} (expected normal | refresh | frozen | off)`);
+    }
+    seen.push({ flag: `--cache-mode ${value}`, mode: value });
+  }
+  if (seen.length > 1) {
+    const flags = seen.map((s) => s.flag).join(" and ");
+    throw new Error(`Conflicting cache flags: can't combine ${flags}`);
+  }
+  return seen[0]?.mode ?? "normal";
+}
+function isCacheMode(s) {
+  return s === "normal" || s === "refresh" || s === "frozen" || s === "off";
+}
+var SECRET_KEY_RE = /token|secret|password|api[-_]?key|auth|credential|bearer|webhook[-_]?url/i;
+function scrubSecrets(value, ancestors = /* @__PURE__ */ new Set()) {
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) return "[CIRCULAR]";
+    ancestors.add(value);
+    try {
+      return value.map((v) => scrubSecrets(v, ancestors));
+    } finally {
+      ancestors.delete(value);
+    }
+  }
+  if (value && typeof value === "object") {
+    if (ancestors.has(value)) return "[CIRCULAR]";
+    ancestors.add(value);
+    try {
+      const out = {};
+      for (const [k, v] of Object.entries(value)) {
+        out[k] = SECRET_KEY_RE.test(k) ? "[REDACTED]" : scrubSecrets(v, ancestors);
+      }
+      return out;
+    } finally {
+      ancestors.delete(value);
+    }
+  }
+  return value;
+}
+function formatZodType(t) {
+  if (!t || typeof t !== "object") return "unknown";
+  const ctor = t.constructor?.name ?? "unknown";
+  const def = t._def ?? {};
+  if (ctor === "ZodOptional" || ctor === "ZodNullable") {
+    return def.innerType ? formatZodType(def.innerType) : "unknown";
+  }
+  switch (ctor) {
+    case "ZodString":
+      return "string";
+    case "ZodNumber":
+      return "number";
+    case "ZodBoolean":
+      return "boolean";
+    case "ZodEnum": {
+      const opts = t.options ?? def.values ?? [];
+      return opts.map((v) => `"${v}"`).join(" | ") || "enum";
+    }
+    case "ZodArray": {
+      const elt = t.element ?? def.type;
+      return `array of ${formatZodType(elt)}`;
+    }
+    case "ZodRecord":
+      return `record<string, ${def.valueType ? formatZodType(def.valueType) : "unknown"}>`;
+    case "ZodObject":
+      return "object";
+    case "ZodLiteral":
+      return JSON.stringify(t.value);
+    case "ZodUnion":
+      return "union";
+    default:
+      return ctor.replace(/^Zod/, "").toLowerCase();
+  }
+}
+function isZodOptional(t) {
+  const ctor = t?.constructor?.name;
+  return ctor === "ZodOptional" || ctor === "ZodNullable";
+}
+
+// src/cli.ts
+var VERSION = true ? "1.0.0" : "0.0.0-dev";
+var args = process.argv.slice(2);
+var command = args[0];
+function getFlag(name) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx === -1) return void 0;
+  return args[idx + 1];
+}
+function hasFlag(name) {
+  return args.includes(`--${name}`);
+}
+var GENERATE_KNOWN_FLAGS = /* @__PURE__ */ new Set([
+  "config",
+  "output",
+  "static",
+  "minify",
+  "strict",
+  "watch",
+  "no-cache",
+  "refresh-cache",
+  "frozen-cache",
+  "cache-mode",
+  "timings",
+  "explain"
+]);
+function warnUnknownFlags(tokens, known) {
+  const valueFlags = /* @__PURE__ */ new Set(["config", "output", "cache-mode"]);
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (!tok.startsWith("--")) continue;
+    const name = tok.slice(2);
+    if (!known.has(name)) {
+      console.error(`\x1B[33m[svg-terminal] warning: unknown flag "${tok}" \u2014 ignoring\x1B[0m`);
+    }
+    if (valueFlags.has(name)) i++;
+  }
+}
+function formatWatchError(err) {
+  if (err instanceof ConfigError || err instanceof BlockConfigError) {
+    console.error(`\x1B[31m${err.formatted}\x1B[0m`);
+  } else {
+    console.error("\x1B[31mError:\x1B[0m", err instanceof Error ? err.message : err);
+  }
+}
+async function main() {
+  if (hasFlag("version") || command === "--version") {
+    console.log(`svg-terminal ${VERSION}`);
+    return;
+  }
+  switch (command) {
+    case "generate": {
+      warnUnknownFlags(args.slice(1), GENERATE_KNOWN_FLAGS);
+      const configPath = getFlag("config") ?? "terminal.yml";
+      const outputPath = getFlag("output") ?? "terminal.svg";
+      const isStatic = hasFlag("static");
+      const minify = hasFlag("minify");
+      const strict = hasFlag("strict");
+      const watch = hasFlag("watch");
+      const timings = hasFlag("timings");
+      const explain = hasFlag("explain");
+      const cacheMode = resolveCacheMode(args);
+      setStrictBlockConfig(strict);
+      const resolvedConfigPath = resolve(configPath);
+      const resolvedOutputPath = resolve(outputPath);
+      const modeTag = formatModeTag({ isStatic, minify, cacheMode });
+      const cacheStats = { hit: 0, miss: 0, refreshed: 0, fallback: 0, fallbacks: [] };
+      const onCacheEvent = (evt, key) => {
+        cacheStats[evt]++;
+        if (evt === "fallback") cacheStats.fallbacks.push(key);
+      };
+      const runOnce = async () => {
+        cacheStats.hit = 0;
+        cacheStats.miss = 0;
+        cacheStats.refreshed = 0;
+        cacheStats.fallback = 0;
+        cacheStats.fallbacks = [];
+        const start = performance.now();
+        const tLoadStart = performance.now();
+        const userConfig = await loadConfig(resolvedConfigPath);
+        const tLoadMs = performance.now() - tLoadStart;
+        if (explain) {
+          const merged = mergeConfig(userConfig);
+          const explainDump = scrubSecrets({
+            configPath: resolvedConfigPath,
+            outputPath: resolvedOutputPath,
+            theme: merged.theme.name,
+            window: merged.window,
+            text: merged.text,
+            effects: merged.effects,
+            variables: userConfig.variables,
+            blockCount: userConfig.blocks.length,
+            blocks: userConfig.blocks.map((entry) => {
+              const block = getBlock(entry.block);
+              return {
+                name: entry.block,
+                cacheable: block?.cacheable ?? false,
+                registered: !!block,
+                config: entry.config
+              };
+            }),
+            maxDuration: merged.maxDuration
+          });
+          console.error(`[svg-terminal --explain]
+${JSON.stringify(explainDump, null, 2)}`);
+        }
+        const genOpts = { configPath: resolvedConfigPath, cacheMode, onCacheEvent };
+        const tGenStart = performance.now();
+        let svg = isStatic ? await generateStatic(userConfig, genOpts) : await generate(userConfig, genOpts);
+        const tGenMs = performance.now() - tGenStart;
+        const tWriteStart = performance.now();
+        if (minify) svg = minifySvg(svg);
+        writeFileSync(resolvedOutputPath, svg, "utf-8");
+        const tWriteMs = performance.now() - tWriteStart;
+        const elapsed = Math.round(performance.now() - start);
+        const prefix = watch ? `[${(/* @__PURE__ */ new Date()).toTimeString().slice(0, 8)}] ` : "";
+        const duration = watch ? `, ${elapsed}ms` : "";
+        console.log(`${prefix}Generated ${outputPath}${modeTag} (${(svg.length / 1024).toFixed(1)} KB${duration})`);
+        if (timings) {
+          console.error(
+            `[svg-terminal --timings]  load: ${tLoadMs.toFixed(1)}ms  generate: ${tGenMs.toFixed(1)}ms  write: ${tWriteMs.toFixed(1)}ms  total: ${elapsed}ms`
+          );
+        }
+        const totalEvents = cacheStats.hit + cacheStats.miss + cacheStats.refreshed + cacheStats.fallback;
+        if (totalEvents > 0) {
+          const parts = [];
+          if (cacheStats.hit) parts.push(`\x1B[32mhit ${cacheStats.hit}\x1B[0m`);
+          if (cacheStats.miss) parts.push(`miss ${cacheStats.miss}`);
+          if (cacheStats.refreshed) parts.push(`refreshed ${cacheStats.refreshed}`);
+          if (cacheStats.fallback) parts.push(`\x1B[33mfallback ${cacheStats.fallback}\x1B[0m`);
+          const fallbackList = cacheStats.fallbacks.length > 0 ? ` [${cacheStats.fallbacks.join(", ")}]` : "";
+          console.error(`[svg-terminal cache]  ${parts.join("  ")}${fallbackList}`);
+        }
+      };
+      if (!watch) {
+        await runOnce();
+        break;
+      }
+      try {
+        await runOnce();
+      } catch (e) {
+        formatWatchError(e);
+      }
+      console.log(`\x1B[2m[svg-terminal] watching ${configPath}... (Ctrl-C to exit)\x1B[0m`);
+      const DEBOUNCE_MS = 100;
+      let timer = null;
+      let running = false;
+      let queued = false;
+      const trigger = () => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(async () => {
+          timer = null;
+          if (running) {
+            queued = true;
+            return;
+          }
+          running = true;
+          try {
+            await runOnce();
+          } catch (e) {
+            formatWatchError(e);
+          } finally {
+            running = false;
+            if (queued) {
+              queued = false;
+              trigger();
+            }
+          }
+        }, DEBOUNCE_MS);
+      };
+      const configDir = dirname(resolvedConfigPath);
+      const configName = basename(resolvedConfigPath);
+      const watcher = fsWatch(configDir, { persistent: true }, (_event, filename) => {
+        if (filename === configName) trigger();
+      });
+      watcher.on("error", (err) => {
+        console.error(`\x1B[31m[svg-terminal] watch error: ${err.message}\x1B[0m`);
+      });
+      const cleanup = () => {
+        watcher.close();
+        console.log("\n\x1B[2m[svg-terminal] stopped\x1B[0m");
+        process.exit(0);
+      };
+      process.on("SIGINT", cleanup);
+      process.on("SIGTERM", cleanup);
+      return;
+    }
+    case "init": {
+      const starter = `# svg-terminal configuration
+# See: https://github.com/williamzujkowski/svg-terminal
+
+theme: dracula
+
+window:
+  width: 1000
+  height: 560
+  title: "user@terminal:~"
+  # style: macos       # macos | win95 | floating | minimal | none
+  # autoHeight: false   # Auto-calculate height from content
+  # minHeight: 300      # Minimum height when autoHeight is true
+  # maxHeight: 1200     # Maximum height when autoHeight is true
+
+terminal:
+  prompt: "user@host:~$ "
+  fontSize: 14
+
+effects:
+  textGlow: false   # phosphor halo \u2014 try true with amber / green-phosphor / cyberpunk
+  shadow: true
+  scanlines: true
+
+# Animation timing (all values in ms)
+# animation:
+#   cursorBlinkCycle: 1000
+#   outputLineStagger: 50
+#   commandOutputPause: 300
+#   loop: true          # true (infinite) | false (play once) | number (N times)
+
+# Window chrome appearance
+# chrome:
+#   titleFontSize: 13
+#   dimOpacity: 0.6
+
+blocks:
+  - block: neofetch
+    config:
+      username: user
+      hostname: terminal
+      os: TerminalOS v1.0
+      shell: bash 5.2
+      role: Developer
+      languages: TypeScript, Python
+
+  - block: fortune
+    config:
+      fortunes:
+        - "The best code is no code at all."
+        - "Talk is cheap. Show me the code."
+        - "First, solve the problem. Then, write the code."
+
+  # Uncomment to see an animated block (the library's signature feature) \u2014
+  # spinners, clocks, dice rolls. Multi-frame animation, single-line restriction.
+  # - block: loading-spinner
+  #   config:
+  #     label: "deploying to production"
+
+  - block: custom
+    config:
+      command: echo "Thanks for visiting!"
+      lines:
+        - "[[fg:green]]Thanks for visiting my profile![[/fg]]"
+        - ""
+        - "Have a great day!"
+`;
+      const targetPath = resolve("terminal.yml");
+      try {
+        writeFileSync(targetPath, starter, { encoding: "utf-8", flag: hasFlag("force") ? "w" : "wx" });
+      } catch (err) {
+        if (err.code === "EEXIST") {
+          console.error("terminal.yml already exists. Use --force to overwrite.");
+          process.exit(1);
+        }
+        throw err;
+      }
+      console.log("Created terminal.yml \u2014 edit it and run: svg-terminal generate");
+      break;
+    }
+    case "themes": {
+      console.log("Available themes:");
+      for (const name of Object.keys(themes)) {
+        console.log(`  - ${name}`);
+      }
+      break;
+    }
+    case "blocks": {
+      const target = args[1];
+      if (target) {
+        const block = getBlock(target);
+        if (!block) {
+          console.error(`Unknown block "${target}". Run: svg-terminal blocks`);
+          process.exit(1);
+        }
+        console.log(`${block.name} \u2014 ${block.description}`);
+        if (block.cacheable) console.log("  cacheable: yes (participates in .svg-terminal-cache.json)");
+        const schema = block.configSchema;
+        const shape = schema?.shape;
+        if (!shape || Object.keys(shape).length === 0) {
+          console.log("  Config: (no fields)");
+          break;
+        }
+        const names = Object.keys(shape);
+        const w = Math.max(...names.map((n) => n.length));
+        console.log("  Config:");
+        for (const name of names) {
+          const t = shape[name];
+          const tag = isZodOptional(t) ? "" : "  (required)";
+          console.log(`    ${name.padEnd(w)}  ${formatZodType(t)}${tag}`);
+        }
+        console.log("");
+        console.log(`  Plus the universal entry-level keys: command, color, typing, pause`);
+        break;
+      }
+      console.log("Available blocks (cacheable blocks marked *):");
+      for (const name of listBlocks()) {
+        const block = getBlock(name);
+        const mark = block?.cacheable ? " *" : "";
+        console.log(`  - ${name}${mark}`);
+      }
+      console.log("");
+      console.log("Run `svg-terminal blocks <name>` to see a block's config schema.");
+      break;
+    }
+    case "cache": {
+      const sub = args[1];
+      if (sub !== "check") {
+        console.error("Usage: svg-terminal cache check [--config <path>]");
+        process.exit(1);
+      }
+      const configPath = getFlag("config") ?? "terminal.yml";
+      const resolved = resolve(configPath);
+      const userConfig = await loadConfig(resolved);
+      const { filePath, results } = inspectCache(userConfig, resolved);
+      const w = Math.max(0, ...results.map((r) => r.key.length));
+      console.log(`Checking cache at ${filePath}...`);
+      if (results.length === 0) {
+        console.log("  (no cacheable blocks in this config)");
+        break;
+      }
+      let bad = 0;
+      for (const r of results) {
+        const ageStr = r.ageSeconds !== void 0 ? `age ${humanAge(r.ageSeconds)}` : "";
+        const tag = r.status === "OK" ? `\x1B[32mOK\x1B[0m   ` : r.status === "STALE" ? `\x1B[33mSTALE\x1B[0m` : `\x1B[31mMISS\x1B[0m `;
+        console.log(`  ${r.key.padEnd(w)}  ${tag}  ${ageStr}`);
+        if (r.status !== "OK") bad++;
+      }
+      if (bad > 0) {
+        console.error(`
+${bad} cacheable block(s) need a refresh. Run: svg-terminal generate --refresh-cache`);
+        process.exit(1);
+      }
+      break;
+    }
+    default: {
+      console.log(`svg-terminal \u2014 Generate animated SVG terminals
+
+Commands:
+  generate           Generate SVG from config file
+  init               Create a starter terminal.yml (refuses to overwrite without --force)
+  themes             List available themes
+  blocks [<name>]    List available block types, or print one block's config schema
+  cache check        Verify dynamic-block cache freshness (exit 1 on stale/missing)
+
+Generate options:
+  --config <path>    Config file path (default: terminal.yml)
+  --output <path>    Output file path (default: terminal.svg)
+  --static           Render the non-animated final-frame snapshot
+  --minify           Strip inter-element whitespace for smaller output
+  --strict           Promote unknown-block-config-key warnings to hard errors
+  --watch            Re-generate on config file change (Ctrl-C to exit)
+  --timings          Print per-phase wall-clock timings (load, generate, write) to stderr
+  --explain          Print the resolved config + block list as JSON to stderr
+
+Cache events appear in stderr automatically when any dynamic block
+participates ([svg-terminal cache] hit N miss N fallback N [block-names]).
+
+Cache modes (mutually exclusive \u2014 defaults to normal):
+  --no-cache         Don't read or write the dynamic-block fetch cache
+  --refresh-cache    Force refresh: ignore existing cache entries, re-fetch all
+  --frozen-cache     Use cached values only; never fetch (CI offline mode)
+  --cache-mode <m>   Explicit: normal | refresh | frozen | off
+
+Init options:
+  --force            Overwrite an existing terminal.yml
+
+Global:
+  --version          Print version number
+
+Examples:
+  svg-terminal init
+  svg-terminal generate --config terminal.yml --output terminal.svg
+  svg-terminal generate --static
+  svg-terminal generate --watch
+  svg-terminal cache check --config terminal.yml
+`);
+    }
+  }
+}
+main().catch((err) => {
+  if (err instanceof ConfigError || err instanceof BlockConfigError) {
+    console.error(err.formatted);
+  } else {
+    console.error("Error:", err instanceof Error ? err.message : err);
+  }
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map