quoxcli 0.2.0 → 0.4.0

package/lib/commands/server.js

@@ -0,0 +1,405 @@
+/**
+ * quox server: lifecycle of a local self-hosted install (plan C4).
+ *
+ *   status     version, health per service, disk, ports, last update (read-only)
+ *   update     current -> latest public quoxcore tag; backup first; fetch, build, migrate, health;
+ *              auto-rollback on failure; resumable; --dry-run prints the plan and runs nothing
+ *   rollback   previous snapshot + previous version; --dry-run
+ *   uninstall  lists exactly what goes, two-step confirmation, keeps backups unless --purge; --dry-run
+ *   doctor     the quox doctor checks + server-side checks (read-only)
+ *   diag       a redacted support bundle written locally (allowlist redaction), never uploaded
+ *
+ * Every mutating host command goes through lib/server/sys.js gate(): in a dry run it is printed, never run.
+ * The install is the one Getting started recorded (or --dir / QUOX_INSTALL_DIR / the running containers).
+ */
+import chalk from 'chalk';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { createSys } from '../server/sys.js';
+import { resolveInstall, backupsRoot, readInstalled, fetchAvailable, cmpSemver, vtag, compareUrl, releaseNotesUrl } from '../server/install.js';
+import { gatherStatus, statusRows, defaultUrls } from '../server/status.js';
+import { runUpdate, runRollback, UPDATE_STEPS } from '../server/update.js';
+import { planUninstall, runUninstall } from '../server/uninstall.js';
+import { serverChecks } from '../server/doctor.js';
+import { writeDiagBundle } from '../server/diag.js';
+import { latestSnapshot, listSnapshots } from '../server/snapshot.js';
+import { loadRegistry, saveServer, buildRows, planGo, hereIdentity, registryPath } from '../server/devServers.js';
+
+const icon = (s) => (s === 'pass' ? chalk.green('✔') : s === 'warn' ? chalk.yellow('⚠') : s === 'skip' ? chalk.dim('·') : chalk.red('✖'));
+
+/** Pure: is the two-step uninstall confirmation satisfied? */
+export function uninstallConfirmed({ word, path, root }) {
+  return String(word || '').trim() === 'uninstall' && resolve(String(path || '').trim() || '/nonexistent') === resolve(root);
+}
+
+function printRows(rows, out = console.log) {
+  for (const r of rows) {
+    if (r.kind === 'head') out(chalk.bold(`\n ${r.text}`));
+    else if (r.kind === 'gap') out('');
+    else if (r.kind === 'dim') out(chalk.dim(` ${r.key ? `${String(r.key).padEnd(16)} ` : ''}${r.text}`));
+    else out(` ${String(r.key).padEnd(16)} ${r.text}`);
+  }
+  out('');
+}
+
+export function registerServerCommands(program, ctx = {}) {
+  const deps = ctx.serverDeps || {};
+  const env = deps.env || process.env;
+  const sys = deps.sys || createSys();
+  const fetchImpl = deps.fetchImpl || ((...a) => globalThis.fetch(...a));
+  const backups = deps.backups || backupsRoot(env);
+  const log = deps.log || ((l) => console.log(chalk.dim(`  ${l}`)));
+  const ask = deps.ask || (async (message) => {
+    const { default: inquirer } = await import('inquirer');
+    const a = await inquirer.prompt([{ type: 'input', name: 'v', message }]);
+    return a.v;
+  });
+  const isTTY = deps.isTTY ?? (() => Boolean(process.stdin.isTTY));
+  const urls = () => deps.urls || defaultUrls(ctx.config);
+  const json = () => program.opts().output === 'json' || program.opts().json;
+  const dry = (o) => Boolean(o.dryRun || program.opts().dryRun);
+  const yes = (o) => Boolean(o.yes || program.opts().yes);
+
+  async function install(o) {
+    const i = await resolveInstall({ dir: o.dir, env, sys, journey: deps.journey });
+    if (i.error) { const e = new Error(i.error); e.exitCode = 2; throw e; }
+    return i;
+  }
+
+  const server = program.command('server').description('Your self-hosted Quox install: status, update, rollback, uninstall, doctor, diag');
+  const withDir = (c) => c.option('--dir <path>', 'the install directory (default: the one Getting started recorded)');
+
+  withDir(server.command('status').description('Version, health per service, disk, ports and the last update (read-only)'))
+    .action(async (o) => {
+      const i = await install(o);
+      const st = await gatherStatus({ install: i, sys, fetchImpl, urls: urls(), backups });
+      if (json()) { console.log(JSON.stringify(st, null, 2)); return; }
+      printRows(statusRows(st));
+      if (!st.http.every((h) => h.ok) || (st.services.ok && st.services.services.some((s) => s.state !== 'running'))) process.exitCode = 1;
+    });
+
+  withDir(server.command('update').description('Update to the latest release: backup first, then fetch, build, migrate, health; rolls back on failure'))
+    .option('--dry-run', 'print the plan and run nothing')
+    .option('--to <version>', 'a specific release (default: the latest quoxcore tag)')
+    .option('--force', 'proceed despite local changes or low disk, or re-apply the same version')
+    .option('--restart', 'abandon a stopped update to a different version and start this one')
+    .option('--no-rollback', 'on failure, stop where it failed instead of rolling back')
+    .option('-y, --yes', 'skip the confirmation')
+    .action(async (o) => {
+      const i = await install(o);
+      const dryRun = dry(o);
+      if (!dryRun && !yes(o)) {
+        const installed = await readInstalled(i, sys);
+        let target = o.to ? vtag(o.to) : null;
+        if (!target) { const av = await fetchAvailable({ fetchImpl }); if (!av.ok) throw new Error(`could not read the available versions: ${av.error}`); target = av.latest; }
+        const cur = installed.release ? vtag(installed.release) : '?';
+        if (cmpSemver(target, cur) !== null && cmpSemver(target, cur) <= 0 && !o.force) { console.log(`Already on ${cur} (latest is ${target}). Nothing to do.`); return; }
+        console.log(`\n Update ${cur} -> ${chalk.bold(target)} at ${i.repoDir}`);
+        console.log(` Changes: ${installed.release ? compareUrl(cur, target) : releaseNotesUrl(target)}`);
+        console.log(` A backup (database + config) is taken first, into ${backups}. The stack stops briefly while volumes are archived.`);
+        console.log(' Preview every command first with: quox server update --dry-run\n');
+        if (!isTTY()) throw new Error('quox server update needs confirmation; re-run with --yes in a non-interactive shell');
+        const a = await ask(`Type "update" to update to ${target}`);
+        if (String(a).trim() !== 'update') { console.log('Not updated. Nothing was changed.'); return; }
+      }
+      const r = await runUpdate({ install: i, sys, backups, urls: urls(), fetchImpl, dryRun, to: o.to, force: o.force, restart: o.restart, noRollback: o.rollback === false, log });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); if (!r.ok) process.exitCode = 2; return; }
+      const p = r.plan || {};
+      if (r.upToDate) { console.log(`Already on ${p.current} (latest is ${p.target}). Nothing to do.`); return; }
+      if (dryRun && r.ok) {
+        console.log(chalk.bold(`\n Plan: ${p.current || '?'} (${p.currentCommit || '?'}) -> ${p.target}${p.targetCommit ? ` (${p.targetCommit})` : ''}`));
+        if (p.changes) console.log(` What changes: ${p.changes}`);
+        console.log(` Release notes: ${p.releaseNotes} (if published for this tag)`);
+        if (p.resumedAfter) console.log(` Resumes after: ${p.resumedAfter}`);
+        console.log(` Steps: ${UPDATE_STEPS.join(' -> ')}; on failure it rolls back automatically.`);
+        if (p.problems?.length) for (const x of p.problems) console.log(chalk.yellow(` ⚠ ${x}`));
+        console.log(chalk.dim(`\n Dry run: ${r.planned.length} changes listed above, none made. Re-run without --dry-run to update.\n`));
+        return;
+      }
+      if (r.ok) { console.log(chalk.green(`\n ✔ Updated to ${p.target}. Backup: ${p.snapshot}\n`)); return; }
+      process.exitCode = 2;
+      console.log(chalk.red(`\n ✖ Update failed at ${r.failedStep}: ${r.error}`));
+      if (r.rollback) console.log(r.rolledBack ? chalk.yellow(` Rolled back (${r.rollback.scope}); you are on ${p.current} again.`) : chalk.red(` Rollback did not complete: ${r.rollback.error}. Backup: ${p.snapshot}. Run quox server rollback.`));
+      else if (r.failedStep !== 'preflight' && r.failedStep !== 'backup') console.log(` Not rolled back. Re-run quox server update to resume, or quox server rollback.`);
+      console.log('');
+    });
+
+  withDir(server.command('rollback').description('Restore the previous snapshot and version (database, config, code)'))
+    .option('--dry-run', 'print the plan and run nothing')
+    .option('--snapshot <dir>', 'a specific snapshot (default: the latest)')
+    .option('--list', 'list the snapshots and exit')
+    .option('-y, --yes', 'skip the confirmation')
+    .action(async (o) => {
+      if (o.list) {
+        const s = listSnapshots(backups);
+        if (json()) { console.log(JSON.stringify(s, null, 2)); return; }
+        if (!s.length) { console.log(`No snapshots in ${backups}.`); return; }
+        for (const x of s) console.log(` ${x.createdAt}  ${String(x.release || '?').padEnd(8)} ${String(x.commit || '?').padEnd(10)} ${x.reason}  ${x.dir}`);
+        return;
+      }
+      const i = await install(o);
+      const dryRun = dry(o);
+      const snap = o.snapshot ? listSnapshots(backups).find((s) => s.dir === o.snapshot || s.dir.endsWith(`/${o.snapshot}`)) : latestSnapshot(backups);
+      if (!snap) throw new Error(o.snapshot ? `no complete snapshot at ${o.snapshot}` : `no snapshot in ${backups}; nothing to roll back to`);
+      if (!dryRun && !yes(o)) {
+        console.log(`\n Roll back to ${snap.release || '?'} (${snap.commit}) from ${snap.createdAt}.`);
+        console.log(chalk.yellow(' This REPLACES the current database and config with the snapshot; anything since then is lost.'));
+        console.log(' Preview first with: quox server rollback --dry-run\n');
+        if (!isTTY()) throw new Error('quox server rollback needs confirmation; re-run with --yes in a non-interactive shell');
+        const a = await ask('Type "rollback" to continue');
+        if (String(a).trim() !== 'rollback') { console.log('Not rolled back. Nothing was changed.'); return; }
+      }
+      const r = await runRollback({ install: i, sys, backups, urls: urls(), fetchImpl, dryRun, snapshotDir: snap.dir, log });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); if (!r.ok) process.exitCode = 2; return; }
+      if (r.ok && dryRun) { console.log(chalk.dim(`\n Dry run: rollback to ${snap.release || snap.commit} from ${snap.dir}; ${r.planned.length} changes listed above, none made.\n`)); return; }
+      if (r.ok) { console.log(chalk.green(`\n ✔ Rolled back to ${snap.release || snap.commit}.\n`)); return; }
+      process.exitCode = 2;
+      console.log(chalk.red(`\n ✖ Rollback failed at ${r.step}: ${r.error}\n`));
+    });
+
+  withDir(server.command('uninstall').description('Remove this install (lists everything first; keeps backups unless --purge)'))
+    .option('--dry-run', 'list what would be removed and run nothing')
+    .option('--purge', 'also delete every backup')
+    .option('--no-backup', 'skip the final snapshot')
+    .option('-y, --yes', 'non-interactive: confirm step one (needs --confirm too)')
+    .option('--confirm <path>', 'non-interactive: confirm step two by naming the install directory')
+    .action(async (o) => {
+      const i = await install(o);
+      const dryRun = dry(o);
+      const plan = await planUninstall({ install: i, sys, backups, purge: Boolean(o.purge), home: deps.home || homedir() });
+      if (json() && dryRun) { console.log(JSON.stringify({ plan }, null, 2)); return; }
+      console.log(chalk.bold('\n This removes:'));
+      console.log(` Containers (${plan.containers.length}): ${plan.containers.join(', ') || plan.containersError || 'none'}`);
+      console.log(` Volumes, with ALL their data (${plan.volumes.length}): ${plan.volumes.join(', ') || 'none'}`);
+      console.log(` Images built for this install (${plan.images.length}): ${plan.images.join(', ') || 'none'}`);
+      console.log(` Networks: ${plan.networks}`);
+      console.log(` Directories: ${[...plan.dirs, ...(plan.root ? [plan.root] : [])].join(', ')}`);
+      if (plan.journeyFile) console.log(` Getting started state: ${plan.journeyFile}`);
+      if (plan.refused.length) console.log(chalk.yellow(` Refusing to remove (too broad): ${plan.refused.join(', ')}`));
+      console.log(chalk.bold(' It keeps:'));
+      console.log(plan.backups.removed ? chalk.red(` Nothing: --purge also deletes ${plan.backups.count} backup(s) in ${plan.backups.dir}`)
+        : ` Backups in ${plan.backups.dir} (${plan.backups.count} now${o.backup === false ? '' : ', plus a final snapshot taken first'})`);
+      console.log('');
+      if (!dryRun) {
+        let ok;
+        if (isTTY() && !(yes(o) && o.confirm)) {
+          const w = await ask('Step 1 of 2: type "uninstall" to continue');
+          if (String(w).trim() !== 'uninstall') { console.log('Not uninstalled. Nothing was changed.'); return; }
+          const p = await ask(`Step 2 of 2: type the install directory (${i.root}) to confirm`);
+          ok = uninstallConfirmed({ word: 'uninstall', path: p, root: i.root });
+        } else ok = yes(o) && uninstallConfirmed({ word: 'uninstall', path: o.confirm, root: i.root });
+        if (!ok) {
+          if (!isTTY()) throw new Error(`quox server uninstall needs two confirmations; in a non-interactive shell pass --yes and --confirm ${i.root}`);
+          console.log('The directory did not match. Not uninstalled. Nothing was changed.');
+          return;
+        }
+      }
+      const r = await runUninstall({ install: i, sys, backups, purge: Boolean(o.purge), noBackup: o.backup === false, dryRun, log, plan });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); if (!r.ok) process.exitCode = 2; return; }
+      if (!r.ok) { process.exitCode = 2; console.log(chalk.red(` ✖ Uninstall stopped at ${r.step}: ${r.error}\n`)); return; }
+      if (dryRun) { console.log(chalk.dim(` Dry run: ${r.planned.length} changes listed above, none made.\n`)); return; }
+      console.log(chalk.green(` ✔ Uninstalled.${r.finalSnapshot ? ` Final snapshot: ${r.finalSnapshot}` : ''}\n`));
+    });
+
+  withDir(server.command('doctor').description('The quox doctor checks plus server-side checks (read-only)'))
+    .action(async (o) => {
+      const i = await install(o);
+      const { runDoctorChecks } = await import('./doctor.js');
+      const platform = deps.platformChecks ? await deps.platformChecks() : await runDoctorChecks({ config: ctx.config });
+      const srv = await serverChecks({ install: i, sys, fetchImpl, urls: urls(), backups });
+      const all = [...platform, ...srv];
+      const failed = all.filter((c) => c.status === 'fail' || c.status === 'error').length;
+      const warned = all.filter((c) => c.status === 'warn').length;
+      if (json()) { console.log(JSON.stringify({ platform, server: srv, summary: { failed, warnings: warned } }, null, 2)); }
+      else {
+        console.log(chalk.bold('\n Platform'));
+        for (const c of platform) console.log(` ${icon(c.status)} ${String(c.name).padEnd(20)} ${chalk.dim(c.detail || '')}`);
+        console.log(chalk.bold('\n Server'));
+        for (const c of srv) console.log(` ${icon(c.status)} ${String(c.name).padEnd(20)} ${chalk.dim(c.detail || '')}`);
+        console.log(`\n ${all.length - failed - warned} passed · ${warned} warnings · ${failed} failed\n`);
+      }
+      process.exitCode = failed ? 2 : warned ? 1 : 0;
+    });
+
+  withDir(server.command('diag').description('Write a redacted support bundle locally (never uploaded)'))
+    .option('--out <dir>', 'where to write it (default: the current directory)')
+    .action(async (o) => {
+      const i = await install(o);
+      const { runDoctorChecks } = await import('./doctor.js');
+      const { resolveCliVersion } = await import('../core/version.js');
+      const st = await gatherStatus({ install: i, sys, fetchImpl, urls: urls(), backups });
+      const platform = deps.platformChecks ? await deps.platformChecks() : await runDoctorChecks({ config: ctx.config }).catch(() => []);
+      const srv = await serverChecks({ install: i, sys, fetchImpl, urls: urls(), backups });
+      const r = await writeDiagBundle({
+        install: i, sys, out: resolve(o.out || process.cwd()),
+        data: { versions: { cli: resolveCliVersion(), installed: st.installed, running: st.running }, status: st, doctor: [...platform, ...srv] }
+      });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(chalk.green(`\n ✔ Support bundle written: ${r.file}`));
+      console.log(chalk.dim(' Nothing was uploaded. Secrets are kept out by an allowlist; look through it before you share it.\n'));
+    });
+
+  // `quox server config app-url [url]`: read or set the public app URL (instance_config app_base_url).
+  // Server-side source of truth, the same value Settings > General > App URL edits.
+  const cfg = server.command('config').description('Instance settings stored on the server');
+  cfg.command('app-url')
+    .description('Show or set the public app URL (used in sign-in links and emails). Pass a URL to set it, or --clear to fall back to the environment value')
+    .argument('[url]', 'the new public app URL, e.g. https://quox.example.com')
+    .option('--clear', 'remove the stored value')
+    .action(async (url, o) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const get = resolveEndpoint('admin.instance.basics.get');
+      const set = resolveEndpoint('admin.instance.basics.set');
+      if (url && o.clear) { const e = new Error('give a URL or --clear, not both'); e.exitCode = 2; throw e; }
+      if (url || o.clear) {
+        const r = await client.put(set.path, { service: set.service, body: { appBaseUrl: o.clear ? null : url } });
+        if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+        console.log(chalk.green(o.clear ? ' ✔ App URL cleared; using the environment value.' : ` ✔ App URL set to ${url}`));
+        console.log(chalk.dim(` Effective now: ${r.effective?.appBaseUrl}\n`));
+        return;
+      }
+      const r = await client.get(get.path, { service: get.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      const src = r.effective?.appBaseUrlSource === 'instance_config' ? 'set on this server' : 'from the environment (not set in Settings)';
+      console.log(`${r.effective?.appBaseUrl} ${chalk.dim(`(${src})`)}`);
+    });
+
+  // `quox server config lan-targets [on|off]`: let integrations (Ollama, LM Studio, vLLM, Grafana ...)
+  // point at private-network addresses. Default off. Loopback and link-local stay blocked either way.
+  cfg.command('lan-targets')
+    .description('Show or set whether AI servers and integrations on your own private network are allowed (default off)')
+    .argument('[state]', 'on or off')
+    .action(async (state) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const get = resolveEndpoint('admin.instance.lan_targets.get');
+      const set = resolveEndpoint('admin.instance.lan_targets.set');
+      if (state !== undefined && !['on', 'off'].includes(String(state).toLowerCase())) { const e = new Error('give on or off'); e.exitCode = 2; throw e; }
+      if (state !== undefined) {
+        const r = await client.put(set.path, { service: set.service, body: { enabled: String(state).toLowerCase() === 'on' } });
+        if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+        console.log(chalk.green(r.enabled ? ' ✔ Private-network targets are ON: integrations may use addresses on your own network.' : ' ✔ Private-network targets are OFF.'));
+        console.log(chalk.dim(' Loopback (localhost) and link-local addresses stay blocked either way.\n'));
+        return;
+      }
+      const r = await client.get(get.path, { service: get.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(`Private-network targets: ${r.enabled ? 'on' : 'off'} ${chalk.dim('(quox server config lan-targets on|off)')}`);
+    });
+
+  // DEVFLEET CX-2: `quox server roles` — the server roles registry (role -> url). A role (brain today) can be pointed
+  // off-box so the service runs on another host without an env edit; resolveServiceUrl reads the registry before env.
+  // list is readable by any instance admin; set/unset mutate instance-wide state so are instance-OWNER (superadmin) only.
+  const roles = server.command('roles').description('Point a server role (e.g. brain) at a URL, so a service can run off-box without an env change');
+  roles.command('list')
+    .description('Show each role, its URL, and whether it comes from the registry or the environment (read-only)')
+    .action(async () => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const ep = resolveEndpoint('server.roles.list');
+      const r = await client.get(ep.path, { service: ep.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      if (r.corrupt) console.log(chalk.yellow(` ⚠ the roles store is unreadable (${r.error}); showing environment values only
+`));
+      for (const row of (r.roles || [])) {
+        const where = row.source === 'registry' ? chalk.green('registry') : (row.source === 'env' ? chalk.dim('environment') : chalk.dim('unset'));
+        console.log(` ${row.role.padEnd(10)} ${row.url || chalk.dim('(none)')}  ${chalk.dim(`[${where}]`)}`);
+      }
+      if (!(r.roles || []).length) console.log(chalk.dim(' no roles'));
+    });
+  roles.command('set')
+    .description('Point a role at a URL (instance owner only). Use --test to probe it for health and version first')
+    .argument('<role>', 'the role, e.g. brain')
+    .argument('<url>', 'the URL the role should resolve to, e.g. http://10.1.2.3:3106')
+    .option('--test', 'probe <url> for health and version before storing it; abort if it is unreachable')
+    .action(async (role, url, o) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      if (o.test) {
+        const tp = resolveEndpoint('server.roles.test', { role });
+        const t = await client.post(tp.path, { service: tp.service, body: { url } });
+        if (!t.success) { const e = new Error(`--test failed: ${t.error || `status ${t.status}`}; not storing`); e.exitCode = 1; throw e; }
+        if (!json()) console.log(chalk.dim(` probe ok: status ${t.status}${t.version ? `, version ${t.version}` : ''}`));
+      }
+      const ep = resolveEndpoint('server.roles.set', { role });
+      const r = await client.put(ep.path, { service: ep.service, body: { url } });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(chalk.green(` ✔ role ${r.role} -> ${r.url}`));
+    });
+  roles.command('unset')
+    .description('Remove a role from the registry so it falls back to the environment value (instance owner only)')
+    .argument('<role>', 'the role to remove')
+    .action(async (role) => {
+      const { client, auth } = ctx;
+      auth?.requireAuth?.();
+      const ep = resolveEndpoint('server.roles.unset', { role });
+      const r = await client.delete(ep.path, { service: ep.service });
+      if (json()) { console.log(JSON.stringify(r, null, 2)); return; }
+      console.log(chalk.green(r.removed ? ` ✔ role ${role} removed; falling back to the environment value` : ` role ${role} was not set`));
+    });
+
+  // DEVFLEET: the registered dev servers. Bastion supplies address + state, the org's dev-server registry supplies purpose/project/workdir.
+  const regPath = () => deps.registryPath || registryPath(env);
+  async function devRows() {
+    const { client, auth } = ctx;
+    auth?.requireAuth?.();
+    const ep = resolveEndpoint('v1.fleet.hosts.list');
+    const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 5000 });
+    const hosts = d?.hosts || d;
+    if (!Array.isArray(hosts)) throw new Error('could not read the Bastion host registry (quox fleet hosts)');
+    { const reg = await loadRegistry({ client, path: regPath() }); return buildRows(hosts, { servers: reg.servers, defaults: reg.defaults }, deps.here || hereIdentity()); }
+  }
+  server.command('list')
+    .description('The registered dev servers: purpose, project, reachable, and which one this is (read-only)')
+    .action(async () => {
+      const rows = await devRows();
+      if (json()) { console.log(JSON.stringify(rows.map(({ ip, user, jump, ...r }) => r), null, 2)); return; }
+      if (!rows.length) { console.log(chalk.dim(` no dev servers registered. Add one: quox server mark <host> --purpose "main dev"`)); return; }
+      const showDeploy = rows.some(r => r.lastDeploy);
+      const cell = (v) => (v == null || v === '' ? '-' : String(v));
+      const w = (k) => Math.max(k.length, ...rows.map(r => cell(r[k]).length));
+      const cols = ['name', 'purpose', 'project', 'repo'];
+      const widths = Object.fromEntries(cols.map(k => [k, w(k)]));
+      console.log(chalk.bold(` ${cols.map(k => k.toUpperCase().padEnd(widths[k])).join('  ')}  REACHABLE${showDeploy ? '  LAST DEPLOY' : ''}`));
+      for (const r of rows) {
+        const line = `${cols.map(k => cell(r[k]).padEnd(widths[k])).join('  ')}  ${(r.reachable ? 'yes' : 'no').padEnd(9)}${showDeploy ? `  ${cell(r.lastDeploy)}` : ''}`;
+        console.log(` ${line}${r.current ? chalk.cyan('  <- this server') : ''}`);
+      }
+    });
+  server.command('mark')
+    .description('Record what a dev server is for (org registry on the Quox server, additive): purpose, project, repo, workdir, ci')
+    .argument('<name>', 'the Bastion host id, e.g. web01')
+    .option('--purpose <text>', 'what this server is for, e.g. "main dev"')
+    .option('--project <text>').option('--repo <text>').option('--workdir <path>', 'where go starts quox on that server')
+    .option('--ci <text>', 'CI or auto-deploy note or URL').option('--user <user>', 'ssh user (default control)').option('--jump <host>', 'ssh ProxyJump alias (default: the registry defaults.jump, else a direct ssh)')
+    .option('--last-deploy <text>', 'last deploy note (shown only if any server has one)')
+    .action(async (name, o) => {
+      ctx.auth?.requireAuth?.();
+      const e = await saveServer({ client: ctx.client, name, fields: { ...o, lastDeploy: o.lastDeploy }, path: regPath() });
+      if (json()) { console.log(JSON.stringify({ name, ...e }, null, 2)); return; }
+      console.log(chalk.green(` ✔ ${name} recorded${e.purpose ? ` as ${e.purpose}` : ''}`));
+    });
+  server.command('go')
+    .description('Open a Quox window on a registered dev server (ssh via your own config and the Bastion jump host, then quox in its workdir)')
+    .argument('<name>', 'a server from `quox server list`')
+    .option('--dry-run', 'print what would run and run nothing')
+    .action(async (name, o) => {
+      const rows = await devRows();
+      const plan = planGo(rows.find(r => r.name === name));
+      if (plan.error) {
+        const known = rows.map(r => r.name).join(', ') || 'none registered';
+        const e = new Error(plan.error === 'unknown server' ? `unknown server "${name}". Registered: ${known}` : plan.error);
+        e.exitCode = 1; throw e;
+      }
+      console.log(chalk.dim(` going to ${name}: ${plan.text}`));
+      if (dry(o)) return;
+      const spawnImpl = deps.spawnSync || (await import('node:child_process')).spawnSync;
+      const r = spawnImpl(plan.cmd, plan.args, { stdio: 'inherit', cwd: plan.cwd });
+      if (r?.error) { const e = new Error(`could not start ${plan.cmd}: ${r.error.message}`); e.exitCode = 1; throw e; }
+      if (r?.status) process.exitCode = r.status;
+    });
+
+  return server;
+}

