@assemblyline/al-control 0.0.0-stage → 0.3.0

package/src/cli/workpieces/requeue.js

@@ -0,0 +1,98 @@
+// @ts-check
+
+import { probe } from '../../transport.js';
+import { formatTable } from '../../utils/format.js';
+import { loadLines } from '../../utils/factory-data.js';
+
+/**
+ * `al-control workpieces requeue [id] --bin STATION/failed -f <factory> [--yes]` — move
+ * workpieces back to their station's `input` to run that station again. With `--bin`, every
+ * workpiece in that station's `failed` bin; with an id, that one workpiece from `failed` or
+ * `done`. Dry run unless `--yes`. The probe re-checks each folder, drops its stale
+ * `error.json`/`error.txt` and logs a `requeued` event; the station's next run picks it up.
+ */
+
+/**
+ * @typedef {object} RequeueEntry
+ * @property {string} id
+ * @property {string} from - `STATION/BIN`
+ * @property {string} rel - folder relative to temp/stations/
+ */
+
+/**
+ * Which workpieces a requeue would move. Throws a user-facing Error when the request can't be
+ * met (unknown station, ambiguous id, nothing found).
+ *
+ * @param {Object<string, import('../../utils/line-state.js').LineState>} lines
+ * @param {{id?: string, bin?: string}} argv
+ * @returns {RequeueEntry[]}
+ */
+export function planRequeue(lines, argv) {
+  if (argv.bin) {
+    const m = argv.bin.match(/^([^/]+)\/failed\/?$/);
+    if (!m) throw new Error(`--bin takes STATION/failed (e.g. EX1/failed); to retry a done workpiece, give its id.`);
+    const station = m[1];
+    const line = Object.values(lines).find((l) => l.stations.includes(station));
+    if (!line) throw new Error(`Station "${station}" not found.`);
+    const map = line.bins[station].failed;
+    return [...(map ?? new Map())].map(([id, sub]) => ({ id, from: `${station}/failed`, rel: `${station}/failed/${sub}` }));
+  }
+
+  /** @type {RequeueEntry[]} */
+  const all = [];
+  for (const line of Object.values(lines)) {
+    for (const station of line.stations) {
+      for (const bin of ['failed', 'done']) {
+        for (const [id, sub] of line.bins[station][bin] ?? new Map()) {
+          all.push({ id, from: `${station}/${bin}`, rel: `${station}/${bin}/${sub}` });
+        }
+      }
+    }
+  }
+  const query = /** @type {string} */ (argv.id);
+  const exact = all.filter((e) => e.id === query);
+  const ids = exact.length > 0 ? [query] : [...new Set(all.filter((e) => e.id.includes(query)).map((e) => e.id))].sort();
+  if (ids.length === 0) throw new Error(`No failed or done workpiece matches "${query}".`);
+  if (ids.length > 1) {
+    const shown = ids.slice(0, 10);
+    throw new Error(`"${query}" matches ${ids.length} workpieces; use the full id:\n  ${shown.join('\n  ')}${ids.length > 10 ? `\n  … +${ids.length - 10} more` : ''}`);
+  }
+  const copies = all.filter((e) => e.id === ids[0]);
+  if (copies.length > 1) {
+    throw new Error(`${ids[0]} is in ${copies.map((c) => c.from).join(' and ')}; requeue one bin with --bin STATION/failed.`);
+  }
+  return copies;
+}
+
+/**
+ * @param {{id?: string, bin?: string, yes?: boolean}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function requeueHandler(argv, factory) {
+  const { lines } = loadLines(factory);
+  let plan;
+  try {
+    plan = planRequeue(lines, argv);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  const where = `${factory.host.name} / ${factory.name}`;
+  if (plan.length === 0) {
+    console.log(`Nothing to requeue: ${argv.bin} is empty on ${where}.`);
+    return;
+  }
+
+  const counts = new Map();
+  for (const e of plan) counts.set(e.from, (counts.get(e.from) ?? 0) + 1);
+  console.log(formatTable(['FROM', 'TO', 'WORKPIECES'], [...counts].map(([from, n]) => [from, `${from.split('/')[0]}/input`, String(n)])));
+  if (plan.length === 1) console.log(`\n${plan[0].id}`);
+  console.log('');
+
+  if (!argv.yes) {
+    console.log(`Dry run: would requeue ${plan.length} workpiece${plan.length === 1 ? '' : 's'} on ${where}. Re-run with --yes to move.`);
+    return;
+  }
+  const { requeued } = probe(factory.host, { type: 'requeue', path: factory.path, dirs: plan.map((e) => e.rel) });
+  console.log(`Requeued ${requeued.length} workpiece${requeued.length === 1 ? '' : 's'} on ${where}. The station's next run picks them up.`);
+}

package/src/cli/workpieces/show.js

@@ -0,0 +1,126 @@
+import { resolvePosition, findWorkpieceMatches, workpieceRelDir } from '../../utils/line-state.js';
+import { loadLines, loadLogs, loadWorkpieceFiles, workpieceLocation } from '../../utils/factory-data.js';
+import { formatDate, formatElapsed, formatSection, localTzLabel } from '../../utils/format.js';
+import { listWorkpiecesHandler } from './list.js';
+
+const STACK_FRAMES = 6;
+const MESSAGE_LINES = 3;
+const LINE_MAX = 300;
+
+/**
+ * `al-control workpieces show <id-or-substring> -f <factory>` — one
+ * workpiece: position, journey from log.jsonl with durations, the error when
+ * it has one, its files, folder.
+ *
+ * A substring matching several ids promotes to the `workpieces list --match`
+ * dashboard; pass the full id to force the single view.
+ *
+ * @param {{id: string, json?: boolean}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function showWorkpieceHandler(argv, factory) {
+  const { id: query, json } = argv;
+  const { root, lines } = loadLines(factory);
+  const matches = findWorkpieceMatches(query, lines);
+
+  if (!matches.has(query) && matches.size > 1) {
+    return listWorkpiecesHandler({ ...argv, match: query }, factory);
+  }
+  const id = matches.has(query) ? query : [...matches.keys()][0];
+  if (!id) {
+    console.error(`No workpiece matches "${query}".`);
+    process.exit(1);
+  }
+
+  const pos = resolvePosition(id, lines);
+  const rel = workpieceRelDir(pos, id);
+  const journey = loadLogs(factory, [rel])[rel];
+  const folder = workpieceLocation(factory, root, rel);
+  const { files, error } = loadWorkpieceFiles(factory, rel);
+
+  if (json) {
+    console.log(JSON.stringify({ id, position: pos, journey, error, files, folder }, null, 2));
+    return;
+  }
+
+  console.log(`Workpiece: ${id}`);
+  console.log(`Position:  ${positionLabel(pos)}`);
+  console.log('');
+  renderJourney(journey);
+  if (error) renderError(error, `al-control workpieces cat ${id} error.txt ${factory.flags}`);
+  console.log(formatSection('Files'));
+  const name_w = Math.max(...files.map((f) => f.name.length), 0);
+  for (const f of files) console.log(`  ${f.name.padEnd(name_w)}  ${formatSize(f.size).padStart(8)}`);
+  console.log('');
+  console.log(`Folder: ${folder}`);
+  console.log('');
+  console.log(`Read a file:  al-control workpieces cat ${id} <file> ${factory.flags}`);
+  console.log(`Go there:     al-control workpieces open ${id} ${factory.flags}`);
+  console.log(`Tail live:    al-control workpieces watch ${id} ${factory.flags}`);
+}
+
+/**
+ * Message (first lines, capped — some carry a whole HTML page), any extra
+ * fields the step attached, then the top of the stack.
+ */
+function renderError(error, full_cmd) {
+  const heading = `Error${error.failed_at ? ` — failed ${formatDate(error.failed_at)}` : ''}`;
+  console.log(formatSection(heading));
+  const cap = (l) => (l.length > LINE_MAX ? `${l.slice(0, LINE_MAX)}… [+${l.length - LINE_MAX} chars]` : l);
+  const message_lines = `${error.name ?? 'Error'}: ${error.message ?? ''}`.split('\n');
+  for (const l of message_lines.slice(0, MESSAGE_LINES)) console.log(`  ${cap(l)}`);
+  if (message_lines.length > MESSAGE_LINES) console.log(`  … +${message_lines.length - MESSAGE_LINES} lines`);
+
+  for (const [key, value] of Object.entries(error)) {
+    if (['failed_at', 'name', 'message', 'stack'].includes(key)) continue;
+    console.log(`  ${key}: ${cap(typeof value === 'string' ? value : JSON.stringify(value))}`);
+  }
+
+  const frames = String(error.stack ?? '').split('\n').filter((l) => /^\s+at /.test(l));
+  if (frames.length > 0) {
+    console.log('');
+    for (const f of frames.slice(0, STACK_FRAMES)) console.log(`  ${f.trim()}`);
+    if (frames.length > STACK_FRAMES) console.log(`  … +${frames.length - STACK_FRAMES} frames`);
+  }
+  console.log(`\n  Full error: ${full_cmd}`);
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function positionLabel(pos) {
+  let label = `${pos.station}/${pos.bin}`;
+  if (pos.anomaly) label += '  (anomaly — only in done, no live presence)';
+  else if (pos.bin === 'failed') label += '  (stuck)';
+  else if (pos.bin === 'output' && pos.terminal) label += '  (finished — terminal output)';
+  else if (pos.bin === 'doing') label += '  (in progress)';
+  return label;
+}
+
+function renderJourney(events) {
+  const heading = `Journey (${localTzLabel()})`;
+  console.log(heading);
+  console.log('-'.repeat(heading.length));
+  if (events.length === 0) {
+    console.log('  (no log.jsonl found at current position)');
+    return;
+  }
+  const started_at = {}; // station → ts of last station_started
+  for (const e of events) {
+    let extra = '';
+    if (e.event === 'station_started') {
+      started_at[e.station] = e.ts;
+    } else if (e.event === 'station_complete' || e.event === 'station_failed') {
+      const start = started_at[e.station];
+      if (start) {
+        const ms = new Date(e.ts).getTime() - new Date(start).getTime();
+        if (!Number.isNaN(ms) && ms >= 0) extra = `       (${formatElapsed(ms)})`;
+        delete started_at[e.station];
+      }
+    }
+    console.log(`${formatDate(e.ts)}  ${e.station.padEnd(3)}  ${e.event}${extra}`);
+  }
+}

package/src/cli/workpieces/watch.js

@@ -0,0 +1,159 @@
+import {
+  resolvePosition,
+  findWorkpieceMatches,
+  collectIdsForBin,
+  idsOnLine,
+  workpieceRelDir,
+} from '../../utils/line-state.js';
+import { loadLines, loadLogs, workpieceLocation } from '../../utils/factory-data.js';
+import { formatTime } from '../../utils/format.js';
+import { listWorkpiecesHandler } from './list.js';
+import { showWorkpieceHandler } from './show.js';
+
+const DEFAULT_INTERVAL_SECS = 2;
+
+/**
+ * `al-control workpieces watch [id | --line | --bin | --match] -f <factory>` —
+ * append-style live tail: prints only bin moves and new log events.
+ *
+ * Renders the matching snapshot first (show for one workpiece, list for a
+ * set), then polls. Each tick is two probe calls — state, then the tracked
+ * workpieces' logs in one batch.
+ *
+ * @param {{id?: string, line?: string, bin?: string, match?: string, interval?: number}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function watchHandler(argv, factory) {
+  const { id, line: line_arg, bin: bin_arg, match: match_arg, interval } = argv;
+  const interval_secs = typeof interval === 'number' ? interval : DEFAULT_INTERVAL_SECS;
+  const { lines } = loadLines(factory);
+
+  if (id) {
+    const matches = findWorkpieceMatches(id, lines);
+    if (matches.size === 0) {
+      console.error(`No workpiece matches "${id}".`);
+      process.exit(1);
+    }
+    if (matches.size === 1 || matches.has(id)) {
+      const resolved_id = matches.has(id) ? id : [...matches.keys()][0];
+      await showWorkpieceHandler({ id: resolved_id }, factory);
+      await watchLoop(factory, [resolved_id], { interval_secs, single: true });
+      return;
+    }
+    await listWorkpiecesHandler({ match: id }, factory);
+    await watchLoop(factory, [...matches.keys()], { interval_secs, single: false });
+    return;
+  }
+
+  let ids;
+  if (bin_arg) {
+    const result = collectIdsForBin(bin_arg, lines);
+    if (!result.ok) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    ids = result.ids;
+  } else if (match_arg) {
+    ids = [...findWorkpieceMatches(match_arg, lines).keys()];
+  } else if (line_arg) {
+    const ls = lines[line_arg];
+    if (!ls) {
+      console.error(`Line "${line_arg}" not found. Available: ${Object.keys(lines).sort().join(', ') || '(none)'}`);
+      process.exit(1);
+    }
+    ids = idsOnLine(ls);
+  } else {
+    console.error(`Usage: al-control workpieces watch <id> | --line <code> | --bin STATION/BIN | --match <substring> ${factory.flags}`);
+    process.exit(1);
+  }
+
+  if (ids.length === 0) {
+    console.log('No workpieces in scope.');
+    return;
+  }
+
+  await listWorkpiecesHandler({ line: line_arg, bin: bin_arg, match: match_arg }, factory);
+  await watchLoop(factory, ids, { interval_secs, single: false });
+}
+
+/**
+ * Poll a fixed set of workpieces. Multi-workpiece output tags each line with
+ * the id; a workpiece reaching terminal output emits `✓ finished` once and
+ * stops being followed.
+ *
+ * @param {import('../../config.js').FactoryContext} factory
+ * @param {string[]} ids
+ * @param {{interval_secs: number, single: boolean}} opts
+ */
+async function watchLoop(factory, ids, { interval_secs, single }) {
+  process.on('SIGINT', () => { console.log('\nStopped.'); process.exit(0); });
+  const label = single ? ids[0] : `${ids.length} workpiece${ids.length === 1 ? '' : 's'}`;
+  console.log(`\n--- watching ${label} (interval ${interval_secs}s, Ctrl-C to stop) ---`);
+
+  /** @type {Map<string, {pos_key: string, log_count: number, finished: boolean}>} */
+  const state = new Map();
+
+  const snapshot = () => {
+    const { root, lines } = loadLines(factory);
+    const tracked = ids
+      .filter((id) => !state.get(id)?.finished)
+      .map((id) => {
+        const pos = resolvePosition(id, lines);
+        return { id, pos, rel: pos ? workpieceRelDir(pos, id) : null };
+      });
+    const logs = loadLogs(factory, tracked.filter((t) => t.pos).map((t) => t.rel));
+    return { root, tracked, logs };
+  };
+
+  const seed = snapshot();
+  for (const { id, pos, rel } of seed.tracked) {
+    if (!pos) {
+      if (single) console.log(`${formatTime(new Date())}  ${id}  not on disk`);
+      continue;
+    }
+    state.set(id, {
+      pos_key: `${pos.station}/${pos.bin}`,
+      log_count: seed.logs[rel].length,
+      finished: !single && pos.bin === 'output' && pos.terminal,
+    });
+  }
+  if (state.size === 0 && single) return;
+
+  const tag = (id) => (single ? '' : `  ${id}`);
+
+  while (true) {
+    await new Promise((r) => setTimeout(r, interval_secs * 1000));
+    const { root, tracked, logs } = snapshot();
+
+    for (const { id, pos, rel } of tracked) {
+      const prev = state.get(id);
+      if (!prev) continue;
+
+      if (!pos) {
+        console.log(`${formatTime(new Date())}${tag(id)}  no longer on disk`);
+        state.delete(id);
+        if (single) return;
+        continue;
+      }
+
+      const pos_key = `${pos.station}/${pos.bin}`;
+      const events = logs[rel];
+      if (pos_key !== prev.pos_key) {
+        console.log(`${formatTime(new Date())}${tag(id)}  → moved from ${prev.pos_key} to ${pos_key}`);
+        console.log(`${single ? 'Folder: ' : '                          '}${workpieceLocation(factory, root, rel)}`);
+        prev.pos_key = pos_key;
+        prev.log_count = events.length;
+      } else if (events.length > prev.log_count) {
+        for (const e of events.slice(prev.log_count)) {
+          console.log(`${formatTime(e.ts)}${tag(id)}  ${single ? e.station.padEnd(3) : e.station}  ${e.event}`);
+        }
+        prev.log_count = events.length;
+      }
+
+      if (!single && pos.bin === 'output' && pos.terminal && !prev.finished) {
+        console.log(`${formatTime(new Date())}${tag(id)}  ✓ finished (terminal output)`);
+        prev.finished = true;
+      }
+    }
+  }
+}

package/src/config.js

@@ -0,0 +1,259 @@
+/**
+ * Config store — ~/.assemblyline/al-control/config.yml — and resolution of which host
+ * and factory the current command targets.
+ *
+ * Shape:
+ *   current_host: local
+ *   hosts:
+ *     local:
+ *       factories:
+ *         factory-acme: ~/factories/factory-acme
+ *     build-box:
+ *       ssh: build-box        # alias from ~/.ssh/config
+ *       node: /home/me/.nvm/versions/node/v20.11.0/bin/node   # optional
+ *       factories:
+ *         factory-acme: /home/me/factories/factory-acme
+ *         factory-demo:                # long form, to protect bins from `workpieces clear`
+ *           path: /home/me/factories/factory-demo
+ *           keep: [DI1/done]
+ *
+ * `local` is reserved for this machine and has no `ssh`. Every other host
+ * must have one. Factory paths are paths on that host (`~` expands there).
+ *
+ * Override the directory with AL_CONTROL_CONFIG_DIR (used by tests).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve, basename } from 'node:path';
+import yaml from 'js-yaml';
+
+export const LOCAL_HOST = 'local';
+
+/** @returns {string} */
+export function configDir() {
+  return process.env.AL_CONTROL_CONFIG_DIR || join(homedir(), '.assemblyline', 'al-control');
+}
+
+/** @returns {string} */
+export function configPath() {
+  return join(configDir(), 'config.yml');
+}
+
+const EXAMPLE = `current_host: local
+hosts:
+  local:
+    factories:
+      factory-acme: ~/path/to/factory-acme
+  my-server:
+    ssh: my-server              # alias from ~/.ssh/config
+    factories:
+      factory-acme: /home/me/factories/factory-acme`;
+
+/**
+ * @typedef {object} HostConfig
+ * @property {string} [ssh] - ssh alias / destination; absent for `local`
+ * @property {string} [node] - absolute path to `node` on the host; its dir is
+ *   prepended to PATH so `pm2` resolves too
+ * @property {Object<string, string|FactoryEntry>} factories - factory name → path
+ *   on the host, or the long form
+ */
+
+/**
+ * @typedef {object} FactoryEntry
+ * @property {string} path
+ * @property {string[]} [keep] - `STATION/BIN` bins `workpieces clear` refuses
+ */
+
+/**
+ * Either form of a factory entry, as `{path, keep}`.
+ * @param {string|FactoryEntry} entry
+ * @returns {{path: string, keep: string[]}}
+ */
+export function factoryEntry(entry) {
+  return typeof entry === 'string' ? { path: entry, keep: [] } : { path: entry.path, keep: entry.keep ?? [] };
+}
+
+/**
+ * @typedef {object} Config
+ * @property {string|null} current_host
+ * @property {Object<string, HostConfig>} hosts
+ */
+
+/**
+ * Load and validate the config. Throws with an example when missing.
+ * @returns {Config}
+ */
+export function loadConfig() {
+  const file = configPath();
+  if (!existsSync(file)) {
+    throw new Error(`No config at ${file}. Create it, for example:\n\n${EXAMPLE}`);
+  }
+  const raw = yaml.load(readFileSync(file, 'utf8')) || {};
+  const cfg = { current_host: raw.current_host ?? null, hosts: raw.hosts ?? {} };
+
+  for (const [name, host] of Object.entries(cfg.hosts)) {
+    if (!host || typeof host !== 'object') throw new Error(`Host '${name}' in ${file} must be a mapping.`);
+    host.factories = host.factories ?? {};
+    if (name === LOCAL_HOST && host.ssh) {
+      throw new Error(`Host 'local' in ${file} is this machine and must not have an 'ssh' key.`);
+    }
+    if (name !== LOCAL_HOST) {
+      if (typeof host.ssh !== 'string' || !host.ssh) throw new Error(`Host '${name}' in ${file} needs an 'ssh' alias.`);
+      // A leading dash would be parsed by ssh as an option.
+      if (host.ssh.startsWith('-')) throw new Error(`Host '${name}' has an invalid ssh alias '${host.ssh}'.`);
+    }
+    for (const [w, entry] of Object.entries(host.factories)) {
+      const ok = typeof entry === 'string'
+        || (entry && typeof entry.path === 'string' && (entry.keep === undefined || (Array.isArray(entry.keep) && entry.keep.every((k) => /^[^/]+\/(done|output)$/.test(k)))));
+      if (!ok) throw new Error(`Factory '${w}' on host '${name}' in ${file} must be a path, or {path, keep: [STATION/done|output, ...]}.`);
+    }
+  }
+  return cfg;
+}
+
+/** @param {Config} cfg */
+export function saveConfig(cfg) {
+  mkdirSync(configDir(), { recursive: true });
+  writeFileSync(configPath(), yaml.dump(cfg), { mode: 0o600 });
+}
+
+/**
+ * @param {string} name
+ * @returns {Config}
+ */
+export function useHost(name) {
+  const cfg = loadConfig();
+  if (!cfg.hosts[name]) {
+    throw new Error(`No host named '${name}'. Configured: ${Object.keys(cfg.hosts).join(', ') || '(none)'}`);
+  }
+  cfg.current_host = name;
+  saveConfig(cfg);
+  return cfg;
+}
+
+/**
+ * @typedef {object} HostContext
+ * @property {string} name
+ * @property {boolean} is_local
+ * @property {string} [ssh]
+ * @property {string} [node]
+ * @property {Object<string, string>} factories - factory name → path on the host
+ * @property {Object<string, string[]>} keep - factory name → bins to never clear
+ */
+
+/**
+ * Resolve the target host: `--host` beats `current_host`.
+ * @param {{host?: string}} argv
+ * @returns {HostContext}
+ */
+export function resolveHost(argv) {
+  const cfg = loadConfig();
+  const name = argv.host || cfg.current_host;
+  if (!name) {
+    throw new Error(`No host selected. Run \`al-control hosts use <name>\` or pass --host. Configured: ${Object.keys(cfg.hosts).join(', ') || '(none)'}`);
+  }
+  const host = cfg.hosts[name];
+  if (!host) {
+    throw new Error(`No host named '${name}' in ${configPath()}. Configured: ${Object.keys(cfg.hosts).join(', ') || '(none)'}`);
+  }
+  const factories = {};
+  const keep = {};
+  for (const [w, entry] of Object.entries(host.factories)) ({ path: factories[w], keep: keep[w] } = factoryEntry(entry));
+  return { name, is_local: name === LOCAL_HOST, ssh: host.ssh, node: host.node, factories, keep };
+}
+
+/**
+ * @typedef {object} FactoryContext
+ * @property {HostContext} host
+ * @property {string} name
+ * @property {string} path - path on the host as configured (may start with `~`)
+ * @property {string[]} keep - bins `workpieces clear` refuses
+ * @property {string} flags - `-f <name>` (plus `--host` when overridden), for
+ *   "run this next" hints
+ */
+
+/**
+ * Whether a `-f` value is a path rather than a configured name. Names never hold a `/`.
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isPathTarget(value) {
+  return value === '.' || value === '..' || value.startsWith('~') || value.includes('/');
+}
+
+/** @param {string} p */
+function expandHome(p) {
+  return p === '~' || p.startsWith('~/') ? join(homedir(), p.slice(1)) : p;
+}
+
+/**
+ * `-f <path>`: a factory named by its folder. Without `--host` the path is on this machine
+ * (relative to the current directory) and needs no config; a configured local factory at the
+ * same path lends its name and `keep` bins. With `--host`, the path is on that host as written.
+ * Typing the path is the explicit target decision 0003 asks for; nothing falls back to the cwd.
+ * @param {{host?: string, factory: string}} argv
+ * @returns {FactoryContext}
+ */
+function resolvePathTarget(argv) {
+  if (argv.host) {
+    const host = resolveHost(argv);
+    const name = basename(argv.factory.replace(/\/+$/, '')) || argv.factory;
+    host.factories = { ...host.factories, [name]: argv.factory };
+    host.keep = { ...host.keep, [name]: host.keep[name] ?? [] };
+    return { ...factoryContext(host, name, argv.host), flags: `-f ${argv.factory} --host ${argv.host}` };
+  }
+  const abs = resolve(expandHome(argv.factory));
+  let name = basename(abs);
+  let keep = [];
+  if (existsSync(configPath())) {
+    const local = loadConfig().hosts[LOCAL_HOST];
+    for (const [n, entry] of Object.entries(local?.factories ?? {})) {
+      const e = factoryEntry(entry);
+      if (resolve(expandHome(e.path)) === abs) ({ name, keep } = { name: n, keep: e.keep });
+    }
+  }
+  /** @type {HostContext} */
+  const host = { name: LOCAL_HOST, is_local: true, factories: { [name]: abs }, keep: { [name]: keep } };
+  return { host, name, path: abs, keep, flags: `-f ${argv.factory}` };
+}
+
+/**
+ * Resolve host + the `-f` factory on it: a configured name, or a path (`-f .`). `-f` is always
+ * required — the current directory is never consulted on its own.
+ * @param {{host?: string, factory?: string}} argv
+ * @returns {FactoryContext}
+ */
+export function resolveFactory(argv) {
+  if (argv.factory && isPathTarget(argv.factory)) return resolvePathTarget({ ...argv, factory: argv.factory });
+  const host = resolveHost(argv);
+  const names = Object.keys(host.factories);
+  if (!argv.factory) {
+    throw new Error(`Specify a factory with -f <name>, or -f . for the one you're in. Factories on ${host.name}: ${names.join(', ') || '(none)'}`);
+  }
+  const p = host.factories[argv.factory];
+  if (!p) {
+    throw new Error(`No factory '${argv.factory}' on host ${host.name}. Factories on ${host.name}: ${names.join(', ') || '(none)'}`);
+  }
+  return factoryContext(host, argv.factory, argv.host);
+}
+
+/**
+ * Every factory on the host when no `-f` is given, else just that one — for
+ * commands whose scope is "the host" but that can narrow to a factory.
+ * @param {{host?: string, factory?: string}} argv
+ * @returns {{host: HostContext, factories: FactoryContext[]}}
+ */
+export function resolveFactories(argv) {
+  if (argv.factory) {
+    const factory = resolveFactory(argv);
+    return { host: factory.host, factories: [factory] };
+  }
+  const host = resolveHost(argv);
+  return { host, factories: Object.keys(host.factories).map((name) => factoryContext(host, name, argv.host)) };
+}
+
+function factoryContext(host, name, host_flag) {
+  const flags = `-f ${name}${host_flag ? ` --host ${host_flag}` : ''}`;
+  return { host, name, path: host.factories[name], keep: host.keep[name], flags };
+}