nnw-theme 0.0.0 → 1.0.0

package/assets/netnewswire/netnewswire.json

@@ -0,0 +1,46 @@
+{
+	"release": "mac-7.1.3",
+	"commit": "f2daca0f24f29c08d9cb16e1bdc56293fd6fe286",
+	"files": [
+		{
+			"destination": "LICENSE",
+			"source": "LICENSE",
+			"sha256": "712d3c84a79fa1dd7e049341797dd638f9517acfe503bb531fb7f0e18cfa1b43"
+		},
+		{
+			"destination": "Mac/main_mac.js",
+			"source": "Mac/MainWindow/Detail/main_mac.js",
+			"sha256": "3ac1ef46523f6c4d8103fe7dbe6f45486d57a94c3d54d0fcb6211a35215bb676"
+		},
+		{
+			"destination": "Mac/page.html",
+			"source": "Mac/MainWindow/Detail/page.html",
+			"sha256": "51518b58d5b320355b7e4dbf76484ba27ebf81946e963cb25f0c9821e0c9804b"
+		},
+		{
+			"destination": "Shared/core.css",
+			"source": "Shared/Article Rendering/core.css",
+			"sha256": "5cd07a57d6511d9e043aaaf4dc6cd544da18b9733725375928edb9b11ae96e6b"
+		},
+		{
+			"destination": "Shared/main.js",
+			"source": "Shared/Article Rendering/main.js",
+			"sha256": "7a229f330ca4adc7043803f044776f36fb086483d236e39947ce46a0909f7329"
+		},
+		{
+			"destination": "Shared/newsfoot.js",
+			"source": "Shared/Article Rendering/newsfoot.js",
+			"sha256": "6a921854ef81214eebb983314023a20417e76c64eb78e2c4742815744476ae4f"
+		},
+		{
+			"destination": "iOS/main_ios.js",
+			"source": "iOS/Resources/main_ios.js",
+			"sha256": "e764183ea8e9ce75df13d268834741b176afdb440eb492efeaba8ccabd7dfb8b"
+		},
+		{
+			"destination": "iOS/page.html",
+			"source": "iOS/Resources/page.html",
+			"sha256": "c5470f24972ac03d0c9256a6c7dcca4344094e3b7bc2b4a5164321634a966279"
+		}
+	]
+}

package/assets/stubs/.agents/skills/creating-nnw-themes/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: creating-nnw-themes
+description: Create, restyle, preview, test, package, or publish the NetNewsWire theme in this repository. Do not use for generic web design or NetNewsWire app development.
+---
+<!-- nnw-theme-stub: skill v1 -->
+
+# Create NetNewsWire themes
+
+Read the full guide first: `npx nnw-theme@1 guide`. Details live in its topics
+(`npx nnw-theme@1 guide theme-format`, `fixtures`, `design-checklist`, `publishing`),
+which update with the tool.
+
+1. If `.nnw-theme-uninitialized` exists, run `npx nnw-theme@1 init` and let the person
+   approve the permanent theme identifier.
+2. Collect a compact design brief: mood, typography, color, reading needs.
+3. Edit `stylesheet.css` first; change `template.html` only when structure requires it.
+4. Run `npx nnw-theme@1 render` and inspect `build/preview/` in light and dark on each
+   device; explain the change and take the person's reaction.
+5. Finish with `npx nnw-theme@1 check` and give the person the preview path.
+
+Never change the bundle name or `ThemeIdentifier` after the first release. Confirm
+with the person immediately before any release or other GitHub mutation.

package/assets/stubs/.agents/skills/creating-nnw-themes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Create NetNewsWire Themes"
+  short_description: "Design, preview, check, and publish a theme"
+  default_prompt: "Use $creating-nnw-themes to help me design a readable NetNewsWire theme."

package/assets/stubs/.github/workflows/check.yml

@@ -0,0 +1,14 @@
+# nnw-theme-stub: check v1
+# Runs the nnw-theme release gate: https://github.com/dave-atx/nnw-theme
+name: Theme checks
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    uses: dave-atx/nnw-theme/.github/workflows/theme-check.yml@v1

package/assets/stubs/.github/workflows/pages.yml

