@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/engine/generate-illustrated-article/scripts/test_source_paths.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * source_paths.js — cited source paths: project-relative always; `../<repo>/…`
+ * only with RTFM_REPOS_ROOT set, only into a git checkout beside the project,
+ * never escaping that checkout (nested `..`, symlinks, the root itself, a
+ * non-repo dir, the project itself). Plus label evidence found in a sibling.
+ */
+'use strict';
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function write(root, rel, text) { const p = path.join(root, rel); fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, text); }
+
+const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'source-paths-')));
+const web = path.join(root, 'acme-web');
+fs.mkdirSync(path.join(web, '.git'), { recursive: true });
+fs.mkdirSync(path.join(root, 'acme-api', '.git'), { recursive: true });
+write(web, 'app/views/plans/index.html.erb', '<h1>Plans</h1>');
+write(root, 'acme-api/config/locales/en.yml', 'en:\n  limit_reached: "You have reached your plan limit"\n');
+write(root, 'notes/readme.md', 'not a repo');
+write(root, 'secret.txt', 'outside every checkout');
+fs.symlinkSync(path.join(root, 'secret.txt'), path.join(root, 'acme-api', 'leak.txt'));
+
+delete process.env.RTFM_REPOS_ROOT;
+const load = () => { for (const m of ['./source_paths.js', './label_evidence.js']) delete require.cache[require.resolve(m)]; return require('./source_paths.js'); };
+
+// Without RTFM_REPOS_ROOT: the strict single-repo rule.
+let sp = load();
+assert.ok(sp.isSafeSourcePath('app/views/plans/index.html.erb'));
+assert.ok(!sp.isSafeSourcePath('../acme-api/config/locales/en.yml'));
+assert.ok(!sp.isSafeSourcePath('/etc/passwd'));
+assert.ok(!sp.isSafeSourcePath(''));
+assert.strictEqual(sp.resolveSourcePath(web, 'app/views/plans/index.html.erb'), path.join(web, 'app/views/plans/index.html.erb'));
+assert.throws(() => sp.resolveSourcePath(web, '../acme-api/config/locales/en.yml'), /project-relative/);
+
+// With RTFM_REPOS_ROOT: one leading `..` into a sibling checkout.
+process.env.RTFM_REPOS_ROOT = root;
+sp = load();
+assert.ok(sp.isSafeSourcePath('../acme-api/config/locales/en.yml'));
+assert.ok(!sp.isSafeSourcePath('../acme-api/../secret.txt'));
+assert.ok(!sp.isSafeSourcePath('app/../../secret.txt'));
+assert.ok(!sp.isSafeSourcePath('../secret.txt'));
+assert.strictEqual(sp.resolveSourcePath(web, '../acme-api/config/locales/en.yml'), path.join(root, 'acme-api/config/locales/en.yml'));
+assert.ok(sp.sourceExists(web, '../acme-api/config/locales/en.yml'));
+assert.ok(!sp.sourceExists(web, '../acme-api/missing.yml'));
+assert.throws(() => sp.resolveSourcePath(web, '../notes/readme.md'), /not a related repository/);
+assert.throws(() => sp.resolveSourcePath(web, '../acme-web/app/views/plans/index.html.erb'), /not a related repository/);
+assert.throws(() => sp.resolveSourcePath(web, '../acme-api/leak.txt'), /outside the project/);
+
+// A project dir that isn't a direct child of the root can't reach siblings.
+const nested = path.join(root, 'acme-api', 'nested');
+fs.mkdirSync(nested);
+assert.throws(() => sp.resolveSourcePath(nested, '../acme-web/app/views/plans/index.html.erb'), /inside RTFM_REPOS_ROOT/);
+
+// Label evidence found in a related repository verifies against that file.
+const { verifyLabelEvidence } = require('./label_evidence.js');
+assert.deepStrictEqual(
+    verifyLabelEvidence({ string: 'You have reached your plan limit', found_in: '../acme-api/config/locales/en.yml' }, 'app/views/plans/index.html.erb', web),
+    { ok: true, kind: 'literal' }
+);
+assert.strictEqual(verifyLabelEvidence({ string: 'Nope', found_in: '../acme-api/config/locales/en.yml' }, null, web).ok, false);
+assert.strictEqual(verifyLabelEvidence({ string: 'outside', found_in: '../acme-api/leak.txt' }, null, web).ok, false);
+
+delete process.env.RTFM_REPOS_ROOT;
+fs.rmSync(root, { recursive: true, force: true });
+console.log('test_source_paths: ok');

