@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/scripts/lib/yolo.mjs

@@ -0,0 +1,362 @@
+// `wtfm yolo`: write a whole help centre as drafts on SupportPages.io.
+// Every account step reuses the terminal flows that init and publish use; the
+// writing itself is the server's `generate_help_centre` operation, which this
+// command starts, follows and (after a failure) resumes.
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { resolveAction, requireExecution } from '../../dist/actions.js';
+import { fail, publicError } from '../../dist/errors.js';
+import { track, secondsSince } from '../../dist/telemetry.js';
+import { Cancelled } from './terminal.mjs';
+import { CLI_NAME } from './brand.mjs';
+
+export const YOLO_ACTION = 'generate_help_centre';
+const clean = value => String(value).replace(/[\p{Cc}\p{Cf}]/gu, '');
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+const say = (ui, text) => ui.ok ? ui.ok(text) : ui.line(text);
+const inform = (ui, text) => ui.info ? ui.info(text) : ui.line(text);
+const pending = operation => ['queued', 'running'].includes(operation.status);
+const recordSchema = z.object({ version: z.literal(1), key: z.uuid(), operation_id: z.string().regex(/^[1-9][0-9]*$/).optional(),
+  reported: z.string().optional() });
+
+/** What a failed run's code means for the user, in their terms. */
+export const failureMeanings = {
+  generation_failed: 'SupportPages.io could not finish writing the help centre.',
+  invalid_content: 'The generated content could not be saved.',
+  no_sections: 'No help-centre sections could be worked out from the repository.',
+  invalid_credentials: 'The repository connection stopped working while writing.',
+  operation_timeout: 'The run stopped responding and timed out.',
+};
+
+/** This folder's run, kept with the other operation journals under .rtfm/supportpages. */
+const recordFile = (bridge, projectId) => `${bridge.stateRoot}/operations/${projectId}/help-centre.json`;
+export async function readYoloRun(bridge) {
+  const { project_id } = await bridge.binding();
+  const file = recordFile(bridge, project_id);
+  if (!await bridge.ws.exists(file)) return undefined;
+  try { const parsed = recordSchema.safeParse(await bridge.ws.json(file)); return parsed.success ? parsed.data : undefined; }
+  catch { return undefined; }
+}
+async function saveYoloRun(bridge, record) {
+  const { project_id } = await bridge.binding();
+  await bridge.ws.writeJson(recordFile(bridge, project_id), record);
+  return record;
+}
+
+/** The latest known state of this folder's run, read again from the server; undefined when there is none. */
+export async function yoloOperation(bridge) {
+  const record = await readYoloRun(bridge);
+  if (!record) return undefined;
+  if (record.operation_id) return { record, operation: await bridge.hosted.get(record.operation_id, 0, false) };
+  // The response to the submission was lost: the key finds it without starting another run.
+  try {
+    const { project_id } = await bridge.binding();
+    const operation = await bridge.api.request('GET', `/projects/${project_id}/writer_operations?idempotency_key=${encodeURIComponent(record.key)}`);
+    if (typeof operation?.id !== 'string' || !operation.id) fail('invalid_response', 'The server returned an invalid operation.');
+    const found = await bridge.hosted.get(operation.id, 0, false);
+    await saveYoloRun(bridge, { ...record, operation_id: found.id });
+    return { record: { ...record, operation_id: found.id }, operation: found };
+  } catch (error) {
+    if (publicError(error).code === 'not_found') return { record };
+    throw error;
+  }
+}
+
+export function describeProgress(result = {}) {
+  const articles = result.articles ?? {};
+  if (result.stage === 'sections') return 'Working out the sections of your help centre…';
+  if (result.stage === 'recommendations') return `Sections: ${result.sections ?? 0} · choosing which articles to write…`;
+  if (result.stage === 'articles' || result.stage === 'done') return `Writing drafts: ${articles.generated ?? 0} of ${articles.total ?? 0} done${articles.failed ? ` · ${articles.failed} failed` : ''}`;
+  return 'Queued on SupportPages.io · reading the repository analysis…';
+}
+const stageSummary = (stage, result) => stage === 'analysis' ? 'Repository analysis read'
+  : stage === 'sections' ? `Sections: ${result.sections ?? 0} accepted`
+  : stage === 'recommendations' ? `Articles to write: ${result.recommendations ?? 0} recommended${result.articles?.total !== undefined ? `, ${result.articles.total} started` : ''}`
+  : undefined;
+const order = ['analysis', 'sections', 'recommendations', 'articles', 'done'];
+
+/** A render-only progress line; test and plain UIs without one print each change once. */
+function progressFor(ui, text) {
+  if (ui.progress) return ui.progress(text);
+  let last = text; ui.line(text);
+  return { update: next => { if (next !== last) { ui.line(next); last = next; } }, stop: message => ui.line(message) };
+}
+
+/** Ctrl-C stops this terminal waiting, never the run on SupportPages.io. */
+function interruption(deps) {
+  const controller = new AbortController();
+  const onInterrupt = () => controller.abort();
+  process.once('SIGINT', onInterrupt);
+  deps.signal?.addEventListener('abort', onInterrupt, { once: true });
+  if (deps.signal?.aborted) controller.abort();
+  return { signal: controller.signal, done: () => { process.removeListener('SIGINT', onInterrupt); deps.signal?.removeEventListener('abort', onInterrupt); } };
+}
+const pause = (ms, signal) => new Promise(resolve => {
+  if (signal.aborted) return resolve();
+  const timer = setTimeout(resolve, ms);
+  signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+});
+
+/** Counted once per run attempt, whichever command observes the end. */
+async function report(bridge, record, operation) {
+  if (pending(operation) || !record) return record;
+  const id = `${operation.id}:${operation.attempt}`;
+  if (record.reported === id) return record;
+  track('yolo_completed', { outcome: operation.status, error_code: operation.error?.code,
+    duration_s: secondsSince(operation.created_at, operation.finished_at ? Date.parse(operation.finished_at) : Date.now()) });
+  return saveYoloRun(bridge, { ...record, reported: id });
+}
+
+/** Poll until the run ends or Ctrl-C detaches; network errors back off rather than end it. */
+export async function followYolo(bridge, initial, { ui, deps = {}, record, command = CLI_NAME }) {
+  const pollMs = deps.yoloPollMs ?? 3000;
+  const interrupt = interruption(deps);
+  let operation = initial, stage, progress, delay = pollMs, failures = 0;
+  const render = () => {
+    const result = operation.result ?? {};
+    const next = order.includes(result.stage) ? result.stage : 'analysis';
+    if (next !== stage) {
+      // A stage that finished between polls is still reported, in order.
+      const from = stage === undefined ? -1 : order.indexOf(stage);
+      if (progress) { progress.stop(stageSummary(stage, result) ?? describeProgress(result)); progress = undefined; }
+      if (stage !== undefined) for (const skipped of order.slice(from + 1, order.indexOf(next))) { const line = stageSummary(skipped, result); if (line) say(ui, line); }
+      stage = next;
+      if (pending(operation)) progress = progressFor(ui, describeProgress(result));
+    } else progress?.update(describeProgress(result));
+  };
+  try {
+    while (true) {
+      render();
+      if (!pending(operation)) break;
+      await pause(delay, interrupt.signal);
+      if (interrupt.signal.aborted) {
+        const message = `Stopped watching. SupportPages.io keeps writing your help centre; run ${command} status to check on it again.`;
+        if (progress) progress.stop(message, 'cancelled'); else ui.line(message);
+        return { detached: true, operation };
+      }
+      try { operation = await bridge.hosted.get(operation.id, 0, false); delay = pollMs; failures = 0; }
+      catch (error) {
+        const safe = publicError(error);
+        if (!['network_error', 'remote_error', 'rate_limited', 'connection_error'].includes(safe.code) || ++failures > (deps.yoloMaxFailures ?? 20)) {
+          progress?.stop(`Lost track of the run: ${safe.message}`, 'error');
+          ui.line(`SupportPages.io keeps writing. Run ${command} status to check on it again.`);
+          throw error;
+        }
+        delay = Math.min(pollMs * 2 ** failures, deps.yoloMaxDelayMs ?? 30_000);
+        progress?.update(`SupportPages.io could not be reached; trying again in ${Math.max(1, Math.round(delay / 1000))}s…`);
+      }
+    }
+  } finally { interrupt.done(); }
+  if (progress) { progress.stop(operation.status === 'succeeded' ? 'Writing finished' : 'The run stopped', operation.status === 'succeeded' ? 'success' : 'error'); }
+  record = await report(bridge, record ?? await readYoloRun(bridge), operation);
+  return { detached: false, operation };
+}
+
+/** The closing summary: counts and the editor link, or what failed and how to resume. */
+export function summarizeYolo(operation, { ui, resume = `${CLI_NAME} yolo` }) {
+  const result = operation.result ?? {};
+  const articles = result.articles ?? {};
+  const link = result.editor_url ?? operation.review_url;
+  if (operation.status === 'succeeded') {
+    const lines = [`Sections        ${result.sections ?? 0}`, `Drafts written  ${articles.generated ?? 0}${articles.failed ? ` (${articles.failed} could not be written)` : ''}`,
+      ...(link ? [`Review          ${clean(link)}`] : [])];
+    if (ui.note) ui.note(lines.join('\n'), 'Your manual is written'); else ui.line(lines.join('\n'));
+    const text = (articles.generated ?? 0) === 0 && !(articles.total)
+      ? 'No new drafts were needed: every recommended article already exists or your plan has no article allowance left.'
+      : `Everything is a draft: nothing goes live until you publish it. Review and publish in SupportPages.io${link ? `: ${clean(link)}` : '.'}`;
+    if (ui.outro) ui.outro(text); else ui.line(text);
+    return;
+  }
+  const code = operation.error?.code ?? 'generation_failed';
+  const meaning = failureMeanings[code] ?? `The run failed (${clean(code)}).`;
+  const kept = articles.generated ? ` The ${plural(articles.generated, 'draft')} already written ${articles.generated === 1 ? 'is' : 'are'} kept.` : '';
+  if (kept || link) ui.line(`${kept.trim()}${kept && link ? '\n' : ''}${link ? `Review: ${clean(link)}` : ''}`);
+  const hint = code === 'invalid_credentials' ? `Reconnect the repository in SupportPages.io, then run ${resume} to resume.` : `Run ${resume} to resume where it stopped.`;
+  fail(code, `${meaning} ${hint}`);
+}
+
+/**
+ * Route each prerequisite the server reports to the flow that resolves it, and
+ * return once generate_help_centre is allowed. Browser steps open their page
+ * (or print it) and poll until the server reports a different state.
+ */
+async function prerequisites(session, deps, helpers, initialBridge, { resuming = false } = {}) {
+  const { ui } = deps;
+  const open = deps.open;
+  let bridge = initialBridge, waited = new Set();
+  for (let rounds = 0; rounds < 20; rounds++) {
+    const decision = await resolveAction(bridge, YOLO_ACTION);
+    if (decision.allowed) { requireExecution(decision, 'hosted'); return bridge; }
+    const next = decision.next_step;
+    // Resuming reuses the allowance the run already reserved, so a spent plan does not block it.
+    if (resuming && next.code === 'plan_limit') return bridge;
+    if (next.code === 'authentication_required') {
+      await helpers.ensureLogin(session, deps);
+      bridge = await session.bridge();
+      continue;
+    }
+    if (next.code === 'permission_required') {
+      const scopes = (next.missing_scopes ?? ['generate']).filter(scope => ['publish', 'manage', 'generate'].includes(scope));
+      ui.line('Writing on SupportPages.io needs this device to have the “generate” permission. Approve it in your browser; the current sign-in keeps working until you do.');
+      await helpers.ensureLogin(session, deps, { scopes });
+      bridge = await session.bridge();
+      continue;
+    }
+    const browserStep = /^repository_(required|disconnected|suspended)$|^analysis_(required|failed)$|^analysing$|^plan_limit$/.test(next.code);
+    if (!browserStep) requireExecution(decision, 'hosted');
+    const titles = { repository_required: 'Connect your repository', repository_disconnected: 'Reconnect your repository', repository_suspended: 'Restore repository access',
+      analysing: 'Analysing your repository', analysis_required: 'Analyse your repository', analysis_failed: 'Repository analysis failed', plan_limit: 'No article allowance left' };
+    const why = /^repository_/.test(next.code) ? 'SupportPages.io reads your code to write the manual, so it needs access to the repository.'
+      : next.code === 'plan_limit' ? 'Your plan has no article allowance left for new drafts.'
+      : 'SupportPages.io analyses the repository before it can plan your help centre.';
+    const message = `${why}\n${clean(next.message)}${next.url ? `\n\n${clean(next.url)}` : ''}`;
+    if (ui.note) ui.note(message, titles[next.code]); else ui.line(message);
+    // Each page opens once per run; later polls of the same state only wait.
+    if (next.url && next.code !== 'analysing' && !waited.has(next.url)) {
+      waited.add(next.url);
+      if (!await open(next.url)) ui.line('Open the link above in your browser, then return here.');
+    }
+    if (next.code === 'plan_limit') {
+      if (!await ui.confirm('Check your plan again and continue?', true)) throw new Cancelled(`Stopped. Run ${CLI_NAME} yolo again once your plan has article allowance.`);
+      continue;
+    }
+    await waitForChange(bridge, next.code, deps);
+  }
+  fail('setup_incomplete', `Setup did not finish. Run ${CLI_NAME} yolo again to continue.`);
+}
+
+/** Poll the server's decision until it leaves `code`, e.g. once the repository is connected. */
+async function waitForChange(bridge, code, deps) {
+  const { ui } = deps;
+  const interrupt = interruption(deps);
+  const waiting = code === 'analysing' || /^analysis_/.test(code) ? 'Waiting for the repository analysis' : code === 'repository_suspended' ? 'Waiting for repository access' : 'Waiting for the repository connection';
+  const progress = progressFor(ui, `${waiting}… Ctrl+C stops waiting.`);
+  const deadline = Date.now() + (deps.yoloWaitMs ?? 30 * 60_000);
+  try {
+    while (Date.now() < deadline) {
+      await pause(deps.yoloPollMs ?? 3000, interrupt.signal);
+      if (interrupt.signal.aborted) { progress.stop('Stopped waiting.', 'cancelled'); throw new Cancelled(`Stopped waiting. Run ${CLI_NAME} yolo again when that step is done.`); }
+      let decision;
+      try { decision = await resolveAction(bridge, YOLO_ACTION); }
+      catch (error) { if (['network_error', 'remote_error', 'rate_limited'].includes(publicError(error).code)) continue; throw error; }
+      if (decision.next_step?.code !== code) { progress.stop(code === 'analysing' || /^analysis_/.test(code) ? 'Repository analysis is ready.' : 'Repository connected.'); return; }
+    }
+    progress.stop('Still waiting.', 'error');
+    fail('setup_incomplete', `That step is not finished yet. Run ${CLI_NAME} yolo again when it is.`);
+  } finally { interrupt.done(); }
+}
+
+/** Remaining allowance for this help centre, or undefined when the server does not say. */
+async function allowance(bridge) {
+  try {
+    const capacity = (await bridge.context()).article_capacity;
+    if (!capacity) return undefined;
+    return capacity.limit === null ? { unlimited: true } : { remaining: Math.max(0, capacity.limit - capacity.used), limit: capacity.limit };
+  } catch { return undefined; }
+}
+
+export async function runYolo({ session, config, options, deps, helpers, root }) {
+  const { ui } = deps;
+  const command = helpers.authCommand('yolo', config);
+  ui.intro?.(`WTFM · Write the whole manual${config.dev ? ' · Development' : ''}`);
+  ui.line('SupportPages.io writes your help centre on its servers from your repository. Everything is saved as drafts: nothing goes live until you publish it.');
+
+  // 1. Account: the same browser sign-in as publish.
+  const signedIn = await helpers.account(session);
+  if (!signedIn) {
+    ui.step?.(1, 'Sign in to SupportPages.io', 3);
+    const mode = await ui.choose('This needs a SupportPages.io account. How would you like to sign in?', helpers.getStartedChoices.slice(0, 2));
+    await helpers.ensureLogin(session, deps, { mode });
+  } else await helpers.ensureLogin(session, deps);
+
+  // 2. Help centre: keep this folder's, or bind/create one as publish does.
+  let bridge = await session.bridge();
+  if (await bridge.destination() !== 'hosted') {
+    ui.step?.(2, 'Choose your help centre', 3);
+    const status = await session.status();
+    if (status.status === 'connection_error') fail('connection_error', status.error?.message ?? `SupportPages.io could not be reached. Check your connection and retry ${command}.`);
+    const local = await bridge.local();
+    await helpers.chooseHelpCentre(session, bridge, deps, { draft: { writingStyle: local?.writing_style } });
+    await helpers.saveProfile(root, config);
+    bridge = await session.bridge();
+  } else {
+    const status = await session.status();
+    if (status.status !== 'ready') fail(status.status === 'project_unavailable' ? 'project_unavailable' : 'connection_error',
+      status.status === 'project_unavailable' ? `This folder's help centre is no longer available to this account. Run ${helpers.authCommand('init', config)} to choose another.` : status.error?.message ?? `SupportPages.io could not be reached. Retry ${command}.`);
+    ui.line(`Help centre: ${clean(status.project.name)}${status.project.help_centre_url ? ` · ${clean(status.project.help_centre_url)}` : ''}`);
+  }
+
+  // 3. A run already known to this folder: attach to it, or resume it after a failure.
+  ui.step?.(3, 'Write the manual', 3);
+  const existing = await yoloOperation(bridge);
+  if (existing?.operation && pending(existing.operation)) {
+    inform(ui, 'SupportPages.io is already writing this help centre. Showing its progress.');
+    return finish(bridge, existing.operation, existing.record);
+  }
+  if (existing?.operation?.status === 'failed') {
+    const code = existing.operation.error?.code ?? 'generation_failed';
+    ui.line(`The last run stopped: ${failureMeanings[code] ?? clean(code)} Resuming keeps everything it already wrote.`);
+    if (!options.yes && !await ui.confirm('Resume writing where it stopped?', true)) throw new Cancelled(`Nothing was started. Run ${command} to resume later.`);
+    bridge = await prerequisites(session, deps, helpers, bridge, { resuming: true });
+    let operation;
+    try { operation = await bridge.hosted.retry(existing.operation.id, existing.operation.attempt); }
+    catch (error) {
+      if (error.code === 'generation_running') return attachElsewhere(ui, command);
+      throw error;
+    }
+    return finish(bridge, operation, existing.record);
+  }
+  if (existing && !existing.operation) {
+    // Submitted, but the server never recorded it: start again with the same key.
+    return submit(session, deps, helpers, bridge, options, existing.record, command);
+  }
+  return submit(session, deps, helpers, bridge, options, undefined, command);
+
+  async function finish(current, operation, record) {
+    const followed = await followYolo(current, operation, { ui, deps, record, command: CLI_NAME });
+    if (followed.detached) return { status: 'detached', operation_id: operation.id, review_url: followed.operation.review_url };
+    summarizeYolo(followed.operation, { ui, resume: command });
+    const result = followed.operation.result ?? {};
+    return { status: followed.operation.status, operation_id: followed.operation.id, editor_url: result.editor_url ?? followed.operation.review_url, result };
+  }
+
+  async function submit(currentSession, currentDeps, currentHelpers, current, opts, previous, cmd) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      current = await prerequisites(currentSession, currentDeps, currentHelpers, current);
+      if (!previous) {
+        const capacity = await allowance(current);
+        const limit = capacity?.unlimited ? 'Your plan has no article limit, so every recommended article is written.'
+          : capacity ? `Your plan allows ${plural(capacity.remaining, 'more article')}${capacity.limit ? ` (of ${capacity.limit})` : ''}, so up to ${plural(capacity.remaining, 'draft')} ${capacity.remaining === 1 ? 'is' : 'are'} written.`
+          : 'Up to your plan’s article allowance is written; free plans cover 10 guides.';
+        const plan = ['SupportPages.io will, on its servers:', '  1. Work out the sections of your help centre from the repository analysis',
+          '  2. Choose the articles your users need', '  3. Write them as drafts', '', limit,
+          'Nothing goes live until you publish it. You can close this terminal; the run keeps going.'].join('\n');
+        if (ui.note) ui.note(plan, 'Ready to write the manual'); else ui.line(plan);
+        if (!opts.yes && !await ui.confirm('Start writing?', true)) throw new Cancelled('Nothing was started.');
+      }
+      const record = previous ?? { version: 1, key: randomUUID() };
+      // The key is saved before submission, so a lost response never starts a second run.
+      await saveYoloRun(current, { version: 1, key: record.key });
+      let operation;
+      try {
+        operation = await current.hosted.submit(YOLO_ACTION, {}, { request_id: record.key, decision: await resolveAction(current, YOLO_ACTION) });
+      } catch (error) {
+        if (error.code === 'generation_running') return attachElsewhere(ui, cmd);
+        // A prerequisite changed between the check and the submission: route it again.
+        if (['permission_denied', 'plan_limit', 'permission_required'].includes(error.code) || /^(repository_|analysis_|analysing$)/.test(error.code ?? '')) { previous = undefined; continue; }
+        throw error;
+      }
+      const saved = await saveYoloRun(current, { version: 1, key: record.key, operation_id: operation.id });
+      track('yolo_started');
+      say(ui, 'Started. SupportPages.io is writing your manual.');
+      return finish(current, operation, saved);
+    }
+    fail('setup_incomplete', `The help centre could not be started. Run ${cmd} again.`);
+  }
+}
+
+/** Another device or session started the run this folder does not know about. */
+function attachElsewhere(ui, command) {
+  ui.line('SupportPages.io is already writing this help centre from another session or device. Watch it in SupportPages.io; drafts appear in the editor as they are written.');
+  return { status: 'already_running', instructions: `Run ${command} again after it finishes to write more.` };
+}

