@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/scripts/lib/auto-update.mjs

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { mkdir, readFile, rm, stat } from 'node:fs/promises';
+import { autoUpdateEnabled, installationRoot } from '../../dist/runtime.js';
+import { releaseInstallation, updateCli } from './update.mjs';
+import { privateJson } from './install.mjs';
+
+export const CHECK_INTERVAL = 24 * 60 * 60 * 1000;
+
+/** An installation-wide lock plus a persisted attempt time prevents every agent
+ * session checking separately. Failed checks are throttled too; manual updates
+ * don't consult this state. Only the installer promotes a verified release.
+ */
+export async function automaticUpdate({ installRoot, env = process.env, now = Date.now, update = updateCli }) {
+  if (!autoUpdateEnabled(env)) return;
+  const root = installationRoot(installRoot);
+  if (!root) return;
+  const updateEnv = { ...env, SUPPORTPAGES_CLI_HOME: path.join(root, 'current') };
+  const lock = path.join(root, '.auto-update.lock');
+  const recovery = path.join(root, '.auto-update-recovery.lock');
+  const state = path.join(root, 'auto-update.json');
+  let locked = false;
+  try {
+    // An old server still running after an update cannot update on its behalf.
+    await releaseInstallation(installRoot, updateEnv);
+    try { await mkdir(lock, { mode: 0o700 }); }
+    catch (error) {
+      if (error.code !== 'EEXIST') return;
+      // Recover an abandoned worker lock on a later day. Installer downloads
+      // are time-bounded, so an attempt can never normally hold it this long.
+      if (now() - (await stat(lock)).mtimeMs < CHECK_INTERVAL) return;
+      // Serialize recovery and recheck: another worker may already have
+      // replaced the stale lock with a live one while we were waiting.
+      try { await mkdir(recovery, { mode: 0o700 }); } catch { return; }
+      try {
+        if (now() - (await stat(lock)).mtimeMs < CHECK_INTERVAL) return;
+        await rm(lock, { recursive: true });
+        await mkdir(lock, { mode: 0o700 });
+      } finally { await rm(recovery, { recursive: true, force: true }); }
+    }
+    locked = true;
+    let previous;
+    try { previous = JSON.parse(await readFile(state, 'utf8')).checked_at; }
+    catch (error) { if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) return; }
+    const checkedAt = now();
+    if (Number.isFinite(previous) && checkedAt >= previous && checkedAt - previous < CHECK_INTERVAL) return;
+    await privateJson(state, { version: 1, checked_at: checkedAt });
+    await update({ installRoot, env: updateEnv, checkTimeout: 5, ui: { line() {} } });
+  } catch { /* Offline, read-only, unavailable and invalid releases are silent. */ }
+  finally { if (locked) await rm(lock, { recursive: true, force: true }).catch(() => {}); }
+}

package/scripts/lib/brand.mjs

@@ -0,0 +1,9 @@
+// The command users type and read. `supportpages` stays installed as an alias,
+// and every persisted integration name (MCP server, tools, config and data
+// directories, SUPPORTPAGES_* variables) keeps its supportpages spelling.
+// Kept dependency-free: the source bootstrap loads it before dist/ exists.
+// Mirrored in src/brand.ts for the MCP server; a test keeps them equal.
+export const CLI_NAME = 'wtfm';
+export const LEGACY_CLI_NAME = 'supportpages';
+export const INSTALL_COMMAND = 'curl -fsSL https://wtfm.sh/install | bash';
+export const LANDING_URL = 'https://supportpages.io/wtfm';

package/scripts/lib/browser.mjs

@@ -0,0 +1,12 @@
+import { execFile } from 'node:child_process';
+
+export async function openBrowser(url, { platform = process.platform, execute = execFile, env = process.env } = {}) {
+  if (!['darwin', 'linux'].includes(platform)) return false;
+  const safeEnv = { ...env };
+  delete safeEnv.SUPPORTPAGES_API_TOKEN;
+  delete safeEnv.SUPPORTPAGES_API_TOKEN_FILE;
+  return new Promise(resolve => {
+    execute(platform === 'darwin' ? 'open' : 'xdg-open', [url],
+      { env: safeEnv, timeout: 5000 }, error => resolve(!error));
+  });
+}

