create-pmos 0.53.0 → 0.53.2

package/workspace/lib/launcher-cli.js

@@ -0,0 +1,207 @@
+'use strict';
+/* launcher-cli.js — `pmos launcher on|off|status`: start the workspace without a terminal (initiative workspace-launcher).
+ *
+ *   pmos launcher on [<path>] [--no-login]   write a PMOS app (and, unless --no-login, a login item) for one repository
+ *   pmos launcher off                        remove what `on` wrote, and nothing else
+ *   pmos launcher status                     say what is installed and whether it still points at a real node and repo
+ *
+ * The app and the login item are two more callers of `pmos up <repo>`; nothing here starts a server itself. The app
+ * opens the browser. The login item passes --no-open, so a login starts the server and opens nothing.
+ *
+ *   macOS  ~/Applications/PMOS.app                         Spotlight, Launchpad, drag it to the Dock
+ *          ~/Library/LaunchAgents/com.pmos.workspace.plist  runs at login (RunAtLoad), once
+ *   Linux  $XDG_DATA_HOME/applications/pmos.desktop        the app menu
+ *          $XDG_CONFIG_HOME/autostart/pmos-workspace.desktop
+ *
+ * A file started by the desktop has no shell profile, so the PATH of the terminal that ran `on` is written into the
+ * script; that is how `claude`, `git` and `tmux` resolve. It never starts remote (tailnet) mode and writes no token.
+ * `off` deletes a file only when it carries MARK, so a file of the same name that the PM wrote is left alone.
+ * Native Windows is refused: the workspace needs WSL there for a real PTY (doctor.js says the same).
+ *
+ * plan() is pure: every input is injected, so each platform's files are assertable from any machine.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const stateRoot = require('./state-root');
+
+const COMMANDS = { launcher: ['on', 'off', 'status'] };
+const MARK = 'pmos-launcher: written by `pmos launcher on`';
+const LABEL = 'com.pmos.workspace';
+const USAGE = [
+  'usage: pmos launcher on|off|status — start the workspace without a terminal',
+  '  pmos launcher on [<path>] [--no-login]   a PMOS app for this repository, and a login item that starts the server',
+  '  pmos launcher off                        remove the app and the login item',
+  '  pmos launcher status                     what is installed, and for which repository',
+];
+
+// POSIX shell single quotes: nothing inside is special except the quote itself.
+const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+// XML text and attribute values in a plist.
+const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+// A .desktop Exec argument: double-quoted, with the four characters the spec reserves escaped.
+const deq = (s) => `"${String(s).replace(/[\\"`$]/g, (c) => '\\' + c)}"`;
+
+function script({ node, bin, repo, pathEnv, log }) {
+  return [
+    '#!/bin/sh',
+    `# ${MARK} (workspace/lib/launcher-cli.js). \`pmos launcher off\` removes it.`,
+    '# It runs `pmos up` on one repository with the PATH the terminal had at setup. Arguments pass through (--no-open).',
+    `PATH=${shq(pathEnv)}; export PATH`,
+    `exec ${shq(node)} ${shq(bin)} up ${shq(repo)} "$@" >>${shq(log)} 2>&1`,
+    '',
+  ].join('\n');
+}
+
+function plist(dict) {
+  const v = (x) => Array.isArray(x) ? `<array>${x.map((s) => `<string>${xml(s)}</string>`).join('')}</array>`
+    : typeof x === 'boolean' ? (x ? '<true/>' : '<false/>') : `<string>${xml(x)}</string>`;
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    `<!-- ${MARK} (workspace/lib/launcher-cli.js). \`pmos launcher off\` removes it. -->`,
+    '<plist version="1.0">',
+    '<dict>',
+    ...Object.entries(dict).map(([k, x]) => `  <key>${xml(k)}</key>${v(x)}`),
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+function desktop(entries) {
+  return [`# ${MARK} (workspace/lib/launcher-cli.js). \`pmos launcher off\` removes it.`, '[Desktop Entry]',
+    ...Object.entries(entries).map(([k, x]) => `${k}=${x}`), ''].join('\n');
+}
+
+/**
+ * The files `on` writes, for one platform. Pure.
+ *   → { files: [{ role: 'app'|'login', path, content, mode }], app, login }   or   { refused: '<reason>' }
+ * `login: false` leaves the login item out.
+ */
+function plan({ platform, home, env = {}, node, bin, repo, login = true }) {
+  if (platform === 'win32') return { refused: 'native Windows needs WSL for a real PTY. Run `pmos launcher on` inside WSL.' };
+  if (platform !== 'darwin' && platform !== 'linux') return { refused: `no launcher is made for ${platform}. Start the workspace with \`pmos\`.` };
+  const log = path.join(stateRoot.defaultRoot({ env, platform, home }), 'launcher.log');
+  const body = script({ node, bin, repo, pathEnv: env.PATH || '/usr/bin:/bin', log });
+  const files = [];
+  if (platform === 'darwin') {
+    const appDir = path.join(home, 'Applications', 'PMOS.app');
+    const exe = path.join(appDir, 'Contents', 'MacOS', 'pmos-launch');
+    files.push({ role: 'app', path: exe, content: body, mode: 0o755 });
+    files.push({ role: 'app', path: path.join(appDir, 'Contents', 'Info.plist'), mode: 0o644, content: plist({
+      CFBundleName: 'PMOS', CFBundleDisplayName: 'PMOS', CFBundleIdentifier: 'com.pmos.launcher',
+      CFBundleExecutable: 'pmos-launch', CFBundlePackageType: 'APPL', CFBundleVersion: '1',
+      // No Dock icon: the script hands off to the browser and exits within seconds.
+      LSUIElement: true,
+    }) });
+    const agent = path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+    if (login) files.push({ role: 'login', path: agent, mode: 0o644, content: plist({
+      Label: LABEL, ProgramArguments: ['/bin/sh', exe, '--no-open'], RunAtLoad: true,
+      // `pmos up` detaches the server and exits; launchd must not reap the group it leaves behind.
+      AbandonProcessGroup: true,
+    }) });
+    return { files, app: appDir, login: login ? agent : null, removable: [appDir, agent] };
+  }
+  const data = env.XDG_DATA_HOME && path.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : path.join(home, '.local', 'share');
+  const conf = env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : path.join(home, '.config');
+  const exe = path.join(data, 'pmos', 'pmos-launch.sh');
+  const app = path.join(data, 'applications', 'pmos.desktop');
+  const auto = path.join(conf, 'autostart', 'pmos-workspace.desktop');
+  files.push({ role: 'app', path: exe, content: body, mode: 0o755 });
+  files.push({ role: 'app', path: app, mode: 0o644, content: desktop({
+    Type: 'Application', Name: 'PMOS', Comment: 'Open the PMOS workspace', Exec: `/bin/sh ${deq(exe)}`,
+    Terminal: 'false', Categories: 'Development;' }) });
+  if (login) files.push({ role: 'login', path: auto, mode: 0o644, content: desktop({
+    Type: 'Application', Name: 'PMOS workspace', Comment: 'Start the PMOS workspace server at login',
+    Exec: `/bin/sh ${deq(exe)} --no-open`, Terminal: 'false', NoDisplay: 'true', 'X-GNOME-Autostart-enabled': 'true' }) });
+  return { files, app, login: login ? auto : null, removable: [exe, app, auto] };
+}
+
+const marked = (f) => { try { return fs.readFileSync(f, 'utf8').includes(MARK); } catch { return false; } };
+// The file under a removable path that carries the mark: the bundle's script for a .app, else the path itself.
+const markFile = (p) => p.endsWith('.app') ? path.join(p, 'Contents', 'MacOS', 'pmos-launch') : p;
+
+function repoRootOf(dir) {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, encoding: 'utf8' });
+  return r.status === 0 ? String(r.stdout).trim() : dir;
+}
+
+// What the installed script points at: the repository and whether node and pmos.js still exist.
+function readTarget(exe) {
+  let src = '';
+  try { src = fs.readFileSync(exe, 'utf8'); } catch { return null; }
+  const m = src.match(/^exec '((?:[^']|'\\'')*)' '((?:[^']|'\\'')*)' up '((?:[^']|'\\'')*)'/m);
+  if (!m) return null;
+  const un = (s) => s.replace(/'\\''/g, "'");
+  return { node: un(m[1]), bin: un(m[2]), repo: un(m[3]) };
+}
+
+function run(argv, { say = console.log, platform = process.platform, home = os.homedir(), env = process.env,
+  node = process.execPath, bin = path.join(__dirname, '..', 'bin', 'pmos.js'), cwd = process.cwd() } = {}) {
+  const pos = argv.slice(1).filter((a) => !a.startsWith('--'));
+  const flags = new Set(argv.slice(1).filter((a) => a.startsWith('--')).map((a) => a.slice(2)));
+  const unknown = [...flags].filter((f) => f !== 'no-login' && f !== 'help');
+  if (unknown.length) { say(`✗ unknown option --${unknown[0]}`); for (const l of USAGE) say(l); return 2; }
+  const sub = pos[0];
+  if (!sub || flags.has('help') || sub === 'help') { for (const l of USAGE) say(l); return sub ? 0 : 2; }
+  if (!COMMANDS.launcher.includes(sub)) { say(`✗ pmos launcher ${sub} is not a command`); for (const l of USAGE) say(l); return 2; }
+
+  if (sub === 'on') {
+    const dir = pos[1] ? path.resolve(cwd, pos[1]) : cwd;
+    if (!fs.existsSync(dir)) { say(`✗ ${dir} does not exist`); return 1; }
+    const repo = repoRootOf(dir);
+    const p = plan({ platform, home, env, node, bin, repo, login: !flags.has('no-login') });
+    if (p.refused) { say(`✗ ${p.refused}`); return 1; }
+    // Never write over a file of the same name that the launcher did not write.
+    const foreign = p.files.filter((f) => fs.existsSync(f.path) && !marked(f.path));
+    if (foreign.length) { say(`✗ not written: ${foreign.map((f) => f.path).join(', ')} exists and was not written by pmos launcher`); return 1; }
+    for (const f of p.files) {
+      fs.mkdirSync(path.dirname(f.path), { recursive: true });
+      fs.writeFileSync(f.path, f.content, { mode: f.mode });
+      fs.chmodSync(f.path, f.mode);
+    }
+    say(`✓ PMOS app for ${repo}`);
+    say(`  ${p.app}`);
+    say(platform === 'darwin' ? '  Open it from Spotlight or Launchpad, or drag it to the Dock.' : '  Open it from the app menu.');
+    if (p.login) {
+      say('✓ login item: the workspace server starts when you log in, without a browser window');
+      say(`  ${p.login}`);
+    } else say('  no login item (--no-login): the server starts when you open the app');
+    say('  The app opens the browser on the running workspace and starts the server when none runs.');
+    say('  If you move or upgrade node, run `pmos launcher on` again.');
+    return 0;
+  }
+
+  const p = plan({ platform, home, env, node, bin, repo: cwd });
+  if (p.refused) { say(`✗ ${p.refused}`); return 1; }
+
+  if (sub === 'off') {
+    let removed = 0;
+    for (const r of p.removable) {
+      if (!fs.existsSync(r)) continue;
+      if (!marked(markFile(r))) { say(`· left ${r}: it was not written by pmos launcher`); continue; }
+      fs.rmSync(r, { recursive: true, force: true });
+      say(`✓ removed ${r}`);
+      removed++;
+    }
+    if (!removed) say('○ nothing to remove: no launcher is installed');
+    return 0;
+  }
+
+  // status
+  const exe = p.files.find((f) => f.role === 'app' && f.mode === 0o755).path;
+  const t = marked(exe) ? readTarget(exe) : null;
+  const loginPath = p.removable.find((r) => r.endsWith('.plist') || r.endsWith('pmos-workspace.desktop'));
+  const login = fs.existsSync(loginPath) && marked(loginPath);
+  if (!t) { say('○ no PMOS app is installed (pmos launcher on)'); if (login) say(`· a login item is installed without the app: ${loginPath}`); return 1; }
+  say(`✓ PMOS app — ${p.app}`);
+  say(`  repository: ${t.repo}${fs.existsSync(t.repo) ? '' : '  ✗ not found'}`);
+  say(`  node: ${t.node}${fs.existsSync(t.node) ? '' : '  ✗ not found — run `pmos launcher on` again'}`);
+  say(`  pmos: ${t.bin}${fs.existsSync(t.bin) ? '' : '  ✗ not found — run `pmos launcher on` again'}`);
+  say(login ? `✓ login item — ${loginPath}` : '○ no login item: the server starts when you open the app');
+  return [t.repo, t.node, t.bin].every((x) => fs.existsSync(x)) ? 0 : 1;
+}
+
+module.exports = { run, plan, readTarget, COMMANDS, USAGE, MARK };