package/scripts/plugin-session.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Plugin SessionStart hook: make sure Chromium for article screenshots exists.
+//
+// Plugin installs run npm without lifecycle scripts, so puppeteer's Chromium
+// download never happened. This hook returns immediately (it must not delay the
+// session or print into its context) and, when Chromium is missing, starts the
+// download in a detached process guarded by a lock.
+//
+//   node plugin-session.mjs              check; start a background download if needed
+//   node plugin-session.mjs --download   download now (used by the background process)
+import { spawn } from 'node:child_process';
+import { mkdir, open, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { command } from './lib/install.mjs';
+import { ensureRenderer, rendererReady } from './lib/renderer.mjs';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const engine = path.join(root, 'engine');
+const dataDir = process.env.CLAUDE_PLUGIN_DATA || path.join(os.tmpdir(), 'supportpages-writer');
+const lockFile = path.join(dataDir, 'chromium-download.lock');
+const STALE_MS = 30 * 60 * 1000;
+const quiet = (cmd, args, options = {}) => command(cmd, args, { ...options, capture: true });
+
+/** True when a download started less than 30 minutes ago is still recorded. */
+export async function downloadInProgress() {
+  try { return Date.now() - (await stat(lockFile)).mtimeMs < STALE_MS; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+/** Start a detached download unless one is already running. */
+export async function startDownload() {
+  if (await downloadInProgress()) return;
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), '--download'], { detached: true, stdio: 'ignore', env: process.env });
+  child.on('error', () => {});
+  child.unref();
+}
+
+async function download() {
+  await mkdir(dataDir, { recursive: true });
+  let handle;
+  try { handle = await open(lockFile, 'wx'); }
+  catch (error) {
+    if (error.code !== 'EEXIST' || await downloadInProgress()) return;
+    await rm(lockFile, { force: true });
+    handle = await open(lockFile, 'wx');
+  }
+  try {
+    await handle.writeFile(String(process.pid));
+    await ensureRenderer(engine, quiet);
+  } finally {
+    await handle.close();
+    await rm(lockFile, { force: true });
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    if (process.argv.includes('--download')) await download();
+    else if (!await rendererReady(engine, quiet)) await startDownload();
+  } catch { /* A hook must never break the session. */ }
+}
+
+export { lockFile };

