memhouse 0.18.12 → 0.20.1

package/examples/04-self-hosted-team/smoke.sh

@@ -3,7 +3,7 @@
 #
 #   ./smoke.sh                  docker compose up -d with ./.env, then test it
 #   SKIP_UP=1 ./smoke.sh        test a stack that is already running (see below)
-#   KEEP=1 ./smoke.sh           keep the `smoke` member and its rooms afterwards
+#   KEEP=1 ./smoke.sh           keep the `smoke` member and its tables afterwards
 #
 # With SKIP_UP=1 nothing is read from .env; give the target instead:
 #   MEMHOUSE_URL              https://<domain>[:port]
@@ -11,8 +11,8 @@
 #   CA_FILE                   the CA that signed the proxy's certificate, if not a public one
 #
 # What it proves: the proxy answers over TLS; the passwordless `default` user is gone; an
-# admin can invite a member; the member installs, ships, and reads its rooms back; a
-# BACKUP to the backups disk restores with the same row count.
+# admin can invite a member; the member installs, ships, and reads its sessions back; a
+# BACKUP of its tables in both databases restores with the same row counts.
 set -euo pipefail
 
 HERE=$(cd "$(dirname "$0")" && pwd)
@@ -33,6 +33,11 @@ if [ "${SKIP_UP:-0}" != "1" ]; then
   MEMHOUSE_URL="https://$MEMHOUSE_DOMAIN$([ "$port" = 443 ] || echo ":$port")"
   MEMHOUSE_ADMIN_USER=${MEMHOUSE_ADMIN_USER:-admin}
   if [ "${MEMHOUSE_TLS:-internal}" = "internal" ]; then
+    # Caddy writes its CA a moment after the container is up: wait for it, up to 60 s.
+    for _ in $(seq 1 30); do
+      (cd "$HERE" && docker compose exec -T caddy test -f /data/caddy/pki/authorities/local/root.crt) && break
+      sleep 2
+    done
     (cd "$HERE" && docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt "$WORK/caddy-root.crt")
     CA_FILE="$WORK/caddy-root.crt"
   fi
@@ -53,8 +58,8 @@ member_q() { ( set -a; . "$WORK/home/env"; set +a; q_as "$MEMHOUSE_USER" "$MEMHO
 cleanup() {
   if [ "${KEEP:-0}" != "1" ] && [ "${CREATED:-0}" = "1" ]; then
     admin_q "DROP USER IF EXISTS smoke" >/dev/null || true
-    for t in $(admin_q "SELECT name FROM system.tables WHERE database = 'mem' AND startsWith(name, 'smoke_') FORMAT TSV"); do
-      admin_q "DROP TABLE IF EXISTS mem.$t SYNC" >/dev/null || true
+    for t in $(admin_q "SELECT database || '.' || name FROM system.tables WHERE database IN ('mem', 'mem_archive') AND startsWith(name, 'smoke_') FORMAT TSV"); do
+      admin_q "DROP TABLE IF EXISTS $t SYNC" >/dev/null || true
     done
   fi
   rm -rf "$WORK"
@@ -88,20 +93,29 @@ out=$(unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD
       mh install --env "$WORK/smoke.env" --editors claude --claude-roots "$WORK/sessions" --yes --no-ship 2>&1 || true)
 case "$out" in *"installed"*) ok "the member installed from the invite file, over https";; *) bad "install failed" "$(printf '%s' "$out" | grep '✗' | head -3)"; exit 1;; esac
 out=$(unset MEMHOUSE_ADMIN_USER MEMHOUSE_ADMIN_PASSWORD; mh ship 2>&1 || true)
-case "$out" in *"shipped 2 sessions"*) ok "shipped: $(printf '%s' "$out" | tail -1 | sed 's/^\[memhouse\] //')";; *) bad "ship failed" "$out";; esac
+case "$out" in *"2 sessions [new 2]"*) ok "shipped: $(printf '%s' "$out" | grep 'capture:' | tail -1 | sed 's/^\[memhouse\] //; s/;.*//')";; *) bad "ship failed" "$out";; esac
 