package/workspace/lib/plan-tree.js

@@ -110,7 +110,20 @@ function profileAndLane(root, initiative) {
   // An unknown or missing lane is the profile's strictest, exactly as workflow-state.js computes `effLane`.
   const fallback = profile === 'pm-artifacts' ? 'prd' : 'feature';
   const lane = declared && defs[declared] ? declared : fallback;
-  return { profile, lane, defs, record: file };
+  return { profile, lane, defs, record: file, group: viewGroup(defs, declared) };
+}
+
+/**
+ * Whether an initiative is a work card or a document in the planning views (D86 point 4), from its DECLARED lane.
+ *
+ * Only a record that declares a document lane is a document. A missing or unknown lane is work: the fallback above
+ * picks the strictest ladder for the gate, and in a pm-artifacts repository that fallback is `prd`, a document lane.
+ * Grouping by the fallback hid every record written before lanes were declared (0.53.0: most of a kit repository's
+ * initiatives were missing from Initiatives, Board and Reports).
+ */
+function viewGroup(defs, declared) {
+  const d = String(declared || '').trim();
+  return d && defs && defs[d] && defs[d].group ? defs[d].group : 'work';
 }
 
 const cap = (s) => (s && /^[a-z]/.test(s) ? s[0].toUpperCase() + s.slice(1) : s);
