nnw-theme 0.0.0 → 1.0.0

package/dist/completion.js

@@ -0,0 +1,203 @@
+// Shell completion scripts, generated from the same command spec the parser uses.
+// Each script also defines an nnw-theme function that runs `npx --yes nnw-theme@1`
+// unless a real nnw-theme is already on PATH. The scripts never call npx to complete,
+// so completion is instant.
+import { BUILT_IN_FIXTURE_NAMES, COMMANDS, PROGRAM, } from "./commands.js";
+const RUN = "npx --yes nnw-theme@1";
+const visible = () => COMMANDS.filter((command) => !command.hidden);
+function flags(option) {
+    return option.negatable ? [`--${option.name}`, `--no-${option.name}`] : [`--${option.name}`];
+}
+function allFlags(command) {
+    return [...command.options.flatMap(flags), "--help"];
+}
+/** Words a command's positional argument completes to, or null for fixture names. */
+function positionalWords(command) {
+    if (command.subcommands)
+        return command.subcommands.map((sub) => sub.name);
+    if (command.positionals?.completeFixtures)
+        return null;
+    return command.positionals?.choices;
+}
+const single = (text) => `'${text.replaceAll("'", `'\\''`)}'`;
+// fish ---------------------------------------------------------------------------
+function fishQuote(text) {
+    return `'${text.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+export function fish() {
+    const lines = [
+        "# nnw-theme completion for fish. Install: npx nnw-theme@1 completion fish > ~/.config/fish/conf.d/nnw-theme.fish",
+        `if not command -q ${PROGRAM}`,
+        `    function ${PROGRAM} --description 'Run nnw-theme through npx'`,
+        `        ${RUN} $argv`,
+        "    end",
+        "end",
+        "function __nnw_theme_fixtures",
+        "    # The theme root, as nnw-theme finds it: the nearest directory with a bundle.",
+        "    set -l root $PWD",
+        "    while test $root != / -a (count $root/*.nnwtheme) -eq 0",
+        "        set root (dirname $root)",
+        "    end",
+        `    begin; printf '%s\\n' ${BUILT_IN_FIXTURE_NAMES.join(" ")}`,
+        "        for file in $root/fixtures/*.toml; basename $file .toml; end",
+        "    end | sort -u",
+        "end",
+        `complete -c ${PROGRAM} -f`,
+        `complete -c ${PROGRAM} -n __fish_use_subcommand -l help -s h -d 'Show help'`,
+        `complete -c ${PROGRAM} -n __fish_use_subcommand -l version -d 'Print the version'`,
+    ];
+    for (const command of visible()) {
+        const when = `'__fish_seen_subcommand_from ${command.name}'`;
+        lines.push(`complete -c ${PROGRAM} -n __fish_use_subcommand -a ${command.name} -d ${fishQuote(command.summary)}`);
+        for (const option of command.options) {
+            const description = option.help ? ` -d ${fishQuote(option.help)}` : "";
+            let values = "";
+            if (option.completeFixtures)
+                values = " -x -a '(__nnw_theme_fixtures)'";
+            else if (option.choices)
+                values = ` -x -a ${fishQuote(option.choices.join(" "))}`;
+            else if (option.type === "string")
+                values = option.name.endsWith("dir") ? " -r -F" : " -x";
+            lines.push(`complete -c ${PROGRAM} -n ${when} -l ${option.name}${values}${description}`);
+            if (option.negatable)
+                lines.push(`complete -c ${PROGRAM} -n ${when} -l no-${option.name}`);
+        }
+        const words = positionalWords(command);
+        if (words === null)
+            lines.push(`complete -c ${PROGRAM} -n ${when} -a '(__nnw_theme_fixtures)'`);
+        else if (words) {
+            const subs = command.subcommands ?? [];
+            for (const word of words) {
+                const sub = subs.find((item) => item.name === word);
+                const description = sub ? ` -d ${fishQuote(sub.summary)}` : "";
+                lines.push(`complete -c ${PROGRAM} -n ${when} -a ${word}${description}`);
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+// bash ---------------------------------------------------------------------------
+export function bash() {
+    const cases = [];
+    for (const command of visible()) {
+        const valueCases = [];
+        for (const option of command.options) {
+            if (option.type !== "string")
+                continue;
+            let reply = "COMPREPLY=()";
+            if (option.completeFixtures)
+                reply = 'COMPREPLY=($(compgen -W "$(_nnw_theme_fixtures)" -- "$cur"))';
+            else if (option.choices)
+                reply = `COMPREPLY=($(compgen -W ${single(option.choices.join(" "))} -- "$cur"))`;
+            else if (option.name.endsWith("dir"))
+                reply = 'COMPREPLY=($(compgen -d -- "$cur"))';
+            valueCases.push(`        --${option.name}) ${reply}; return ;;`);
+        }
+        const words = positionalWords(command);
+        let positional = "COMPREPLY=()";
+        if (words === null)
+            positional = 'COMPREPLY=($(compgen -W "$(_nnw_theme_fixtures)" -- "$cur"))';
+        else if (words)
+            positional = `COMPREPLY=($(compgen -W ${single(words.join(" "))} -- "$cur"))`;
+        cases.push(`    ${command.name})`, ...(valueCases.length ? ['      case "$prev" in', ...valueCases, "      esac"] : []), '      if [[ "$cur" == -* ]]; then', `        COMPREPLY=($(compgen -W ${single(allFlags(command).join(" "))} -- "$cur"))`, "      else", `        ${positional}`, "      fi", "      ;;");
+    }
+    return `# nnw-theme completion for bash. Install: source <(npx --yes nnw-theme@1 completion bash)
+if ! type -P ${PROGRAM} >/dev/null 2>&1; then
+  ${PROGRAM}() { ${RUN} "$@"; }
+fi
+_nnw_theme_fixtures() {
+  local root=$PWD file
+  # The theme root, as nnw-theme finds it: the nearest directory with a bundle.
+  while [[ $root != / ]] && ! compgen -G "$root/*.nnwtheme" >/dev/null; do root=$(dirname "$root"); done
+  {
+    printf '%s\\n' ${BUILT_IN_FIXTURE_NAMES.join(" ")}
+    for file in "$root"/fixtures/*.toml; do [ -e "$file" ] && basename "$file" .toml; done
+  } | sort -u
+}
+_nnw_theme() {
+  local cur=\${COMP_WORDS[COMP_CWORD]} prev=\${COMP_WORDS[COMP_CWORD-1]}
+  if (( COMP_CWORD == 1 )); then
+    COMPREPLY=($(compgen -W ${single(`${visible()
+        .map((command) => command.name)
+        .join(" ")} --help --version`)} -- "$cur"))
+    return
+  fi
+  case "\${COMP_WORDS[1]}" in
+${cases.join("\n")}
+  esac
+}
+complete -F _nnw_theme ${PROGRAM}
+`;
+}
+// zsh ----------------------------------------------------------------------------
+function zshEscape(text) {
+    return text
+        .replaceAll("'", `'\\''`)
+        .replaceAll(":", "\\:")
+        .replaceAll("[", "\\[")
+        .replaceAll("]", "\\]");
+}
+function zshOption(option) {
+    const help = zshEscape(option.help ?? option.name);
+    let value = "";
+    if (option.completeFixtures)
+        value = ":fixture:_nnw_theme_fixtures";
+    else if (option.choices)
+        value = `:${option.name}:(${option.choices.join(" ")})`;
+    else if (option.type === "string")
+        value = option.name.endsWith("dir") ? `:${option.name}:_files -/` : `:${option.name}: `;
+    const specs = [`'--${option.name}[${help}]${value}'`];
+    if (option.negatable)
+        specs.push(`'--no-${option.name}[${help}]'`);
+    return specs;
+}
+export function zsh() {
+    const described = visible().map((command) => `    '${command.name}:${zshEscape(command.summary)}'`);
+    const cases = [];
+    for (const command of visible()) {
+        const specs = [...command.options.flatMap(zshOption), "'(- *)'{-h,--help}'[show help]'"];
+        const words = positionalWords(command);
+        if (words === null)
+            specs.push("'*:fixture:_nnw_theme_fixtures'");
+        else if (words)
+            specs.push(`'1:${command.positionals?.name ?? "command"}:(${words.join(" ")})'`);
+        cases.push(`    ${command.name}) _arguments -s ${specs.join(" ")} ;;`);
+    }
+    return `# nnw-theme completion for zsh. Install: source <(npx --yes nnw-theme@1 completion zsh)
+if (( ! $+commands[${PROGRAM}] )); then
+  ${PROGRAM}() { ${RUN} "$@"; }
+fi
+_nnw_theme_fixtures() {
+  local root=$PWD
+  local -a names
+  # The theme root, as nnw-theme finds it: the nearest directory with a bundle.
+  while [[ $root != / ]]; do
+    names=($root/*.nnwtheme(N/))
+    (( $#names )) && break
+    root=\${root:h}
+  done
+  names=(${BUILT_IN_FIXTURE_NAMES.join(" ")} $root/fixtures/*.toml(N:t:r))
+  compadd -- \${(u)names}
+}
+_nnw_theme() {
+  local -a commands
+  commands=(
+${described.join("\n")}
+  )
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'nnw-theme command' commands
+    return
+  fi
+  local command=$words[2]
+  shift words
+  (( CURRENT-- ))
+  case $command in
+${cases.join("\n")}
+  esac
+}
+if (( $+functions[compdef] )); then
+  compdef _nnw_theme ${PROGRAM}
+fi
+`;
+}
+export const SCRIPTS = { fish, bash, zsh };

package/dist/interactive.js

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+import { ThemeError } from "./project.js";
+/** Prompts appear only when stdin and stdout are both terminals. */
+export function interactive() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+function cancelled(error) {
+    if (error?.name === "ExitPromptError")
+        throw new ThemeError("cancelled");
+    throw error;
+}
+export async function promptText(message, fallback) {
+    const { input } = await import("@inquirer/prompts");
+    const answer = await input({ message, default: fallback }).catch(cancelled);
+    return answer.trim();
+}
+export async function promptConfirm(message, fallback = true) {
+    const { confirm } = await import("@inquirer/prompts");
+    return await confirm({ message, default: fallback }).catch(cancelled);
+}
+/** Open a file path or URL in the default browser; failures are ignored. */
+export function openInBrowser(target) {
+    const command = process.platform === "darwin" ? "open" : "xdg-open";
+    try {
+        const child = spawn(command, [target], { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // No browser to open; the path was printed.
+    }
+}

package/dist/main.js

@@ -0,0 +1,229 @@
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { COMMANDS, DESCRIPTION, findCommand, PROGRAM, } from "./commands.js";
+import { packagePath, ThemeError } from "./project.js";
+// Loaded on demand, so a quick command never pays for Playwright or the prompts.
+const HANDLERS = {
+    init: () => import("./commands/init.js"),
+    setup: () => import("./commands/setup.js"),
+    preview: () => import("./commands/preview.js"),
+    render: () => import("./commands/render.js"),
+    check: () => import("./commands/check.js"),
+    screenshot: () => import("./commands/screenshot.js"),
+    package: () => import("./commands/package.js"),
+    capture: () => import("./commands/capture.js"),
+    bump: () => import("./commands/bump.js"),
+    "marketplace enable": () => import("./commands/marketplace.js"),
+    guide: () => import("./commands/guide.js"),
+    completion: () => import("./commands/completion.js"),
+    update: () => import("./commands/update.js"),
+    "release-check": () => import("./commands/release-check.js"),
+};
+class UsageError extends Error {
+}
+export function version() {
+    const manifest = JSON.parse(readFileSync(packagePath("package.json"), "utf8"));
+    return manifest.version;
+}
+function optionUsage(option) {
+    const name = option.negatable ? `--${option.name} | --no-${option.name}` : `--${option.name}`;
+    if (option.type === "boolean")
+        return name;
+    const value = option.choices
+        ? `{${option.choices.join(",")}}`
+        : option.name.toUpperCase().replaceAll("-", "_");
+    return `${name} ${value}`;
+}
+function wrap(text, indent, width = 80) {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(/\s+/)) {
+        if (line && indent + line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        lines.push(line);
+    return lines.map((item) => " ".repeat(indent) + item).join("\n");
+}
+function rows(items) {
+    const column = Math.min(24, Math.max(...items.map(([left]) => left.length)) + 4);
+    return items
+        .map(([left, right]) => {
+        if (!right)
+            return `  ${left}`;
+        if (left.length + 4 > column)
+            return `  ${left}\n${wrap(right, column)}`;
+        return `  ${left.padEnd(column - 2)}${wrap(right, column).trimStart()}`;
+    })
+        .join("\n");
+}
+export function mainHelp() {
+    const visible = COMMANDS.filter((command) => !command.hidden);
+    return [
+        `usage: ${PROGRAM} [-h] [--version] COMMAND ...`,
+        "",
+        DESCRIPTION,
+        "",
+        "commands:",
+        rows(visible.map((command) => [command.name, command.summary])),
+        "",
+        "options:",
+        rows([
+            ["-h, --help", "show this help message and exit"],
+            ["--version", "print the nnw-theme version and exit"],
+        ]),
+        "",
+        `Run \`${PROGRAM} COMMAND --help\` for a command's options.`,
+        `Run it through npx: \`npx nnw-theme@1 COMMAND\`.`,
+        "",
+    ].join("\n");
+}
+export function commandHelp(command, path) {
+    const usage = [`usage: ${PROGRAM} ${path.join(" ")} [-h]`];
+    for (const option of command.options) {
+        const text = optionUsage(option);
+        usage.push(option.required ? text : `[${text}]`);
+    }
+    if (command.subcommands)
+        usage.push(`{${command.subcommands.map((sub) => sub.name).join(",")}}`);
+    if (command.positionals) {
+        const name = command.positionals.name.toUpperCase();
+        usage.push(command.positionals.variadic ? `[${name} ...]` : `[${name}]`);
+    }
+    const sections = [
+        wrap(usage.join(" "), 0),
+        "",
+        wrap(command.description ?? command.summary, 0),
+    ];
+    if (command.subcommands) {
+        sections.push("", "commands:", rows(command.subcommands.map((sub) => [sub.name, sub.summary])));
+    }
+    if (command.positionals) {
+        sections.push("", "positional arguments:", rows([[command.positionals.name, command.positionals.help]]));
+    }
+    const options = [["-h, --help", "show this help message and exit"]];
+    for (const option of command.options) {
+        const help = option.help ?? "";
+        const fallback = option.default ? ` (default: ${option.default})` : "";
+        options.push([optionUsage(option), help + (help ? fallback : fallback.trim())]);
+    }
+    sections.push("", "options:", rows(options), "");
+    return sections.join("\n");
+}
+function parseCommand(command, argv) {
+    const options = {
+        help: { type: "boolean", short: "h" },
+    };
+    for (const option of command.options)
+        options[option.name] = { type: option.type };
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options,
+            allowPositionals: true,
+            allowNegative: command.options.some((option) => option.negatable),
+            strict: true,
+        });
+    }
+    catch (error) {
+        const message = error.message;
+        const unknown = /Unknown option '([^']+)'/.exec(message);
+        throw new UsageError(unknown ? `unrecognized arguments: ${unknown[1]}` : message);
+    }
+    const values = parsed.values;
+    if (values.help)
+        return "help";
+    delete values.help;
+    for (const option of command.options) {
+        const value = values[option.name];
+        if (value === false && option.type === "boolean" && !option.negatable) {
+            throw new UsageError(`unrecognized arguments: --no-${option.name}`);
+        }
+        if (value === undefined && option.default !== undefined)
+            values[option.name] = option.default;
+        if (typeof value === "string" && option.choices && !option.choices.includes(value)) {
+            throw new UsageError(`argument --${option.name}: invalid choice: '${value}' (choose from ${option.choices.map((choice) => `'${choice}'`).join(", ")})`);
+        }
+        if (option.required && value === undefined) {
+            throw new UsageError(`the following arguments are required: --${option.name}`);
+        }
+    }
+    const positionals = parsed.positionals;
+    const spec = command.positionals;
+    if (!spec && positionals.length) {
+        throw new UsageError(`unrecognized arguments: ${positionals.join(" ")}`);
+    }
+    if (spec && !spec.variadic && positionals.length > 1) {
+        throw new UsageError(`unrecognized arguments: ${positionals.slice(1).join(" ")}`);
+    }
+    if (spec?.choices) {
+        for (const value of positionals) {
+            if (!spec.choices.includes(value)) {
+                throw new UsageError(`argument ${spec.name}: invalid choice: '${value}' (choose from ${spec.choices.map((choice) => `'${choice}'`).join(", ")})`);
+            }
+        }
+    }
+    return { values, positionals };
+}
+export async function main(argv = process.argv.slice(2)) {
+    const [name, ...rest] = argv;
+    if (name === undefined || name === "-h" || name === "--help") {
+        process.stdout.write(mainHelp());
+        return name === undefined ? 2 : 0;
+    }
+    if (name === "--version" || name === "-V") {
+        console.log(version());
+        return 0;
+    }
+    try {
+        let command = findCommand(name);
+        const path = [name];
+        let args = rest;
+        if (!command) {
+            const choices = COMMANDS.filter((item) => !item.hidden).map((item) => `'${item.name}'`);
+            throw new UsageError(`argument COMMAND: invalid choice: '${name}' (choose from ${choices.join(", ")})`);
+        }
+        if (command.subcommands) {
+            const [subName, ...subRest] = rest;
+            if (subName === undefined || subName === "-h" || subName === "--help") {
+                process.stdout.write(commandHelp(command, path));
+                return subName === undefined ? 2 : 0;
+            }
+            const sub = command.subcommands.find((item) => item.name === subName);
+            if (!sub) {
+                const choices = command.subcommands.map((item) => `'${item.name}'`).join(", ");
+                throw new UsageError(`argument ${name}: invalid choice: '${subName}' (choose from ${choices})`);
+            }
+            command = sub;
+            path.push(subName);
+            args = subRest;
+        }
+        const parsed = parseCommand(command, args);
+        if (parsed === "help") {
+            process.stdout.write(commandHelp(command, path));
+            return 0;
+        }
+        const load = HANDLERS[path.join(" ")];
+        if (!load)
+            throw new UsageError(`${path.join(" ")} is not implemented yet`);
+        const handler = (await load()).default;
+        await handler(parsed);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            process.stderr.write(`usage: ${PROGRAM} ${name} [-h] ...\n${PROGRAM}: error: ${error.message}\n`);
+            return 2;
+        }
+        if (error instanceof ThemeError) {
+            process.stderr.write(`error: ${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}

package/dist/netnewswire.js

@@ -0,0 +1,84 @@
+// The NetNewsWire rendering files the previews use. They ship in the package under
+// assets/netnewswire/, fetched and SHA-256-verified at build time from the pin in
+// netnewswire.json (see scripts/fetch-netnewswire.ts).
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packagePath, ThemeError } from "./project.js";
+function safeRelativePath(value, field) {
+    if (typeof value !== "string" || !value) {
+        throw new ThemeError(`snapshot configuration ${field} must be a non-empty string`);
+    }
+    const parts = value.split("/").filter((part) => part && part !== ".");
+    if (value.startsWith("/") || parts.includes("..") || !parts.length) {
+        throw new ThemeError(`snapshot configuration ${field} contains an unsafe path`);
+    }
+    return parts.join("/");
+}
+export function readPin(text, name = "netnewswire.json") {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ThemeError(`${name}: invalid NetNewsWire snapshot configuration: ${error}`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ThemeError(`${name}: NetNewsWire snapshot configuration must be an object`);
+    }
+    const { release, commit, files } = value;
+    if (typeof release !== "string" || !release) {
+        throw new ThemeError(`${name}: release must be a non-empty string`);
+    }
+    if (typeof commit !== "string" || !/^[0-9a-f]{40}$/.test(commit)) {
+        throw new ThemeError(`${name}: commit must be a full lowercase Git SHA`);
+    }
+    if (!Array.isArray(files) || !files.length) {
+        throw new ThemeError(`${name}: files must be a non-empty array`);
+    }
+    const parsed = [];
+    for (const details of files) {
+        if (!details || typeof details !== "object") {
+            throw new ThemeError(`${name}: each file must be an object`);
+        }
+        const destination = safeRelativePath(details.destination, "destination");
+        if (parsed.some((file) => file.destination === destination)) {
+            throw new ThemeError(`${name}: duplicate destination ${destination}`);
+        }
+        const source = safeRelativePath(details.source, `source for ${destination}`);
+        const sha256 = details.sha256;
+        if (typeof sha256 !== "string" || !/^[0-9a-f]{64}$/.test(sha256)) {
+            throw new ThemeError(`${name}: sha256 for ${destination} is invalid`);
+        }
+        parsed.push({ destination, source, sha256 });
+    }
+    return { release, commit, files: parsed };
+}
+let verified;
+/** The bundled rendering files, verified against their pin once per process. */
+export function renderingInputs() {
+    if (verified)
+        return verified;
+    const path = packagePath("assets", "netnewswire");
+    const manifest = join(path, "netnewswire.json");
+    if (!existsSync(manifest)) {
+        throw new ThemeError("the NetNewsWire rendering files are missing from this nnw-theme install; " +
+            "in a checkout of the tool, run `npm run fetch-netnewswire`");
+    }
+    const pin = readPin(readFileSync(manifest, "utf8"), manifest);
+    for (const file of pin.files) {
+        const filePath = join(path, ...file.destination.split("/"));
+        let actual = "";
+        try {
+            actual = createHash("sha256").update(readFileSync(filePath)).digest("hex");
+        }
+        catch {
+            // Reported below as a failed verification.
+        }
+        if (actual !== file.sha256) {
+            throw new ThemeError(`bundled NetNewsWire file failed SHA-256 verification: ${filePath}`);
+        }
+    }
+    verified = { path, release: pin.release };
+    return verified;
+}

package/dist/package.js

@@ -0,0 +1,28 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { ThemeError } from "./project.js";
+import { validateArchive, validateSource } from "./validate.js";
+import { writeZip } from "./zip.js";
+/** Build the deterministic ZIP. The only place package validation runs. */
+export function archiveBytes(theme, { allowRemoteMedia = false } = {}) {
+    const sourceReport = validateSource(theme, { allowRemoteMedia });
+    sourceReport.requireOk();
+    const name = basename(theme);
+    const files = readdirSync(theme)
+        .sort()
+        .map((file) => [`${name}/${file}`, readFileSync(join(theme, file))]);
+    const content = writeZip(files);
+    const archiveReport = validateArchive(content, `${name}.zip`);
+    archiveReport.requireOk();
+    return { content, warnings: [...sourceReport.warnings, ...archiveReport.warnings] };
+}
+export function buildArchive(theme, outputDir, { allowRemoteMedia = false } = {}) {
+    const { content, warnings } = archiveBytes(theme, { allowRemoteMedia });
+    mkdirSync(outputDir, { recursive: true });
+    const path = join(outputDir, `${basename(theme)}.zip`);
+    writeFileSync(path, content);
+    if (!path.endsWith(".nnwtheme.zip")) {
+        throw new ThemeError("internal error: package has an invalid release asset name");
+    }
+    return { path, warnings };
+}