-r=$(member_q "SELECT count() FROM mem.smoke_messages FINAL FORMAT TSV")
-[ "$r" = "6" ] && ok "the member reads its 6 messages back through the proxy" || bad "read-back count" "$r"
+r=$(member_q "SELECT count() FROM mem.smoke_sessions FINAL FORMAT TSV")
+[ "$r" = "2" ] && ok "the member reads its 2 sessions back through the proxy" || bad "read-back count" "$r"
 r=$(member_q "CREATE TABLE mem.not_mine (x UInt8) ENGINE = MergeTree ORDER BY x" || true)
 case "$r" in *ACCESS_DENIED*|*"Not enough privileges"*) ok "the member cannot create tables outside mem.smoke_*";; *) bad "the member created a table outside its rooms" "$r";; esac
 
+# The member's message parts in the house and its units in the capture archive: both databases
+# are backed up (docs/guides/operate.md, Backups). Each table is first proved to exist, so a backup
+# of a table the layout no longer has fails here, by name, rather than further down.
 ts=$(date -u +%Y-%m-%d-%H_%M_%S)
-r=$(admin_q "BACKUP TABLE mem.smoke_messages TO Disk('backups', 'mem-smoke-$ts.zip')")
-case "$r" in *BACKUP_CREATED*) ok "BACKUP to the backups disk";; *) bad "backup failed" "$r";; esac
-r=$(admin_q "RESTORE TABLE mem.smoke_messages AS mem.smoke_restore_check FROM Disk('backups', 'mem-smoke-$ts.zip')")
+n_tables=$(admin_q "SELECT count() FROM system.tables WHERE (database = 'mem' AND name = 'smoke_session_parts') OR (database = 'mem_archive' AND name = 'smoke_session_units') FORMAT TSV")
+[ "$n_tables" = "2" ] && ok "the member's tables exist in both databases" || bad "missing table: mem.smoke_session_parts or mem_archive.smoke_session_units" "found $n_tables of 2"
+r=$(admin_q "BACKUP TABLE mem.smoke_session_parts, TABLE mem_archive.smoke_session_units TO Disk('backups', 'mem-smoke-$ts.zip')")
+case "$r" in *BACKUP_CREATED*) ok "BACKUP of both databases to the backups disk";; *) bad "backup failed" "$r";; esac
+n_parts=$(admin_q "SELECT count() FROM mem.smoke_session_parts FORMAT TSV")
+n_units=$(admin_q "SELECT count() FROM mem_archive.smoke_session_units FORMAT TSV")
+r=$(admin_q "RESTORE TABLE mem.smoke_session_parts AS mem.smoke_restore_check, TABLE mem_archive.smoke_session_units AS mem_archive.smoke_restore_check FROM Disk('backups', 'mem-smoke-$ts.zip')")
 case "$r" in *RESTORED*) ok "RESTORE from it";; *) bad "restore failed" "$r";; esac
 r=$(admin_q "SELECT count() FROM mem.smoke_restore_check FORMAT TSV")
-[ "$r" = "6" ] && ok "the restored copy holds the same 6 rows" || bad "restored count" "$r"
+[ "$r" = "$n_parts" ] && [ "$n_parts" != "0" ] && ok "the restored copy holds the same $n_parts message parts" || bad "restored parts" "$r (live: $n_parts)"
+r=$(admin_q "SELECT count() FROM mem_archive.smoke_restore_check FORMAT TSV")
+[ "$r" = "$n_units" ] && [ "$n_units" != "0" ] && ok "and the same $n_units archive units" || bad "restored units" "$r (live: $n_units)"
 
 r=$(admin_q "SELECT status FROM system.backups WHERE name LIKE '%''mem-2%' AND startsWith(toString(status), 'BACKUP') ORDER BY start_time DESC LIMIT 1 FORMAT TSV")
 case "$r" in BACKUP_CREATED) ok "the backup service has written a nightly backup since the server started";;

package/examples/README.md

@@ -36,7 +36,11 @@ same shell, which keeps it off the screen and out of shell history.
 
 ## How they were tested
 