package/engine/generate-illustrated-article/scripts/trace_hook.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * trace_hook.js — PostToolUse hook for the rtfm-skills bundle.
+ *
+ * Logs every tool call the agent makes WHILE a skill run is active into a
+ * project-local NDJSON trace, so runs can be diffed for repeated navigation.
+ * The same hook serves generate-illustrated-article and generate-walkthrough.
+ *
+ * Scoping: a run is "active" only while ./.rtfm-trace/CURRENT exists. STEP 0 of
+ * each SKILL.md writes it (the run's <slug>); the final STEP removes it. Outside
+ * a run this hook is a quick no-op, so it's safe to leave registered.
+ *
+ * Contract (PostToolUse): receives the event JSON on stdin (.cwd, .session_id,
+ * .tool_name, .tool_input). It is non-blocking — it never affects the tool
+ * result. It writes ONLY to the trace file, emits nothing on stdout, and always
+ * exits 0. Works in interactive and headless runs alike.
+ *
+ * No lock: each entry is a single small line (long fields truncated to 500
+ * characters), so the append stays under PIPE_BUF and is atomic on local
+ * filesystems even when the agent fires tool calls in parallel.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function truncate(value) {
+    if (value === undefined || value === null) return null;
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    return [...text].slice(0, 500).join('');
+}
+
+function orNull(value) {
+    return value === undefined || value === null || value === false ? null : value;
+}
+
+function record(payload, now = new Date()) {
+    const input = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
+    return {
+        ts: now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+        session: payload.session_id ?? null,
+        tool: payload.tool_name ?? null,
+        file: orNull(input.file_path),
+        pattern: orNull(input.pattern),
+        path: orNull(input.path),
+        glob: orNull(input.glob),
+        command: truncate(input.command),
+    };
+}
+
+function main(stdin) {
+    let payload;
+    try { payload = JSON.parse(stdin); } catch { return; }
+    if (!payload || typeof payload !== 'object') return;
+    const cwd = orNull(payload.cwd);
+    if (!cwd) return;
+
+    const marker = path.join(String(cwd), '.rtfm-trace', 'CURRENT');
+    let slug;
+    try { slug = fs.readFileSync(marker, 'utf8').split('\n')[0].split('\t')[0]; }
+    catch { return; } // not inside a skill run -> no-op
+    const out = path.join(String(cwd), '.rtfm-trace', `${slug || 'run'}.ndjson`);
+
+    try { fs.appendFileSync(out, JSON.stringify(record(payload)) + '\n'); }
+    catch { /* never affect the tool call */ }
+}
+
+if (require.main === module) {
+    const chunks = [];
+    process.stdin.on('data', chunk => chunks.push(chunk));
+    process.stdin.on('end', () => {
+        try { main(Buffer.concat(chunks).toString('utf8')); } catch { /* always exit 0 */ }
+        process.exitCode = 0;
+    });
+    process.stdin.on('error', () => { process.exitCode = 0; });
+}
+
+module.exports = { record };

package/engine/generate-illustrated-article/scripts/trace_hook.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Compatibility shim: hooks registered by older installs point here. The hook
+# itself is trace_hook.js; see that file for its contract. Always exits 0.
+exec node "$(dirname "$0")/trace_hook.js" 2>/dev/null || exit 0

package/engine/generate-illustrated-article/scripts/validate_html.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * HTML Validation Script
+ * Validates HTML mockups before rendering to catch common issues.
+ * Returns JSON with validation results.
+ */
+
+const fs = require('fs');
+
+function validateHtml(htmlFile) {
+    const html = fs.readFileSync(htmlFile, 'utf8').trim();
+    const errors = [];
+    const warnings = [];
+
+    if (!html) {
+        errors.push('HTML file is empty');
+        return { valid: false, errors, warnings, html_length: 0 };
+    }
+
+    if (!html.match(/<!DOCTYPE\s+html>/i)) {
+        warnings.push('Missing DOCTYPE declaration');
+    }
+
+    if (!/<html/i.test(html)) {
+        errors.push('Missing <html> tag');
+    }
+
+    if (!/<body/i.test(html)) {
+        errors.push('Missing <body> tag');
+    }
+
+    const styleOpenCount = (html.match(/<style/gi) || []).length;
+    const styleCloseCount = (html.match(/<\/style>/gi) || []).length;
+    if (styleOpenCount !== styleCloseCount) {
+        errors.push(`Mismatched style tags: ${styleOpenCount} opening, ${styleCloseCount} closing`);
+    }
+
+    const scriptOpenCount = (html.match(/<script/gi) || []).length;
+    const scriptCloseCount = (html.match(/<\/script>/gi) || []).length;
+    if (scriptOpenCount !== scriptCloseCount) {
+        errors.push(`Mismatched script tags: ${scriptOpenCount} opening, ${scriptCloseCount} closing`);
+    }
+
+    const fileUrlMatches = html.match(/(?:src|href)=["']file:\/\/[^"']+["']/gi);
+    if (fileUrlMatches) {
+        fileUrlMatches.forEach((match) => {
+            errors.push(`file:// URL found (won't render): ${match.substring(0, 50)}...`);
+        });
+    }
+
+    const imgWithoutSrc = html.match(/<img(?![^>]*\bsrc\s*=)[^>]*>/gi);
+    if (imgWithoutSrc) {
+        warnings.push(`${imgWithoutSrc.length} image(s) without src attribute`);
+    }
+
+    const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+    if (bodyMatch) {
+        const bodyContent = bodyMatch[1].replace(/<[^>]*>/g, '').trim();
+        if (bodyContent.length === 0) {
+            const hasVisibleElements = /<(div|p|h[1-6]|span|button|input|form|table|ul|ol|li|img|a)[^>]*>/i.test(bodyMatch[1]);
+            if (!hasVisibleElements) {
+                warnings.push('Body appears to have no visible content');
+            }
+        }
+    }
+
+    if (html.includes('class="undefined"')) {
+        warnings.push('Found "undefined" in class attribute - possible template error');
+    }
+    if (html.includes('class="null"')) {
+        warnings.push('Found "null" in class attribute - possible template error');
+    }
+
+    const hasHead = /<head/i.test(html);
+    if (!hasHead) {
+        warnings.push('Missing <head> tag - styles may not load correctly');
+    }
+
+    const hasStyle = /<style/i.test(html);
+    const hasStylesheet = /<link[^>]*stylesheet/i.test(html);
+    const hasInlineStyle = /style\s*=/i.test(html);
+    if (!hasStyle && !hasStylesheet && !hasInlineStyle) {
+        warnings.push('No CSS found - mockup may appear unstyled');
+    }
+
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        html_length: html.length,
+        has_styles: hasStyle || hasStylesheet || hasInlineStyle,
+        has_doctype: /<!DOCTYPE\s+html>/i.test(html),
+    };
+}
+
+const htmlFile = process.argv[2];
+if (!htmlFile) {
+    console.error('Usage: validate_html.js <html_file>');
+    process.exit(1);
+}
+
+if (!fs.existsSync(htmlFile)) {
+    console.error(JSON.stringify({ valid: false, errors: [`File not found: ${htmlFile}`], warnings: [] }));
+    process.exit(1);
+}
+
+try {
+    const result = validateHtml(htmlFile);
+    console.log(JSON.stringify(result));
+    process.exit(result.valid ? 0 : 1);
+} catch (e) {
+    console.error(JSON.stringify({ valid: false, errors: [`Validation error: ${e.message}`], warnings: [] }));
+    process.exit(1);
+}