package/scripts/prepare-update.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { prepareUpdate } from './lib/prepare-update.mjs';
+
+try {
+  if (!process.argv[2]) throw Error('The previous installation is required.');
+  await prepareUpdate(process.argv[2], path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+} catch (error) {
+  process.stderr.write(error.message + '\n');
+  process.exitCode = 1;
+}

package/scripts/publish-release.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { copyFile, readFile, writeFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { parseArgs, promisify } from 'node:util';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { checkRelease, releaseVersionPattern, repositoryRoot } from './check-release.mjs';
+
+// Keep publishing independent of the built CLI and its npm dependencies.
+const execute = promisify(execFile);
+const runAws = async (args, env) => (await execute('aws', args, { env, maxBuffer: 1024 * 1024 })).stdout;
+
+function newerThan(version, previous) {
+  if (!releaseVersionPattern.test(previous)) throw Error('The remote latest.txt is not a valid release version.');
+  const a = version.split('.').map(BigInt), b = previous.split('.').map(BigInt);
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return false;
+}
+
+export async function publishRelease({ directory = 'release', root = repositoryRoot, dryRun = false, env = process.env, run = runAws } = {}) {
+  directory = path.resolve(directory);
+  const version = await checkRelease({ root, env });
+  const archives = [];
+  // Validate every platform before making any remote changes.
+  for (const platform of ['darwin', 'linux']) for (const arch of ['arm64', 'x64']) {
+    const name = `supportpages-${version}-${platform}-${arch}.tar.gz`;
+    const sha256 = createHash('sha256').update(await readFile(path.join(directory, name))).digest('hex');
+    if ((await readFile(path.join(directory, name + '.sha256'), 'utf8')).trim() !== `${sha256}  ${name}`) {
+      throw Error(`Release checksum mismatch: ${name}`);
+    }
+    archives.push({ platform, arch, name, sha256 });
+  }
+  const manifest = { version, archives };
+  await writeFile(path.join(directory, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+  await writeFile(path.join(directory, 'latest.txt'), version + '\n');
+  await copyFile(path.join(root, 'install-cli.sh'), path.join(directory, 'install.sh'));
+  if (dryRun) return manifest;
+
+  const bucket = env.CLI_RELEASE_BUCKET;
+  if (!bucket || !/^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/.test(bucket)) {
+    throw Error('Set CLI_RELEASE_BUCKET to the dedicated R2 download bucket.');
+  }
+  // Accept Cloudflare's default and jurisdiction-specific S3 endpoints only.
+  const endpoint = env.CLI_RELEASE_R2_ENDPOINT;
+  if (!/^https:\/\/[a-f0-9]{32}(?:\.(?:eu|fedramp|us))?\.r2\.cloudflarestorage\.com\/?$/.test(endpoint ?? '')) {
+    throw Error('Set CLI_RELEASE_R2_ENDPOINT to the HTTPS S3 API endpoint shown in the R2 bucket settings.');
+  }
+  if (!env.AWS_ACCESS_KEY_ID || !env.AWS_SECRET_ACCESS_KEY) {
+    throw Error('Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to the R2 access key pair.');
+  }
+  const awsEnv = { ...env, AWS_DEFAULT_REGION: 'auto', AWS_REGION: 'auto', AWS_EC2_METADATA_DISABLED: 'true', AWS_PAGER: '',
+    AWS_REQUEST_CHECKSUM_CALCULATION: 'when_required', AWS_RESPONSE_CHECKSUM_VALIDATION: 'when_required' };
+  delete awsEnv.AWS_SESSION_TOKEN;
+  delete awsEnv.AWS_PROFILE;
+  const aws = args => run(['--endpoint-url', endpoint, '--region', 'auto', ...args], awsEnv);
+  const contents = async (prefix, maxKeys) => {
+    const result = JSON.parse(await aws(['s3api', 'list-objects-v2', '--bucket', bucket, '--prefix', prefix, '--max-keys', String(maxKeys), '--no-paginate', '--output', 'json']));
+    if (!result || typeof result !== 'object' || (result.Contents !== undefined && !Array.isArray(result.Contents))) {
+      throw Error('Could not check the R2 bucket contents.');
+    }
+    return result.Contents ?? [];
+  };
+  if ((await contents(`${version}/`, 1)).length) throw Error('Cannot publish over an existing release. Use a new version.');
+  if ((await contents('latest.txt', 1)).some(object => object.Key === 'latest.txt')) {
+    const previous = (await aws(['s3', 'cp', `s3://${bucket}/latest.txt`, '-', '--only-show-errors'])).trim();
+    if (!newerThan(version, previous)) throw Error(`Cannot promote ${version}: latest is already ${previous}.`);
+  }
+  const upload = async (name, key, cacheControl) => {
+    const contentType = name.endsWith('.tar.gz') ? 'application/gzip' : name.endsWith('.json') ? 'application/json' : 'text/plain';
+    await aws(['s3', 'cp', path.join(directory, name), `s3://${bucket}/${key}`, '--cache-control', cacheControl, '--content-type', contentType, '--only-show-errors']);
+  };
+  for (const name of [...archives.flatMap(archive => [archive.name, archive.name + '.sha256']), 'manifest.json', 'install.sh']) {
+    await upload(name, `${version}/${name}`, 'public,max-age=31536000,immutable');
+  }
+  // Mutable entry points are promoted only after every versioned upload succeeds.
+  await upload('install.sh', 'install.sh', 'no-cache');
+  await upload('latest.txt', 'latest.txt', 'no-cache');
+  return manifest;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  const { values } = parseArgs({ options: { directory: { type: 'string' }, 'dry-run': { type: 'boolean' } } });
+  try {
+    const manifest = await publishRelease({ directory: values.directory, dryRun: values['dry-run'] });
+    process.stdout.write(values['dry-run'] ? JSON.stringify(manifest, null, 2) + '\n' : `Published SupportPages.io ${manifest.version} to R2.\n`);
+  } catch (error) {
+    process.stderr.write(`Release failed: ${error.message}\nlatest.txt is promoted only after all other uploads succeed.\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/skills/supportpages/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: supportpages
+description: Create or retry illustrated help articles in SupportPages.io using its MCP connection and article writer. Use for SupportPages.io article requests, including generating an unpublished draft for review.
+---
+
+<!-- Managed by SupportPages: article coordination v1 -->
+
+# SupportPages.io articles
+
+Use the SupportPages.io MCP connection for the current project.
+
+For inventory questions such as "what support articles do we have?", call
+`supportpages_list_articles` directly, without status or initialization first.
+When signed out or in local mode it reads the project's current local article
+files. Report those titles and paths without asking the user to sign in. An empty
+local list means no local articles were found, not that the hosted help centre is
+empty. Do not infer the inventory from Git status. Use `source: "hosted"` only
+when the user explicitly asks what is on SupportPages.io.
+
+For article creation, check
+`supportpages_status`, finish initialization if required, and call
+`supportpages_prepare_article` before writing. Follow the returned readiness or
+capacity instructions. Show the prepared editor link; a preview is not a finished
+draft.
+
+When the prepared run has `prefer_background: true`, **delegate the writing task
+to a background subagent**. This skill explicitly requests delegation for that
+article. Use the SupportPages.io writer and the returned Codex launch instructions,
+including the complete task brief, model settings and self-contained entrypoint.
+Pass the complete task brief directly in the subagent tool's task/message argument
+on launches and retries. Do not copy it into a temporary JSON file, create a
+handoff script, or print it with a shell command. The existing entrypoint already
+loads the saved run; no parent-side file edit is needed to launch the writer.
+If no custom-agent selector exists, use a named SupportPages.io subagent with the
+supplied writer instructions. The writer runs the entrypoint before generating
+anything, uses the command wrapper, and runs the finish command after validation.
+
+**Prioritize completion and approvals over quiet operation.** After launch,
+record the actual execution mode and host task identity with
+`supportpages_update_run`. Show the editor link and say "launched" unless actual
+writer startup is confirmed. Keep the main turn active and supervise the writer
+using the host's agent wait/message facilities. Use bounded waits and concise
+progress updates; do not end the turn merely because launch succeeded.
+
+The writer may send milestone updates and must surface blockers immediately.
+When an operation needs permission and host policy permits it, the writer should
+request approval directly through the host's native approval mechanism, with the
+exact command and reason. A sandbox restriction is not an explicit user denial.
+Do not suppress approval prompts or route them only to an idle parent. Continue
+after approval is granted. An explicit denial or a policy forbidding approval
+requests stops that action; never bypass it or enable YOLO.
+
+If a background writer cannot surface approvals, confirm it has stopped and
+continue the same article in the foreground using MCP recovery instructions and
+the normal approval mechanism. Foreground execution retains the same permissions.
+If the host cannot supervise a delegated task, use foreground execution. Keep
+the MCP session alive; do not launch a separate agent CLI.
+
+Inspect the writer's final result and saved run. A host "Completed" notification
+does not establish success. For a stopped writer that failed or is
+`permission_blocked` before generation finished, record `event: "failed"` and
+`stopped: true` with `supportpages_update_run`, then show the specific cause,
+recovery and editor link. Do not mark a writer failed while awaiting approval.
+If generation succeeded but delivery is pending or failed, recover with
+`supportpages_complete_article` without regenerating or marking the writer failed.
+
+The main agent owns MCP calls. After successful writing, call
+`supportpages_complete_article` to confirm delivery, report the final editor link
+and follow its completion instructions. Leave the article unpublished until the
+user affirmatively asks to publish that draft.
+
+**Local folders.** When `supportpages_status` or `supportpages_init` reports
+`local`, the folder has no help centre and needs no sign-in: articles are saved
+as Markdown with their screenshots. There is no capacity check, preview or editor
+link. Show the saved markdown path returned by `supportpages_complete_article` as
+the deliverable and never ask whether to publish automatically. Mention once
+that running `wtfm publish` in the terminal hosts the saved articles.
+
+If the user explicitly asks to host or publish saved local articles, call
+`supportpages_publish`. Follow its browser approval and help-centre selection
+steps, then pass the selected article slugs. It uploads drafts and connects the
+folder for future articles. Do not accept credentials in chat or approve sign-in
+for the user. Making those drafts publicly visible is a separate action using
+`supportpages_publish_article` when authorized.
+
+**Hosted analysis and videos.** Use `supportpages_find_article_gaps`,
+`supportpages_suggest_sections`, `supportpages_recommend_articles` or
+`supportpages_create_video_walkthrough` for the requested action. These tools
+check the prerequisites and open required browser setup pages. When signed out,
+first explain that an account/device sign-in is needed; sign in or create an
+account through the opened approval page. Do not begin with a repository invitation
+or send the user to the app homepage. Show the comparison code, and show the link
+as a fallback if `browser_opened` is false. Never approve browser consent.
+
+After the user completes a step, call `supportpages_setup_hosted` with the
+returned `next_arguments`. Ask which help centre to use when `project_required`
+is returned (or use `supportpages_create_project` if the user wants a new one),
+then pass its `project_id`. The next required device-consent or repository setup
+page opens automatically. Preserve the original request and `resume_arguments`
+through these steps; do not start local analysis, recording or unrelated jobs.
+Once setup is available, retry `resume_tool` with `resume_arguments`. Walkthroughs
+require a completed hosted article: use `supportpages_list_articles` with
+`source: "hosted"` to select it. Do not restore deleted files or upload a local
+article without the user's explicit instruction. Finished videos remain private
+until explicitly shared.
+
+Honor an explicit request to return immediately, explaining that approvals and
+completion may need another user turn on hosts that do not wake the parent.
+Retain the run ID and host task identity; reconcile the run on resumption.
+
+Honor an explicit foreground request. If delegation cannot run, distinguish a
+missing host tool, an explicit session restriction, or the actual launch error;
+do not infer that background execution is disabled merely because the user did
+not separately request a subagent. Explain the specific limitation and use the
+same prepared brief in the foreground. Stop any launched writer before switching
+modes. Do not override host restrictions or launch a separate agent CLI.
+
+For retries, follow the MCP recovery instructions and use
+`supportpages_retry_article` after stopping the old writer. If generation already
+finished and delivery failed, recover delivery instead of regenerating.