-Last run on 2026-10-08, memhouse 0.18.9 (main `ccdcfb8`), against ClickHouse 26.7.1.1315,
-the version memhouse's own production house runs: 01 on a disposable Linux VM with Docker,
-02 and 03 against a disposable ClickHouse, 04 as the full compose stack. The output each
-README quotes is from that run.
+Last run on 2026-10-22, memhouse 0.20.0-dev.15, on
+a lab host: 01 with Docker 29, 02 and 03 against a lab ClickHouse 26.7.4.58, 04 as the full
+compose stack on ClickHouse 26.7.1.1315. A new house is schema 3; the output each README
+quotes is from that run.
+
+That run predates the tables 0.20.0 creates, the harness-sessions-sql profile: the quoted outputs still
+name the development builds' layout (`_turns`, `_records`, `_files`). The scripts and the prose
+use the profile's tables; the outputs are run again and re-quoted on the release candidate.

package/examples/fixtures/README.md

@@ -12,7 +12,10 @@ Each project gets one session: a question, a tool call (`memhouse whoami`) and i
 and an answer. The `alpha` session is about an `ACCESS_DENIED` error and the `beta` one
 about rotating a password, so a search can tell them apart. memhouse records the project
 as the last segment of the session's folder (`/home/<person>/work/alpha`), which is what a
-scoped share like `--only project=alpha` matches.
+scoped share like `--only project=alpha` matches. Each reply carries its API response id and
+its usage, as Claude Code writes them: memhouse counts a response's tokens once, by that id,
+so the made-up sessions have token counts and `memhouse doctor`'s token-capture check reads
+them like real ones.
 
 Point memhouse at the directory, and at nothing else, with:
 

package/examples/fixtures/make-sessions.js

@@ -10,7 +10,9 @@
 //   MEMHOUSE_EDITORS=claude MEMHOUSE_CLAUDE_ROOTS=<claude-root> memhouse ship
 //
 // and nothing else on the machine is read. Each project gets one session: a question, a
-// tool call, an answer. The project memhouse records is the folder's last segment, so
+// tool call, an answer. Each reply carries its API response id and usage, as Claude Code
+// writes them: memhouse counts a response's tokens once, by that id, so a reply without one
+// would ship no usage at all. The project memhouse records is the folder's last segment, so
 // `--only project=alpha` in a scoped share matches the session written for `alpha`.
 //
 // Prints one line per session: <project> <session-id>.
