nnw-theme 0.0.0 → 1.0.0

package/dist/commands/init.js

@@ -0,0 +1,155 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { setupWebkit } from "../browser.js";
+import { interactive, promptConfirm, promptText } from "../interactive.js";
+import { findRoot, findTheme, IDENTITY_END, IDENTITY_START, PLACEHOLDER_MARKER, readPlist, ThemeError, writePlist, } from "../project.js";
+import { pyRepr } from "../pyformat.js";
+import { urlsplit } from "../urlparse.js";
+import { marketplaceEnable } from "./marketplace.js";
+function slug(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function identifierSlug(value) {
+    return slug(value).replace(/[^a-z0-9-]+/g, "") || "theme";
+}
+/** Owner and fork status of the current repository, when gh can report them. */
+function repository() {
+    const result = spawnSync("gh", ["repo", "view", "--json", "owner,isFork"], {
+        encoding: "utf8",
+    });
+    if (result.error || result.status)
+        return {};
+    try {
+        const value = JSON.parse(result.stdout);
+        return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function defaultIdentifier(name, homepage, githubUser) {
+    const suffix = identifierSlug(name);
+    if (githubUser)
+        return `io.github.${identifierSlug(githubUser)}.${suffix}`;
+    const hostname = (urlsplit(homepage).hostname ?? "example.com").toLowerCase().split(".");
+    const domain = hostname.map(identifierSlug).reverse().join(".");
+    return `${domain}.${suffix}`;
+}
+export function absoluteHomepage(value) {
+    const parsed = urlsplit(value);
+    if (!["http", "https"].includes(parsed.scheme) || !parsed.netloc) {
+        throw new ThemeError("creator home page must be an absolute HTTP(S) URL");
+    }
+    if (parsed.hostname === "example.com" || parsed.hostname === "www.example.com") {
+        throw new ThemeError("creator home page must not use the example.com placeholder");
+    }
+    return value;
+}
+function updateReadme(root, name, creator, homepage) {
+    const path = join(root, "README.md");
+    const text = readFileSync(path, "utf8");
+    const start = text.indexOf(IDENTITY_START);
+    const end = text.indexOf(IDENTITY_END);
+    if (start < 0 || end < start)
+        throw new ThemeError("README identity markers are missing");
+    const replacement = `${IDENTITY_START}\n# ${name}\n\n` +
+        `A NetNewsWire theme by [${creator}](${homepage}).\n${IDENTITY_END}`;
+    writeFileSync(path, text.slice(0, start) + replacement + text.slice(end + IDENTITY_END.length), "utf8");
+}
+async function ask(value, flag, label, fallback) {
+    if (value)
+        return value;
+    if (!interactive())
+        throw new ThemeError(`pass --${flag} (no terminal to ask for ${label.toLowerCase()})`);
+    return await promptText(label, fallback);
+}
+export default async function init({ values }) {
+    const root = findRoot();
+    let theme = findTheme(root);
+    if (!existsSync(join(root, PLACEHOLDER_MARKER))) {
+        throw new ThemeError("this repository is already initialized; run `npx nnw-theme@1 setup` to install preview tools");
+    }
+    const flag = (name) => values[name];
+    const prompting = !(flag("name") && flag("creator") && flag("homepage"));
+    const repo = repository();
+    if (repo.isFork) {
+        console.error("Warning: this repository is a fork. The theme marketplace skips forks, so " +
+            "the theme will never be discovered. Start from GitHub's \"Use this " +
+            'template" button instead, then rerun initialization.');
+    }
+    const githubUser = flag("github-user") || repo.owner?.login || undefined;
+    const name = await ask(flag("name"), "name", "Theme name", "Quiet Reader");
+    const creator = await ask(flag("creator"), "creator", "Your name", "Theme Author");
+    const homepage = absoluteHomepage(await ask(flag("homepage"), "homepage", "Your HTTP(S) home page (for example, your GitHub profile)", githubUser ? `https://github.com/${githubUser}` : ""));
+    const proposed = flag("identifier") || defaultIdentifier(name, homepage, githubUser);
+    let identifier = proposed;
+    if (prompting && !flag("identifier"))
+        identifier = await promptText("Stable theme identifier", proposed);
+    const confirmation = flag("confirm-identifier");
+    if (confirmation) {
+        if (confirmation !== identifier) {
+            throw new ThemeError("--confirm-identifier must exactly match the chosen identifier");
+        }
+    }
+    else if (!interactive()) {
+        throw new ThemeError("pass --confirm-identifier with the identifier to keep permanently");
+    }
+    else if (!(await promptConfirm(`Use ${pyRepr(identifier)} permanently? It cannot change after the first release.`, true))) {
+        throw new ThemeError("choose a permanent identifier and rerun initialization");
+    }
+    if (!name.trim() || name === "." || name === ".." || /[/\\\0]/.test(name)) {
+        throw new ThemeError("theme name must be non-empty and cannot contain path separators");
+    }
+    const destination = join(root, `${name}.nnwtheme`);
+    if (existsSync(destination) && destination !== theme) {
+        throw new ThemeError(`theme bundle already exists: ${destination}`);
+    }
+    const metadata = readPlist(theme);
+    Object.assign(metadata, {
+        ThemeIdentifier: identifier,
+        Name: name,
+        CreatorHomePage: homepage,
+        CreatorName: creator,
+        Version: 1,
+    });
+    if (destination !== theme) {
+        renameSync(theme, destination);
+        theme = destination;
+    }
+    writePlist(join(theme, "Info.plist"), metadata);
+    updateReadme(root, name, creator, homepage);
+    rmSync(join(root, "screenshots", "theme-preview.png"), { force: true });
+    rmSync(join(root, PLACEHOLDER_MARKER));
+    console.log(`Initialized ${name}.nnwtheme with identifier ${identifier}.`);
+    console.log("Create a deliberate marketplace image with `npx nnw-theme@1 screenshot --promote`.");
+    let marketplace = flag("marketplace");
+    if (marketplace === undefined) {
+        marketplace =
+            interactive() && (await promptConfirm("Add this repository to the theme marketplace?"))
+                ? "yes"
+                : "no";
+    }
+    if (marketplace === "yes")
+        marketplaceEnable();
+    let install = values["install-browser"];
+    if (install === undefined && prompting && interactive()) {
+        install = await promptConfirm("Set up WebKit for previews now?");
+    }
+    if (install) {
+        // Initialization is already complete; a preview setup failure must not look like
+        // an init failure, because rerunning init is refused from here on.
+        try {
+            await setupWebkit();
+        }
+        catch (error) {
+            console.error(`Warning: initialization succeeded, but preview setup did not: ${error.message}\n` +
+                "Finish preview setup later with `npx nnw-theme@1 setup`.");
+        }
+    }
+    console.log("Next: describe the design you want, then run `npx nnw-theme@1 preview`.");
+}

package/dist/commands/marketplace.js

@@ -0,0 +1,22 @@
+import { spawnSync } from "node:child_process";
+/** Add the marketplace discovery topic with gh; warn rather than fail. */
+export function marketplaceEnable() {
+    const result = spawnSync("gh", ["repo", "edit", "--add-topic", "netnewswire-theme"], {
+        encoding: "utf8",
+    });
+    if (result.error) {
+        console.error("Warning: GitHub CLI is not installed. Run `npx nnw-theme@1 marketplace enable` " +
+            "after installing and authenticating gh.");
+        return false;
+    }
+    if (result.status) {
+        console.error("Warning: could not add the marketplace topic. " +
+            `Run \`npx nnw-theme@1 marketplace enable\` later.\n${(result.stderr || result.stdout).trim()}`);
+        return false;
+    }
+    console.log("Added the netnewswire-theme GitHub topic.");
+    return true;
+}
+export default function marketplace() {
+    marketplaceEnable();
+}

package/dist/commands/package.js

@@ -0,0 +1,16 @@
+import { resolve } from "node:path";
+import { buildArchive } from "../package.js";
+import { findRoot, findTheme } from "../project.js";
+export function printWarnings(warnings) {
+    for (const warning of warnings)
+        console.error(`warning: ${warning}`);
+}
+export default function packageTheme({ values }) {
+    const root = findRoot();
+    const theme = findTheme(root);
+    const { path, warnings } = buildArchive(theme, resolve(root, String(values["output-dir"])), {
+        allowRemoteMedia: values["allow-remote-media"] === true,
+    });
+    printWarnings(warnings);
+    console.log(path);
+}

package/dist/commands/preview.js

@@ -0,0 +1,49 @@
+import { watch } from "node:fs";
+import { relative, sep } from "node:path";
+import { serve } from "../browser.js";
+import { openInBrowser } from "../interactive.js";
+import { findRoot, findTheme } from "../project.js";
+import { extraFixtures, normalTargets, renderSite } from "../render.js";
+/** Whether a changed path is theme or fixture content the gallery is built from. */
+export function watched(root, path) {
+    const parts = relative(root, path).split(sep);
+    if (parts.length !== 2)
+        return false;
+    const [directory = "", name = ""] = parts;
+    return (directory.endsWith(".nnwtheme") || (directory === "fixtures" && name.endsWith(".toml")));
+}
+export default async function preview({ values }) {
+    const root = findRoot();
+    const theme = findTheme(root);
+    const build = () => renderSite(root, theme, normalTargets(extraFixtures(root)));
+    const site = build();
+    const server = await serve(site);
+    console.log(`Preview: ${server.url}`);
+    if (!values["no-open"])
+        openInBrowser(server.url);
+    console.log("Watching theme and fixtures. Press Ctrl-C to stop.");
+    let timer;
+    const watcher = watch(root, { recursive: true }, (_event, name) => {
+        if (!name || !watched(root, `${root}${sep}${name}`))
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            try {
+                build();
+                console.log("Rebuilt preview.");
+            }
+            catch (error) {
+                console.error(`error: ${error.message}`);
+            }
+        }, 200);
+    });
+    await new Promise((resolve) => {
+        process.once("SIGINT", () => {
+            console.log("\nPreview stopped.");
+            resolve();
+        });
+    });
+    watcher.close();
+    clearTimeout(timer);
+    await server.close();
+}

package/dist/commands/progress.js

@@ -0,0 +1,31 @@
+/** One line rewritten in place on a terminal; one plain line per case elsewhere. */
+export class CheckProgress {
+    total;
+    stream;
+    live;
+    constructor(total, stream = process.stderr) {
+        this.total = total;
+        this.stream = stream;
+        this.live = stream.isTTY === true;
+    }
+    status(message) {
+        this.stream.write(this.live ? `\r\x1b[K${message}` : `${message}\n`);
+    }
+    start(index, target) {
+        if (this.live)
+            this.stream.write(`\r\x1b[KChecking ${index}/${this.total} · ${target.label}`);
+    }
+    finish(index, target, failures) {
+        if (this.live && failures.length) {
+            this.stream.write(`\r\x1b[K✗ ${target.label}: ${failures.join("; ")}\n`);
+        }
+        else if (!this.live) {
+            const outcome = failures.length ? `FAILED: ${failures.join("; ")}` : "passed";
+            this.stream.write(`[${index}/${this.total}] ${target.label} … ${outcome}\n`);
+        }
+    }
+    done() {
+        if (this.live)
+            this.stream.write("\r\x1b[K");
+    }
+}

package/dist/commands/release-check.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { parsePlist } from "../plist.js";
+import { findRoot, findTheme, readPlist, ThemeError } from "../project.js";
+import { readZip } from "../zip.js";
+export default function releaseCheck({ values }) {
+    const root = findRoot();
+    const theme = findTheme(root);
+    const current = readPlist(theme);
+    const path = String(values["previous-asset"]);
+    let content;
+    try {
+        content = readFileSync(path);
+    }
+    catch (error) {
+        throw new ThemeError(`could not read the previous release: ${error.message}`);
+    }
+    let entries;
+    try {
+        entries = readZip(content);
+    }
+    catch (error) {
+        throw new ThemeError(`previous release is not a valid ZIP: ${error.message}`);
+    }
+    const infos = entries.filter((entry) => entry.name.endsWith("/Info.plist"));
+    const [info] = infos;
+    if (infos.length !== 1 || !info) {
+        throw new ThemeError("previous release must contain exactly one Info.plist");
+    }
+    const previous = parsePlist(new TextDecoder().decode(info.read()));
+    const oldBundle = info.name.split("/", 1)[0];
+    const bundle = basename(theme);
+    if (oldBundle !== bundle) {
+        throw new ThemeError(`bundle filename changed after release: ${oldBundle} -> ${bundle}`);
+    }
+    if (previous.ThemeIdentifier !== current.ThemeIdentifier) {
+        throw new ThemeError("ThemeIdentifier cannot change after the first release");
+    }
+    const version = current.Version;
+    const previousVersion = typeof previous.Version === "number" ? previous.Version : 0;
+    if (typeof version !== "number" || !Number.isInteger(version) || version <= previousVersion) {
+        throw new ThemeError("Info.plist Version must increase after the previous release");
+    }
+    console.log(`Release identity is stable and Version increases ${previous.Version ?? "None"} -> ${version}.`);
+}

package/dist/commands/render.js

@@ -0,0 +1,17 @@
+import { findRoot, findTheme, ThemeError } from "../project.js";
+import { extraFixtures, normalTargets, renderSite } from "../render.js";
+export default function render({ positionals }) {
+    const root = findRoot();
+    const theme = findTheme(root);
+    let targets = normalTargets(extraFixtures(root));
+    if (positionals.length) {
+        const requested = new Set(positionals);
+        targets = targets.filter((target) => requested.has(target.fixture));
+        const found = new Set(targets.map((target) => target.fixture));
+        const unknown = [...requested].filter((name) => !found.has(name)).sort();
+        if (unknown.length)
+            throw new ThemeError(`unknown fixture(s): ${unknown.join(", ")}`);
+    }
+    const site = renderSite(root, theme, targets);
+    console.log(`${site}/index.html`);
+}

package/dist/commands/screenshot.js

@@ -0,0 +1,36 @@
+import { copyFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { checkPages } from "../browser.js";
+import { findRoot, findTheme, ThemeError } from "../project.js";
+import { extraFixtures, normalTargets, renderSite } from "../render.js";
+import { expectations } from "./check.js";
+function selectTarget(root, values) {
+    const targets = normalTargets(extraFixtures(root));
+    const { fixture, platform, appearance } = values;
+    if (!targets.some((target) => target.fixture === fixture)) {
+        throw new ThemeError(`unknown fixture: ${fixture}`);
+    }
+    const target = targets.find((item) => item.fixture === fixture && item.platform === platform && item.appearance === appearance);
+    if (!target)
+        throw new ThemeError(`${fixture} is checked on Mac and iPhone only`);
+    return target;
+}
+export default async function screenshot({ values }) {
+    const root = findRoot();
+    const theme = findTheme(root);
+    const target = selectTarget(root, values);
+    const site = renderSite(root, theme, [target]);
+    const results = await checkPages(site, [target], undefined, expectations(root, [target]));
+    const failures = results[target.slug] ?? [];
+    if (failures.length) {
+        throw new ThemeError(`screenshot checks failed:\n- ${failures.join("\n- ")}`);
+    }
+    const source = join(site, "screenshots", `${target.slug}.png`);
+    console.log(source);
+    if (values.promote) {
+        const destination = join(root, "screenshots", "theme-preview.png");
+        mkdirSync(join(root, "screenshots"), { recursive: true });
+        copyFileSync(source, destination);
+        console.log(`Promoted marketplace screenshot: ${destination}`);
+    }
+}

package/dist/commands/setup.js

@@ -0,0 +1,4 @@
+import { setupWebkit } from "../browser.js";
+export default async function setup({ values }) {
+    await setupWebkit({ withDeps: values["with-deps"] === true });
+}

package/dist/commands/update.js

@@ -0,0 +1,7 @@
+import { ThemeError } from "../project.js";
+export default function update() {
+    throw new ThemeError("update was removed: the tooling now runs from npm with `npx nnw-theme@1`, so " +
+        "fixes arrive without changing this repository. Delete src/, tests/, " +
+        "pyproject.toml, uv.lock, and .python-version, and replace the stubs `check` " +
+        "warns about.");
+}

package/dist/commands.js

@@ -0,0 +1,175 @@
+// The one description of the command line: the parser, help, and shell completion
+// are all generated from it, so they cannot drift apart.
+export const PROGRAM = "nnw-theme";
+export const DESCRIPTION = "Create, preview, check, and publish a NetNewsWire theme.";
+export const GUIDE_TOPICS = [
+    "skill",
+    "theme-format",
+    "fixtures",
+    "design-checklist",
+    "publishing",
+];
+export const SHELLS = ["fish", "zsh", "bash"];
+/** Fixtures that ship in the package; also in project.ts, which reads them. */
+export const BUILT_IN_FIXTURE_NAMES = ["article", "kitchen-sink"];
+const allowRemoteMedia = {
+    name: "allow-remote-media",
+    type: "boolean",
+    help: "acknowledge warnings for theme-owned remote fonts/images/media",
+};
+export const COMMANDS = [
+    {
+        name: "init",
+        summary: "personalize a fresh copy of the template (run once)",
+        description: "Name the theme, choose its permanent identifier, and optionally join the " +
+            "marketplace and install WebKit. Runs once, while .nnw-theme-uninitialized exists.",
+        options: [
+            { name: "name", type: "string" },
+            { name: "creator", type: "string" },
+            { name: "homepage", type: "string" },
+            { name: "identifier", type: "string" },
+            { name: "confirm-identifier", type: "string" },
+            { name: "github-user", type: "string" },
+            { name: "marketplace", type: "string", choices: ["yes", "no"] },
+            { name: "install-browser", type: "boolean", negatable: true },
+        ],
+    },
+    {
+        name: "setup",
+        summary: "install the WebKit browser that check and screenshot use",
+        description: "Install the WebKit build this version of nnw-theme checks with. " +
+            "--with-deps also installs its Linux system libraries (for CI). Safe to rerun.",
+        options: [
+            {
+                name: "with-deps",
+                type: "boolean",
+                help: "also install WebKit's Linux system dependencies",
+            },
+        ],
+    },
+    {
+        name: "preview",
+        summary: "live gallery for editing: serves, opens, and rebuilds on save",
+        description: "Serve the preview gallery on localhost, open it, and rebuild whenever the theme " +
+            "or fixtures change. Pages render live in your own browser; nothing is checked. " +
+            "Runs until Ctrl-C.",
+        options: [{ name: "no-open", type: "boolean", help: "do not open a browser" }],
+    },
+    {
+        name: "render",
+        summary: "write the preview gallery once, without serving or checking",
+        description: "Write the same gallery as preview to build/preview/ and exit. Useful for scripts " +
+            "and agents, since preview never exits.",
+        options: [],
+        positionals: {
+            name: "fixtures",
+            help: "fixtures to include (default: all), e.g. article",
+            variadic: true,
+            completeFixtures: true,
+        },
+    },
+    {
+        name: "check",
+        summary: "release gate: package and test every case in WebKit",
+        description: "Validate and package the theme, then render 16 cases (the article and " +
+            "kitchen-sink fixtures on Mac, iPhone, and iPad in light and dark, plus large " +
+            "text and Article JavaScript off) and four more for each fixture you add (Mac " +
+            "and iPhone, light and dark) in WebKit. Screenshot each, and fail on missing " +
+            "content, unresolved macros, overflow, broken images, footnotes that do not " +
+            "open, external requests, or JavaScript errors. Results go into the gallery in " +
+            "build/preview/.",
+        options: [
+            allowRemoteMedia,
+            {
+                name: "open",
+                type: "boolean",
+                negatable: true,
+                help: "open the gallery when done (default: ask in a terminal)",
+            },
+        ],
+    },
+    {
+        name: "screenshot",
+        summary: "check one case in WebKit and save its image",
+        description: "Render and check a single case in WebKit and save its full-page screenshot. " +
+            "With --promote, it becomes screenshots/theme-preview.png, the marketplace card.",
+        options: [
+            {
+                name: "fixture",
+                type: "string",
+                default: "article",
+                help: "fixture name",
+                completeFixtures: true,
+            },
+            { name: "platform", type: "string", choices: ["mac", "iphone", "ipad"], default: "mac" },
+            { name: "appearance", type: "string", choices: ["light", "dark"], default: "light" },
+            { name: "promote", type: "boolean", help: "use it as the marketplace screenshot" },
+        ],
+    },
+    {
+        name: "package",
+        summary: "validate the theme and build its release ZIP (no WebKit)",
+        options: [{ name: "output-dir", type: "string", default: "dist" }, allowRemoteMedia],
+    },
+    {
+        name: "capture",
+        summary: "explain how to capture a real article from NetNewsWire as a fixture",
+        options: [],
+    },
+    {
+        name: "bump",
+        summary: "increase the Info.plist Version before a release",
+        options: [{ name: "yes", type: "boolean", help: "skip the confirmation" }],
+    },
+    {
+        name: "marketplace",
+        summary: "manage marketplace participation",
+        options: [],
+        subcommands: [
+            { name: "enable", summary: "add the discovery topic on GitHub", options: [] },
+        ],
+    },
+    {
+        name: "guide",
+        summary: "print the theme authoring guide for agents and people",
+        description: "Print the guidance for building a theme with this tool. Topics: " +
+            `${GUIDE_TOPICS.join(", ")} (default: skill).`,
+        options: [],
+        positionals: {
+            name: "topic",
+            help: "guide topic (default: skill)",
+            variadic: false,
+            choices: GUIDE_TOPICS,
+        },
+    },
+    {
+        name: "completion",
+        summary: "print shell completion and an npx wrapper for fish, zsh, or bash",
+        description: "Print a script that defines an nnw-theme command running `npx --yes nnw-theme@1` " +
+            "(skipped when nnw-theme is already installed) and completes its commands, " +
+            "options, and fixture names.",
+        options: [],
+        positionals: {
+            name: "shell",
+            help: "fish, zsh, or bash",
+            variadic: false,
+            choices: SHELLS,
+        },
+    },
+    {
+        name: "update",
+        summary: "removed: tooling now runs from npm",
+        options: [],
+        hidden: true,
+    },
+    // Used only by the Publish workflow.
+    {
+        name: "release-check",
+        summary: "compare the theme with its previous release",
+        options: [{ name: "previous-asset", type: "string", required: true }],
+        hidden: true,
+    },
+];
+export function findCommand(name) {
+    return COMMANDS.find((command) => command.name === name);
+}