@@ -0,0 +1,24 @@
+# nnw-theme-stub: pages v1
+# Publishes the checked preview gallery when Pages builds from GitHub Actions.
+name: Publish preview pages
+
+on:
+  workflow_run:
+    workflows: [Theme checks]
+    types: [completed]
+
+permissions:
+  contents: read
+  actions: read
+  pages: write
+  id-token: write
+
+# One group per branch or tag: a tag pushed with main triggers a second run, which
+# skips its deploy and must not cancel main's.
+concurrency:
+  group: pages-${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: true
+
+jobs:
+  pages:
+    uses: dave-atx/nnw-theme/.github/workflows/theme-pages.yml@v1

package/assets/stubs/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+# nnw-theme-stub: release v1
+name: Publish theme
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag beginning with v (for example, v1.0.0)
+        required: true
+        type: string
+      notes:
+        description: Optional release notes (default generated by git-cliff from .github/cliff.toml, if present)
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    uses: dave-atx/nnw-theme/.github/workflows/theme-release.yml@v1
+    with:
+      tag: ${{ inputs.tag }}
+      notes: ${{ inputs.notes }}

package/assets/stubs/.github/workflows/screenshot.yml

@@ -0,0 +1,27 @@
+# nnw-theme-stub: screenshot v1
+name: Refresh marketplace screenshot
+
+on:
+  workflow_dispatch:
+    inputs:
+      fixture:
+        description: Fixture to capture
+        type: choice
+        options: [article, kitchen-sink]
+        default: article
+      appearance:
+        description: Appearance to capture
+        type: choice
+        options: [light, dark]
+        default: light
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  screenshot:
+    uses: dave-atx/nnw-theme/.github/workflows/theme-screenshot.yml@v1
+    with:
+      fixture: ${{ inputs.fixture }}
+      appearance: ${{ inputs.appearance }}

package/assets/stubs/AGENTS.md

@@ -0,0 +1,24 @@
+<!-- nnw-theme-stub: agents v1 -->
+# Repository guidance
+
+This repository is one NetNewsWire theme: the single root `*.nnwtheme` bundle,
+its `fixtures/`, and `screenshots/`. The tooling is the `nnw-theme` npm package;
+run it as `npx nnw-theme@1 <command>`. Never install it globally and never add
+it to this repository. Read `npx nnw-theme@1 guide` before theme work.
+
+If `.nnw-theme-uninitialized` exists, run `npx nnw-theme@1 init` first and let
+the user confirm the permanent theme identifier. Prefer CSS changes; change
+`template.html` only when the requested structure or behavior requires it.
+Finish theme work with `npx nnw-theme@1 check` and report the preview path.
+
+Do not change `ThemeIdentifier` or the `.nnwtheme` bundle name after the first
+release. Increase the plist `Version` (`npx nnw-theme@1 bump`) before every
+release.
+
+If the tooling misbehaves, do not work around it here: report it at
+https://github.com/dave-atx/nnw-theme/issues with the `check` version line.
+
+Local edits, renders, checks and packages are safe. Creating a GitHub release,
+opening a pull request, changing repository topics, or otherwise mutating
+GitHub requires the user's explicit intent. Theme and fixture HTML/JavaScript
+are untrusted executable inputs; browser checks stay loopback-only.

package/dist/browser.js

@@ -0,0 +1,227 @@
+// WebKit checks through the Playwright library: one browser per run, a fresh context
+// per case. Theme and fixture HTML/JavaScript are untrusted: pages are served from
+// 127.0.0.1 only, every other request is blocked and fails the case, and the only
+// outputs are screenshots and results.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { createRequire } from "node:module";
+import { extname, join, normalize, sep } from "node:path";
+import { packagePath, ThemeError } from "./project.js";
+import { pyReprList } from "./pyformat.js";
+const FOOTNOTE_CHECK = readFileSync(packagePath("assets", "footnotes.js"), "utf8");
+const NOT_INSTALLED = "WebKit is not installed; run `npx nnw-theme@1 setup`";
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".png": "image/png",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".json": "application/json",
+    ".txt": "text/plain; charset=utf-8",
+};
+/** Serve a directory on 127.0.0.1 at a free port. */
+export async function serve(directory, port = 0) {
+    const root = normalize(directory);
+    const server = createServer((request, response) => {
+        let path;
+        try {
+            path = decodeURIComponent(new URL(request.url ?? "/", "http://127.0.0.1").pathname);
+        }
+        catch {
+            response.writeHead(400).end();
+            return;
+        }
+        if (path.endsWith("/"))
+            path += "index.html";
+        const file = normalize(join(root, path));
+        if (!file.startsWith(root + sep) ||
+            (request.method !== "GET" && request.method !== "HEAD")) {
+            response.writeHead(404).end();
+            return;
+        }
+        let content;
+        try {
+            content = readFileSync(file);
+        }
+        catch {
+            response.writeHead(404).end();
+            return;
+        }
+        response.writeHead(200, {
+            "Content-Type": CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream",
+            "Content-Length": content.length,
+            "Cache-Control": "no-store",
+        });
+        response.end(request.method === "HEAD" ? undefined : content);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("server has no port");
+    return {
+        url: `http://127.0.0.1:${address.port}`,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}
+async function playwright() {
+    return await import("playwright-core");
+}
+/** Whether this version's WebKit build is installed. */
+export async function webkitInstalled() {
+    const { webkit } = await playwright();
+    return existsSync(webkit.executablePath());
+}
+async function launch() {
+    const { webkit } = await playwright();
+    if (!existsSync(webkit.executablePath()))
+        throw new ThemeError(NOT_INSTALLED);
+    try {
+        return await webkit.launch();
+    }
+    catch (error) {
+        const message = error.message;
+        if (/Executable doesn't exist|install/i.test(message) && !/dependencies/i.test(message)) {
+            throw new ThemeError(NOT_INSTALLED);
+        }
+        throw new ThemeError(`could not start WebKit: ${message.split("\n")[0]}`);
+    }
+}
+/** Install this version's WebKit build (and, withDeps, its Linux system libraries). */
+export async function setupWebkit({ withDeps = false } = {}) {
+    if (!withDeps && (await webkitInstalled())) {
+        try {
+            await (await launch()).close();
+            console.log("WebKit is already installed.");
+            return;
+        }
+        catch {
+            // Installed but not runnable: reinstall below.
+        }
+    }
+    console.log(withDeps
+        ? "Installing WebKit and its Linux runtime dependencies…"
+        : "Installing the WebKit browser used by theme checks…");
+    const cli = join(createRequire(import.meta.url).resolve("playwright-core"), "..", "cli.js");
+    const args = [cli, "install", ...(withDeps ? ["--with-deps"] : []), "webkit"];
+    const status = await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, args, { stdio: "inherit" });
+        child.once("error", reject);
+        child.once("exit", resolve);
+    });
+    if (status !== 0)
+        throw new ThemeError("WebKit installation failed; see the output above");
+}
+export function failures(state) {
+    const found = [];
+    if (!state.article || state.textLength < 40)
+        found.push("article content is missing or unreadable");
+    if (state.unresolved)
+        found.push("unresolved theme macro");
+    if (state.overflow)
+        found.push("horizontal document overflow");
+    if (state.brokenImages.length)
+        found.push(`broken images: ${pyReprList(state.brokenImages)}`);
+    found.push(...(state.footnotes ?? []));
+    if (state.blocked.length)
+        found.push(`external requests: ${pyReprList(state.blocked)}`);
+    if (state.pageErrors.length)
+        found.push(`page errors: ${pyReprList(state.pageErrors)}`);
+    return found;
+}
+// Runs in the page after its screenshot.
+function pageState() {
+    const article = document.querySelector(".articleBody");
+    const root = document.documentElement;
+    return {
+        article: Boolean(article),
+        textLength: (article?.innerText || "").trim().length,
+        // Body only: macOS CSS legitimately keeps the font-size macro literal. Match
+        // whole macro names, so a theme script's regex such as /[[(]/ is no macro.
+        unresolved: /\[\[[A-Za-z0-9_-]+\]\]/.test(document.body.innerHTML),
+        overflow: root.scrollWidth > root.clientWidth + 1,
+        brokenImages: [...document.images]
+            .filter((image) => image.complete && image.naturalWidth === 0)
+            .map((image) => image.currentSrc || image.src),
+    };
+}
+/**
+ * Each target's slug mapped to its failures (empty when it passed).
+ *
+ * expectations maps a fixture name to its [expect.footnotes] table. They describe
+ * the theme's own footnote handling, so they are skipped with theme scripts off.
+ */
+export async function checkPages(site, targets, progress, expectations = {}) {
+    const results = {};
+    const screenshots = join(site, "screenshots");
+    mkdirSync(screenshots, { recursive: true });
+    const server = await serve(site);
+    try {
+        progress?.status("Starting WebKit…");
+        const browser = await launch();
+        try {
+            for (const [offset, target] of targets.entries()) {
+                const index = offset + 1;
+                progress?.start(index, target);
+                const url = `${server.url}/pages/${encodeURIComponent(target.slug)}.html`;
+                const footnotes = target.themeScripts ? (expectations[target.fixture] ?? {}) : {};
+                const state = await checkPage(browser, server.url, url, target, join(screenshots, `${target.slug}.png`), footnotes);
+                const found = failures(state);
+                results[target.slug] = found;
+                progress?.finish(index, target, found);
+            }
+        }
+        finally {
+            await browser.close();
+        }
+    }
+    finally {
+        await server.close();
+    }
+    return results;
+}
+async function checkPage(browser, origin, url, target, screenshot, footnotes) {
+    const context = await browser.newContext({
+        viewport: { width: target.width, height: target.height },
+        colorScheme: target.appearance,
+        serviceWorkers: "block",
+    });
+    try {
+        const blocked = [];
+        const pageErrors = [];
+        await context.route("**/*", async (route) => {
+            const requestURL = route.request().url();
+            if (requestURL.startsWith("data:"))
+                return route.continue();
+            let requestOrigin = null;
+            try {
+                requestOrigin = new URL(requestURL).origin;
+            }
+            catch {
+                // Not a URL with an origin: blocked below.
+            }
+            // Whole-origin match: a prefix test would accept 127.0.0.1:PORT.example.net.
+            if (requestOrigin === origin)
+                return route.continue();
+            blocked.push(requestURL);
+            return route.abort("blockedbyclient");
+        });
+        const page = await context.newPage();
+        page.on("pageerror", (error) => pageErrors.push(String(error)));
+        await page.goto(url, { waitUntil: "networkidle" });
+        await page.screenshot({ path: screenshot, fullPage: true });
+        const state = await page.evaluate(pageState);
+        // Last: it clicks footnotes open, so it must not disturb the screenshot.
+        const found = (await page.evaluate(`(${FOOTNOTE_CHECK})(${JSON.stringify(footnotes)})`));
+        return { ...state, footnotes: found, blocked, pageErrors };
+    }
+    finally {
+        await context.close();
+    }
+}

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./main.js";
+process.exitCode = await main();