@@ -45,17 +47,18 @@ for (const [i, project] of projects.entries()) {
   const t = (s) => new Date(now - (projects.length - i) * 3600e3 + s * 1000).toISOString();
   const { ask, answer } = topic(project);
   const base = { sessionId: sid, cwd: folder, gitBranch: 'main', version: '2.1.0' };
+  const tag = sid.replace(/-/g, '').slice(0, 16);
   const lines = [
     { ...base, type: 'user', uuid: 'u1', timestamp: t(0), message: { role: 'user', content: ask } },
-    { ...base, type: 'assistant', uuid: 'a1', parentUuid: 'u1', timestamp: t(4),
-      message: { role: 'assistant', model: 'claude-example', content: [
+    { ...base, type: 'assistant', uuid: 'a1', parentUuid: 'u1', timestamp: t(4), requestId: `req_example_${tag}_1`,
+      message: { id: `msg_example_${tag}_1`, role: 'assistant', model: 'claude-example', content: [
         { type: 'text', text: 'Let me look at the grants first.' },
         { type: 'tool_use', id: `toolu_${i}`, name: 'Bash', input: { command: 'memhouse whoami' } },
       ], usage: { input_tokens: 120, output_tokens: 30 } } },
     { ...base, type: 'user', uuid: 'u2', parentUuid: 'a1', timestamp: t(6),
       message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: `toolu_${i}`, content: `member ${person}` }] } },
-    { ...base, type: 'assistant', uuid: 'a2', parentUuid: 'u2', timestamp: t(10),
-      message: { role: 'assistant', model: 'claude-example', content: [{ type: 'text', text: answer }],
+    { ...base, type: 'assistant', uuid: 'a2', parentUuid: 'u2', timestamp: t(10), requestId: `req_example_${tag}_2`,
+      message: { id: `msg_example_${tag}_2`, role: 'assistant', model: 'claude-example', content: [{ type: 'text', text: answer }],
         usage: { input_tokens: 180, output_tokens: 60 } } },
   ];
   fs.writeFileSync(path.join(dir, `${sid}.jsonl`), lines.map((l) => JSON.stringify(l)).join('\n') + '\n');

package/memhouse/admin-secret.js

@@ -1,21 +1,23 @@
-// Where an ADMIN password comes from — and why the command line is the last place.
+// Where an ADMIN password comes from — and why the command line is not one of the places.
 //
 // A password passed as `--admin-password <p>` is in the process list (`ps`) for as long
 // as the command runs and in shell history unless the caller remembered a leading space.
 // The only scriptable admin path used to demand exactly that: `--admin-user` as a flag
 // turned off every other source, so an agent or CI job that held the password in an
 // environment variable (or in a secret store, via `with-secret`) still had to put it on
-// argv. Found by O's sandbox rehearsal (finding 6).
+// argv. Found by O's sandbox rehearsal (finding 6). 0.18.10 deprecated the flag; 0.20.0
+// refuses it, naming the ways that keep the password off the command line.
 //
 // Order, first answer wins:
-//   1. --admin-password-file <path>  a file holding the password (trailing newline dropped)
+//   1. --admin-password-file <path>  a file holding the password (trailing newline dropped),
+//                                    readable by its owner only (chmod 600)
 //      --admin-password-file -       read it from stdin   (printf '%s' "$P" | memhouse …)
-//   2. --admin-password <p>          still accepted, with a warning — never required
-//   3. MEMHOUSE_ADMIN_PASSWORD       the environment; `with-secret` lends it to one command
-//   4. the stored credential         only when it belongs to the SAME admin user
+//   2. MEMHOUSE_ADMIN_PASSWORD       the environment; `with-secret` lends it to one command
+//   3. the stored credential         only when it belongs to the SAME admin user
 // Nothing here prompts: the caller decides whether a TTY prompt is the next step.
 //
-// Pure apart from the one file/stdin read, which is injectable, so it is unit tested.
+// Pure apart from the one file/stdin read and its stat, which are injectable, so it is unit
+// tested.
 
 const fs = require('fs');
 
@@ -25,37 +27,57 @@ function stripOneNewline(s) {
   return String(s).replace(/\r?\n$/, '');
 }
 
-function readSecretFile(spec, { readFile = fs.readFileSync, stdinIsTTY = process.stdin.isTTY } = {}) {
+// Container runtimes mount secrets read-only for everyone inside the container (Docker's
+// /run/secrets is 0444, Kubernetes' secret volumes default to 0644). Those directories are
+// the container's own; the mode check would only refuse the intended way in.
+const CONTAINER_SECRET_DIRS = ['/run/secrets/', '/var/run/secrets/'];
+
+// `label` names the flag in every message; the admin password's is the default.
+function readSecretFile(spec, { readFile = fs.readFileSync, stdinIsTTY = process.stdin.isTTY, stat = fs.statSync, platform = process.platform } = {}, label = '--admin-password-file') {
   if (spec === '-') {
-    if (stdinIsTTY) throw new Error('--admin-password-file - reads the password from stdin, but stdin is a terminal — pipe it in, or leave the flag off to be prompted');
+    if (stdinIsTTY) throw new Error(`${label} - reads the password from stdin, but stdin is a terminal — pipe it in, or leave the flag off to be prompted`);
     return stripOneNewline(readFile(0, 'utf-8'));
   }
+  let st;
+  try { st = stat(spec); } catch (e) { throw new Error(`${label} ${spec}: ${e.code === 'ENOENT' ? 'no such file' : e.message.split('\n')[0]}`); }
+  // Like ssh with a private key: a password file other users can read is not a secret. Only
+  // regular files: a pipe or a process substitution (/dev/fd/N) is the caller's own.
+  if (platform !== 'win32' && st.isFile() && (st.mode & 0o077)
+      && !CONTAINER_SECRET_DIRS.some((d) => String(spec).startsWith(d))) {
+    const mode = (st.mode & 0o777).toString(8).padStart(3, '0');
+    throw new Error(`${label} ${spec} is open to other users (mode ${mode}) — restrict it first:  chmod 600 ${spec}`);
+  }
   let text;
-  try { text = readFile(spec, 'utf-8'); } catch (e) { throw new Error(`--admin-password-file ${spec}: ${e.code === 'ENOENT' ? 'no such file' : e.message.split('\n')[0]}`); }
+  try { text = readFile(spec, 'utf-8'); } catch (e) { throw new Error(`${label} ${spec}: ${e.code === 'ENOENT' ? 'no such file' : e.message.split('\n')[0]}`); }
   return stripOneNewline(text);
 }
 
+// The ways to give an admin password that keep it off the command line.
+const SAFE_FORMS = [
+  '     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse …',
+  '     printf \'%s\' "$PASSWORD" | memhouse … --admin-password-file -',
+  '     memhouse … --admin-password-file <file, mode 600>',
+];
+
 /**
  * @param {object} o
  * @param {string} o.adminUser      the admin user this password is for
  * @param {object} o.flags          parsed CLI flags
  * @param {object} [o.env]          process.env (injectable)
  * @param {object} [o.stored]       { user, password } this install keeps, if any
- * @param {object} [o.io]           { readFile, stdinIsTTY } for tests
- * @returns {{ password: string|undefined, source: 'file'|'stdin'|'flag'|'env'|'stored'|null }}
+ * @param {object} [o.io]           { readFile, stdinIsTTY, stat, platform } for tests
+ * @returns {{ password: string|undefined, source: 'file'|'stdin'|'env'|'stored'|null }}
  */
 function resolveAdminPassword({ adminUser, flags = {}, env = process.env, stored = null, io = {} }) {
-  const fileFlag = flags['admin-password-file'];
-  const argvFlag = flags['admin-password'];
-  if (fileFlag !== undefined && argvFlag !== undefined) {
-    throw new Error('give the admin password one way: --admin-password-file or --admin-password, not both');
+  if (flags['admin-password'] !== undefined) {
+    throw new Error(['--admin-password on the command line was removed in 0.20.0: it shows in `ps` and in shell history. Give the admin password one of these ways:', ...SAFE_FORMS].join('\n'));
   }
+  const fileFlag = flags['admin-password-file'];
   if (fileFlag !== undefined) {
     if (fileFlag === true || fileFlag === '') throw new Error('--admin-password-file needs a path, or - for stdin');
     const password = readSecretFile(String(fileFlag), io);
     return { password, source: fileFlag === '-' ? 'stdin' : 'file' };
   }
-  if (argvFlag !== undefined && argvFlag !== true) return { password: String(argvFlag), source: 'flag' };
   if (env && typeof env.MEMHOUSE_ADMIN_PASSWORD === 'string' && env.MEMHOUSE_ADMIN_PASSWORD !== '') {
     return { password: env.MEMHOUSE_ADMIN_PASSWORD, source: 'env' };
   }
@@ -65,17 +87,60 @@ function resolveAdminPassword({ adminUser, flags = {}, env = process.env, stored
   return { password: undefined, source: null };
 }
 
-// One line for a caller that took the password off argv anyway.
-const ARGV_WARNING = '--admin-password on the command line is visible in `ps` and shell history, and is deprecated: it is removed in 0.19.0. Use MEMHOUSE_ADMIN_PASSWORD (with-secret) or --admin-password-file -';
-
 // What to tell a caller with no TTY and no password from any source.
 function missingAdminPasswordHelp(adminUser) {
   return [
     `no password for admin '${adminUser}', and no TTY to prompt on. Give it without putting it on the command line:`,
-    `     with-secret MEMHOUSE_ADMIN_PASSWORD=<reference> -- memhouse …`,
-    `     printf '%s' "$PASSWORD" | memhouse … --admin-password-file -`,
-    `     memhouse … --admin-password-file <file, mode 600>`,
+    ...SAFE_FORMS,
   ];
 }
 
-module.exports = { resolveAdminPassword, readSecretFile, stripOneNewline, ARGV_WARNING, missingAdminPasswordHelp };
+// How to set each variable an admin step can be missing, so a refusal names the fix for exactly
+// those. The password never goes on a command line.
+const SET_FORMS = {
+  MEMHOUSE_URL: 'export MEMHOUSE_URL=<house-url>',
+  MEMHOUSE_ADMIN_USER: 'export MEMHOUSE_ADMIN_USER=<admin>                 (or --admin-user <admin>)',
+  MEMHOUSE_ADMIN_PASSWORD: 'read -rs MEMHOUSE_ADMIN_PASSWORD && export MEMHOUSE_ADMIN_PASSWORD   (or with-secret, or --admin-password-file)',
+};
+
+/**
+ * Which credential an admin step acts as (`memhouse migrate --v3-prepare`, `--v3-convert`,
+ * `--v3-reconcile`, `--v3-shares`), decided before anything connects. A drill found these steps
+ * on the member credential: from an admin's machine with no install, that was resolveConfig()'s
+ * `memhouse_root` default with no password, and every query failed authentication.
+ *   1. The admin names, as invite, members and convert read them: --admin-user or
+ *      MEMHOUSE_ADMIN_USER (or the admin this install keeps). Its password then comes from
+ *      resolveAdminPassword, through bin/memhouse.js adminPasswordFor.
+ *   2. For 0.20 only, the member names: the 0.20 upgrade guide taught MEMHOUSE_USER /
+ *      MEMHOUSE_PASSWORD for these steps. They still work, and `note` says they are deprecated.
+ *   3. Neither: refused, naming exactly what is missing. An admin password with no admin user is
+ *      refused too, never paired with the member's name.
+ * The house's URL must be stated somewhere (flag, environment, env file), never the localhost default.
+ *
+ * @param {object} o
+ * @param {string} o.step                  the step, for the messages ('migrate --v3-prepare')
+ * @param {string} [o.adminUser]           --admin-user / MEMHOUSE_ADMIN_USER / the kept one; '' when none
+ * @param {boolean} [o.adminPasswordGiven] MEMHOUSE_ADMIN_PASSWORD or --admin-password-file is present
+ * @param {string} [o.memberUser]          MEMHOUSE_USER when stated (flag, environment, env file); '' when not
+ * @param {boolean} [o.urlStated]          MEMHOUSE_URL is stated
+ * @returns {{ via: 'admin', user: string }
+ *         | { via: 'member', user: string, note: string }
+ *         | { refuse: string, missing: string[], fix: string[] }}
+ */
+function adminStepCredential({ step, adminUser = '', adminPasswordGiven = false, memberUser = '', urlStated = false }) {
+  const missing = urlStated ? [] : ['MEMHOUSE_URL'];
+  let pick = null;
+  if (adminUser) pick = { via: 'admin', user: adminUser };
+  else if (adminPasswordGiven) missing.push('MEMHOUSE_ADMIN_USER');
+  else if (memberUser) {
+    pick = { via: 'member', user: memberUser,
+      note: `${step} acts as '${memberUser}' from MEMHOUSE_USER/MEMHOUSE_PASSWORD, which are deprecated for admin steps: use MEMHOUSE_ADMIN_USER/MEMHOUSE_ADMIN_PASSWORD` };
+  } else missing.push('MEMHOUSE_ADMIN_USER', 'MEMHOUSE_ADMIN_PASSWORD');
+  if (!missing.length) return pick;
+  return {
+    refuse: `${step} acts as the house's administrator, and ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not set — nothing was contacted`,
+    missing, fix: missing.map((v) => SET_FORMS[v]),
+  };
+}
+
+module.exports = { resolveAdminPassword, readSecretFile, stripOneNewline, missingAdminPasswordHelp, adminStepCredential, SAFE_FORMS };

package/memhouse/argv-secrets.js

@@ -0,0 +1,64 @@
+// Passwords other than the admin's, and how they reach a command without the command line.
+//
+// `--password`, `--member-password` and relocate's `--to-password` each take a password as a
+// value, so it sits in `ps` while the command runs and in shell history after it. The admin
+// password was taken off argv in 0.20.0 (memhouse/admin-secret.js); these were never
+// announced as deprecated, so 0.20 warns, loudly, and the next minor release refuses them.
+//
+// Each has the same safe forms as the admin password:
+//   --<flag>-file <path>   a file holding it, readable by its owner only (chmod 600)
+//   --<flag>-file -        read it from stdin
+//   an environment variable, for the two that have no existing one in the config
+// `--password` keeps MEMHOUSE_PASSWORD, which resolveConfig already reads; it is not copied
+// into the flag here, because for `passwd` the flag means the NEW password.
+//
+// intake() runs once at startup, before any command reads a flag: it turns a file or an
+// environment value into the flag the command already reads, and reports what was given on
+// argv. Pure apart from the reads, which are injectable, so it is unit tested.
+
+const { readSecretFile } = require('./admin-secret');
+
+const SECRETS = [
+  { flag: 'password', file: 'password-file', env: null },
+  { flag: 'member-password', file: 'member-password-file', env: 'MEMHOUSE_MEMBER_PASSWORD' },
+  { flag: 'to-password', file: 'to-password-file', env: 'MEMHOUSE_TO_PASSWORD' },
+];
+
+// For `passwd`, --password is the NEW password, so MEMHOUSE_PASSWORD (the current one) is no
+// way to give it.
+function warning(s, cmd) {
+  const env = s.env || (cmd === 'passwd' ? null : 'MEMHOUSE_PASSWORD');
+  return `--${s.flag} on the command line shows in \`ps\` and in shell history. It is deprecated and refused from the next minor release: use ${env ? `${env}, or ` : ''}--${s.file} <file, mode 600>, or --${s.file} - (stdin).`;
+}
+
+/**
+ * @param {object} flags  parsed CLI flags; a file or environment value is written into it
+ * @param {object} [o]
+ * @param {object} [o.env]  process.env (injectable)
+ * @param {object} [o.io]   { readFile, stdinIsTTY, stat, platform } for tests
+ * @param {string} [o.cmd]  the command, which decides what a hint can name
+ * @returns {{ warnings: string[], fromArgv: string[] }}  throws on a conflict or an unreadable/unsafe
+ *   file. fromArgv names the flags whose value was typed on the command line, so a caller can
+ *   tell them from the ones a file or the environment filled in.
+ */
+function intake(flags, { env = process.env, io = {}, cmd = null } = {}) {
+  const warnings = [];
+  const fromArgv = [];
+  const fromStdin = [...SECRETS.map((s) => s.file), 'admin-password-file'].filter((f) => flags[f] === '-');
+  if (fromStdin.length > 1) throw new Error(`only one password can come from stdin: ${fromStdin.map((f) => `--${f} -`).join(', ')}`);
+  for (const s of SECRETS) {
+    const onArgv = flags[s.flag] !== undefined && flags[s.flag] !== true;
+    const file = flags[s.file];
+    if (file !== undefined) {
+      if (onArgv) throw new Error(`give the password one way: --${s.file} or --${s.flag}, not both`);
+      if (file === true || file === '') throw new Error(`--${s.file} needs a path, or - for stdin`);
+      flags[s.flag] = readSecretFile(String(file), io, `--${s.file}`);
+      continue;
+    }
+    if (onArgv) { warnings.push(warning(s, cmd)); fromArgv.push(s.flag); continue; }
+    if (s.env && flags[s.flag] === undefined && typeof env[s.env] === 'string' && env[s.env] !== '') flags[s.flag] = env[s.env];
+  }
+  return { warnings, fromArgv };
+}
+
+module.exports = { intake, SECRETS };

package/memhouse/channel.js

@@ -22,10 +22,14 @@ function isPrerelease(version) { return /-/.test(String(version || '')); }
 function pickChannel({ version, pinned = null, tags = null }) {
   const t = tags || {};
   if (pinned) {
+    if (!tags) return { channel: pinned, target: null, reason: `channel '${pinned}': the registry did not answer, so its version is unknown` };
     return t[pinned]
       ? { channel: pinned, target: t[pinned], reason: `pinned by MEMHOUSE_CHANNEL` }
-      : { channel: pinned, target: null, reason: `pinned to '${pinned}', which is not a tag on the registry${tags ? '' : ' (or the registry did not answer)'}` };
+      : { channel: pinned, target: null, reason: `pinned to '${pinned}', which is not a tag on the registry` };
   }
+  // Without the registry's answer nothing can be told: not the line, and not whether a
+  // pre-release is a published one or a tarball.
+  if (!tags) return { channel: null, target: null, reason: 'the registry did not answer — cannot tell which line to follow' };
   const matching = Object.entries(t).filter(([, v]) => v === version).map(([k]) => k);
   if (matching.includes('latest')) return { channel: 'latest', target: t.latest, reason: 'installed version is latest' };
   if (matching.length) return { channel: matching[0], target: t[matching[0]], reason: `installed version is published as '${matching[0]}'` };
@@ -41,25 +45,61 @@ function pickChannel({ version, pinned = null, tags = null }) {
     const k = sameLine.includes('latest') ? 'latest' : sameLine[0];
     return { channel: k, target: t[k], reason: `following '${k}' — the tag on the ${line}.x line this install is on` };
   }
-  if (!tags) return { channel: null, target: null, reason: 'the registry did not answer — cannot tell which line to follow; retry, or: memhouse update --channel <tag>' };
   return { channel: null, target: null, reason: `${version} is on the ${line}.x line and no registry tag points at ${line}.x — crossing lines is a decision: memhouse update --channel <tag>` };
 }
 
 /** "0.18" of "0.18.2" — the line a version belongs to. */
 function lineOf(v) { const m = /^(\d+)\.(\d+)/.exec(String(v || '')); return m ? `${m[1]}.${m[2]}` : ''; }
 
-/** The registry's dist-tags, or null when it cannot be reached. Abbreviated document, small. */
-async function fetchTags(fetchImpl = globalThis.fetch) {
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org/';
+
+/** `npm config get registry`: the user's and the global npmrc, as npm itself resolves them. */
+function npmConfigRegistry() {
+  const p = require('child_process').spawnSync('npm', ['config', 'get', 'registry'], { encoding: 'utf-8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+  return p.status === 0 ? p.stdout.trim() : null;
+}
+
+/**
+ * The registry npm installs from, so the tags are read where `npm install -g` will look: behind
+ * a mirror, registry.npmjs.org is the wrong answer and often one that cannot be reached.
+ * npm_config_registry first (npm reads its environment in either case), then npm's own config,
+ * then npmjs.
+ */
+function registryUrl({ env = process.env, run = npmConfigRegistry } = {}) {
+  let r = env.npm_config_registry || env.NPM_CONFIG_REGISTRY || '';
+  if (!r) { try { r = run() || ''; } catch { r = ''; } }
+  r = String(r).trim();
+  if (!/^https?:\/\//i.test(r)) r = DEFAULT_REGISTRY;
+  return r.endsWith('/') ? r : `${r}/`;
+}
+
+/** A registry URL fit to print: no credentials, no query. */
+function shownRegistry(url) {
+  try { const u = new URL(url); u.username = ''; u.password = ''; u.search = ''; u.hash = ''; return u.toString(); } catch { return '(unreadable registry URL)'; }
+}
+
+/**
+ * The registry's dist-tags: { tags, registry, error }. `tags` is null when they could not be
+ * read, and `error` says why (an HTTP status, no answer, a refused connection). Abbreviated
+ * document, small. A registry that needs a login is read without one, and reads as not answering.
+ */
+async function readTags({ fetchImpl = globalThis.fetch, registry = registryUrl() } = {}) {
   try {
-    const res = await fetchImpl('https://registry.npmjs.org/memhouse', {
+    const res = await fetchImpl(`${registry}memhouse`, {
       headers: { accept: 'application/vnd.npm.install-v1+json' }, signal: AbortSignal.timeout(8000),
     });
-    if (!res.ok) return null;
+    if (!res.ok) return { tags: null, registry, error: `HTTP ${res.status}` };
     const j = await res.json();
-    return j && j['dist-tags'] ? j['dist-tags'] : null;
-  } catch { return null; }
+    return j && j['dist-tags'] ? { tags: j['dist-tags'], registry, error: null } : { tags: null, registry, error: 'its answer has no dist-tags' };
+  } catch (e) {
+    const why = e && e.name === 'TimeoutError' ? 'no answer within 8s' : (e && e.cause && e.cause.code) || (e && e.message) || String(e);
+    return { tags: null, registry, error: why };
+  }
 }
 
+/** The registry's dist-tags, or null when they cannot be read. */
+async function fetchTags(fetchImpl = globalThis.fetch, o = {}) { return (await readTags({ fetchImpl, ...o })).tags; }
+
 /**
  * Is this install behind its channel? Pure — the caller supplies the tags, so nothing here
  * reaches the network and `status` stays offline-safe.
@@ -83,4 +123,4 @@ function behind({ version, pinned = null, tags = null }) {
   return null;
 }
 
-module.exports = { behind, pickChannel, fetchTags, isPrerelease, lineOf };
+module.exports = { behind, pickChannel, fetchTags, readTags, registryUrl, shownRegistry, DEFAULT_REGISTRY, isPrerelease, lineOf };