@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/scripts/lib/terminal.mjs

@@ -0,0 +1,252 @@
+import readline from 'node:readline';
+import { Writable } from 'node:stream';
+import { stripVTControlCharacters } from 'node:util';
+import { CLI_NAME, LEGACY_CLI_NAME } from './brand.mjs';
+// The standalone CLI bundles Clack. The source install.sh bootstrap can run
+// before npm dependencies exist, so keep its plain prompts and --help usable.
+let prompts;
+try {
+  prompts = await import('@clack/prompts');
+}
+catch (error) {
+  if (error.code !== 'ERR_MODULE_NOT_FOUND' || !error.message.includes("Cannot find package '@clack/prompts'")) throw error;
+}
+
+const plain = value => stripVTControlCharacters(String(value)).replace(/[\r\n\t]/g, ' ').replace(/[\p{Cc}\p{Cf}]/gu, '');
+
+// Style human-facing command references at the display boundary, keeping saved
+// messages, prompt values and machine-readable output free of ANSI escapes.
+export function emphasizeCommands(text, output = process.stdout, env = process.env) {
+  if (!output.isTTY || env.TERM === 'dumb' || env.NO_COLOR !== undefined) return String(text);
+  const argument = String.raw`(?:'[^'\n]*'|"[^"\n]*"|[^\s,;!?]+)`;
+  const flag = String.raw`(?:--(?:dev|refresh|yes|json|skills-only)\b|--(?:workspace|api-url|config-dir|skills-dir|project|agent|app-type)(?:[ \t]+|=)${argument})`;
+  const command = new RegExp(String.raw`(?<![\w/.-])(?:${CLI_NAME}|${LEGACY_CLI_NAME})[ \t]+(?:setup|init|uninit|login|logout|status|sync|configure|doctor|analyse|sections|recommend|write|publish|yolo|update|remove|--help|--version)\b(?:[ \t]+${flag})*`, 'g');
+  return String(text).replace(command, value => {
+    const suffix = value.match(/[.]+$/)?.[0] ?? '';
+    return `\x1b[1;36m${suffix ? value.slice(0, -suffix.length) : value}\x1b[39;22m${suffix}`;
+  });
+}
+
+const wrapWords = (text, width) => {
+  const lines = [];
+  let current = '';
+  for (const word of text.trim().split(/\s+/u)) {
+    if (current && Array.from(`${current} ${word}`).length <= width) { current += ` ${word}`; continue; }
+    if (current) lines.push(current);
+    const chars = Array.from(word);
+    while (chars.length > width) lines.push(chars.splice(0, width).join(''));
+    current = chars.join('');
+  }
+  if (current) lines.push(current);
+  return lines;
+};
+
+// "Write the F***ing Manual" in figlet's "Pagga" font, over two lines so it
+// fits an 80-column terminal. Generated once with figlet (see
+// dev/figlet-fonts.mjs); the CLI does not depend on it.
+const logoRows = [
+  '░█░█░█▀▄░▀█▀░▀█▀░█▀▀░░░▀█▀░█░█░█▀▀░░░░░░░░░░░░░░░░░░░░',
+  '░█▄█░█▀▄░░█░░░█░░█▀▀░░░░█░░█▀█░█▀▀░░░░░░░░░░░░░░░░░░░░',
+  '░▀░▀░▀░▀░▀▀▀░░▀░░▀▀▀░░░░▀░░▀░▀░▀▀▀░░░░░░░░░░░░░░░░░░░░',
+  '░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░',
+  '░█▀▀░▄░▄░▄░▄░▄░▄░▀█▀░█▀█░█▀▀░░░█▄█░█▀█░█▀█░█░█░█▀█░█░░',
+  '░█▀▀░▄█▄░▄█▄░▄█▄░░█░░█░█░█░█░░░█░█░█▀█░█░█░█░█░█▀█░█░░',
+  '░▀░░░▄▀▄░▄▀▄░▄▀▄░▀▀▀░▀░▀░▀▀▀░░░▀░▀░▀░▀░▀░▀░▀▀▀░▀░▀░▀▀▀',
+];
+const logoWidth = 54;
+// "F***ing" (rows 4-6, before this column) is green, as on the landing page;
+// the ░ texture is dimmed.
+const accentRow = 4, accentColumn = 28;
+
+/** The logo when it fits unwrapped, otherwise undefined. */
+export function logo({ columns = 80, color = false } = {}) {
+  if (columns <= logoWidth) return undefined;
+  if (!color) return logoRows.join('\n');
+  const paint = (char, row, column) =>
+    char === '░' ? `\x1b[90m${char}\x1b[39m` : row >= accentRow && column < accentColumn ? `\x1b[32m${char}\x1b[39m` : char;
+  return logoRows.map((row, index) => Array.from(row, (char, column) => paint(char, index, column)).join('')
+    .replace(/\x1b\[39m\x1b\[(90|32)m/g, '\x1b[$1m')).join('\n');
+}
+
+export class Cancelled extends Error {
+  constructor(message = 'Setup cancelled. Completed installation steps are kept; rerun to continue.') { super(message); }
+}
+
+export function createTerminal(input = process.stdin, output = process.stdout, env = process.env) {
+  let active;
+  const color = output.isTTY && env.TERM !== 'dumb' && env.NO_COLOR === undefined;
+  const menus = prompts && input.isTTY && output.isTTY && typeof input.setRawMode === 'function' && env.TERM !== 'dumb';
+  const accent = text => color ? `\x1b[36m${text}\x1b[0m` : text;
+  const format = text => emphasizeCommands(text, output, env);
+  const raw = text => output.write(text + '\n');
+  // Clack does not wrap log lines; wrap paragraphs to the frame width ourselves.
+  const wrap = text => String(text).split('\n').flatMap(paragraph => paragraph.trim() ? wrapWords(paragraph, Math.max(20, (output.columns || 80) - 5)) : ['']).join('\n');
+  // Interactive sessions keep every message inside Clack's guide line; literal
+  // output (JSON, commands to copy) is never reflowed or prefixed.
+  const line = (text, { literal = false } = {}) => literal || !menus ? raw(literal ? text : format(text)) : prompts.log.message(format(wrap(text)), display);
+  // Clack uses process-wide colour detection. Respect this terminal's NO_COLOR
+  // setting too, while retaining cursor movement for keyboard navigation.
+  const styledOutput = new Proxy(output, {
+    get(target, key) {
+      if (key === 'columns') return target.columns > 0 ? target.columns : 80;
+      if (key === 'rows') return target.rows > 0 ? target.rows : 24;
+      if (key === 'write' && !color) return (chunk, ...args) => target.write(String(chunk).replace(/\x1b\[[0-9;]*m/g, ''), ...args);
+      const value = Reflect.get(target, key, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+  const display = { output: styledOutput };
+  const prompt = async (render, options) => {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    const onKey = (_text, key) => { if (key?.ctrl && key.name === 'd') cancel(); };
+    const wasRaw = Boolean(input.isRaw), wasFlowing = input.readableFlowing === true;
+    active = cancel;
+    input.once('end', cancel);
+    input.once('close', cancel);
+    input.on('keypress', onKey);
+    try {
+      const value = await render({ ...options, input, ...display, signal: controller.signal });
+      if (prompts.isCancel(value)) throw new Cancelled();
+      return value;
+    } finally {
+      input.off('end', cancel);
+      input.off('close', cancel);
+      input.off('keypress', onKey);
+      input.setRawMode(wasRaw);
+      if (!wasFlowing) input.pause();
+      if (active === cancel) active = undefined;
+    }
+  };
+  const ask = (label, fallback = '', hidden = false) => new Promise((resolve, reject) => {
+    if (!input.isTTY || !output.isTTY) return reject(new Error('Interactive setup requires a terminal. Use --yes with explicit options for unattended setup.'));
+    // A muted output stream keeps readline editing/history off screen for secrets.
+    // There is no fallback to echoed input on terminals that cannot hide it.
+    const sink = hidden ? new Writable({ write(_chunk, _encoding, done) { done(); } }) : output;
+    const rl = readline.createInterface({ input, output: sink, terminal: true, historySize: 0 });
+    let settled = false;
+    const finish = (err, value) => {
+      if (settled) return;
+      settled = true;
+      active = undefined;
+      rl.close();
+      if (hidden) output.write('\n');
+      err ? reject(err) : resolve(value?.trim() || fallback);
+    };
+    active = () => finish(new Cancelled());
+    rl.once('SIGINT', () => finish(new Cancelled()));
+    rl.once('close', () => { if (!settled) finish(new Cancelled()); });
+    output.write(`${label}${fallback ? ` [${fallback}]` : ''}: `);
+    rl.question('', value => finish(null, value));
+  });
+  const choices = options => {
+    if (!options.length) throw new Error('This question has no options to select.');
+    return options.map(option => ({ ...option, label: plain(option.label), ...(option.hint ? { hint: plain(option.hint) } : {}) }));
+  };
+  return {
+    cancel: () => active?.(),
+    line,
+    // A fresh screen keeps the wizard's frame and choices in view; scrollback is kept.
+    // The wordmark is decoration: only on the wizard screen, and only when it fits unwrapped.
+    intro: (title, { banner = false } = {}) => {
+      if (!menus) return line(`\n${title}`);
+      output.write('\x1b[H\x1b[2J');
+      const art = banner && logo({ columns: output.columns || 80, color });
+      if (art) output.write(`\n${art}\n\n`);
+      prompts.intro(title, display);
+    },
+    // Clack starts the outro after its └ corner; align continuation lines with the first.
+    outro: text => menus ? prompts.outro(format(wrap(text)).replace(/\n/g, '\n   '), display) : line(`\n${text}`),
+    note: (text, title) => menus ? prompts.note(format(text), title, display) : line(`\n${title}\n${text}`),
+    info: text => menus ? prompts.log.info(format(wrap(text)), display) : line(text),
+    progress: initial => {
+      // Clack's spinner captures stdin and exits on Ctrl+C. Keep this display
+      // render-only so the runner can stop the child and restore the terminal.
+      let stopped = false, lastLine = Date.now(), lastMessage = plain(initial);
+      let frame = 0, animation;
+      const render = () => {
+        const width = Math.max(8, (output.columns || 80) - 6);
+        const chars = Array.from(lastMessage);
+        const text = chars.length > width ? chars.slice(0, width - 1).join('') + '…' : lastMessage;
+        output.write(`\r\x1b[2K│  ${accent(['|', '/', '-', '\\'][frame++ % 4])} ${format(text)}`);
+      };
+      if (menus) {
+        output.write('\x1b[?25l'); render();
+        animation = setInterval(render, 100);
+      } else line(lastMessage);
+      return {
+        update(message, { heartbeat = false } = {}) {
+          if (stopped) return;
+          const text = plain(message);
+          if (menus) { lastMessage = text; render(); return; }
+          if (text === lastMessage || (heartbeat && Date.now() - lastLine < 15000)) return;
+          line(text); lastMessage = text; lastLine = Date.now();
+        },
+        stop(message, status = 'success') {
+          if (stopped) return;
+          stopped = true;
+          clearInterval(animation);
+          if (!menus) return line(plain(message));
+          output.write('\r\x1b[2K\x1b[?25h');
+          (status === 'success' ? prompts.log.success : status === 'cancelled' ? prompts.log.warn : prompts.log.error)(format(wrap(plain(message))), display);
+        },
+      };
+    },
+    step: (number, title, total) => {
+      const text = `${number}${total ? ` of ${total}` : ''}. ${title}`;
+      menus ? prompts.log.step(text, display) : line(`\n${accent(text)}`);
+    },
+    ok: text => menus ? prompts.log.success(format(wrap(text)), display) : line(`  OK ${text}`),
+    async ask(label, fallback = '', { validate } = {}) {
+      if (menus) return (await prompt(prompts.text, { message: plain(label), placeholder: plain(fallback), defaultValue: fallback,
+        validate: value => validate?.(value?.trim() || fallback) })).trim() || fallback;
+      while (true) {
+        const value = await ask(label, fallback);
+        const error = validate?.(value);
+        if (!error) return value;
+        line(error);
+      }
+    },
+    secret: label => menus ? prompt(prompts.password, { message: plain(label), mask: '*' }) : ask(label, '', true),
+    async confirm(label, fallback = true) {
+      if (menus) return prompt(prompts.confirm, { message: plain(label), initialValue: fallback });
+      while (true) {
+        const answer = (await ask(`${label} (${fallback ? 'Y/n' : 'y/N'})`, fallback ? 'y' : 'n')).toLowerCase();
+        if (['y', 'yes'].includes(answer)) return true;
+        if (['n', 'no'].includes(answer)) return false;
+        line('Please enter y or n.');
+      }
+    },
+    async choose(label, options, defaultIndex = 0) {
+      options = choices(options);
+      // Short menus are plain lists; searching only helps once a list would scroll.
+      if (menus && options.length <= 8) return prompt(prompts.select, { message: plain(label), options, initialValue: options[defaultIndex]?.value });
+      if (menus) return prompt(prompts.autocomplete, { message: plain(label), options, initialValue: options[defaultIndex]?.value,
+        placeholder: 'Type to filter', maxItems: 8,
+        validate: value => options.some(option => option.value === value) ? undefined : 'Choose a matching option, or clear your search.' });
+      line(label);
+      options.forEach((option, i) => line(`  ${i + 1}) ${option.label}`));
+      while (true) {
+        const value = await ask('Choose a number', String(defaultIndex + 1));
+        const index = Number(value) - 1;
+        if (Number.isInteger(index) && index >= 0 && index < options.length) return options[index].value;
+        line(`Please enter a number from 1 to ${options.length}.`);
+      }
+    },
+    async multiselect(label, options, defaults = []) {
+      options = choices(options);
+      if (menus) return prompt(prompts.autocompleteMultiselect, { message: plain(label), options, initialValues: defaults,
+        required: false, placeholder: 'Type to filter', maxItems: 8 });
+      line(label);
+      options.forEach((option, i) => line(`  ${i + 1}) ${option.label}`));
+      const fallback = options.flatMap((option, index) => defaults.includes(option.value) ? [index + 1] : []).join(',');
+      while (true) {
+        const raw = await ask(defaults.length ? 'Choose numbers separated by commas, none to clear, or Enter to keep selection' : 'Choose numbers separated by commas, or Enter to skip', fallback);
+        if (!raw || raw.toLowerCase() === 'none') return [];
+        const indices = raw.split(',').map(value => Number(value.trim()) - 1);
+        if (indices.every(index => Number.isInteger(index) && index >= 0 && index < options.length)) return [...new Set(indices)].map(index => options[index].value);
+        line(`Please enter numbers from 1 to ${options.length}.`);
+      }
+    },
+  };
+}

package/scripts/lib/uninit.mjs

@@ -0,0 +1,72 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, lstat, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { Workspace } from '../../dist/workspace.js';
+import { Runs } from '../../dist/runs.js';
+import { fail } from '../../dist/errors.js';
+import { Cancelled } from './terminal.mjs';
+import { CLI_NAME } from './brand.mjs';
+
+const stateRoot = '.rtfm/supportpages';
+const retained = new Set(['operation.lock', 'archives']);
+async function readProfile(filename) {
+  try {
+    if (!(await lstat(filename)).isFile()) fail('invalid_configuration', 'The workspace profile must be a regular file.');
+    return await readFile(filename);
+  } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+/** Forget this folder's setup in every environment, without contacting an API. */
+export async function uninitWorkspace(root, configDir, { ui, yes = false } = {}) {
+  const ws = await Workspace.create(root);
+  const profile = path.join(configDir, 'workspaces', createHash('sha256').update(ws.root).digest('hex') + '.json');
+  const before = await readProfile(profile);
+  const entries = async () => (await ws.list(stateRoot)).filter(entry => !retained.has(entry.name)).map(entry => entry.name).sort();
+  const originalEntries = await entries();
+  if (!before && !originalEntries.length) {
+    ui.ok(`This folder is already uninitialized. Run ${CLI_NAME} init to set it up.`);
+    return { status: 'uninitialized', already_uninitialized: true, workspace: ws.root };
+  }
+  ui.intro?.('SupportPages Writer · Forget project setup');
+  ui.line(`Folder: ${ws.root.replace(/[\p{Cc}\p{Cf}]/gu, '')}`);
+  ui.line('Forget this folder’s local, development and production setup, including its remembered API environment.');
+  ui.line('Setup and recovery files will be archived. Exported articles, remote content, device sign-in and agent integrations are kept. Hosted jobs already submitted keep running.');
+  if (!yes && !await ui.confirm('Forget setup for this folder?', false)) throw new Cancelled('Project setup was kept.');
+  const result = await ws.lock(async () => {
+    const current = await readProfile(profile);
+    if (!((before === null && current === null) || before?.equals(current ?? Buffer.alloc(0))) ||
+        JSON.stringify(await entries()) !== JSON.stringify(originalEntries)) {
+      fail('configuration_changed', `Project setup changed during review. Rerun ${CLI_NAME} uninit.`);
+    }
+    await new Runs(ws, stateRoot).assertAvailable();
+    const roots = [stateRoot, ...(await ws.list(`${stateRoot}/dev`)).filter(entry => entry.isDirectory()).map(entry => `${stateRoot}/dev/${entry.name}`)];
+    for (const directory of roots) {
+      const task = `${directory}/setup/task.json`;
+      if (await ws.exists(task) && (await ws.json(task)).status === 'running') {
+        fail('workspace_busy', `Finish or stop project analysis before running ${CLI_NAME} uninit.`);
+      }
+    }
+    const archive = `${stateRoot}/archives/uninit-${randomUUID()}`;
+    await ws.writeJson(`${archive}/recovery.json`, { version: 1, workspace: ws.root, profile, entries: originalEntries, created_at: new Date().toISOString() });
+    if (before) await ws.write(`${archive}/workspace-profile.json`, before);
+    const moved = [];
+    try {
+      for (const entry of originalEntries) {
+        await rename(await ws.resolve(`${stateRoot}/${entry}`), await ws.resolve(`${archive}/${entry}`));
+        moved.push(entry);
+      }
+      if (before) {
+        if (!before.equals(await readProfile(profile) ?? Buffer.alloc(0))) fail('configuration_changed', `The workspace environment changed. Rerun ${CLI_NAME} uninit.`);
+        await unlink(profile);
+      }
+    } catch (error) {
+      for (const entry of moved.reverse()) await rename(await ws.resolve(`${archive}/${entry}`), await ws.resolve(`${stateRoot}/${entry}`));
+      throw error;
+    }
+    return { status: 'uninitialized', workspace: ws.root, archive: await ws.resolve(archive) };
+  });
+  ui.ok(`Project setup removed. Run ${CLI_NAME} init to choose where articles go.`);
+  ui.line(`Recovery files: ${result.archive}`);
+  ui.line('Use --dev only when you want the development service. Restart existing agent sessions to refresh their connection state.');
+  return result;
+}

package/scripts/lib/update.mjs

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { fail } from '../../dist/errors.js';
+import { command } from './install.mjs';
+import { CLI_NAME } from './brand.mjs';
+
+const versionPattern = /^\d+\.\d+\.\d+$/;
+export function compareVersions(left, right) {
+  if (!versionPattern.test(left) || !versionPattern.test(right)) fail('invalid_release', 'The release version must be X.Y.Z. Retry after the release has been corrected.');
+  const a = left.split('.').map(BigInt), b = right.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i] ? 1 : -1;
+  return 0;
+}
+
+/** Update the managed executable without opening a workspace or authenticating. */
+export async function releaseInstallation(installRoot, env = process.env) {
+  const reinstall = 'Rerun the SupportPages Writer installer with your original --data-dir and --bin-dir to enable updates. Your configuration and article files are kept.';
+  let receipt;
+  const home = env.SUPPORTPAGES_CLI_HOME;
+  if (!home) fail('unmanaged_installation', 'This command is running from a source or unmanaged installation. Rerun ./install-cli.sh from your source checkout, or use the public installer.');
+  const root = path.dirname(path.resolve(home));
+  try {
+    if (path.basename(home) !== 'current' || await realpath(path.join(home, 'mcp')) !== await realpath(installRoot)) throw Error();
+    const file = path.join(root, 'install.json');
+    if (!(await lstat(file)).isFile()) throw Error();
+    receipt = JSON.parse(await readFile(file, 'utf8'));
+    if (receipt.version !== 1 || !['release', 'local'].includes(receipt.type) ||
+        typeof receipt.data_dir !== 'string' || !path.isAbsolute(receipt.data_dir) ||
+        await realpath(receipt.data_dir) !== await realpath(root) ||
+        typeof receipt.bin_dir !== 'string' || !path.isAbsolute(receipt.bin_dir)) throw Error();
+    const url = new URL(receipt.release_url);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw Error();
+  } catch { fail('invalid_installation', `The installation receipt is missing or invalid. ${reinstall}`); }
+  if (receipt.type === 'local') fail('local_installation', 'This is a local development build. Rerun ./install-cli.sh from your source checkout to update it.');
+  return receipt;
+}
+
+export async function updateCli({ installRoot, env = process.env, run = command, ui, checkTimeout = 60 }) {
+  const receipt = await releaseInstallation(installRoot, env);
+  const current = JSON.parse(await readFile(path.join(installRoot, 'package.json'), 'utf8')).version;
+  const releaseUrl = receipt.release_url.replace(/\/$/, '');
+  ui.line('Checking for a SupportPages Writer update…');
+  const latest = await run('curl', ['--proto', '=https', '--proto-redir', '=https', '-fsSL', '--max-time', String(checkTimeout), `${releaseUrl}/latest.txt`], { capture: true, env });
+  if (latest.code !== 0) fail('update_unavailable', `Could not check for updates. Ensure curl is installed and your network is available, then rerun ${CLI_NAME} update.`);
+  const next = latest.stdout.trim();
+  if (compareVersions(current, next) >= 0) {
+    ui.line(`SupportPages Writer ${current} is up to date. No update needed.`);
+    return { status: 'current', version: current };
+  }
+  ui.line(`Updating SupportPages Writer ${current} to ${next}…`);
+  const result = await run('bash', [path.join(installRoot, 'install-cli.sh'), '--yes', '--update', '--version', next,
+    '--data-dir', receipt.data_dir, '--bin-dir', receipt.bin_dir], { env: { ...env, SUPPORTPAGES_CLI_RELEASE_URL: releaseUrl } });
+  if (result.code !== 0) fail('update_failed', `Update could not finish. Your previous version remains available. Resolve the installer error above and rerun ${CLI_NAME} update.`);
+  return { status: 'updated', version: next };
+}

package/scripts/lib/writer-recovery.mjs

@@ -0,0 +1,35 @@
+import { fail } from '../../dist/errors.js';
+import { Cancelled } from './terminal.mjs';
+import { CLI_NAME } from './brand.mjs';
+
+const clean = value => String(value).replace(/[\p{Cc}\p{Cf}]/gu, '');
+
+/** Host task liveness is unknown to the CLI. Clear only after the user confirms it stopped. */
+export async function ensureWriterAvailable(bridge, ui) {
+  for (;;) {
+    const active = await bridge.lock(() => bridge.runs.blocking());
+    if (!active) return;
+    const { run, state_directory: stateRoot } = active;
+    if (stateRoot !== bridge.stateRoot) {
+      fail('generation_active', `An unfinished article run belongs to another SupportPages.io connection (${clean(run.api_origin ?? stateRoot)}). Run ${CLI_NAME} init for that connection${stateRoot.includes('/dev/') ? ' with --dev' : ' without --dev'} to clear it after its writer has stopped.`, { run_id: run.id, state_directory: stateRoot });
+    }
+    const message = [
+      clean(run.title ?? 'Untitled article'),
+      `Last reported: ${clean(run.phase ?? run.status)} · ${clean(run.updated_at ?? run.started_at)}`,
+      `Article files: ${clean(run.artifact_dir)}`,
+      'This saved record does not mean a writer is still running.',
+    ].join('\n');
+    if (ui.note) ui.note(message, 'Unfinished article run');
+    else ui.line(message);
+    const action = await ui.choose('How would you like to continue?', [
+      { value: 'clear', label: 'Writer has stopped — clear run and continue', hint: 'Keeps all existing article files.' },
+      { value: 'keep', label: 'Writer is running or unsure — keep run and exit' },
+    ]);
+    if (action !== 'clear') {
+      ui.line('The article run was kept. Rerun when its writer has stopped.');
+      throw new Cancelled();
+    }
+    await bridge.cancel(run.id, true, run);
+    ui.ok('Cleared the unfinished run. Existing article files were kept.');
+  }
+}