package/engine/generate-illustrated-article/scripts/watermark.js

@@ -0,0 +1,69 @@
+/**
+ * Watermark strip — "Screenshot/Video created automatically by supportpages.io".
+ *
+ * Injected at CAPTURE time (render_mockup.js for article PNGs,
+ * record_walkthrough.js for walkthrough MP4s), never into the step_N.html
+ * artifacts — the fidelity lint runs before capture in both skills, so the
+ * banner needs no lint exemptions and the authored HTML stays clean.
+ *
+ * Disable via SUPPORTPAGES_WATERMARK=off (also 0/false/no); default is on.
+ * RTFM_WATERMARK is the older name and is read when the new one is unset. The
+ * `watermark` skill argument prefixes the env var onto the render/record
+ * invocation (see both SKILL.md post-process blocks).
+ */
+
+const WATERMARK_TEXT_SCREENSHOT = 'Screenshot created automatically by supportpages.io';
+const WATERMARK_TEXT_VIDEO = 'Video created automatically by supportpages.io';
+const WATERMARK_FONT = "-apple-system,BlinkMacSystemFont,'Segoe UI',system-ui,sans-serif";
+
+// One sizing rule for both outputs, anchored to PHYSICAL pixels of the
+// captured frame — physical size is what survives when a page embed scales
+// the output down, and captures differ in deviceScaleFactor (article PNGs
+// and touch recordings render at dSF 2, web/desktop recordings at dSF 1),
+// so a plain logical-px rule made a desktop video's strip half the physical
+// size of a mobile one. The rule: ~3.4% of frame height, clamped to a
+// 48..70 PHYSICAL px window (expressed here in CSS px by dividing the
+// bounds by dSF, keeping every result an integer). The 48px physical floor
+// is what lifts the dSF-1 frames — web 900 and desktop 1100 — to the
+// same physical text size as a mobile recording.
+function watermarkMetrics(viewportHeight, deviceScaleFactor) {
+    const stripHeight = Math.min(
+        70 / deviceScaleFactor,
+        Math.max(48 / deviceScaleFactor, Math.round(viewportHeight * 0.034))
+    );
+    const fontSize = Math.round(stripHeight * 0.46);
+    return { stripHeight, fontSize };
+}
+
+// Video overlay strip: fixed, full-width, appended as a body-level child
+// OUTSIDE [data-walkthrough-stage] so the recorder's zoom transform never
+// moves it (the ghost-cursor pattern). z-index 9999: above the step-transition
+// fade overlay (9997) and the outro fade-to-black (9998) so the strip reads as
+// constant broadcast chrome from first frame to last; below the cursor helper
+// (10000) so pointers stay visually on top.
+function buildWatermarkVideoCss(viewportHeight, deviceScaleFactor) {
+    const { stripHeight, fontSize } = watermarkMetrics(viewportHeight, deviceScaleFactor);
+    return `
+[data-rtfm-watermark]{
+  position:fixed;left:0;right:0;bottom:0;height:${stripHeight}px;
+  display:flex;align-items:center;justify-content:center;
+  box-sizing:border-box;margin:0;padding:0;
+  background:rgba(15,23,42,0.82);color:rgba(255,255,255,0.92);
+  font:500 ${fontSize}px/1 ${WATERMARK_FONT};letter-spacing:0.02em;
+  z-index:9999;pointer-events:none;
+}`;
+}
+
+function isWatermarkEnabled(env = process.env) {
+    const v = String(env.SUPPORTPAGES_WATERMARK ?? env.RTFM_WATERMARK ?? 'on').trim().toLowerCase();
+    return !(v === 'off' || v === '0' || v === 'false' || v === 'no');
+}
+
+module.exports = {
+    WATERMARK_TEXT_SCREENSHOT,
+    WATERMARK_TEXT_VIDEO,
+    WATERMARK_FONT,
+    watermarkMetrics,
+    buildWatermarkVideoCss,
+    isWatermarkEnabled,
+};