package/scripts/lib/claude-connection.mjs

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import os from 'node:os';
+import { lstat, readFile } from 'node:fs/promises';
+import { backup, privateJson } from './install.mjs';
+import { CLI_NAME } from './brand.mjs';
+
+/** Match Claude's /mcp project toggle without removing global registrations. */
+export async function selectClaudeConnection({ workspace, dev, configDir, home = os.homedir(), env = process.env }) {
+  const filename = env.CLAUDE_CONFIG_DIR ? path.join(env.CLAUDE_CONFIG_DIR, '.claude.json') : path.join(home, '.claude.json');
+  for (const entry of [path.dirname(filename), filename]) {
+    try { if ((await lstat(entry)).isSymbolicLink()) throw Error('Cannot update a linked Claude configuration.'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  let contents;
+  try { contents = await readFile(filename, 'utf8'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const config = contents === undefined ? {} : JSON.parse(contents);
+  const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (!object(config) || (config.projects !== undefined && !object(config.projects))) throw Error('Claude project settings are invalid.');
+  const root = path.resolve(workspace);
+  const project = config.projects?.[root] ?? {};
+  if (!object(project) || (project.disabledMcpServers !== undefined && (!Array.isArray(project.disabledMcpServers) || project.disabledMcpServers.some(name => typeof name !== 'string')))) throw Error('Claude MCP choices are invalid.');
+  const selected = dev ? 'supportpages-dev' : 'supportpages';
+  const other = dev ? 'supportpages' : 'supportpages-dev';
+  const disabled = [...new Set([...(project.disabledMcpServers ?? []).filter(name => name !== selected), other])];
+  if (JSON.stringify(disabled) === JSON.stringify(project.disabledMcpServers)) return false;
+  await backup(filename, path.join(configDir, 'backups'));
+  let current;
+  try { current = await readFile(filename, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (current !== contents) throw Error(`Claude configuration changed. Rerun ${CLI_NAME} init to retry.`);
+  await privateJson(filename, { ...config, projects: { ...config.projects, [root]: { ...project, disabledMcpServers: disabled } } });
+  return true;
+}

package/scripts/lib/claude-permissions.mjs

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { lstat, readFile } from 'node:fs/promises';
+
+/** Tools that remove content from a help centre: always confirmed, even when the rest are allowed. */
+export const askFirstTools = ['supportpages_delete_article', 'supportpages_unpublish_article'];
+
+/** The rules setup adds for a registered MCP connection: every tool on it allowed, removals asked. */
+export const claudePermissionRules = name => ({
+  allow: [`mcp__${name}`],
+  ask: askFirstTools.map(tool => `mcp__${name}__${tool}`),
+});
+
+/**
+ * Allow the SupportPages tools on the successfully registered MCP connection, so
+ * uploads and edits the user asked for are not blocked in auto mode. Deleting and
+ * unpublishing stay on ask. Existing rules are kept: Claude Code applies deny, then
+ * ask, then allow, so any restriction the user added still wins.
+ */
+export async function installClaudePermissions({ home, env = process.env, name, configDir, backup, writeJson }) {
+  if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,79}$/.test(name)) throw Error('Invalid SupportPages.io connection name.');
+  const directory = path.resolve(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'));
+  const filename = path.join(directory, 'settings.json');
+  for (const entry of [directory, filename]) {
+    try {
+      const info = await lstat(entry);
+      if (info.isSymbolicLink() || (entry === filename ? !info.isFile() : !info.isDirectory())) throw Error(`Cannot update Claude permissions at an unsafe path: ${entry}`);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  let settings;
+  try { settings = JSON.parse(await readFile(filename, 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; settings = {}; }
+  const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (!object(settings) || (settings.permissions !== undefined && !object(settings.permissions))) throw Error('Claude Code permission settings are invalid. Repair settings.json before installing.');
+  const permissions = settings.permissions ?? {};
+  for (const key of ['allow', 'ask', 'deny']) {
+    if (permissions[key] !== undefined && (!Array.isArray(permissions[key]) || permissions[key].some(rule => typeof rule !== 'string'))) throw Error('Claude Code permission rules are invalid. Repair settings.json before installing.');
+  }
+  const rules = claudePermissionRules(name);
+  const missing = key => rules[key].filter(rule => !permissions[key]?.includes(rule));
+  const allow = missing('allow'), ask = missing('ask');
+  if (!allow.length && !ask.length) return { filename, rules, changed: false };
+  await backup(filename, path.join(configDir, 'backups'));
+  await writeJson(filename, { ...settings, permissions: { ...permissions,
+    ...(allow.length ? { allow: [...(permissions.allow ?? []), ...allow] } : {}),
+    ...(ask.length ? { ask: [...(permissions.ask ?? []), ...ask] } : {}) } });
+  return { filename, rules, changed: true };
+}

package/scripts/lib/claude-plugin.mjs

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+export const PLUGIN_NAME = 'supportpages-writer';
+
+/** True when Claude Code has the SupportPages Writer plugin installed (any
+ * marketplace, any scope). The plugin brings its own MCP server and writer
+ * agent, so a separate registration would show every tool twice. */
+export async function claudePluginInstalled({ home, env = {} }) {
+  const file = path.join(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'plugins', 'installed_plugins.json');
+  try {
+    const plugins = JSON.parse(await readFile(file, 'utf8')).plugins ?? {};
+    return Object.entries(plugins).some(([id, installs]) => id.split('@')[0] === PLUGIN_NAME && Array.isArray(installs) && installs.length > 0);
+  } catch { return false; }
+}

package/scripts/lib/claude-writer.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path';
+import os from 'node:os';
+import { installManagedWriter } from './managed-writer.mjs';
+
+/** Install the personal agent so Claude launched outside our CLI can discover it. */
+export async function installClaudeWriter({ home = os.homedir(), env = process.env } = {}) {
+  const { writerAgentFile, writerAgentType } = await import('../../dist/writer-agent.js');
+  return installManagedWriter({ config: path.resolve(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude')),
+    name: writerAgentType, extension: 'md', contents: writerAgentFile, marker: '<!-- Managed by SupportPages: article writer v1 -->' });
+}

package/scripts/lib/cli-main.mjs

@@ -0,0 +1,85 @@
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile, realpath } from 'node:fs/promises';
+import { createTerminal, Cancelled, emphasizeCommands } from './terminal.mjs';
+import { publicError } from '../../dist/errors.js';
+import { runCli, telemetryCommand } from './cli.mjs';
+import { reportError } from '../../dist/telemetry.js';
+import { updateCli } from './update.mjs';
+import { CLI_NAME, LEGACY_CLI_NAME } from './brand.mjs';
+
+let installRoot=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'../..');
+if(process.env.SUPPORTPAGES_CLI_HOME) {
+  const stableRoot=path.join(process.env.SUPPORTPAGES_CLI_HOME,'mcp');
+  try {if(await realpath(stableRoot)===await realpath(installRoot)) installRoot=stableRoot;} catch { /* Ignore stale launcher environment. */ }
+}
+const help=`WTFM (Write the F***ing Manual) — local article generation
+
+Usage: ${CLI_NAME} <command> [options]
+
+  setup       One-time setup for this computer: coding agent, renderer and account
+  init        Set up this project: where its articles go, model and project detection
+  uninit      Forget this folder's setup and environment; archive recovery files
+  publish     Host this project's locally saved articles on a SupportPages.io help centre
+  yolo        Write the whole manual on SupportPages.io (account required; drafts only)
+  analyse     Complete required project analysis (--refresh to rerun)
+  status      Show the connection and last-reported article progress
+  configure   Choose coding agent, model, effort, writing style and preferences
+  login       Sign in to SupportPages.io on this computer (one browser approval)
+  logout      Sign out of SupportPages.io on this computer
+  sync        Refresh remote project settings and article history
+  doctor      Check your installation and generation prerequisites
+  telemetry   Show or change anonymous usage reporting: telemetry on|off|status
+  update      Install the latest SupportPages Writer release; keep your settings and articles
+  remove      Remove local coding-agent integrations; keep projects and articles
+  mcp         Run the MCP server on stdio (for MCP client configuration)
+
+Run ${CLI_NAME} setup once on this computer and ${CLI_NAME} init inside each
+project, then open Claude Code or Codex there and ask for an article. Articles can be saved in the project as Markdown and screenshots with no
+account, or published to a SupportPages.io help centre. Your repository stays
+with your coding agent.
+
+Or run ${CLI_NAME} yolo to have SupportPages.io write the whole manual as drafts
+on its servers; it needs an account and access to your repository.
+
+Permission consent: ${CLI_NAME} login --scopes manage,generate,publish
+
+Options: --workspace PATH, --dev, --api-url ORIGIN, --config-dir PATH,
+         --skills-dir PATH, --project ID (init), --agent claude|codex,
+         --refresh (init, analyse), --app-type TYPE (init, analyse),
+         --skills-only (remove), --yes (remove/uninit/yolo),
+         --json (status/doctor/sync), --help, --version
+
+${LEGACY_CLI_NAME} is an alias for ${CLI_NAME}; both run the same command.
+`;
+try {
+  let parsed;
+  try {parsed=parseArgs({allowPositionals:true,options:{
+    ...Object.fromEntries(['workspace','api-url','config-dir','skills-dir','project','agent','app-type','scopes'].map(name=>[name,{type:'string'}])),
+    'skills-only':{type:'boolean'},yes:{type:'boolean'},refresh:{type:'boolean'},dev:{type:'boolean'},json:{type:'boolean'},help:{type:'boolean',short:'h'},version:{type:'boolean',short:'v'},
+  }});} catch {throw Object.assign(new Error(),{usage:true});}
+  const {values,positionals}=parsed;
+  if(values.version) process.stdout.write(JSON.parse(await readFile(path.join(installRoot,'package.json'),'utf8')).version+'\n');
+  else if(values.help || positionals.length===0) process.stdout.write(emphasizeCommands(help));
+  else {
+    const command=positionals[0];
+    if(command==='telemetry') {
+      const action=positionals[1] ?? 'status';
+      if(positionals.length>2 || !['on','off','status'].includes(action) || Object.keys(values).some(key=>!['dev','api-url','config-dir','json'].includes(key))) throw Object.assign(new Error(),{usage:true});
+      const result=await telemetryCommand(action,values);
+      if(values.json) process.stdout.write(JSON.stringify(result)+'\n');
+      else process.stdout.write(`${result.message ?? `Anonymous usage reporting is ${result.enabled?'on':'off'} (${result.reason}).`}\n${result.sends}\n${result.disable}\n`);
+    } else if(command==='update') {
+      if(positionals.length!==1 || Object.keys(values).length) throw Object.assign(new Error(),{usage:true});
+      await updateCli({installRoot,ui:createTerminal()});
+    } else {
+      if((values.scopes !== undefined && (command !== 'login' || !/^(publish|manage|generate)(,(publish|manage|generate))*$/.test(values.scopes))) || (command === 'remove' && values.workspace !== undefined) || (values.yes && !['remove','uninit','yolo'].includes(command)) || (values['skills-only'] && command!=='remove') || (values.project !== undefined && (command!=='init' || !/^[1-9][0-9]*$/.test(values.project))) || positionals.length!==1 || !['setup','init','uninit','login','logout','status','configure','doctor','analyse','sections','recommend','write','publish','yolo','remove','sync'].includes(command) || (values.json && !['status','doctor','sync'].includes(command)) || (values.agent && !['claude','codex'].includes(values.agent)) || (values.refresh && !['init','analyse','sections','recommend'].includes(command)) || (values['app-type'] && (!['init','analyse'].includes(command) || !['web','terminal','mobile','desktop','win32','macos','game'].includes(values['app-type'])))) throw Object.assign(new Error(),{usage:true});
+      if(!['status','doctor','sync','logout'].includes(command) && !(['remove','uninit'].includes(command) && values.yes) && (!process.stdin.isTTY || !process.stdout.isTTY)) {process.stderr.write(`Run ${CLI_NAME} `+command+' in an interactive terminal. Use status --json or doctor --json for automation.\n');process.exitCode=2;}
+      else await runCli({...values,command},{installRoot,ui:createTerminal()});
+    }
+  }
+} catch(error) {
+  if(error.usage) {process.stderr.write(emphasizeCommands(`Invalid command or options. Run ${CLI_NAME} --help.\n`,process.stderr));process.exitCode=2;}
+  else {if(!(error instanceof Cancelled)) reportError(error);process.stderr.write(emphasizeCommands((error instanceof Cancelled ? error.message : publicError(error).message)+'\n',process.stderr));process.exitCode=error instanceof Cancelled || error.code==='authorization_cancelled' ? 130:1;}
+}