@@ -363,5 +376,5 @@ function layout({ root, initiative, fold, ladder, now }) {
 
 module.exports = {
   STAGE_GROUPS, STEP_NOUN, OWED_ACTOR, OPEN, DONE_WINDOW_MS, INIT_RE, NOT_MERGED_LABEL, withFactory,
-  mainTree, recordPath, profileAndLane, stagesFor, stageIdsFor, resolveStage, owedFor, nounFor, byLabel, progressLabel, layout, historyText,
+  mainTree, recordPath, profileAndLane, viewGroup, stagesFor, stageIdsFor, resolveStage, owedFor, nounFor, byLabel, progressLabel, layout, historyText,
 };

package/workspace/lib/pmos-verbs.js

@@ -34,6 +34,9 @@ const VERBS = Object.freeze({
     help: 'pmos verify-work — mark work items integrated from the default branch (local refs only)' }),
   report: Object.freeze({ module: 'report-cli.js', run: 5, guide: 'reports.md',
     help: 'pmos report draft|issue|list … — draft and issue reports (pmos report help)' }),
+  // Not a pm-os-absorb verb (run: null): the workspace-launcher initiative added it through the same table.
+  launcher: Object.freeze({ module: 'launcher-cli.js', run: null, guide: 'launcher.md',
+    help: 'pmos launcher on|off|status — a PMOS app and a login item, so the workspace starts without a terminal' }),
 });
 
 const has = (verb) => typeof verb === 'string' && Object.prototype.hasOwnProperty.call(VERBS, verb);