package/install.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# A small, dependency-free bootstrap. The Node wizard handles the actual setup.
+if ! command -v node >/dev/null 2>&1; then
+  echo 'SupportPages Writer needs Node.js 22.12 or later. Install it from https://nodejs.org, then rerun ./install.sh.' >&2
+  exit 1
+fi
+if ! node -e 'const [major, minor] = process.versions.node.split(".").map(Number); process.exit(major > 22 || major === 22 && minor >= 12 ? 0 : 1)'; then
+  echo 'Please upgrade to Node.js 22.12 or later, then rerun ./install.sh.' >&2
+  exit 1
+fi
+installer_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+exec node "$installer_root/scripts/install.mjs" "$@"

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@supportpages.io/wtfm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "SupportPages Writer — illustrated article authoring from your codebase",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SupportPages-io/wtfm.git"
+  },
+  "homepage": "https://github.com/SupportPages-io/wtfm#readme",
+  "bugs": {
+    "url": "https://github.com/SupportPages-io/wtfm/issues"
+  },
+  "type": "module",
+  "bin": {
+    "supportpages-writer": "scripts/cli.mjs",
+    "supportpages-mcp": "dist/index.js",
+    "supportpages-setup": "scripts/install.mjs",
+    "supportpages": "scripts/cli.mjs",
+    "wtfm": "scripts/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "engine",
+    "scripts",
+    "install.sh",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "server.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && SUPPORTPAGES_TELEMETRY=0 node --test test/*.test.mjs",
+    "start": "node dist/index.js",
+    "prepack": "npm run build",
+    "setup": "node scripts/install.mjs",
+    "test:scenarios": "npm run build && node --test test/access-scenarios.test.mjs test/cli-scenarios.test.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.6.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "marked": "17.0.6",
+    "puppeteer": "25.11.0",
+    "yauzl": "3.4.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "typescript": "5.9.3"
+  },
+  "mcpName": "io.github.supportpages-io/supportpages-writer"
+}

