@tensor.chat/companion 0.4.1 → 0.4.3

package/README.md

@@ -13,8 +13,11 @@ npx @tensor.chat/companion pair
 ```
 
 The command prints a code such as `AB3D-7KQ2`. In tensor.chat open
-**Settings → Companion devices → Pair a device** and enter it. Then keep the daemon
-running:
+**Settings → Companion devices → Pair a device** and enter it. Once paired, a short
+setup asks in the terminal what the AI may use on this computer: folders from a list of
+suggestions or a folder browser, everything (not recommended), or nothing yet, and
+whether it may run commands. Run it again any time with
+`npx @tensor.chat/companion setup`. Then keep the daemon running:
 
 ```
 npx @tensor.chat/companion run
@@ -25,9 +28,11 @@ It then appears as the folder `Devices/<name>/` in that chat's file tree.
 
 ## What the AI can do, and where
 
-- **Shared folders** must be approved locally on the computer first with
-  `tensor-companion approve-folder <full-path>`. The website can request and display
-  folders, but it cannot grant itself access. Read, Write, Edit, Glob and Grep only
+- **Shared folders** must be approved locally on the computer first, with
+  `tensor-companion setup` or `tensor-companion approve-folder <full-path>`. The website
+  can request and display folders, but it cannot grant itself access. When a chat asks
+  for a folder the computer already approved (or one inside it), the daemon confirms
+  that by itself; anything else waits for `tensor-companion allow <code>`. Read, Write, Edit, Glob and Grep only
   work inside locally approved folders. Paths outside, including symlinks that point
   outside, are refused on this machine even if the server asks for them.
 - **Shell commands** stay in tensor.chat's server sandbox by default. Approve shell locally

package/bin/tensor-companion.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 // tensor-companion — pair this machine with your tensor.chat account and keep it
-// available for the AI. Commands: pair, run, status, shell, unpair.
+// available for the AI. Commands: pair, setup, run, status, shell, unpair.
 
 const os = require('os');
 const config = require('../src/config');
@@ -33,14 +33,35 @@ async function pair() {
   const cfg = await pairing.waitAndSave(server, start, { name });
   if (!cfg) throw new Error('the pairing code expired — run "npx @tensor.chat/companion pair" again');
   out(`  Paired as "${cfg.name}". Config saved to ${config.configPath()}`);
+  if (process.stdin.isTTY && process.stdout.isTTY) await setup();
+  else out('  Choose what the AI may use here with: npx @tensor.chat/companion setup');
   out('  Start the daemon with: npx @tensor.chat/companion run');
 }
 