package/dist/commands/bump.js

@@ -0,0 +1,23 @@
+import { join } from "node:path";
+import { interactive, promptConfirm } from "../interactive.js";
+import { findRoot, findTheme, readPlist, ThemeError, writePlist } from "../project.js";
+export default async function bump({ values }) {
+    const root = findRoot();
+    const theme = findTheme(root);
+    const metadata = readPlist(theme);
+    const current = metadata.Version;
+    if (typeof current !== "number" || !Number.isInteger(current)) {
+        throw new ThemeError("Info.plist Version must be an integer");
+    }
+    const proposed = current + 1;
+    if (!values.yes) {
+        if (!interactive())
+            throw new ThemeError("pass --yes to increase Version without a terminal");
+        if (!(await promptConfirm(`Increase Version from ${current} to ${proposed}?`))) {
+            throw new ThemeError("version bump cancelled");
+        }
+    }
+    metadata.Version = proposed;
+    writePlist(join(theme, "Info.plist"), metadata);
+    console.log(`Version is now ${proposed}. Commit this change before publishing.`);
+}

package/dist/commands/capture.js

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+import { findRoot, packagePath } from "../project.js";
+export default function capture() {
+    const script = packagePath("lldb", "nnwdump.py");
+    const output = join(findRoot(), "fixtures", "my-article.toml");
+    console.log(`Capture a real article as a fixture from a NetNewsWire debug build (needs Xcode).
+
+1. Clone https://github.com/Ranchero-Software/NetNewsWire and open it in Xcode.
+   In Shared/Article Rendering/ArticleRenderer.swift, set a breakpoint on the
+   \`return d\` line at the end of articleSubstitutions(), then run the app.
+2. Select the article to capture. When the breakpoint stops, load the command
+   in the debugger console (once per debug session):
+
+   command script import ${script}
+
+3. Write the fixture, then let the app continue:
+
+   nnwdump ${output}
+   continue
+
+4. Preview it with \`npx nnw-theme@1 render my-article\`.
+
+nnwdump embeds the feed's real icon; pass --no-icon to keep the generated one.
+The debugger's working directory is /, so give nnwdump an absolute path.
+The script lives in the npx cache; rerun capture if that path stops working.`);
+}