package/scripts/auth.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createTerminal } from './lib/terminal.mjs';
+import { apiOrigin, ApiClient, defaultOrigin } from '../dist/api.js';
+import { credentialLocation, defaultConfigDir } from '../dist/session.js';
+import { saveTokenFile } from '../dist/credentials.js';
+import { CLI_NAME } from './lib/brand.mjs';
+
+/** Manual fallback: paste a token created in the web app and save it as this device's credential. */
+export async function authenticate(options, { ui, fetcher = fetch } = {}) {
+  const dev = options.dev === true;
+  const origin = apiOrigin(options['api-url'] ?? defaultOrigin(dev), dev);
+  ui.line(`Sign this device in to ${origin} with a token\nCreate a token for all help centres at ${origin}/settings/local-api-tokens\nUse read and import permissions, plus create projects and publish if required.`);
+  const token = (await ui.secret('Paste API token (hidden)')).trim();
+  if (!/^sp_local_[a-f0-9]{64}$/.test(token)) throw new Error('Invalid token format. No credential was saved.');
+  const settings = await new ApiClient(origin, token, fetcher, dev).request('GET', '/mcp/settings');
+  const account = settings?.account;
+  if (!account || typeof account.id !== 'string' || !/^[1-9][0-9]*$/.test(account.id) || typeof account.email !== 'string') throw new Error('The API returned an invalid account. No credential was saved.');
+  const { filename } = credentialLocation(origin, path.resolve(options['config-dir'] ?? defaultConfigDir()));
+  await saveTokenFile(filename, origin, token, { id: account.id, email: account.email });
+  ui.line(`Token verified and saved privately for ${account.email}. Run ${CLI_NAME} init inside a project folder to connect it to a help centre.`);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try {
+    let options;
+    try { options = parseArgs({ options: { workspace: { type: 'string' }, 'api-url': { type: 'string' }, 'config-dir': { type: 'string' }, dev: { type: 'boolean' } } }).values; }
+    catch { throw new Error('Invalid authentication options. Tokens must only be entered at the hidden prompt.'); }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Run this command in your own interactive terminal.');
+    await authenticate(options, { ui: createTerminal() });
+  } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}

package/scripts/auto-update.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { automaticUpdate } from './lib/auto-update.mjs';
+
+// This worker is launched with all streams disconnected from the MCP transport.
+await automaticUpdate({ installRoot: path.dirname(path.dirname(fileURLToPath(import.meta.url))) });