package/workspace/lib/proactive-cli.js

@@ -13,6 +13,7 @@
  *   pmos proactive brief [show]
  *   pmos proactive brief submit --file PATH
  *   pmos proactive brief schedule [--repo PATH]
+ *   pmos proactive goals [list] | add TEXT [--initiative ID] | done N | drop N | reopen N | remove N | plan [--repo PATH]
  *   pmos proactive prepare plan --initiative ID [--repo PATH]
  *   pmos proactive prepare queue --initiative ID --item ITEM --sha HASH [--repo PATH]
  *   pmos proactive prepare status | cancel ID | run
@@ -23,8 +24,8 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const { parseArgs } = require('./schedule-cli');
 
-const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief', 'prepare', 'learn'] };
-const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
+const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief', 'goals', 'prepare', 'learn'] };
+const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'slack', 'jira', 'confluence'];
 const onOff = (v, what) => (v === 'on' || v === 'true' ? true : v === 'off' || v === 'false' ? false : { err: `${what} takes on or off` });
 
 async function run(argv, { call, say, cwd = process.cwd() }) {
@@ -189,6 +190,61 @@ async function run(argv, { call, say, cwd = process.cwd() }) {
     for (const l of r.lessons.filter((x) => x.status === 'proposed' || x.status === 'approved')) say(`${l.id}  ${l.status}  ${l.text}`);
     return 0;
   }
+  if (verb === 'goals') {
+    const sub = pos[0] || 'list';
+    const usage = 'usage: pmos proactive goals [list] | add TEXT [--initiative ID] | done N | drop N | reopen N | remove N | plan [--repo PATH]';
+    const wsOfRepo = async () => {
+      let root; try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: flags.repo ? path.resolve(cwd, flags.repo) : cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; }
+      const wl = await call('GET', '/api/workspaces');
+      const hit = ((wl && wl.workspaces) || []).find((w) => path.resolve(w.root) === path.resolve(root));
+      return hit ? hit.id : null;
+    };
+    const get = async () => { const ws = await wsOfRepo(); return call('GET', '/api/proactive/goals' + (ws ? '?ws=' + encodeURIComponent(ws) : '')); };
+    if (sub === 'add') {
+      const text = pos.slice(1).join(' ');
+      if (!text.trim()) return fail(usage);
+      const r = await call('POST', '/api/proactive/goals', { action: 'add', text, ...(flags.initiative ? { initiative_id: flags.initiative } : {}) });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing changed.`);
+      say(`added goal ${r.day.goals.length}: ${r.goal.text}${r.goal.initiative_id ? ' · ' + r.goal.initiative_id : ''}`);
+      return 0;
+    }
+    if (['done', 'drop', 'reopen', 'remove'].includes(sub)) {
+      const t = await get();
+      if (!t || t.ok === false) return fail((t && t.error) || 'the server did not answer');
+      const ref = pos[1];
+      const g = /^\d+$/.test(String(ref)) ? t.plan.goals[Number(ref) - 1] : t.plan.goals.find((x) => x.id === ref);
+      if (!g) return fail(`no goal ${ref || ''} today — ${usage}`);
+      const r = await call('POST', '/api/proactive/goals', { action: sub, id: g.id });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing changed.`);
+      say(`${sub === 'remove' ? 'removed' : sub === 'reopen' ? 'reopened' : sub === 'drop' ? 'dropped' : 'done'}: ${g.text}`);
+      return 0;
+    }
+    if (sub === 'plan') {
+      const ws = await wsOfRepo();
+      if (!ws) return fail('this is not inside a registered workspace — open it with pmos first, or use --repo PATH');
+      const r = await call('POST', '/api/proactive/goals/plan', { ws });
+      if (!r || r.ok === false) return fail(`not started — ${(r && r.error) || 'the server did not answer'}`);
+      say(`${r.seeded ? `scheduled the morning brief daily at ${r.schedule.time}, and ` : ''}started a morning-brief session to plan ${r.goals} goal(s). The plan shows when it submits the brief.`);
+      return 0;
+    }
+    if (sub !== 'list') return fail(usage);
+    const t = await get();
+    if (!t || t.ok === false) return fail((t && t.error) || 'the server did not answer');
+    const pl = t.plan;
+    if (!pl.goals.length) say(`No goals for ${t.today}. Add one with: pmos proactive goals add "…"`);
+    pl.goals.forEach((g, i) => {
+      say(`${i + 1}. ${g.id} [${g.coverage}] ${g.text}${g.initiative_id ? ' · ' + g.initiative_id : ''}`);
+      for (const e of g.context) say(`     ${e.start}  ${e.title}`);
+      for (const st of g.steps) say(`     ${st.owner === 'pm' ? 'you  ' : 'agent'}  ${st.title}  (${st.source}${st.mention ? ', mention' : ''}${st.prepare ? ', can prepare' : ''})`);
+    });
+    if (pl.also.length) { say('Also on your plate:'); for (const st of pl.also) say(`   ${st.owner === 'pm' ? 'you  ' : 'agent'}  ${st.title}  (${st.source})`); }
+    if (pl.brief && !pl.brief.fresh) say(`The brief is for ${pl.brief.date}, not today: it is not used. Run: pmos proactive goals plan`);
+    if (!pl.brief) say('No brief yet, so the plan uses only what Today derived. Run: pmos proactive goals plan');
+    if (pl.time) say(`Free until ${pl.time.until}: ${pl.time.free_minutes} min${pl.time.next ? ` · next: ${pl.time.next.title} at ${pl.time.next.start}` : ''}`);
+    if (pl.not_read.length) say('not read: ' + pl.not_read.map((x) => `${x.source} (${x.state})`).join(', '));
+    if (t.cards_error) say('! Today could not be read: ' + t.cards_error);
+    return 0;
+  }
   if (verb === 'brief') {
     const sub = pos[0] || 'show';
     if (sub === 'submit') {

package/workspace/lib/proactive.js

@@ -29,9 +29,9 @@ const DISMISS_MS = 7 * DAY;
 const BASE = { needs: 100, returned: 100, review: 80, schedule: 60, stalled: 40 };
 const OWNER = { needs: 'pm', returned: 'pm', review: 'pm', schedule: 'pm', stalled: 'agent' };
 
-const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
+const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'slack', 'jira', 'confluence'];
 // Mail is off by default: a brief reads titles and metadata of the other sources, and the PM turns mail on.
-const BRIEF_DEFAULT = Object.freeze({ calendar: true, wispr: true, mail: false, jira: true, confluence: true });
+const BRIEF_DEFAULT = Object.freeze({ calendar: true, wispr: true, mail: false, slack: true, jira: true, confluence: true });
 const DEFAULTS = Object.freeze({ name: '', briefSources: BRIEF_DEFAULT, briefScoring: false, backgroundPrepare: false, enabled: true, triggers: Object.freeze(Object.fromEntries(TRIGGERS.map((t) => [t, true]))), stalledDays: 5, quiet: null, pauseLearning: false });
 
 const idOf = (key) => crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 12);