package/dist/commands/check.js

@@ -0,0 +1,67 @@
+import { writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { checkPages } from "../browser.js";
+import { interactive, openInBrowser, promptConfirm } from "../interactive.js";
+import { version } from "../main.js";
+import { buildArchive } from "../package.js";
+import { findRoot, findTheme, fixturePath, footnoteExpectations, readFixture, ThemeError, themeStem, } from "../project.js";
+import { checkTargets, extraFixtures, renderSite, writeGallery, } from "../render.js";
+import { staleStubs } from "../stubs.js";
+import { printWarnings } from "./package.js";
+import { CheckProgress } from "./progress.js";
+export function expectations(root, targets) {
+    const result = {};
+    for (const name of new Set(targets.map((target) => target.fixture))) {
+        result[name] = footnoteExpectations(readFixture(fixturePath(root, name)), `fixtures/${name}.toml`);
+    }
+    return result;
+}
+async function offerToOpen(index, choice) {
+    const open = choice ?? (interactive() && (await promptConfirm("Open the preview?", true)));
+    if (open)
+        openInBrowser(pathToFileURL(index).href);
+}
+export default async function check({ values }) {
+    const root = findRoot();
+    const theme = findTheme(root);
+    console.log(`nnw-theme ${version()}`);
+    printWarnings(staleStubs(root));
+    const targets = checkTargets(extraFixtures(root));
+    const expected = expectations(root, targets);
+    const progress = new CheckProgress(targets.length);
+    progress.status("Validating and packaging the theme…");
+    const archive = buildArchive(theme, join(root, "build", "release"), {
+        allowRemoteMedia: values["allow-remote-media"] === true,
+    });
+    progress.done();
+    printWarnings(archive.warnings);
+    progress.status(`Rendering ${targets.length} pages…`);
+    const site = renderSite(root, theme, targets);
+    let results;
+    try {
+        results = await checkPages(site, targets, progress, expected);
+    }
+    finally {
+        progress.done();
+    }
+    writeGallery(site, themeStem(theme), targets, results);
+    const failures = targets.flatMap((target) => (results[target.slug] ?? []).map((message) => `${target.label}: ${message}`));
+    const passed = targets.filter((target) => !results[target.slug]?.length).length;
+    const packageName = basename(archive.path);
+    const footer = `nnw-theme ${version()}\n`;
+    const report = join(root, "build", "check-report.txt");
+    if (failures.length) {
+        writeFileSync(report, `FAIL\n${failures.join("\n")}\n${footer}`, "utf8");
+    }
+    else {
+        writeFileSync(report, `PASS\n${targets.length} WebKit renders checked\nPackage: ${packageName}\n${footer}`, "utf8");
+        console.log(`PASS: ${targets.length} WebKit renders and ${packageName}`);
+    }
+    const index = join(site, "index.html");
+    console.log(`Preview: ${index}`);
+    await offerToOpen(index, values.open);
+    if (failures.length) {
+        throw new ThemeError(`${targets.length - passed} of ${targets.length} WebKit renders failed:\n- ${failures.join("\n- ")}`);
+    }
+}

package/dist/commands/completion.js

@@ -0,0 +1,8 @@
+import { SCRIPTS } from "../completion.js";
+import { ThemeError } from "../project.js";
+export default function completion({ positionals }) {
+    const shell = positionals[0];
+    if (!shell)
+        throw new ThemeError("name a shell: fish, zsh, or bash");
+    process.stdout.write(SCRIPTS[shell]());
+}

package/dist/commands/guide.js

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+import { GUIDE_TOPICS } from "../commands.js";
+import { packagePath } from "../project.js";
+export function guideText(topic = GUIDE_TOPICS[0]) {
+    return readFileSync(packagePath("assets", "guide", `${topic}.md`), "utf8");
+}
+export default function guide({ positionals }) {
+    process.stdout.write(guideText(positionals[0]));
+}