package/scripts/build-plugin.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Assemble the installable plugin tree that the `plugin` branch publishes.
+//
+// Claude Code and Codex install plugins by copying a git checkout. Neither
+// builds TypeScript, and Codex installs no npm dependencies, so the tree ships
+// compiled dist/ and production node_modules. Chromium is not included: the
+// plugin's SessionStart hook downloads it on first use.
+//
+// Usage: node scripts/build-plugin.mjs --out <directory> [--skip-install]
+//   --skip-install  leave out node_modules (tests)
+import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { command, exists } from './lib/install.mjs';
+
+export const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PACKAGE_FILES = ['dist', 'engine', 'scripts', 'package.json', 'package-lock.json', 'LICENSE', 'NOTICE', 'README.md'];
+
+export async function buildPlugin({ out, root = repositoryRoot, install = true, run = command } = {}) {
+  if (!await exists(path.join(root, 'dist/writer-agent.js'))) throw Error('Build the server first: npm run build.');
+  const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  out = path.resolve(out);
+  await mkdir(out, { recursive: true });
+  // Replace everything except the branch's own git metadata.
+  for (const name of await readdir(out)) if (name !== '.git') await rm(path.join(out, name), { recursive: true, force: true });
+
+  await cp(path.join(root, 'plugin'), out, { recursive: true });
+  const manifest = path.join(out, '.claude-plugin/plugin.json');
+  const plugin = JSON.parse(await readFile(manifest, 'utf8'));
+  await writeFile(manifest, JSON.stringify({ ...plugin, version: pkg.version }, null, 2) + '\n');
+
+  // The writer subagent, from the same definition the CLI installs.
+  const { writerAgentFile, writerAgentType } = await import(pathToFileURL(path.join(root, 'dist/writer-agent.js')).href);
+  await mkdir(path.join(out, 'agents'), { recursive: true });
+  await writeFile(path.join(out, 'agents', `${writerAgentType}.md`), writerAgentFile);
+
+  for (const name of PACKAGE_FILES) await cp(path.join(root, name), path.join(out, name), { recursive: true });
+
+  if (install) {
+    // --ignore-scripts skips puppeteer's Chromium download, as plugin installs do.
+    const result = await run('npm', ['ci', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], { cwd: out });
+    if (result.code) throw Error('npm ci failed while building the plugin.');
+  }
+  return { out, version: pkg.version };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try {
+    const { values } = parseArgs({ options: { out: { type: 'string' }, 'skip-install': { type: 'boolean' } } });
+    if (!values.out) throw Error('Usage: build-plugin.mjs --out <directory> [--skip-install]');
+    const result = await buildPlugin({ out: values.out, install: !values['skip-install'] });
+    process.stdout.write(`${result.out} (${result.version})\n`);
+  } catch (error) {
+    process.stderr.write(error.message + '\n');
+    process.exitCode = 1;
+  }
+}