package/workspace/lib/qr.js

@@ -0,0 +1,293 @@
+'use strict';
+/*
+ * qr — a QR code encoder small enough to read, for one job: the remote-mode startup banner prints
+ * the phone URL as a code the phone camera can scan (workspace-phone-app). Typing
+ * http://100.x.y.z:7433/?token=<43 characters> on a phone keyboard is the step that made the
+ * tailnet flow impractical.
+ *
+ * Why it is written here and not installed: the workspace ships offline (D62) and `create-pmos
+ * workspace` installs it with `npm install -g`, so every dependency is weight on every adopter.
+ * The encoder needs about 200 lines. test.js (QR-*) checks it against published vectors: the
+ * Reed-Solomon worked example for "HELLO WORLD" 1-M, a format string, the alignment positions and
+ * the data capacities. When it was written, every version 1 to 10 at both levels and with each of
+ * the eight masks (193 codes) was also decoded by an independent reader, zxing-cpp; that reader is
+ * not a dependency, so the suite does not repeat the check.
+ *
+ * Scope, on purpose: byte mode only, error-correction level M (or L), versions 1 to 10 (up to 213
+ * bytes at M). A URL with a token is about 80 bytes. Anything longer throws rather than producing
+ * a code that cannot scan. The structure follows ISO/IEC 18004 and Project Nayuki's reference
+ * implementation (MIT), cut down to that scope.
+ */
+
+// Per version 1..10 (index 0 unused): error-correction codewords per block, and number of blocks.
+const ECC = {
+  L: { bits: 1, perBlock: [0, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18], blocks: [0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4] },
+  M: { bits: 0, perBlock: [0, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26], blocks: [0, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5] },
+};
+const MAX_VERSION = 10;
+
+// ── GF(256) arithmetic and Reed-Solomon, over the QR polynomial x^8+x^4+x^3+x^2+1 (0x11D) ────────
+function gfMul(x, y) {
+  let z = 0;
+  for (let i = 7; i >= 0; i--) {
+    z = (z << 1) ^ ((z >>> 7) * 0x11d);
+    z ^= ((y >>> i) & 1) * x;
+  }
+  return z & 0xff;
+}
+function rsDivisor(degree) {
+  const out = new Array(degree).fill(0);
+  out[degree - 1] = 1;
+  let root = 1;
+  for (let i = 0; i < degree; i++) {
+    for (let j = 0; j < out.length; j++) {
+      out[j] = gfMul(out[j], root);
+      if (j + 1 < out.length) out[j] ^= out[j + 1];
+    }
+    root = gfMul(root, 0x02);
+  }
+  return out;
+}
+function rsRemainder(data, divisor) {
+  const out = new Array(divisor.length).fill(0);
+  for (const b of data) {
+    const factor = b ^ out.shift();
+    out.push(0);
+    divisor.forEach((coef, i) => { out[i] ^= gfMul(coef, factor); });
+  }
+  return out;
+}
+
+// ── sizes ────────────────────────────────────────────────────────────────────────────────────
+function rawDataModules(ver) {
+  let n = (16 * ver + 128) * ver + 64;
+  if (ver >= 2) {
+    const align = Math.floor(ver / 7) + 2;
+    n -= (25 * align - 10) * align - 55;
+    if (ver >= 7) n -= 36;
+  }
+  return n;
+}
+function dataCodewords(ver, ecl) {
+  return Math.floor(rawDataModules(ver) / 8) - ECC[ecl].perBlock[ver] * ECC[ecl].blocks[ver];
+}
+function alignmentPositions(ver) {
+  if (ver === 1) return [];
+  const count = Math.floor(ver / 7) + 2;
+  const step = Math.ceil((ver * 4 + 4) / (count * 2 - 2)) * 2;
+  const out = [6];
+  for (let pos = ver * 4 + 17 - 7; out.length < count; pos -= step) out.splice(1, 0, pos);
+  return out;
+}
+
+// ── data codewords: byte-mode segment, terminator, padding ───────────────────────────────────
+function dataBits(bytes, ver, ecl) {
+  const bits = [];
+  const put = (val, len) => { for (let i = len - 1; i >= 0; i--) bits.push((val >>> i) & 1); };
+  put(0x4, 4);                              // byte mode
+  put(bytes.length, ver <= 9 ? 8 : 16);     // character count
+  for (const b of bytes) put(b, 8);
+  const capacity = dataCodewords(ver, ecl) * 8;
+  put(0, Math.min(4, capacity - bits.length));
+  put(0, (8 - (bits.length % 8)) % 8);
+  for (let pad = 0xec; bits.length < capacity; pad ^= 0xec ^ 0x11) put(pad, 8);
+  const out = [];
+  for (let i = 0; i < bits.length; i += 8) out.push(parseInt(bits.slice(i, i + 8).join(''), 2));
+  return out;
+}
+
+function withEccInterleaved(data, ver, ecl) {
+  const numBlocks = ECC[ecl].blocks[ver];
+  const eccLen = ECC[ecl].perBlock[ver];
+  const raw = Math.floor(rawDataModules(ver) / 8);
+  const numShort = numBlocks - (raw % numBlocks);
+  const shortLen = Math.floor(raw / numBlocks);
+  const div = rsDivisor(eccLen);
+  const blocks = [];
+  for (let i = 0, k = 0; i < numBlocks; i++) {
+    const dat = data.slice(k, k + shortLen - eccLen + (i < numShort ? 0 : 1));
+    k += dat.length;
+    const ecc = rsRemainder(dat, div);
+    if (i < numShort) dat.push(0);          // placeholder so every block has the same length
+    blocks.push(dat.concat(ecc));
+  }
+  const out = [];
+  for (let i = 0; i < blocks[0].length; i++) {
+    blocks.forEach((blk, j) => { if (i !== shortLen - eccLen || j >= numShort) out.push(blk[i]); });
+  }
+  return out;
+}
+
+// ── the module grid ──────────────────────────────────────────────────────────────────────────
+function formatBits(ecl, mask) {
+  const data = (ECC[ecl].bits << 3) | mask;
+  let rem = data;
+  for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);
+  return ((data << 10) | rem) ^ 0x5412;
+}
+function versionBits(ver) {
+  let rem = ver;
+  for (let i = 0; i < 12; i++) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25);
+  return (ver << 12) | rem;
+}
+const MASKS = [
+  (x, y) => (x + y) % 2 === 0,
+  (x, y) => y % 2 === 0,
+  (x) => x % 3 === 0,
+  (x, y) => (x + y) % 3 === 0,
+  (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0,
+  (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,
+  (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,
+  (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,
+];
+
+function build(codewords, ver, ecl, mask) {
+  const size = ver * 4 + 17;
+  const mod = Array.from({ length: size }, () => new Array(size).fill(false));
+  const fn = Array.from({ length: size }, () => new Array(size).fill(false));
+  const set = (x, y, dark) => { mod[y][x] = dark; fn[y][x] = true; };
+  const bit = (v, i) => ((v >>> i) & 1) !== 0;
+
+  for (let i = 0; i < size; i++) { set(6, i, i % 2 === 0); set(i, 6, i % 2 === 0); }
+  for (const [cx, cy] of [[3, 3], [size - 4, 3], [3, size - 4]]) {
+    for (let dy = -4; dy <= 4; dy++) for (let dx = -4; dx <= 4; dx++) {
+      const d = Math.max(Math.abs(dx), Math.abs(dy));
+      const x = cx + dx; const y = cy + dy;
+      if (x >= 0 && x < size && y >= 0 && y < size) set(x, y, d !== 2 && d !== 4);
+    }
+  }
+  const al = alignmentPositions(ver);
+  for (let i = 0; i < al.length; i++) for (let j = 0; j < al.length; j++) {
+    if ((i === 0 && j === 0) || (i === 0 && j === al.length - 1) || (i === al.length - 1 && j === 0)) continue;
+    for (let dy = -2; dy <= 2; dy++) for (let dx = -2; dx <= 2; dx++) {
+      set(al[i] + dx, al[j] + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+    }
+  }
+  const drawFormat = (m) => {
+    const f = formatBits(ecl, m);
+    for (let i = 0; i <= 5; i++) set(8, i, bit(f, i));
+    set(8, 7, bit(f, 6)); set(8, 8, bit(f, 7)); set(7, 8, bit(f, 8));
+    for (let i = 9; i < 15; i++) set(14 - i, 8, bit(f, i));
+    for (let i = 0; i < 8; i++) set(size - 1 - i, 8, bit(f, i));
+    for (let i = 8; i < 15; i++) set(8, size - 15 + i, bit(f, i));
+    set(8, size - 8, true);                 // the always-dark module
+  };
+  drawFormat(0);                            // reserve the area; redrawn with the real mask below
+  if (ver >= 7) {
+    const v = versionBits(ver);
+    for (let i = 0; i < 18; i++) {
+      const a = size - 11 + (i % 3); const b = Math.floor(i / 3);
+      set(a, b, bit(v, i)); set(b, a, bit(v, i));
+    }
+  }
+
+  // Codewords in the two-column zigzag, right to left, skipping the vertical timing column.
+  let i = 0;
+  for (let right = size - 1; right >= 1; right -= 2) {
+    if (right === 6) right = 5;
+    for (let vert = 0; vert < size; vert++) for (let j = 0; j < 2; j++) {
+      const x = right - j;
+      const y = ((right + 1) & 2) === 0 ? size - 1 - vert : vert;
+      if (!fn[y][x] && i < codewords.length * 8) {
+        mod[y][x] = bit(codewords[i >>> 3], 7 - (i & 7));
+        i++;
+      }
+    }
+  }
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    if (!fn[y][x] && MASKS[mask](x, y)) mod[y][x] = !mod[y][x];
+  }
+  drawFormat(mask);
+  return mod;
+}
+
+// The standard's four penalty rules, so the mask chosen is the one a camera reads most easily.
+function penalty(mod) {
+  const size = mod.length;
+  let score = 0;
+  const lines = [];
+  for (let y = 0; y < size; y++) lines.push(mod[y]);
+  for (let x = 0; x < size; x++) lines.push(mod.map((row) => row[x]));
+  const finderLike = [true, false, true, true, true, false, true];
+  for (const line of lines) {
+    let run = 1;
+    for (let k = 1; k <= line.length; k++) {
+      if (k < line.length && line[k] === line[k - 1]) { run++; continue; }
+      if (run >= 5) score += 3 + (run - 5);
+      run = 1;
+    }
+    for (let k = 0; k + 7 <= line.length; k++) {
+      if (!finderLike.every((v, n) => line[k + n] === v)) continue;
+      const lightBefore = k >= 4 && [1, 2, 3, 4].every((n) => !line[k - n]);
+      const lightAfter = k + 11 <= line.length && [7, 8, 9, 10].every((n) => !line[k + n]);
+      if (lightBefore || lightAfter) score += 40;
+    }
+  }
+  let dark = 0;
+  for (let y = 0; y < size; y++) for (let x = 0; x < size; x++) {
+    if (mod[y][x]) dark++;
+    if (x + 1 < size && y + 1 < size) {
+      const c = mod[y][x];
+      if (mod[y][x + 1] === c && mod[y + 1][x] === c && mod[y + 1][x + 1] === c) score += 3;
+    }
+  }
+  score += 10 * Math.floor(Math.abs((dark * 100) / (size * size) - 50) / 5);
+  return score;
+}
+
+/**
+ * Encode a string as a QR code. Returns the module grid: rows of booleans, true = dark, with no
+ * quiet zone (the renderer adds it).
+ *   encode('http://100.64.0.1:7433/?token=abc')            → level M, smallest version that fits
+ *   encode(text, { ecl: 'L' })                              → more capacity, less damage tolerance
+ *   encode(text, { mask: 3 })                               → force a mask (tests only)
+ * Throws on text longer than version 10 holds at the chosen level.
+ */
+function encode(text, { ecl = 'M', mask = null, minVersion = 1 } = {}) {
+  if (!ECC[ecl]) throw new Error(`qr: unsupported error-correction level ${ecl} (use M or L)`);
+  const bytes = [...Buffer.from(String(text), 'utf8')];
+  let ver = minVersion;
+  for (; ver <= MAX_VERSION; ver++) {
+    const need = 4 + (ver <= 9 ? 8 : 16) + bytes.length * 8;
+    if (need <= dataCodewords(ver, ecl) * 8) break;
+  }
+  if (ver > MAX_VERSION) throw new Error(`qr: ${bytes.length} bytes do not fit in a version-${MAX_VERSION} code at level ${ecl}`);
+  const codewords = withEccInterleaved(dataBits(bytes, ver, ecl), ver, ecl);
+  if (mask != null) return build(codewords, ver, ecl, mask);
+  let best = null; let bestScore = Infinity;
+  for (let m = 0; m < 8; m++) {
+    const grid = build(codewords, ver, ecl, m);
+    const s = penalty(grid);
+    if (s < bestScore) { best = grid; bestScore = s; }
+  }
+  return best;
+}
+
+/**
+ * Draw a module grid as terminal lines, two module rows per text line (half blocks), with the
+ * 4-module quiet zone a scanner needs.
+ *   ansi: true   explicit black-on-white colours, correct on any terminal theme (the default for a TTY)
+ *   ansi: false  no escape codes; light modules are drawn as blocks, so it reads correctly on the
+ *                usual dark terminal and inverted on a light one (most phone cameras read both)
+ */
+function toTerminal(grid, { ansi = true } = {}) {
+  const q = 4;
+  const size = grid.length + q * 2;
+  const dark = (x, y) => {
+    const gx = x - q; const gy = y - q;
+    return gx >= 0 && gy >= 0 && gx < grid.length && gy < grid.length && grid[gy][gx];
+  };
+  const lines = [];
+  for (let y = 0; y < size; y += 2) {
+    let s = '';
+    for (let x = 0; x < size; x++) {
+      const top = dark(x, y); const bottom = y + 1 < size ? dark(x, y + 1) : false;
+      if (ansi) s += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' ';
+      else s += !top && !bottom ? '█' : !top ? '▀' : !bottom ? '▄' : ' ';
+    }
+    lines.push(ansi ? `\x1b[30;47m${s}\x1b[0m` : s);
+  }
+  return lines;
+}
+
+module.exports = { encode, toTerminal, _internal: { rsDivisor, rsRemainder, formatBits, dataCodewords, alignmentPositions } };