package/lib/commands/setup.js

@@ -7,6 +7,16 @@ import { formatDetail, printSuccess, printInfo } from '../core/output.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxApiError, QuoxValidationError } from '../core/errors.js';
 import { confirmDestructive } from '../core/confirm.js';
+import { passwordProblem } from '../quoxon/onboarding/finish.js';
+
+// The auth service's rule (services/auth/utils/passwordValidation.js), said up front.
+export const PASSWORD_POLICY = 'Passwords need at least 12 characters, with an uppercase letter, a lowercase letter, a number and a special character (for example - or !).';
+
+async function readStdinText() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
 
 /**
  * LICENSE-LAUNCH LL-8: read a license-key-v2 JSON object from a file or
@@ -183,11 +193,23 @@ export function registerSetupCommands(program, ctx) {
     .command('admin')
     .description('Create the initial admin account')
     .option('--email <email>', 'admin email')
-    .option('--password <password>', 'admin password')
+    .option('--password <password>', 'admin password (visible in the process list; prefer --password-stdin)')
+    .option('--password-stdin', 'read the admin password from stdin (first line), never argv')
     .option('--name <name>', 'admin display name')
     .action(async (options) => {
       let { email, password, name } = options;
 
+      // QUOXON-Z2H lane R: argv is visible in ps and shell history, so a
+      // script pipes the password in, same as `quox login --password-stdin`.
+      if (options.password && options.passwordStdin) {
+        throw new QuoxValidationError('Pass the password with --password or --password-stdin, not both.');
+      }
+      if (options.passwordStdin) {
+        const text = await (ctx.readStdin || readStdinText)();
+        password = String(text || '').split('\n')[0].replace(/\r$/, '');
+        if (!password) throw new QuoxValidationError('--password-stdin given but stdin was empty.');
+      }
+
       if (!email || !password || !name) {
         const { default: inquirer } = await import('inquirer');
 
@@ -206,18 +228,22 @@ export function registerSetupCommands(program, ctx) {
         }
         if (!password) {
           const ans = await inquirer.prompt([{
-            type: 'password', name: 'password', message: 'Password:', mask: '*',
+            type: 'password', name: 'password', message: `Password (${PASSWORD_POLICY}):`, mask: '*',
+            validate: (v) => { const bad = passwordProblem(v); return bad ? `${bad} ${PASSWORD_POLICY}` : true; },
           }]);
           password = ans.password;
         }
       }
 
+      // The policy is the FIRST thing a weak password meets, before any
+      // server call (the server enforces the same rule; this only says it sooner).
+      const problem = passwordProblem(password);
+      if (problem) throw new QuoxValidationError(`${PASSWORD_POLICY} ${problem} Nothing was sent to the server.`);
+
       // services/auth/routes/setup.js POST /admin destructures `name` (not
-      // `display_name`) from req.body — sending only display_name silently
-      // dropped the admin's name (fell back to 'Admin'). Send both: `name`
-      // is what the endpoint actually reads; `display_name` is kept for
-      // forward-compat / any other consumer that expects it.
-      const data = await client.post(resolveEndpoint('setup.admin').path, {
+      // `display_name`) from req.body. Send both: `name` is what the endpoint
+      // reads; `display_name` is kept for forward-compat.
+      await client.post(resolveEndpoint('setup.admin').path, {
         service: resolveEndpoint('setup.admin').service,
         body: { email, password, name, display_name: name },
         noAuth: true,

package/lib/commands/shortcut.js

@@ -0,0 +1,41 @@
+// `quox shortcut add|remove`: a short command (default `q`) for quox. Local only; never shadows an existing command.
+import chalk from 'chalk';
+import { createInterface } from 'node:readline/promises';
+import { addShortcut, removeShortcut, DEFAULT_NAME } from '../core/shortcut.js';
+import { askText } from '../quoxon/ask.js';
+
+async function askYes(line) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return /^y(es)?$/i.test((await rl.question(`${line} `)).trim()); } finally { rl.close(); }
+}
+
+export function registerShortcutCommand(program, ctx = {}) {
+  const d = ctx.shortcutDeps || {};
+  const out = d.log || ((l) => console.log(l));
+  const sc = program.command('shortcut')
+    .description('A short command for quox, like q (add / remove); refuses if the name already runs something else, never uses sudo');
+  sc.command('add')
+    .description('Make a "q" command that runs quox: a symlink in a directory you own that is on PATH. Refuses (and says what it found) if q already resolves to something else on PATH; never shadows an existing command, no sudo, no shell rc edits. Safe to repeat.')
+    .option('--name <name>', 'the short command name', DEFAULT_NAME)
+    .option('-y, --yes', 'create without asking (needed in a non-interactive shell)')
+    .action(async (o) => {
+      const name = o.name || DEFAULT_NAME;
+      const yes = o.yes || program.opts().yes;
+      if (!yes) {
+        const tty = d.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        if (!tty) { out('Not created: this needs a yes. Re-run with quox shortcut add --yes in a non-interactive shell.'); process.exitCode = 1; return; }
+        if (!(await (d.ask || askYes)(askText(`Make \`${name}\` run quox?`, { keys: 'y/N' })))) { out('Not created. Nothing was changed.'); return; }
+      }
+      const r = (d.add || addShortcut)({ name, ...(d.opts || {}) });
+      out(r.ok ? chalk.green(`✔ ${r.message}`) : chalk.red(`✖ ${r.message}`));
+      if (!r.ok) process.exitCode = 1;
+    });
+  sc.command('remove')
+    .description('Remove the short command, only if it is a link to this quox (anything else named q is left alone)')
+    .option('--name <name>', 'the short command name', DEFAULT_NAME)
+    .action(async (o) => {
+      const r = (d.remove || removeShortcut)({ name: o.name || DEFAULT_NAME, ...(d.opts || {}) });
+      out(r.ok ? r.message : chalk.red(`✖ ${r.message}`));
+      if (!r.ok) process.exitCode = 1;
+    });
+}

package/lib/commands/skills.js

@@ -71,6 +71,38 @@ export function registerSkillsCommands(program, ctx) {
       const data = await client.get(resolveEndpoint('quoxflow.skills.list').path, { service: resolveEndpoint('quoxflow.skills.list').service, query });
       let rows = data.data || data.records || data;
       if (!Array.isArray(rows)) rows = [];
+      rows = rows.map((r) => ({ ...r, store: 'library' }));
+
+      // 4.2.4 skills/t3-skill-view: a library skill with an active quox#748 review row (pending or rejected) cannot
+      // run, and skill_view refuses it. Say so per skill. A queue read failure leaves runnable unknown, never true.
+      try {
+        const rq = resolveEndpoint('skills.reviewQueue.list');
+        const active = new Map();
+        for (const status of ['pending', 'rejected']) {
+          const r = await client.get(rq.path, { service: rq.service, query: { status, orgId: query.orgId } });
+          const items = r && (r.data || r.records);
+          for (const it of Array.isArray(items) ? items : []) if (it && it.skill_id) active.set(it.skill_id, it.status || status);
+        }
+        rows = rows.map((r) => ({ ...r, review_status: active.get(r.id) || null, runnable: !active.has(r.id) }));
+      } catch (err) {
+        printWarning(`Skill review queue could not be read, so which skills can run is unknown: ${err.message}`);
+      }
+
+      // #1006: crystals (`skills from-execution`) live in quoxflow's crystal store, not this library. Merge them
+      // unless a library-only filter is set (crystals have no edition/category/agent fit). A failure there warns,
+      // it never sinks the library listing.
+      if (!options.edition && !options.category && !options.agent) {
+        try {
+          const ep = resolveEndpoint('skills.crystals.list');
+          const c = await client.get(ep.path, { service: ep.service, query: { orgId: query.orgId } });
+          let crystals = c.data || c.skills || c;
+          if (!Array.isArray(crystals)) crystals = [];
+          if (options.tag) crystals = crystals.filter((r) => Array.isArray(r.tags) && r.tags.includes(options.tag));
+          rows = rows.concat(crystals.map((r) => ({ ...r, store: 'crystal' })));
+        } catch (err) {
+          printWarning(`Crystal store (skills from-execution) could not be read, showing the library only: ${err.message}`);
+        }
+      }
 
       if (options.search) {
         const needle = options.search.toLowerCase();
@@ -84,8 +116,8 @@ export function registerSkillsCommands(program, ctx) {
       // shown as undeclared, never defaulted to a licence.
       rows = rows.map((r) => ({ ...r, licence: shortLicenceLabel(r.license) }));
       formatOutput({
-        columns: ['id', 'name', 'category', 'edition', 'version', 'licence', 'decayState', 'createdAt'],
-        headers: ['ID', 'Name', 'Category', 'Edition', 'Version', 'Licence', 'Decay', 'Created'],
+        columns: ['id', 'store', 'name', 'category', 'edition', 'version', 'licence', 'decayState', 'createdAt'],
+        headers: ['ID', 'Store', 'Name', 'Category', 'Edition', 'Version', 'Licence', 'Decay', 'Created'],
         rows,
       }, { format: program.opts().output, emptyMessage: 'No skills found.' });
     });
@@ -101,8 +133,17 @@ export function registerSkillsCommands(program, ctx) {
     .action(async (id, options) => {
       auth.requireAuth();
       const query = { orgId: options.org || resolveOrgId(auth, program) };
-      const data = await client.get(resolveEndpoint('quoxflow.skills.get', { id }).path, { service: resolveEndpoint('quoxflow.skills.get', { id }).service, query });
-      formatDetail(data.data || data, { format: program.opts().output, title: `Skill: ${id}` });
+      let data, store = 'library';
+      try {
+        data = await client.get(resolveEndpoint('quoxflow.skills.get', { id }).path, { service: resolveEndpoint('quoxflow.skills.get', { id }).service, query });
+      } catch (err) {
+        if (err.status !== 404) throw err;
+        // #1006: not in the library; a crystal from `skills from-execution` lives in the crystal store
+        const ep = resolveEndpoint('skills.crystals.get', { id });
+        try { data = await client.get(ep.path, { service: ep.service, query }); } catch (err2) { if (err2.status === 404) throw err; throw err2; }
+        store = 'crystal';
+      }
+      formatDetail({ ...(data.data || data), store }, { format: program.opts().output, title: `Skill: ${id}` });
     });
 
   // ── skills run ───────────────────────────────────────────────────────────
@@ -354,7 +395,9 @@ export function registerSkillsCommands(program, ctx) {
       const ep = resolveEndpoint('skills.rollbackToVersion');
       const data = await client.post(ep.path, { service: ep.service, body, query: { orgId } });
       const record = data.data || data;
-      printSuccess(`Skill rolled back to version ${targetVersion}.`);
+      // #1006: rolling back to the version that is already current is a server-side no-op (it returns that row)
+      if (record && Number(record.version) === targetVersion) printInfo(`Already at version ${targetVersion}: nothing was written.`);
+      else printSuccess(`Skill rolled back to version ${targetVersion} (written as version ${record?.version ?? '?'}).`);
       formatDetail(record, { format: program.opts().output });
     });
 
@@ -542,11 +585,27 @@ export function registerSkillsCommands(program, ctx) {
   sealed
     .command('show')
     .description('Show a sealed skill\'s manifest (name, description, input contract, content hash). Manifest only.')
-    .argument('<sealedId>', 'sealed skill ID')
-    .action(async (sealedId) => {
+    .argument('<sealedId>', 'sealed skill ID or name')
+    .action(async (idOrName) => {
       auth.requireAuth();
-      const ep = resolveEndpoint('skills.sealed.get', { sealedId });
-      const data = await client.get(ep.path, { service: ep.service });
+      let sealedId = idOrName;
+      let data;
+      try {
+        const ep = resolveEndpoint('skills.sealed.get', { sealedId });
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (err) {
+        // Coverage wave (ev_mvg4iwfp_d0b2e3): chat passed the skill's name. A 404 that matches exactly one sealed
+        // skill's name resolves to its id; anything else keeps the original error.
+        if (err.status !== 404) throw err;
+        const lep = resolveEndpoint('skills.sealed.list');
+        const list = await client.get(lep.path, { service: lep.service });
+        const rows = (list && (list.sealed ?? list)) || [];
+        const hits = (Array.isArray(rows) ? rows : []).filter((r) => r && r.name === idOrName);
+        if (hits.length !== 1) throw err;
+        sealedId = hits[0].sealedId;
+        const ep = resolveEndpoint('skills.sealed.get', { sealedId });
+        data = await client.get(ep.path, { service: ep.service });
+      }
       printInfo('Manifest only. The sealed content is never returned by the API.');
       formatDetail(data, { format: program.opts().output, title: `Sealed skill: ${sealedId}` });
     });