package/scripts/build-release.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile, realpath, chmod } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import os from 'node:os';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { command, checkSkills, exists } from './lib/install.mjs';
+
+const {values}=parseArgs({options:{local:{type:'boolean'},'runtime-dir':{type:'string'},out:{type:'string'}}});
+if(values.local && values['runtime-dir']) throw Error('--local uses this machine’s runtime. Use --runtime-dir for a public release.');
+if(!values.local && !values['runtime-dir']) throw Error('Use --local, or --runtime-dir with a built checkout.');
+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
+// The article engine ships in this repository (exported from the skills repository).
+const engine=path.join(root,'engine');
+await checkSkills(engine);
+const version=JSON.parse(await readFile(path.join(root,'package.json'),'utf8')).version;
+const lock=JSON.parse(await readFile(path.join(root,'package-lock.json'),'utf8'));
+if(lock.version!==version || lock.packages?.['']?.version!==version) throw Error('Keep package.json and package-lock.json release versions aligned.');
+if(!/^\d+\.\d+\.\d+$/.test(version)) throw Error('Release versions must be X.Y.Z.');
+if(!['darwin','linux'].includes(process.platform) || !['x64','arm64'].includes(process.arch)) throw Error('Unsupported release platform.');
+let npmRoot;
+if(values.local) {
+  const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+  if(nodeMajor < 22 || nodeMajor === 22 && nodeMinor < 12) throw Error('Local builds require Node.js 22.12 or later.');
+  // Find npm next to Node first (nvm/official distributions), then on PATH
+  // (Homebrew). Copy its package, not the entire system runtime prefix.
+  for(const directory of [path.dirname(process.execPath),...(process.env.PATH ?? '').split(path.delimiter).filter(Boolean)]) {
+    const candidate=path.join(directory,'npm');
+    if(!await exists(candidate)) continue;
+    const executable=await realpath(candidate);
+    const candidateRoot=path.dirname(path.dirname(executable));
+    if(await exists(path.join(candidateRoot,'bin/npm-cli.js'))) {npmRoot=candidateRoot;break;}
+  }
+  if(!npmRoot) throw Error('Could not find npm alongside Node or on PATH. Install npm and rerun the installer.');
+  const npmArgs=[path.join(npmRoot,'bin/npm-cli.js')];
+  const env={...process.env,PATH:path.dirname(process.execPath)+path.delimiter+(process.env.PATH ?? '')};
+  const checked=async args=>{
+    const result=await command(process.execPath,[...npmArgs,...args],{cwd:root,capture:true,env});
+    if(result.stdout) process.stderr.write(result.stdout);
+    if(result.stderr) process.stderr.write(result.stderr);
+    if(result.code) throw Error(`npm ${args[0]} failed. Fix the reported issue and rerun the installer.`);
+  };
+  const dependencies=await command(process.execPath,[...npmArgs,'ls','--include=dev','--all'],{cwd:root,capture:true,env});
+  if(dependencies.code) {
+    process.stderr.write('Installing build dependencies...\n');
+    await checked(['ci','--include=dev','--no-audit','--no-fund','--prefer-offline']);
+  }
+  process.stderr.write('Building SupportPages Writer...\n');
+  await checked(['run','build']);
+} else {
+  npmRoot=path.dirname(path.dirname(await realpath(path.join(values['runtime-dir'],'bin/npm'))));
+}
+const stage=await mkdtemp(path.join(os.tmpdir(),'supportpages-release-'));
+const out=path.resolve(values.out ?? path.join(root,'release'));
+try {
+  const bundle=path.join(stage,'supportpages');await mkdir(path.join(bundle,'mcp'),{recursive:true});
+  if(values.local) {
+    await mkdir(path.join(bundle,'runtime/bin'),{recursive:true});
+    await cp(process.execPath,path.join(bundle,'runtime/bin/node'),{dereference:true});
+    // Homebrew's Node executable loads libnode relative to its runtime prefix.
+    // Copy that library too, without pulling in unrelated system packages.
+    const lib=path.resolve(path.dirname(process.execPath),'../lib');
+    if(await exists(lib)) for(const name of await readdir(lib)) {
+      if(!/^libnode[.-]/.test(name)) continue;
+      await mkdir(path.join(bundle,'runtime/lib'),{recursive:true});
+      await cp(path.join(lib,name),path.join(bundle,'runtime/lib',name),{dereference:true});
+    }
+  } else await cp(values['runtime-dir'],path.join(bundle,'runtime'),{recursive:true,dereference:true});
+  await cp(npmRoot,path.join(bundle,'runtime/lib/node_modules/npm'),{recursive:true,dereference:true});
+  for(const name of ['npm','npx']) {
+    const script=path.join(bundle,'runtime/bin',name);
+    await writeFile(script,`#!/bin/sh\nsp_runtime_bin="$(cd -- "$(dirname -- "$0")" && pwd)"\nexec "$sp_runtime_bin/node" "$sp_runtime_bin/../lib/node_modules/npm/bin/${name}-cli.js" "$@"\n`);
+    await chmod(script,0o755);
+  }
+  const npmProbe=await command(path.join(bundle,'runtime/bin/npm'),['--version'],{capture:true});
+  if(npmProbe.code) {process.stderr.write(npmProbe.stderr);throw Error('Bundled npm smoke test failed.');}
+  for(const name of ['dist','scripts','engine','install.sh','install-cli.sh','package.json','package-lock.json','README.md','LICENSE','NOTICE','node_modules']) await cp(path.join(root,name),path.join(bundle,'mcp',name),{recursive:true,dereference:true});
+  await rm(path.join(bundle,'mcp/node_modules/typescript'),{recursive:true,force:true});
+  await rm(path.join(bundle,'mcp/node_modules/@types'),{recursive:true,force:true});
+  const probe=await command(path.join(bundle,'runtime/bin/node'),[path.join(bundle,'mcp/scripts/cli.mjs'),'--version'],{capture:true});
+  if(probe.code || probe.stdout.trim()!==version) {process.stderr.write(probe.stderr);throw Error('Bundled runtime smoke test failed.');}
+  await writeFile(path.join(bundle,'release.json'),JSON.stringify({version,platform:process.platform,arch:process.arch,node:process.version,engine:(await readFile(path.join(engine,'VERSION'),'utf8')).trim(),...(values.local ? {local:true} : {})})+'\n');
+  await mkdir(out,{recursive:true});
+  const archive=path.join(out,`supportpages-${version}-${process.platform}-${process.arch}.tar.gz`);
+  // -h stores symlink targets as ordinary files, so extraction needs no link
+  // support or trust. The stage was copied with dereference, so it holds no
+  // hardlinks either. COPYFILE_DISABLE keeps macOS metadata out of the archive.
+  const result=await command('tar',['-czhf',archive,'-C',stage,'supportpages'],{capture:true,env:{...process.env,COPYFILE_DISABLE:'1'}});
+  if(result.code) throw Error('Could not create the release archive.');
+  const digest=createHash('sha256').update(await readFile(archive)).digest('hex');
+  await writeFile(archive+'.sha256',`${digest}  ${path.basename(archive)}\n`);
+  process.stdout.write(archive+'\n');
+} finally {await rm(stage,{recursive:true,force:true});}