nnw-theme 0.0.0 → 0.1.0

package/dist/validate.js

@@ -0,0 +1,259 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Parser } from "htmlparser2";
+import { PlistReal, parsePlist } from "./plist.js";
+import { PLACEHOLDER_MARKER, REQUIRED_THEME_FILES, readPlist, ThemeError, themeStem, } from "./project.js";
+import { pyRepr } from "./pyformat.js";
+import { urlsplit } from "./urlparse.js";
+import { readZip } from "./zip.js";
+const MAX_ASSET_BYTES = 25 * 1024 * 1024;
+const MAX_UNCOMPRESSED_BYTES = 50 * 1024 * 1024;
+const REQUIRED_PLIST_FIELDS = [
+    ["ThemeIdentifier", "str"],
+    ["Name", "str"],
+    ["CreatorHomePage", "str"],
+    ["CreatorName", "str"],
+    ["Version", "int"],
+];
+const PLACEHOLDERS = ["starter", "example.com", "your name", "change me", "todo"];
+const SAFE_BUNDLE_NAME = /^[^/\\\0]+$/;
+const OPTIONAL_THEME_FILE = /^(?:LICENSE|NOTICE)(?:\.[A-Za-z0-9-]+)?$/;
+const S_IFMT = 0o170000;
+const S_IFLNK = 0o120000;
+export class ValidationReport {
+    errors = [];
+    warnings = [];
+    requireOk() {
+        if (this.errors.length) {
+            throw new ThemeError(`theme validation failed:\n- ${this.errors.join("\n- ")}`);
+        }
+    }
+}
+function resourceReferences(template) {
+    const references = [];
+    let attributes = new Map();
+    const parser = new Parser({
+        onattribute(name, value) {
+            attributes.set(name.toLowerCase(), value ?? "");
+        },
+        onopentag(name) {
+            const tag = name.toLowerCase();
+            if (tag === "link" && (attributes.get("rel") ?? "").toLowerCase() === "stylesheet") {
+                references.push(["stylesheet", "href", attributes.get("href") ?? ""]);
+            }
+            for (const attribute of ["src", "poster"]) {
+                const value = attributes.get(attribute);
+                if (value !== undefined)
+                    references.push([tag, attribute, value]);
+            }
+            attributes = new Map();
+        },
+    }, { decodeEntities: true, lowerCaseTags: true, lowerCaseAttributeNames: true });
+    parser.end(template);
+    return references;
+}
+function isRemote(value) {
+    return value.startsWith("//") || ["http", "https"].includes(urlsplit(value).scheme);
+}
+function isAllowedFile(name) {
+    return (REQUIRED_THEME_FILES.includes(name) ||
+        OPTIONAL_THEME_FILE.test(name.toUpperCase()));
+}
+function isInt(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+export function validateMetadata(metadata, bundleStem) {
+    const report = new ValidationReport();
+    for (const [field, type] of REQUIRED_PLIST_FIELDS) {
+        const value = metadata[field];
+        const valid = type === "int" ? isInt(value) : typeof value === "string";
+        if (!valid || (typeof value === "string" && !value.trim())) {
+            report.errors.push(`Info.plist: ${field} must be a non-empty ${type}`);
+        }
+    }
+    if (report.errors.length)
+        return report;
+    const text = (field) => metadata[field];
+    if (text("Name") !== bundleStem) {
+        report.errors.push(`Info.plist Name (${pyRepr(text("Name"))}) must match bundle name (${pyRepr(bundleStem)})`);
+    }
+    const home = urlsplit(text("CreatorHomePage"));
+    if (!["http", "https"].includes(home.scheme) || !home.netloc) {
+        report.errors.push("Info.plist CreatorHomePage must be an absolute HTTP(S) URL");
+    }
+    for (const field of ["ThemeIdentifier", "Name", "CreatorHomePage", "CreatorName"]) {
+        const lowered = text(field).trim().toLowerCase();
+        if (PLACEHOLDERS.some((token) => lowered.includes(token))) {
+            report.errors.push(`Info.plist ${field} still contains placeholder metadata`);
+        }
+    }
+    if (metadata.Version < 1) {
+        report.errors.push("Info.plist Version must be an integer of at least 1");
+    }
+    return report;
+}
+function remoteMessage(report, message, allowRemoteMedia) {
+    if (allowRemoteMedia)
+        report.warnings.push(message);
+    else
+        report.errors.push(`${message} (pass --allow-remote-media to acknowledge)`);
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function validateSource(theme, { allowRemoteMedia = false } = {}) {
+    const report = new ValidationReport();
+    const stem = themeStem(theme);
+    if (!SAFE_BUNDLE_NAME.test(stem) || stem === "." || stem === "..") {
+        report.errors.push("theme bundle name contains path-unsafe characters");
+    }
+    if (existsSync(join(dirname(theme), PLACEHOLDER_MARKER))) {
+        report.errors.push("run `npx nnw-theme@1 init` before packaging this theme");
+    }
+    const names = readdirSync(theme);
+    for (const required of REQUIRED_THEME_FILES) {
+        if (!names.includes(required)) {
+            report.errors.push(`theme is missing exact required file ${required}`);
+        }
+    }
+    for (const name of names) {
+        const path = join(theme, name);
+        if (lstatSync(path).isSymbolicLink()) {
+            report.errors.push(`theme contains symbolic link ${name}`);
+        }
+        else if (!isRegularFile(path)) {
+            report.errors.push(`theme contains unsupported directory ${name}`);
+        }
+        else if (!isAllowedFile(name)) {
+            report.errors.push(`theme contains unsupported file ${name}`);
+        }
+    }
+    if (report.errors.length && !names.includes("Info.plist"))
+        return report;
+    const metadataReport = validateMetadata(readPlist(theme), stem);
+    report.errors.push(...metadataReport.errors);
+    report.warnings.push(...metadataReport.warnings);
+    const templatePath = join(theme, "template.html");
+    if (isRegularFile(templatePath)) {
+        const template = readFileSync(templatePath, "utf8");
+        if (!template.includes("[[")) {
+            report.warnings.push("template.html contains no NetNewsWire macros");
+        }
+        const references = resourceReferences(template);
+        if (/<style\b[^>]*>[\s\S]*?@import\s/i.test(template)) {
+            report.errors.push("CSS @import is not allowed in template.html");
+        }
+        for (const [tag, attribute, value] of references) {
+            if (!value ||
+                ["data:", "#", "mailto:", "tel:"].some((prefix) => value.startsWith(prefix))) {
+                continue;
+            }
+            if (tag === "script" || tag === "stylesheet") {
+                report.errors.push(`external ${tag} is not allowed: ${value}`);
+            }
+            else if (isRemote(value)) {
+                remoteMessage(report, `remote theme-owned ${tag} may not load in NetNewsWire: ${value}`, allowRemoteMedia);
+            }
+            else if (!value.includes("[[")) {
+                report.errors.push("bundle-local resource references do not work in NetNewsWire: " +
+                    `${attribute}=${pyRepr(value)}`);
+            }
+        }
+    }
+    const stylesheetPath = join(theme, "stylesheet.css");
+    if (isRegularFile(stylesheetPath)) {
+        const css = readFileSync(stylesheetPath, "utf8");
+        for (const match of css.matchAll(/url\(\s*['"]?([^)'"]+)/gi)) {
+            const value = (match[1] ?? "").trim();
+            if (value.startsWith("data:"))
+                continue;
+            if (isRemote(value)) {
+                remoteMessage(report, `remote CSS resource may not load in NetNewsWire: ${value}`, allowRemoteMedia);
+            }
+            else {
+                report.errors.push(`bundle-local CSS resource does not work in NetNewsWire: ${value}`);
+            }
+        }
+        if (/@import\s/i.test(css))
+            report.errors.push("CSS @import is not allowed");
+    }
+    return report;
+}
+/** A ZIP member name as PurePosixPath sees it: parts without empty or "." segments. */
+function posixParts(name) {
+    return {
+        parts: name.split("/").filter((part) => part && part !== "."),
+        absolute: name.startsWith("/"),
+    };
+}
+export function validateArchive(content, assetName) {
+    const report = new ValidationReport();
+    if (!assetName.endsWith(".nnwtheme.zip")) {
+        // Everything below derives the bundle name from this suffix.
+        report.errors.push("release asset name must end in .nnwtheme.zip");
+        return report;
+    }
+    if (content.length > MAX_ASSET_BYTES) {
+        report.errors.push("release asset exceeds the 25 MiB compressed limit");
+        return report;
+    }
+    try {
+        const infos = readZip(content);
+        if (infos.reduce((sum, info) => sum + info.size, 0) > MAX_UNCOMPRESSED_BYTES) {
+            report.errors.push("release asset exceeds the 50 MiB expanded limit");
+        }
+        if (infos.some((info) => (info.mode & S_IFMT) === S_IFLNK)) {
+            report.errors.push("release asset contains a symbolic link");
+        }
+        const files = infos.filter((info) => !info.isDirectory);
+        const paths = files.map((info) => posixParts(info.name));
+        const keys = paths.map((path) => `${path.absolute ? "/" : ""}${path.parts.join("/")}`);
+        if (new Set(keys).size !== keys.length) {
+            report.errors.push("release asset contains duplicate paths");
+        }
+        if (paths.some((path) => path.absolute || path.parts.includes(".."))) {
+            report.errors.push("release asset contains an unsafe path");
+            return report;
+        }
+        const roots = new Set(paths.map((path) => path.parts[0]).filter((part) => part?.endsWith(".nnwtheme")));
+        const expectedStem = assetName.slice(0, -".nnwtheme.zip".length);
+        const expectedRoot = `${expectedStem}.nnwtheme`;
+        if (roots.size !== 1 || !roots.has(expectedRoot)) {
+            report.errors.push(`archive must contain exactly one top-level ${expectedRoot} bundle`);
+            return report;
+        }
+        const names = new Set(keys);
+        for (const required of REQUIRED_THEME_FILES) {
+            if (!names.has(`${expectedRoot}/${required}`)) {
+                report.errors.push(`archive is missing exact required file ${required}`);
+            }
+        }
+        for (const [index, path] of paths.entries()) {
+            if (path.parts.length !== 2 || !isAllowedFile(path.parts.at(-1) ?? "")) {
+                report.errors.push(`archive contains unsupported path ${keys[index]}`);
+            }
+        }
+        if (!report.errors.length) {
+            const info = files.find((entry) => entry.name === `${expectedRoot}/Info.plist`);
+            if (!info)
+                throw new Error(`There is no item named '${expectedRoot}/Info.plist' in the archive`);
+            const metadata = parsePlist(new TextDecoder().decode(info.read()));
+            if (!metadata ||
+                typeof metadata !== "object" ||
+                metadata instanceof PlistReal ||
+                Array.isArray(metadata)) {
+                throw new Error("Info.plist must be a dictionary");
+            }
+            report.errors.push(...validateMetadata(metadata, expectedStem).errors);
+        }
+    }
+    catch (error) {
+        report.errors.push(`invalid theme archive: ${error.message}`);
+    }
+    return report;
+}

package/dist/zip.js

@@ -0,0 +1,72 @@
+// Deterministic ZIP writing, and a small reader that sees what validation needs:
+// every central-directory entry, including duplicates and Unix mode bits, which
+// fflate's own unzip hides.
+import { inflateSync, zipSync } from "fflate";
+/**
+ * Write a ZIP whose bytes depend only on its content: names in the given order,
+ * 1980-01-01 00:00 timestamps, Unix mode 0644, maximum compression.
+ */
+export function writeZip(files) {
+    const entries = {};
+    // fflate writes DOS times from local-time fields, so this is 1980-01-01 00:00 exactly.
+    const mtime = new Date(1980, 0, 1, 0, 0, 0);
+    for (const [name, content] of files) {
+        entries[name] = [content, { level: 9, mtime, os: 3, attrs: 0o100644 << 16 }];
+    }
+    return zipSync(entries);
+}
+export class ZipFormatError extends Error {
+}
+export function readZip(content) {
+    const view = new DataView(content.buffer, content.byteOffset, content.byteLength);
+    let end = -1;
+    for (let offset = content.length - 22; offset >= Math.max(0, content.length - 65557); offset--) {
+        if (view.getUint32(offset, true) === 0x06054b50) {
+            end = offset;
+            break;
+        }
+    }
+    if (end < 0)
+        throw new ZipFormatError("File is not a zip file");
+    const count = view.getUint16(end + 10, true);
+    let offset = view.getUint32(end + 16, true);
+    const decoder = new TextDecoder();
+    const entries = [];
+    for (let index = 0; index < count; index++) {
+        if (offset + 46 > content.length || view.getUint32(offset, true) !== 0x02014b50) {
+            throw new ZipFormatError("Bad magic number for central directory");
+        }
+        const method = view.getUint16(offset + 10, true);
+        const compressedSize = view.getUint32(offset + 20, true);
+        const size = view.getUint32(offset + 24, true);
+        const nameLength = view.getUint16(offset + 28, true);
+        const extraLength = view.getUint16(offset + 30, true);
+        const commentLength = view.getUint16(offset + 32, true);
+        const external = view.getUint32(offset + 38, true);
+        const localOffset = view.getUint32(offset + 42, true);
+        const name = decoder.decode(content.subarray(offset + 46, offset + 46 + nameLength));
+        offset += 46 + nameLength + extraLength + commentLength;
+        entries.push({
+            name,
+            size,
+            mode: external >>> 16,
+            isDirectory: name.endsWith("/"),
+            read() {
+                if (view.getUint32(localOffset, true) !== 0x04034b50) {
+                    throw new ZipFormatError("Bad magic number for file header");
+                }
+                const start = localOffset +
+                    30 +
+                    view.getUint16(localOffset + 26, true) +
+                    view.getUint16(localOffset + 28, true);
+                const data = content.subarray(start, start + compressedSize);
+                if (method === 0)
+                    return data;
+                if (method === 8)
+                    return inflateSync(data, { out: new Uint8Array(size) });
+                throw new ZipFormatError(`compression method ${method} is not supported`);
+            },
+        });
+    }
+    return entries;
+}

package/lldb/nnwdump.py

@@ -0,0 +1,151 @@
+"""nnwdump: capture a NetNewsWire article as a fixture, from inside lldb.
+
+Stopped at the final `return d` of ArticleRenderer.articleSubstitutions(), this
+reads the substitution dictionary NetNewsWire built for the selected article and
+writes it as a TOML fixture. `npx nnw-theme@1 capture` prints the setup steps.
+
+Values cross the debugger boundary base64-encoded, so nothing is truncated or
+mis-escaped. HTML values are written as '''literal''' strings, so fixtures stay
+readable and diff cleanly.
+
+This file runs in Xcode's lldb Python, not the project's: keep it standard-library
+only and compatible with Python 3.9. It imports lldb lazily so the formatting
+helpers can be tested without a debugger.
+"""
+
+from __future__ import annotations
+
+import base64
+import optparse
+import shlex
+from pathlib import Path
+
+USAGE = "nnwdump [--var NAME] [--article NAME] [--no-icon] [OUTPUT.toml]"
+DEFAULT_OUTPUT = "fixtures/nnw-capture.toml"
+# Sorted last so the short metadata stays at the top of the file.
+_HTML_KEYS = {"body"}
+
+
+def resolve_output(argument: str) -> Path:
+    """Relative paths resolve against the working directory.
+
+    This file ships in the nnw-theme package, not the theme repository, and lldb's
+    working directory under Xcode is /, so `npx nnw-theme@1 capture` prints an absolute
+    output path to pass instead.
+    """
+    path = Path(argument).expanduser()
+    return path if path.is_absolute() else Path.cwd() / path
+
+
+def _toml_basic(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    escaped = escaped.replace("\n", "\\n").replace("\t", "\\t").replace("\r", "\\r")
+    return "".join(c if ord(c) >= 0x20 and c != "\x7f" else f"\\u{ord(c):04x}" for c in escaped)
+
+
+def toml_line(key: str, value: str) -> str:
+    """One `key = value` line in the most readable string form that is exact."""
+    # Literal strings cannot hold control characters (multiline ones allow newlines).
+    literal = not any((ord(c) < 0x20 and c not in "\t\n") or c == "\x7f" for c in value)
+    if literal and ("\n" in value or "<" in value) and "'''" not in value:
+        # TOML drops the newline right after the opening delimiter, so this one is
+        # layout, and a value's own leading newline survives.
+        return f"{key} = '''\n{value}'''"
+    if literal and "\n" not in value and "'" not in value:
+        return f"{key} = '{value}'"
+    return f'{key} = "{_toml_basic(value)}"'
+
+
+def fixture_text(pairs: list[tuple[str, str]], name: str) -> str:
+    ordered = sorted(pairs, key=lambda pair: (pair[0] in _HTML_KEYS, pair[0]))
+    header = (
+        "# NetNewsWire article captured with nnwdump.\n"
+        f"# Preview with: npx nnw-theme@1 render {name}\n\n"
+    )
+    return header + "\n".join(toml_line(key, value) for key, value in ordered) + "\n"
+
+
+def _evaluate(interpreter, expression: str):
+    """The exact text of a Swift String expression, or (None, error)."""
+    import lldb
+
+    wrapped = f"Data(({expression}).utf8).base64EncodedString()"
+    result = lldb.SBCommandReturnObject()
+    interpreter.HandleCommand("expression -l Swift -O -- " + wrapped, result)
+    if not result.Succeeded():
+        return None, (result.GetError() or "").strip()
+    token = (result.GetOutput() or "").strip().strip('"').strip()
+    try:
+        return base64.b64decode(token).decode("utf-8"), None
+    except ValueError as error:
+        return None, f"could not decode debugger output: {error}"
+
+
+def _icon_data_url(interpreter, article: str):
+    # Mirrors ArticleIconSchemeHandler: the feed icon as PNG data.
+    encoded, _ = _evaluate(
+        interpreter,
+        f'{article}.iconImage()?.image.dataRepresentation()?.base64EncodedString() ?? ""',
+    )
+    return f"data:image/png;base64,{encoded}" if encoded else None
+
+
+def nnwdump(debugger, command, result, internal_dict):
+    parser = optparse.OptionParser(prog="nnwdump", usage=USAGE)
+    parser.add_option("--var", default="d", help="substitution dictionary (default: d)")
+    parser.add_option("--article", default="article", help="Article value (default: article)")
+    parser.add_option("--no-icon", action="store_true", help="keep the generated feed icon")
+    try:
+        options, arguments = parser.parse_args(shlex.split(command))
+    except SystemExit:
+        result.SetError(f"usage: {USAGE}")
+        return
+    output = resolve_output(arguments[0] if arguments else DEFAULT_OUTPUT)
+
+    frame = debugger.GetSelectedTarget().GetProcess().GetSelectedThread().GetSelectedFrame()
+    if not frame or not frame.IsValid():
+        result.SetError("no stack frame; stop at the breakpoint first")
+        return
+    debugger.HandleCommand("settings set target.max-string-summary-length 0")
+
+    # One "key<TAB>base64(value)" line per entry; base64 never contains either separator.
+    interpreter = debugger.GetCommandInterpreter()
+    raw, error = _evaluate(
+        interpreter,
+        f'{options.var}.map {{ $0.key + "\\t" + Data($0.value.utf8).base64EncodedString() }}'
+        '.joined(separator: "\\n")',
+    )
+    if raw is None:
+        result.SetError(f"could not read `{options.var}`: {error}. Stop at `return d` first.")
+        return
+    pairs = []
+    for line in raw.strip().splitlines():
+        key, _, encoded = line.partition("\t")
+        if key and encoded:
+            pairs.append((key.strip(), base64.b64decode(encoded).decode("utf-8")))
+    if not pairs:
+        result.SetError(f"`{options.var}` is empty; is this the substitution dictionary?")
+        return
+
+    note = ""
+    if not options.no_icon:
+        icon = _icon_data_url(interpreter, options.article)
+        if icon:
+            pairs = [(key, value) for key, value in pairs if key != "avatar_src"]
+            pairs.append(("avatar_src", icon))
+            note = " with the feed's icon"
+        else:
+            note = "; the feed has no icon, so previews generate one"
+
+    try:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(fixture_text(pairs, output.stem), encoding="utf-8")
+    except OSError as error:
+        result.SetError(f"could not write {output}: {error}")
+        return
+    result.AppendMessage(f"nnwdump: wrote {len(pairs)} values to {output}{note}")
+
+
+def __lldb_init_module(debugger, internal_dict):
+    debugger.HandleCommand("command script add -f nnwdump.nnwdump nnwdump")
+    print(f"nnwdump is ready. At the breakpoint: {USAGE}")

package/package.json

@@ -1,2 +1,55 @@
-{"name":"nnw-theme","version":"0.0.0","description":"Placeholder for https://github.com/dave-atx/nnw-theme","license"
-  :"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/dave-atx/nnw-theme.git"}}
+{
+	"name": "nnw-theme",
+	"version": "0.1.0",
+	"description": "Create, preview, check, and publish a NetNewsWire theme.",
+	"license": "Apache-2.0",
+	"author": "Dave Marquard",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dave-atx/nnw-theme.git"
+	},
+	"homepage": "https://github.com/dave-atx/nnw-theme#readme",
+	"bugs": "https://github.com/dave-atx/nnw-theme/issues",
+	"keywords": [
+		"netnewswire",
+		"theme",
+		"nnwtheme"
+	],
+	"type": "module",
+	"bin": {
+		"nnw-theme": "dist/cli.js"
+	},
+	"files": [
+		"dist/",
+		"assets/",
+		"lldb/nnwdump.py",
+		"THIRD_PARTY_NOTICES.md",
+		"LICENSE",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=24"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json && node scripts/fetch-netnewswire.ts",
+		"fetch-netnewswire": "node scripts/fetch-netnewswire.ts",
+		"lint": "biome check .",
+		"fix": "biome check --write .",
+		"typecheck": "tsc --noEmit",
+		"test": "node --test \"test/**/*.test.ts\"",
+		"prepack": "npm run build"
+	},
+	"dependencies": {
+		"@inquirer/prompts": "8.7.2",
+		"entities": "8.1.0",
+		"fflate": "0.8.3",
+		"htmlparser2": "12.0.0",
+		"playwright-core": "1.64.0-alpha-2026-09-14",
+		"smol-toml": "1.8.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.14",
+		"@types/node": "24.13.6",
+		"typescript": "7.0.2"
+	}
+}