+// What this computer lets the AI use, chosen in a guided menu
+async function setup() {
+  const { runSetup } = require('../src/setup/wizard');
+  const { translator, pickLanguage } = require('../src/setup/i18n');
+  const t = translator(pickLanguage(process.env, opt('--lang')));
+  if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error(t('done.noTty'));
+  let user = '';
+  try { user = os.userInfo().username; } catch (_) {}
+  const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+  const r = await runSetup({ user, device: config.load().name || os.hostname(), isRoot, lang: opt('--lang') });
+  out('');
+  if (!r.saved) { out(`  ${t('done.unchanged')}`); return; }
+  out(`  ✔ ${t('done.saved')}`);
+  out(`    ${t('review.folders')}: ${r.everything ? t('everything.summary') : (r.roots.length ? r.roots.join(', ') : t('review.noFolders'))}`);
+  out(`    ${t('review.commands')}: ${r.shellUntil ? t('review.cmdUntil', { date: t.date(r.shellUntil) }) : t('review.cmdNo')}`);
+  if (r.roots.length) out(`  ${t('done.web')}`);
+  out('');
+}
+
 function run() {
   const cfg = config.load();
   if (!cfg.token || !cfg.serverUrl) throw new Error('not paired yet — run "npx @tensor.chat/companion pair" first');
   const stamp = () => new Date().toISOString().slice(11, 19);
-  const daemon = createDaemon({ serverUrl: cfg.serverUrl, token: cfg.token, shell: cfg.shell, approvedRoots: () => config.approvedRoots(), approvedShell: () => config.shellApproved(), log: (m) => out(`[${stamp()}] ${m}`) });
+  const daemon = createDaemon({ serverUrl: cfg.serverUrl, token: cfg.token, shell: cfg.shell, approvedRoots: () => config.approvedRoots(), approvedShell: () => config.shellApproved(), approver: 'terminal', log: (m) => out(`[${stamp()}] ${m}`) });
   daemon.events.on('welcome', (w) => out(`[${stamp()}] ready as "${w.name || cfg.name}" (device ${w.deviceId})`));
   daemon.events.on('config', (c) => {
     const bad = c.roots.filter((r) => !r.ok);
@@ -144,6 +165,7 @@ function help() {
   out(`tensor-companion ${VERSION}
 
   tensor-companion pair [--server URL] [--name NAME]   pair this machine with your account
+  tensor-companion setup [--lang en|de]                choose what the AI may use on this computer
   tensor-companion run                                 stay connected and run tools for the AI
   tensor-companion status                              show the current pairing
   tensor-companion shell <path|auto>                   choose the shell Bash commands run in
@@ -159,6 +181,7 @@ function help() {
 (async () => {
   try {
     if (cmd === 'pair') await pair();
+    else if (cmd === 'setup') await setup();
     else if (cmd === 'run') run();
     else if (cmd === 'status') status();
     else if (cmd === 'shell') shell();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tensor.chat/companion",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Lets your tensor.chat AI use this machine: files, shell and internet through your own connection.",
   "license": "MIT",
   "homepage": "https://tensor.chat",

package/src/daemon.js

@@ -48,7 +48,9 @@ function isRoot() {
   try { return typeof process.getuid === 'function' && process.getuid() === 0; } catch (_) { return false; }
 }
 
-function systemInfo(shell, localAuthority = false) {
+// approver: where this computer confirms what the website asks for - 'app' (a dialog of
+// the desktop app) or 'terminal' (a command run on it, often over SSH)
+function systemInfo(shell, localAuthority = false, approver = null) {
   let username = null;
   try { username = os.userInfo().username; } catch (_) {}
   return {
@@ -65,18 +67,29 @@ function systemInfo(shell, localAuthority = false) {
     shellKind: bash.shellFor(shell).kind,
     cwd: process.cwd(),
     localAuthority: localAuthority ? 1 : null,
+    approver: approver === 'app' || approver === 'terminal' ? approver : null,
   };
 }
 
+// Whether a real path lies in (or is) one of the folders this computer approved
+function insideApproved(real, approvedRoots) {
+  const norm = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
+  return (Array.isArray(approvedRoots) ? approvedRoots : []).some((r) => {
+    const rel = path.relative(norm(path.resolve(String(r))), norm(real));
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  });
+}
+
+// A request the computer already allows: a folder inside one it approved, or the
+// shell while its approval runs
+function coveredLocally(request, approvedRoots, shellApproved) {
+  if (request.kind === 'shell') return !!shellApproved;
+  try { return insideApproved(fs.realpathSync.native(path.resolve(String(request.path || ''))), approvedRoots); } catch (_) { return false; }
+}
+
 function authorizeRequestedRoots(requestedRoots, labels, approvedRoots) {
   const requested = Array.isArray(requestedRoots) ? requestedRoots.map(String) : [];
   const names = Array.isArray(labels) ? labels.map(String) : [];
-  const approved = (Array.isArray(approvedRoots) ? approvedRoots : []).map((r) => path.resolve(String(r)));
-  const norm = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
-  const inside = (candidate, allowed) => {
-    const rel = path.relative(norm(allowed), norm(candidate));
-    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-  };
   const roots = [];
   const keptLabels = [];
   const rejected = [];
@@ -87,7 +100,7 @@ function authorizeRequestedRoots(requestedRoots, labels, approvedRoots) {
       rejected.push({ path: abs, ok: false, error: 'folder does not exist on this computer' });
       return;
     }
-    if (approved.some((allow) => inside(real, allow))) {
+    if (insideApproved(real, approvedRoots)) {
       roots.push(real);
       keptLabels.push(names[i] || '');
     } else rejected.push({ path: abs, ok: false, error: 'not approved on this computer' });
@@ -95,7 +108,7 @@ function authorizeRequestedRoots(requestedRoots, labels, approvedRoots) {
   return { roots, labels: keptLabels, rejected };
 }
 
-function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShell, slowSpawnMs = SLOW_SPAWN_MS } = {}) {
+function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShell, approver = null, slowSpawnMs = SLOW_SPAWN_MS } = {}) {
   if (!serverUrl || !token) throw new Error('serverUrl and token are required');
   const emitter = new EventEmitter();
   const say = typeof log === 'function' ? log : () => {};
@@ -113,6 +126,26 @@ function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShe
     try { state.ws.send(JSON.stringify(msg)); return true; } catch (_) { return false; }
   }
 
+  // What this computer already allows needs nobody at it: the daemon says yes itself.
+  // Everything else waits for a person there (the desktop app's dialog, or "allow").
+  async function confirmIfCovered(msg) {
+    const what = msg.kind === 'shell' ? 'shell access' : `folder ${msg.path}`;
+    if (!localApprovals || !coveredLocally(msg, localApprovals(), localShellApproval && localShellApproval())) {
+      emitter.emit('local_approval_request', msg);
+      return;
+    }
+    try {
+      const url = `${serverUrl.replace(/\/+$/, '')}/api/companion/local-approvals/${encodeURIComponent(String(msg.code))}/complete`;
+      const res = await fetch(url, { method: 'POST', headers: { authorization: `Bearer ${token}` } });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      say(`${what} confirmed: already approved on this computer`);
+      emitter.emit('local_approval_confirmed', msg);
+    } catch (e) {
+      say(`${what} is approved on this computer, but confirming it failed (${e.message})`);
+      emitter.emit('local_approval_request', msg);
+    }
+  }
+
   function applyConfig(msg) {
     const requested = Array.isArray(msg.roots) ? msg.roots.map(String) : [];
     const labels = Array.isArray(msg.labels) ? msg.labels.map(String) : [];
@@ -264,7 +297,7 @@ function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShe
       case 'cancel': { const c = running.get(String(msg.id)); if (c) c.abort(); break; }
       case 'approval': emitter.emit('approval', msg); break;
       case 'approval_resolved': emitter.emit('approval_resolved', msg); break;
-      case 'local_approval_request': emitter.emit('local_approval_request', msg); break;
+      case 'local_approval_request': confirmIfCovered(msg); break;
       default: break;
     }
   }
@@ -304,7 +337,7 @@ function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShe
       state.connectedAt = Date.now();
       state.lastPingAt = null;
       state.reconnectMs = RECONNECT_MIN_MS;
-      send(systemInfo(shell, !!localApprovals && !!localShellApproval));
+      send(systemInfo(shell, !!localApprovals && !!localShellApproval, approver));
       flushExits();
       say(`connected to ${serverUrl}`);
       emitter.emit('connected');

package/src/setup/i18n.js

@@ -0,0 +1,157 @@
+'use strict';
+// The setup's words, in the language the computer is set to (LC_ALL, LC_MESSAGES,
+// LANG - an SSH session usually brings the caller's), English otherwise.
+
+const STRINGS = {
+  en: {
+    setup: 'setup',
+    steps: ['What', 'Folders', 'Commands', 'Save'],
+    'start.title': 'What may the AI use on this computer?',
+    'start.folders': 'Choose folders', 'start.foldersNote': 'recommended',
+    'start.nothing': 'Nothing yet', 'start.nothingNote': 'a chat asks when it needs a folder',
+    'start.everything': 'Everything', 'start.everythingNote': 'not recommended',
+    'start.help': 'The AI reads, changes and deletes files only where you allow it here.',
+    'start.now': 'Approved now:',
+    'start.later': 'Change it any time:',
+    'places.title': 'Which folders may the AI use?',
+    'places.loading': 'Looking for folders…',
+    'places.none': 'No suggestions on this computer.',
+    'places.browse': 'Browse all folders…', 'places.type': 'Type a path…', 'places.continue': 'Continue',
+    selected: '{n} selected',
+    'note.git': '{n} Git projects', 'note.git1': '1 Git project', 'note.project': 'Git project',
+    'note.web': 'websites', 'note.srv': 'server data', 'note.opt': 'installed programs',
+    'note.etc': 'system settings', 'note.log': 'logs', 'note.home': 'your whole home folder',
+    'note.readOnly': 'read-only for you', 'note.added': 'added by you', 'note.earlier': 'approved earlier',
+    'note.inside': 'inside {path}',
+    'help.home': 'Everything in {home}, also hidden settings and keys such as ~/.ssh.',
+    'help.etc': 'Settings of the whole system. A wrong change there can stop the server.',
+    'help.log': 'Log files of the system and its services. Good for finding errors.',
+    'help.web': 'Files of the websites this server delivers.',
+    'help.srv': 'Data of the services on this server.',
+    'help.opt': 'Programs installed outside the package manager.',
+    'help.code': 'Your code projects.',
+    'help.readOnly': 'You can read here but not write. The AI can do the same, no more.',
+    'help.browse': 'Pick any folder on this computer, like in a file manager.',
+    'help.type': 'Enter a full path. Tab completes it.',
+    'help.continue': 'Next: commands.',
+    'browse.title': 'Browse', 'browse.thisPc': 'This PC',
+    'browse.loading': 'loading…', 'browse.empty': 'no folders', 'browse.noAccess': 'no access', 'browse.link': 'link',
+    'browse.blocked': '{path} is inside {parent}, which is already selected.',
+    'browse.hidden': 'Hidden folders are shown.', 'browse.hiddenOff': 'Hidden folders are hidden.',
+    'type.title': 'Type a folder path', 'type.label': 'Path',
+    'type.notFound': 'There is no folder {path}.',
+    'everything.title': 'Share everything?',
+    'everything.body': 'The AI can read, change and delete every file that {user} can reach on this computer.',
+    'everything.root': 'You are root: that is every file on the system, the system itself included.',
+    'everything.free': 'It lets the AI work freely on this server. Not recommended.',
+    'everything.no': 'No, go back', 'everything.yes': 'Yes, share everything',
+    'everything.summary': 'Everything on this computer',
+    'shell.title': 'May the AI run commands here?',
+    'shell.body': 'Commands run as {user}, with full internet access. They are not limited to the shared folders.',
+    'shell.keep': 'Keep as it is', 'shell.keepNote': 'until {date}',
+    'shell.no': 'Not now', 'shell.noNote': 'a chat asks first when it needs them',
+    'shell.off': 'Turn off', 'shell.offNote': 'a chat asks first when it needs them',
+    'shell.d7': 'Yes, for 7 days', 'shell.d30': 'Yes, for 30 days', 'shell.d365': 'Yes, for a year',
+    'review.title': 'Check and save',
+    'review.folders': 'Folders', 'review.commands': 'Commands',
+    'review.noFolders': 'none — a chat asks when it needs one',
+    'review.removed': 'approval removed',
+    'review.cmdNo': 'not approved — a chat asks first',
+    'review.cmdUntil': 'approved until {date}',
+    'review.save': 'Save', 'review.back': 'Back', 'review.quit': 'Quit without saving',
+    'review.where': 'Saved only on this computer, in {file}',
+    keyNames: { space: 'space', enter: 'enter', esc: 'esc', tab: 'tab', backspace: 'backspace' },
+    keys: { move: 'move', select: 'select', toggle: 'select', back: 'back', quit: 'quit', open: 'open', close: 'close', openClose: 'open/close', up: 'folder up', hidden: 'hidden', done: 'done', tab: 'complete', add: 'add' },
+    'done.saved': 'Saved on this computer.',
+    'done.unchanged': 'Nothing changed.',
+    'done.web': 'When a chat on tensor.chat shares one of these folders, this computer confirms it by itself.',
+    'done.run': 'Start the companion with:',
+    'done.noTty': 'The setup needs an interactive terminal. Without one, use approve-folder and approve-shell.',
+  },
+  de: {
+    setup: 'Einrichtung',
+    steps: ['Was', 'Ordner', 'Befehle', 'Speichern'],
+    'start.title': 'Was darf die KI auf diesem Computer nutzen?',
+    'start.folders': 'Ordner auswählen', 'start.foldersNote': 'empfohlen',
+    'start.nothing': 'Noch nichts', 'start.nothingNote': 'ein Chat fragt, wenn er einen Ordner braucht',
+    'start.everything': 'Alles', 'start.everythingNote': 'nicht empfohlen',
+    'start.help': 'Die KI liest, ändert und löscht Dateien nur dort, wo du es hier erlaubst.',
+    'start.now': 'Jetzt freigegeben:',
+    'start.later': 'Jederzeit änderbar:',
+    'places.title': 'Welche Ordner darf die KI nutzen?',
+    'places.loading': 'Suche Ordner…',
+    'places.none': 'Keine Vorschläge auf diesem Computer.',
+    'places.browse': 'Alle Ordner durchsuchen…', 'places.type': 'Pfad eingeben…', 'places.continue': 'Weiter',
+    selected: '{n} ausgewählt',
+    'note.git': '{n} Git-Projekte', 'note.git1': '1 Git-Projekt', 'note.project': 'Git-Projekt',
+    'note.web': 'Webseiten', 'note.srv': 'Serverdaten', 'note.opt': 'installierte Programme',
+    'note.etc': 'Systemeinstellungen', 'note.log': 'Protokolle', 'note.home': 'dein ganzer Home-Ordner',
+    'note.readOnly': 'für dich nur lesbar', 'note.added': 'von dir hinzugefügt', 'note.earlier': 'schon freigegeben',
+    'note.inside': 'liegt in {path}',
+    'help.home': 'Alles in {home}, auch versteckte Einstellungen und Schlüssel wie ~/.ssh.',
+    'help.etc': 'Einstellungen des ganzen Systems. Eine falsche Änderung dort kann den Server lahmlegen.',
+    'help.log': 'Protokolle des Systems und seiner Dienste. Gut für die Fehlersuche.',
+    'help.web': 'Dateien der Webseiten, die dieser Server ausliefert.',
+    'help.srv': 'Daten der Dienste auf diesem Server.',
+    'help.opt': 'Programme, die neben der Paketverwaltung installiert sind.',
+    'help.code': 'Deine Code-Projekte.',
+    'help.readOnly': 'Du kannst hier lesen, aber nicht schreiben. Die KI kann dasselbe, nicht mehr.',
+    'help.browse': 'Wähle einen beliebigen Ordner auf diesem Computer, wie in einem Dateimanager.',
+    'help.type': 'Gib einen vollständigen Pfad ein. Tab ergänzt ihn.',
+    'help.continue': 'Weiter zu den Befehlen.',
+    'browse.title': 'Durchsuchen', 'browse.thisPc': 'Dieser PC',
+    'browse.loading': 'lädt…', 'browse.empty': 'keine Ordner', 'browse.noAccess': 'kein Zugriff', 'browse.link': 'Verknüpfung',
+    'browse.blocked': '{path} liegt in {parent}, und der ist schon ausgewählt.',
+    'browse.hidden': 'Versteckte Ordner werden angezeigt.', 'browse.hiddenOff': 'Versteckte Ordner sind ausgeblendet.',
+    'type.title': 'Ordnerpfad eingeben', 'type.label': 'Pfad',
+    'type.notFound': 'Den Ordner {path} gibt es nicht.',
+    'everything.title': 'Alles freigeben?',
+    'everything.body': 'Die KI kann jede Datei lesen, ändern und löschen, an die {user} auf diesem Computer herankommt.',
+    'everything.root': 'Du bist root: Das ist jede Datei des Systems, das System selbst eingeschlossen.',
+    'everything.free': 'So kann die KI frei auf diesem Server arbeiten. Nicht empfohlen.',
+    'everything.no': 'Nein, zurück', 'everything.yes': 'Ja, alles freigeben',
+    'everything.summary': 'Alles auf diesem Computer',
+    'shell.title': 'Darf die KI hier Befehle ausführen?',
+    'shell.body': 'Befehle laufen als {user}, mit vollem Internetzugang. Sie sind nicht auf die freigegebenen Ordner beschränkt.',
+    'shell.keep': 'So lassen', 'shell.keepNote': 'bis {date}',
+    'shell.no': 'Jetzt nicht', 'shell.noNote': 'ein Chat fragt vorher, wenn er sie braucht',
+    'shell.off': 'Ausschalten', 'shell.offNote': 'ein Chat fragt vorher, wenn er sie braucht',
+    'shell.d7': 'Ja, für 7 Tage', 'shell.d30': 'Ja, für 30 Tage', 'shell.d365': 'Ja, für ein Jahr',
+    'review.title': 'Prüfen und speichern',
+    'review.folders': 'Ordner', 'review.commands': 'Befehle',
+    'review.noFolders': 'keine – ein Chat fragt, wenn er einen braucht',
+    'review.removed': 'Freigabe entfernt',
+    'review.cmdNo': 'nicht freigegeben – ein Chat fragt vorher',
+    'review.cmdUntil': 'freigegeben bis {date}',
+    'review.save': 'Speichern', 'review.back': 'Zurück', 'review.quit': 'Beenden ohne zu speichern',
+    'review.where': 'Wird nur auf diesem Computer gespeichert, in {file}',
+    keyNames: { space: 'Leertaste', enter: 'Enter', esc: 'Esc', tab: 'Tab', backspace: 'Rücktaste' },
+    keys: { move: 'wählen', select: 'bestätigen', toggle: 'auswählen', back: 'zurück', quit: 'beenden', open: 'öffnen', close: 'schließen', openClose: 'öffnen/schließen', up: 'Ordner hoch', hidden: 'versteckte', done: 'fertig', tab: 'ergänzen', add: 'hinzufügen' },
+    'done.saved': 'Auf diesem Computer gespeichert.',
+    'done.unchanged': 'Nichts geändert.',
+    'done.web': 'Gibt ein Chat auf tensor.chat einen dieser Ordner frei, bestätigt dieser Computer das selbst.',
+    'done.run': 'Den Companion starten mit:',
+    'done.noTty': 'Die Einrichtung braucht ein interaktives Terminal. Ohne eines gehen approve-folder und approve-shell.',
+  },
+};
+
+function pickLanguage(env = process.env, override) {
+  let raw = override || env.TENSOR_COMPANION_LANG || env.LC_ALL || env.LC_MESSAGES || env.LANG;
+  if (!raw) { try { raw = Intl.DateTimeFormat().resolvedOptions().locale; } catch (_) { raw = ''; } }
+  const code = String(raw || '').slice(0, 2).toLowerCase();
+  return Object.prototype.hasOwnProperty.call(STRINGS, code) ? code : 'en';
+}
+
+function translator(lang) {
+  const table = STRINGS[lang] || STRINGS.en;
+  const t = (key, vars) => {
+    const s = Object.prototype.hasOwnProperty.call(table, key) ? table[key] : STRINGS.en[key];
+    if (typeof s !== 'string') return s;
+    return s.replace(/\{(\w+)\}/g, (m, k) => (vars && vars[k] != null ? String(vars[k]) : m));
+  };
+  t.lang = STRINGS[lang] ? lang : 'en';
+  t.date = (iso) => { try { return new Intl.DateTimeFormat(t.lang, { dateStyle: 'medium' }).format(new Date(iso)); } catch (_) { return String(iso).slice(0, 10); } };
+  return t;
+}
+
+module.exports = { pickLanguage, translator, STRINGS };

package/src/setup/layout.js

@@ -0,0 +1,49 @@
+'use strict';
+// How the setup's lines are laid out: wrapped text, columns, the key hints and framed
+// blocks. Widths count what the terminal shows, not the escape codes.
+
+const { width, pad } = require('./term');
+
+function wrap(text, cols) {
+  const lines = [];
+  let line = '';
+  for (const word of String(text).split(/\s+/)) {
+    if (line && width(line) + 1 + width(word) > cols) { lines.push(line); line = word; } else line = line ? `${line} ${word}` : word;
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+// A label in its column, always followed by a gap
+function cell(label, col) {
+  return pad(label, col - 2) + '  ';
+}
+
+function spread(left, right, cols) {
+  return left + ' '.repeat(Math.max(1, cols - width(left) - width(right))) + right;
+}
+
+// The key hints, on as many lines as the width needs
+function keyLines(S, keys, w) {
+  const lines = [''];
+  for (const [k, label] of keys) {
+    const part = `${S.bold(k)} ${S.dim(label)}`;
+    const last = lines[lines.length - 1];
+    if (last && width(last) + 3 + width(part) > w) lines.push(part); else lines[lines.length - 1] = last ? `${last}   ${part}` : part;
+  }
+  return lines.map((l) => '  ' + l);
+}
+
+// A framed block: a warning in yellow, a note in grey
+function panel(S, lines, tone, w) {
+  const edge = (s) => (tone ? S[tone](s) : S.dim(s));
+  const inner = [];
+  for (const l of lines) inner.push(...(width(l) <= w - 4 ? [l] : wrap(l, w - 4)));
+  return [
+    '  ' + edge('╭' + '─'.repeat(w - 2) + '╮'),
+    ...inner.map((l) => '  ' + edge('│') + ' ' + pad(l, w - 4) + ' ' + edge('│')),
+    '  ' + edge('╰' + '─'.repeat(w - 2) + '╯'),
+  ];
+}
+
+module.exports = { wrap, cell, spread, keyLines, panel };

package/src/setup/places.js

@@ -0,0 +1,113 @@
+'use strict';
+// Folders worth offering on this computer: where code, documents and server data
+// usually live. Only folders that exist are offered, each once.
+
+const fs = require('fs');
+const path = require('path');
+
+const fsp = fs.promises;
+const CODE_DIRS = ['projects', 'Projects', 'src', 'code', 'Code', 'dev', 'Developer', 'git', 'repos', 'workspace', 'work', path.join('source', 'repos')];
+// Where a server keeps its sites, data, programs, settings and logs
+const SYSTEM = {
+  linux: [['/var/www', 'web'], ['/srv', 'srv'], ['/opt', 'opt'], ['/etc', 'etc'], ['/var/log', 'log']],
+};
+const GIT_LOOK_LIMIT = 300;
+const PROJECTS_IN_HOME = 8;
+
+async function isDir(p) {
+  try { return (await fsp.stat(p)).isDirectory(); } catch (_) { return false; }
+}
+
+async function writable(p) {
+  try { await fsp.access(p, fs.constants.W_OK); return true; } catch (_) { return false; }
+}
+
+async function hasEntries(p) {
+  try { return (await fsp.readdir(p)).length > 0; } catch (_) { return false; }
+}
+
+async function subfolders(dir) {
+  try {
+    return (await fsp.readdir(dir, { withFileTypes: true }))
+      .filter((d) => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'node_modules')
+      .map((d) => path.join(dir, d.name));
+  } catch (_) { return []; }
+}
+
+// Git projects in a folder and one level below; looks at no more than `limit` folders
+async function countGit(dir, limit = GIT_LOOK_LIMIT) {
+  if (await isDir(path.join(dir, '.git'))) return 1;
+  const first = (await subfolders(dir)).slice(0, limit);
+  let n = 0;
+  let looked = first.length;
+  for (const sub of first) {
+    if (await isDir(path.join(sub, '.git'))) { n++; continue; }
+    if (looked >= limit) continue;
+    const second = (await subfolders(sub)).slice(0, limit - looked);
+    looked += second.length;
+    for (const deeper of second) if (await isDir(path.join(deeper, '.git'))) n++;
+  }
+  return n;
+}
+
+// ~/.config/user-dirs.dirs names the desktop, documents and downloads folders, in the
+// computer's language (XDG_DOCUMENTS_DIR="$HOME/Dokumente")
+async function xdgUserDirs(home) {
+  const found = {};
+  try {
+    const text = await fsp.readFile(path.join(home, '.config', 'user-dirs.dirs'), 'utf8');
+    for (const m of text.matchAll(/^XDG_(DESKTOP|DOCUMENTS|DOWNLOAD)_DIR="([^"]+)"/gm)) {
+      found[m[1]] = m[2].startsWith('$HOME/') ? path.join(home, ...m[2].slice(6).split('/')) : m[2];
+    }
+  } catch (_) {}
+  return found;
+}
+
+async function candidates({ platform, home, env, system }) {
+  const list = [];
+  const add = (p, kind) => { if (p) list.push({ path: p, kind }); };
+  for (const d of CODE_DIRS) add(path.join(home, d), 'code');
+  if (platform === 'linux') {
+    const xdg = await xdgUserDirs(home);
+    add(xdg.DOCUMENTS || path.join(home, 'Documents'), 'docs');
+    add(xdg.DESKTOP || path.join(home, 'Desktop'), 'docs');
+    add(xdg.DOWNLOAD || path.join(home, 'Downloads'), 'docs');
+  } else {
+    if (platform === 'win32' && env.OneDrive) add(path.join(env.OneDrive, 'Documents'), 'docs');
+    for (const d of ['Documents', 'Desktop', 'Downloads']) add(path.join(home, d), 'docs');
+  }
+  add(home, 'home');
+  if (platform === 'win32') add(path.join(env.SystemDrive || 'C:', '\\inetpub', 'wwwroot'), 'web');
+  for (const [p, kind] of system) add(p, kind);
+  return list;
+}
+
+// [{ path, kind, git, readOnly }] - kind: code, project, docs, web, srv, opt, home, etc, log
+async function suggestPlaces({ platform = process.platform, home, env = process.env, system = SYSTEM[platform] || [] } = {}) {
+  const seen = new Set();
+  const key = (p) => (platform === 'win32' || platform === 'darwin' ? p.toLowerCase() : p);
+  const out = [];
+  const keep = async (p, kind) => {
+    let real;
+    try { real = await fsp.realpath(p); } catch (_) { return; }
+    if (seen.has(key(real)) || !(await isDir(real))) return;
+    // A server folder that is there but empty helps nobody
+    if ((kind === 'srv' || kind === 'opt') && !(await hasEntries(real))) return;
+    seen.add(key(real));
+    const item = { path: real, kind, git: 0, readOnly: !(await writable(real)) };
+    if (kind === 'code') item.git = await countGit(real);
+    out.push(item);
+  };
+  const list = await candidates({ platform, home, env, system });
+  for (const c of list.filter((x) => x.kind === 'code')) await keep(c.path, c.kind);
+  // Git projects right in the home folder, as on many servers (~/shop, ~/api)
+  let projects = 0;
+  for (const sub of await subfolders(home)) {
+    if (projects >= PROJECTS_IN_HOME) break;
+    if (await isDir(path.join(sub, '.git'))) { await keep(sub, 'project'); projects++; }
+  }
+  for (const c of list.filter((x) => x.kind !== 'code')) await keep(c.path, c.kind);
+  return out;
+}
+
+module.exports = { suggestPlaces, countGit, xdgUserDirs, SYSTEM };

package/src/setup/term.js

@@ -0,0 +1,94 @@
+'use strict';
+// The parts of a terminal the setup screens need: keys in, whole frames out. The
+// screens draw on the alternate screen, so the shell's history stays as it was.
+
+const readline = require('readline');
+
+const CSI = '\x1b[';
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/g;
+
+// Colour only where the terminal wants it (https://no-color.org); weight and
+// dimming stay, they carry the layout.
+function styles(color) {
+  const sgr = (open, close, isColor) => (s) => ((isColor && !color) ? String(s) : `${CSI}${open}m${s}${CSI}${close}m`);
+  return {
+    bold: sgr(1, 22), dim: sgr(2, 22), inverse: sgr(7, 27), underline: sgr(4, 24),
+    cyan: sgr(36, 39, true), green: sgr(32, 39, true), yellow: sgr(33, 39, true), red: sgr(31, 39, true), gray: sgr(90, 39, true),
+  };
+}
+
+function charWidth(cp) {
+  // East Asian wide and fullwidth forms take two cells
+  if ((cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0xa4cf) || (cp >= 0xac00 && cp <= 0xd7a3)
+    || (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0xfe30 && cp <= 0xfe4f) || (cp >= 0xff00 && cp <= 0xff60)
+    || (cp >= 0xffe0 && cp <= 0xffe6)) return 2;
+  return 1;
+}
+
+function width(s) {
+  let n = 0;
+  for (const ch of String(s).replace(ANSI_RE, '')) n += charWidth(ch.codePointAt(0));
+  return n;
+}
+
+// Cut a line to the screen width, keeping its escape codes; a cut line ends in "…"
+function fit(line, cols) {
+  if (width(line) <= cols) return line;
+  let out = '';
+  let n = 0;
+  let full = false;
+  for (const part of String(line).split(/(\x1b\[[0-9;?]*[A-Za-z])/)) {
+    if (part.startsWith('\x1b[')) { if (!full) out += part; continue; }
+    for (const ch of part) {
+      const w = charWidth(ch.codePointAt(0));
+      if (full || n + w > cols - 1) { full = true; break; }
+      out += ch;
+      n += w;
+    }
+  }
+  return out + '…' + `${CSI}0m`;
+}
+
+function pad(s, cols) {
+  return s + ' '.repeat(Math.max(0, cols - width(s)));
+}
+
+// Opens the screen: raw keys from `input`, frames to `output`. stop() puts the
+// terminal back the way it was, also after an error.
+function openScreen({ input, output }) {
+  const keyHandlers = [];
+  const onKey = (str, key) => { for (const h of keyHandlers) h(str, key || {}); };
+  const onResize = () => { for (const h of resizeHandlers) h(); };
+  const resizeHandlers = [];
+  let open = false;
+  readline.emitKeypressEvents(input);
+  return {
+    start() {
+      if (input.isTTY && typeof input.setRawMode === 'function') input.setRawMode(true);
+      input.on('keypress', onKey);
+      output.on('resize', onResize);
+      input.resume();
+      output.write(`${CSI}?1049h${CSI}?25l`);
+      open = true;
+    },
+    size() { return { cols: Math.max(40, output.columns || 80), rows: Math.max(12, output.rows || 24) }; },
+    draw(lines) {
+      const { cols, rows } = this.size();
+      const shown = lines.slice(0, rows).map((l) => fit(l, cols) + `${CSI}K`);
+      output.write(`${CSI}H` + shown.join('\r\n') + `${CSI}0m${CSI}J`);
+    },
+    onKey(h) { keyHandlers.push(h); },
+    onResize(h) { resizeHandlers.push(h); },
+    stop() {
+      if (!open) return;
+      open = false;
+      input.removeListener('keypress', onKey);
+      output.removeListener('resize', onResize);
+      if (input.isTTY && typeof input.setRawMode === 'function') input.setRawMode(false);
+      input.pause();
+      output.write(`${CSI}0m${CSI}?25h${CSI}?1049l`);
+    },
+  };
+}
+
+module.exports = { styles, width, fit, pad, openScreen };