@assemblyline/al-control 0.0.0-stage → 0.3.0

package/src/cli/procs/list.js

@@ -0,0 +1,25 @@
+import { probeProcesses } from '../../transport.js';
+import { formatTable } from '../../utils/format.js';
+
+/**
+ * `al-control procs list` — every factory process on the host, configured
+ * or not, pm2-managed or run directly.
+ * @param {{json?: boolean}} argv
+ * @param {import('../../config.js').HostContext} host
+ */
+export async function listProcsHandler(argv, host) {
+  const { procs } = probeProcesses(host, { type: 'procs' });
+
+  if (argv.json) {
+    console.log(JSON.stringify(procs, null, 2));
+    return;
+  }
+  if (procs.length === 0) {
+    console.log(`No running factories on ${host.name}.`);
+    return;
+  }
+  console.log(formatTable(
+    ['PID', 'FACTORY', 'MODE', 'PM2', 'PORT', 'UPTIME', 'STARTED'],
+    procs.map((r) => [r.pid, r.factory, r.mode, r.pm2, r.port, r.uptime, r.started]),
+  ));
+}

package/src/cli/stations/status.js

@@ -0,0 +1,79 @@
+import { formatHeader } from '../../utils/format.js';
+import { LIVE_BINS } from '../../utils/line-state.js';
+import { loadLines } from '../../utils/factory-data.js';
+import { watchRender, DEFAULT_WATCH_INTERVAL_SECS } from '../../utils/watch-render.js';
+
+/**
+ * `al-control stations status <code> -f <factory>` — one station's bins and
+ * the workpieces in each.
+ *
+ * `--watch [--interval=N]` re-renders in place; exclusive with `--json`.
+ *
+ * @param {{id: string, json?: boolean, watch?: boolean, interval?: number}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function statusStationHandler(argv, factory) {
+  const { id, json, watch, interval } = argv;
+  if (watch && json) {
+    console.error('--watch and --json are mutually exclusive (watch is a TTY redraw; json is a one-shot snapshot).');
+    process.exit(1);
+  }
+  const interval_secs = typeof interval === 'number' ? interval : DEFAULT_WATCH_INTERVAL_SECS;
+
+  const renderOnce = () => {
+    const { lines } = loadLines(factory);
+    const station_line = Object.values(lines).find((ls) => ls.stations.includes(id));
+    if (!station_line) {
+      // In watch mode the station may appear later, so surface and retry.
+      if (watch) {
+        console.log(`No station "${id}" on ${factory.name}.`);
+        return;
+      }
+      console.error(`No station "${id}" on ${factory.name}.`);
+      console.error(`Pass the station short_code (e.g. VM3). Run \`al-control lines status ${factory.flags}\` to see active lines.`);
+      process.exit(1);
+    }
+
+    const bins = station_line.bins[id];
+    const is_terminal = id === station_line.terminal;
+
+    if (json) {
+      const out = { station: id, line: station_line.code, terminal: is_terminal, bins: {} };
+      for (const bin of [...LIVE_BINS, 'done']) {
+        const map = bins[bin];
+        out.bins[bin] = map ? [...map.keys()].sort() : null;
+      }
+      console.log(JSON.stringify(out, null, 2));
+      return;
+    }
+
+    console.log(formatHeader('Station', id));
+    console.log(`Line:     ${station_line.code}${is_terminal ? '  (terminal)' : ''}`);
+    console.log('');
+
+    for (const bin of [...LIVE_BINS, 'done']) {
+      const map = bins[bin];
+      const label = bin === 'done' ? '(done)' : bin;
+      if (map === null) {
+        console.log(`${label.padEnd(8)} —`);
+        continue;
+      }
+      const sorted = [...map.keys()].sort();
+      console.log(`${label.padEnd(8)} (${sorted.length})`);
+      // Show the sub-bin when a workpiece lives under one (invoices/hi-1__...).
+      for (const wp_id of sorted) {
+        const sub = map.get(wp_id);
+        const display = sub && sub !== wp_id ? `${wp_id}  (in ${sub.slice(0, sub.lastIndexOf('/'))}/)` : wp_id;
+        console.log(`         ${display}`);
+      }
+      if (sorted.length === 0) console.log('         —');
+      console.log('');
+    }
+  };
+
+  if (watch) {
+    await watchRender({ render: renderOnce, interval_secs });
+    return;
+  }
+  renderOnce();
+}

package/src/cli/workpieces/_resolve.js

@@ -0,0 +1,25 @@
+import { resolveWorkpieceQuery, workpieceRelDir } from '../../utils/line-state.js';
+import { loadLines } from '../../utils/factory-data.js';
+
+/**
+ * The one workpiece an id (or unambiguous substring) names, for commands that
+ * act on a single folder. Exits with the candidates when it's ambiguous.
+ * @param {import('../../config.js').FactoryContext} factory
+ * @param {string} query
+ * @returns {{id: string, root: string, rel: string}}
+ */
+export function resolveOneWorkpiece(factory, query) {
+  const { root, lines } = loadLines(factory);
+  const found = resolveWorkpieceQuery(query, lines);
+  if (!found) {
+    console.error(`No workpiece matches "${query}".`);
+    process.exit(1);
+  }
+  if ('ambiguous' in found) {
+    const shown = found.ambiguous.slice(0, 10);
+    const more = found.ambiguous.length - shown.length;
+    console.error(`"${query}" matches ${found.ambiguous.length} workpieces; use the full id:\n  ${shown.join('\n  ')}${more ? `\n  … +${more} more` : ''}`);
+    process.exit(1);
+  }
+  return { id: found.id, root, rel: workpieceRelDir(found.pos, found.id) };
+}

package/src/cli/workpieces/cat.js

@@ -0,0 +1,20 @@
+import { probe } from '../../transport.js';
+import { resolveOneWorkpiece } from './_resolve.js';
+
+/**
+ * `al-control workpieces cat <id> <file> -f <factory>` — one file from the
+ * workpiece folder to stdout, byte-for-byte (so `> invoice.pdf` works).
+ * Binary output to a terminal is refused.
+ *
+ * @param {{id: string, file: string}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function catHandler(argv, factory) {
+  const { rel } = resolveOneWorkpiece(factory, argv.id);
+  const { encoding, content } = probe(factory.host, { type: 'read', path: factory.path, dir: rel, file: argv.file });
+  if (encoding === 'base64' && process.stdout.isTTY) {
+    console.error(`${argv.file} is binary. Redirect it to a file: … > ${argv.file.split('/').pop()}`);
+    process.exit(1);
+  }
+  process.stdout.write(Buffer.from(content, encoding));
+}

package/src/cli/workpieces/clear.js

@@ -0,0 +1,121 @@
+import { probe } from '../../transport.js';
+import { formatTable } from '../../utils/format.js';
+import { loadAges, loadLines } from '../../utils/factory-data.js';
+import { drainedBins } from '../../utils/conveyors.js';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * `al-control workpieces clear [id] --bin done|finished -f <factory> [--line]
+ * [--station] [--older-than <days>] [--yes]` — delete workpieces from `done`
+ * bins, or from the output of each line's terminal station (`finished`).
+ * With `id` instead of `--bin`: every done or finished copy of that one
+ * workpiece. `--older-than` keeps anything active (folder or log.jsonl
+ * modified) within that many days. Prints what it would delete and stops
+ * unless `--yes`. Skipped: bins in the factory's config `keep` list, and bins
+ * a conveyor (`move_files`) still drains — a terminal output can feed another
+ * line. The probe re-checks every folder before deleting (see
+ * docs/decisions/0005).
+ *
+ * @param {{id?: string, bin?: 'done'|'finished', line?: string, station?: string, olderThan?: number, yes?: boolean}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function clearHandler(argv, factory) {
+  const { lines, stations } = loadLines(factory);
+
+  if (argv.line && !lines[argv.line]) fail(`Line "${argv.line}" not found. Available: ${Object.keys(lines).sort().join(', ') || '(none)'}`);
+  if (argv.station) {
+    const line = Object.values(lines).find((l) => l.stations.includes(argv.station));
+    if (!line) fail(`Station "${argv.station}" not found.`);
+    if (argv.bin === 'finished' && line.terminal !== argv.station) {
+      fail(`${argv.station} isn't the terminal station of line ${line.code} (${line.terminal} is); only terminal output counts as finished.`);
+    }
+  }
+
+  // STATION/BIN → where a conveyor moves it; source_bin may name a sub-bin.
+  const drained_by = drainedBins(stations.map((s) => s.data));
+
+  // Every clearable bin in scope: done anywhere, output of a terminal station.
+  const groups = [];
+  for (const line of Object.values(lines)) {
+    if (argv.line && line.code !== argv.line) continue;
+    for (const station of line.stations) {
+      if (argv.station && station !== argv.station) continue;
+      const bins = [];
+      if (argv.bin !== 'finished') bins.push('done');
+      if (argv.bin !== 'done' && station === line.terminal) bins.push('output');
+      for (const bin of bins) {
+        const map = line.bins[station][bin];
+        if (!map || map.size === 0) continue;
+        const spec = `${station}/${bin}`;
+        let skip = null;
+        if (factory.keep.includes(spec)) skip = 'kept (config keep list)';
+        else if (drained_by.has(spec)) skip = `skipped: conveyor moves it to ${drained_by.get(spec)}`;
+        groups.push({ line: line.code, spec, skip, entries: [...map].map(([id, sub]) => ({ id, rel: `${spec}/${sub}` })) });
+      }
+    }
+  }
+
+  let what = `${argv.bin} bins`;
+  if (argv.id) {
+    const ids = new Set(groups.flatMap((g) => g.entries.map((e) => e.id)));
+    const matches = ids.has(argv.id) ? [argv.id] : [...ids].filter((id) => id.includes(argv.id)).sort();
+    if (matches.length === 0) fail(`No done or finished workpiece matches "${argv.id}" on ${factory.name}. Only done bins and terminal outputs can be cleared.`);
+    if (matches.length > 1) {
+      const shown = matches.slice(0, 10);
+      fail(`"${argv.id}" matches ${matches.length} workpieces; use the full id:\n  ${shown.join('\n  ')}${matches.length > 10 ? `\n  … +${matches.length - 10} more` : ''}`);
+    }
+    for (const g of groups) g.entries = g.entries.filter((e) => e.id === matches[0]);
+    what = `done or finished copies of ${matches[0]}`;
+  }
+
+  if (argv.olderThan !== undefined) {
+    const ages = loadAges(factory, groups.filter((g) => !g.skip).flatMap((g) => g.entries.map((e) => e.rel)));
+    const cutoff = Date.now() - argv.olderThan * DAY_MS;
+    for (const g of groups) {
+      if (g.skip) continue;
+      const before = g.entries.length;
+      g.entries = g.entries.filter((e) => ages[e.rel] !== null && ages[e.rel] < cutoff);
+      g.newer = before - g.entries.length;
+    }
+    what += ` older than ${argv.olderThan} day${argv.olderThan === 1 ? '' : 's'}`;
+  }
+
+  const shown = groups.filter((g) => g.entries.length > 0 || g.newer);
+  if (shown.length === 0) {
+    console.log(`Nothing to clear: no ${what} on ${factory.name}.`);
+    return;
+  }
+
+  const has_age = argv.olderThan !== undefined;
+  console.log(formatTable(
+    ['LINE', 'BIN', 'WORKPIECES', ...(has_age ? ['NEWER (KEPT)'] : []), 'NOTE'],
+    shown.map((g) => [
+      g.line,
+      g.spec,
+      String(g.entries.length),
+      ...(has_age ? [g.skip ? '' : String(g.newer ?? 0)] : []),
+      g.skip ?? '',
+    ]),
+  ));
+  console.log('');
+
+  const to_delete = shown.filter((g) => !g.skip).flatMap((g) => g.entries.map((e) => e.rel));
+  if (to_delete.length === 0) {
+    console.log(`Nothing to delete: every matching bin is skipped${has_age ? ' or too recent' : ''}.`);
+    return;
+  }
+  const where = `${factory.host.name} / ${factory.name}`;
+  if (!argv.yes) {
+    console.log(`Dry run: would delete ${to_delete.length} workpiece${to_delete.length === 1 ? '' : 's'} on ${where}. Re-run with --yes to delete.`);
+    return;
+  }
+
+  const { removed } = probe(factory.host, { type: 'remove', path: factory.path, dirs: to_delete, keep: factory.keep });
+  console.log(`Deleted ${removed.length} workpiece${removed.length === 1 ? '' : 's'} on ${where}.`);
+}
+
+function fail(msg) {
+  console.error(msg);
+  process.exit(1);
+}

package/src/cli/workpieces/count.js

@@ -0,0 +1,73 @@
+import { formatTable } from '../../utils/format.js';
+import { loadLinesEach } from '../../utils/factory-data.js';
+
+const LEVELS = ['factory', 'line', 'station'];
+
+const BINS = ['failed', 'done', 'finished'];
+
+/**
+ * `al-control workpieces count [failed|done|finished] [-f <factory>]
+ * [--by factory|line|station]` — FAILED / DONE / FINISHED per station, rolled
+ * up to the `--by` level; naming a bin shows only that count. Every factory on
+ * the host unless `-f` narrows it. FINISHED is the output bin of a line's
+ * terminal station. Rows that are zero in every shown count are hidden.
+ * FAILED includes orphaned failed folders (no pointer.json), noted below the
+ * table since nothing else can see them.
+ *
+ * @param {{bin?: string, by?: string, json?: boolean}} argv
+ * @param {{host: import('../../config.js').HostContext, factories: import('../../config.js').FactoryContext[]}} scope
+ */
+export async function countWorkpiecesHandler(argv, { factories }) {
+  const by = argv.by ?? 'station';
+  const keys = LEVELS.slice(0, LEVELS.indexOf(by) + 1);
+
+  const rows = new Map();
+  let orphan_total = 0;
+  for (const { factory, lines, orphans } of loadLinesEach(factories)) {
+    for (const line of Object.values(lines)) {
+      for (const station of line.stations) {
+        const bins = line.bins[station];
+        const at = { factory: factory.name, line: line.code, station };
+        const id = keys.map((k) => at[k]).join('\0');
+        if (!rows.has(id)) rows.set(id, { ...Object.fromEntries(keys.map((k) => [k, at[k]])), failed: 0, done: 0, finished: 0 });
+        const row = rows.get(id);
+        const orphan_count = Object.keys(orphans[station] ?? {}).length;
+        orphan_total += orphan_count;
+        row.failed += (bins.failed?.size ?? 0) + orphan_count;
+        row.done += bins.done?.size ?? 0;
+        if (station === line.terminal) row.finished += bins.output?.size ?? 0;
+      }
+    }
+  }
+
+  const bins = argv.bin ? [argv.bin] : BINS;
+  const nonzero = [...rows.values()]
+    .filter((r) => bins.some((b) => r[b]))
+    .map((r) => ({ ...Object.fromEntries(keys.map((k) => [k, r[k]])), ...Object.fromEntries(bins.map((b) => [b, r[b]])) }));
+
+  if (argv.json) {
+    console.log(JSON.stringify({ by, rows: nonzero, orphaned: orphan_total }, null, 2));
+    return;
+  }
+
+  if (nonzero.length === 0) {
+    console.log(`No ${bins.join(', ')} workpieces.`);
+    return;
+  }
+
+  const n = (v) => (v ? String(v) : '—');
+  const blank = keys.map(() => '');
+  blank[0] = 'TOTAL';
+  console.log(formatTable(
+    [...keys.map((k) => k.toUpperCase()), ...bins.map((b) => b.toUpperCase())],
+    [
+      ...nonzero.map((r) => [...keys.map((k) => r[k]), ...bins.map((b) => n(r[b]))]),
+      [...blank, ...bins.map((b) => n(nonzero.reduce((t, r) => t + r[b], 0)))],
+    ],
+  ));
+  if (bins.includes('finished')) console.log('\nFINISHED = output of a line\'s terminal station.');
+  if (bins.includes('failed') && orphan_total > 0) {
+    console.log(`${bins.includes('finished') ? '' : '\n'}FAILED includes ${orphan_total} orphaned folder${orphan_total === 1 ? '' : 's'} (no pointer.json); \`workpieces errors\` lists them.`);
+  }
+  if (bins.includes('failed')) console.log(`${bins.includes('finished') || orphan_total > 0 ? '' : '\n'}Why things failed: \`al-control workpieces errors\`.`);
+}

package/src/cli/workpieces/errors.js

@@ -0,0 +1,79 @@
+import { errorKey } from '../../utils/failures.js';
+import { formatTable, formatDate, localTzLabel } from '../../utils/format.js';
+import { loadLinesEach, loadErrors } from '../../utils/factory-data.js';
+
+const MAX_EXAMPLES = 2;
+const ERROR_COL = 80;
+
+/**
+ * `al-control workpieces errors [-f <factory>] [--line] [--station]` — failed
+ * workpieces grouped by error (see utils/failures.js), most common first.
+ * Every factory on the host unless `-f` narrows it. One probe call per factory.
+ * Orphaned failed folders (no pointer.json) are included and flagged.
+ *
+ * @param {{line?: string, station?: string, json?: boolean}} argv
+ * @param {{host: import('../../config.js').HostContext, factories: import('../../config.js').FactoryContext[]}} scope
+ */
+export async function errorsHandler(argv, { factories }) {
+  const host_wide = factories.length > 1;
+  const groups = new Map();
+
+  let orphan_total = 0;
+  for (const { factory, lines, orphans } of loadLinesEach(factories)) {
+    const failed = [];
+    for (const line of Object.values(lines)) {
+      if (argv.line && line.code !== argv.line) continue;
+      for (const station of line.stations) {
+        if (argv.station && station !== argv.station) continue;
+        for (const [id, sub] of line.bins[station].failed ?? []) failed.push({ id, station, rel: `${station}/failed/${sub}`, orphan: false });
+        for (const [id, sub] of Object.entries(orphans[station] ?? {})) failed.push({ id, station, rel: `${station}/failed/${sub}`, orphan: true });
+      }
+    }
+    const errors = loadErrors(factory, failed.map((f) => f.rel));
+    for (const f of failed) {
+      const err = errors[f.rel];
+      const key = errorKey(err);
+      if (!groups.has(key)) groups.set(key, { key, count: 0, where: {}, workpieces: [], last_failed_at: null });
+      const g = groups.get(key);
+      const where = host_wide ? `${factory.name}/${f.station}` : f.station;
+      g.count += 1;
+      g.where[where] = (g.where[where] ?? 0) + 1;
+      g.workpieces.push({ factory: factory.name, id: f.id, station: f.station, failed_at: err?.failed_at ?? null, message: err?.message ?? null, orphan: f.orphan });
+      if (f.orphan) { g.orphans = (g.orphans ?? 0) + 1; orphan_total += 1; }
+      if (err?.failed_at && (!g.last_failed_at || err.failed_at > g.last_failed_at)) g.last_failed_at = err.failed_at;
+    }
+  }
+
+  const sorted = [...groups.values()].sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
+
+  if (argv.json) {
+    console.log(JSON.stringify({ groups: sorted }, null, 2));
+    return;
+  }
+
+  if (sorted.length === 0) {
+    console.log('No failed workpieces.');
+    return;
+  }
+
+  const total = sorted.reduce((n, g) => n + g.count, 0);
+  console.log(`${total} failed workpiece${total === 1 ? '' : 's'}, ${sorted.length} distinct error${sorted.length === 1 ? '' : 's'}\n`);
+  console.log(formatTable(
+    ['COUNT', 'ERROR', 'WHERE', `LAST FAILED (${localTzLabel()})`, 'EXAMPLES'],
+    sorted.map((g) => [
+      g.orphans ? `${g.count} (${g.orphans} orphaned)` : String(g.count),
+      g.key.length > ERROR_COL ? `${g.key.slice(0, ERROR_COL - 1)}…` : g.key,
+      Object.keys(g.where).length === 1
+        ? Object.keys(g.where)[0]
+        : Object.entries(g.where).map(([w, n]) => `${w} ×${n}`).join(', '),
+      g.last_failed_at ? formatDate(g.last_failed_at) : '—',
+      g.workpieces.slice(0, MAX_EXAMPLES).map((w) => w.id).join(', ') + (g.count > MAX_EXAMPLES ? ` +${g.count - MAX_EXAMPLES}` : ''),
+    ]),
+  ));
+  if (orphan_total > 0) {
+    console.log(`\n${orphan_total} orphaned: failed folder${orphan_total === 1 ? '' : 's'} with no pointer.json. \`show\` and \`clear\` can't see them; inspect or remove them on the host (--json has their stations).`);
+  }
+  const ex = sorted.flatMap((g) => g.workpieces).find((w) => !w.orphan) ?? sorted[0].workpieces[0];
+  const flags = factories.find((w) => w.name === ex.factory).flags;
+  console.log(`\nDetails: \`al-control workpieces show ${ex.id} ${flags}\`. Every id per group: --json.`);
+}

package/src/cli/workpieces/list.js

@@ -0,0 +1,140 @@
+import { formatTable, formatSection, formatTime, formatElapsed, localTzLabel } from '../../utils/format.js';
+import {
+  resolvePosition,
+  findWorkpieceMatches,
+  collectIdsForBin,
+  idsOnLine,
+  workpieceRelDir,
+} from '../../utils/line-state.js';
+import { loadLines, loadLogs, workpieceLocation } from '../../utils/factory-data.js';
+
+/**
+ * `al-control workpieces list -f <factory> [--line] [--bin] [--match]` —
+ * dashboard of workpieces on disk: position, last event, folder.
+ *
+ * Scope flags are optional and layer when combined:
+ *   --line VM            all workpieces on the VM line
+ *   --bin STATION/BIN    one bin, e.g. VM3/failed
+ *   --match <substring>  workpiece-id substring
+ *
+ * @param {{line?: string, bin?: string, match?: string, json?: boolean}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function listWorkpiecesHandler(argv, factory) {
+  const { line: line_arg, bin: bin_arg, match: match_arg, json } = argv;
+  const { root, lines } = loadLines(factory);
+
+  if (Object.keys(lines).length === 0) {
+    if (json) {
+      console.log(JSON.stringify({ header: 'Workpieces', workpieces: [] }, null, 2));
+      return;
+    }
+    console.log(`No lines in ${factory.name}/.orchestrator/stations/. Run "al-orc stations pull --all" in the factory repo.`);
+    return;
+  }
+
+  let ids;
+  let header = 'Workpieces';
+  if (bin_arg) {
+    const result = collectIdsForBin(bin_arg, lines);
+    if (!result.ok) {
+      console.error(result.error);
+      process.exit(1);
+    }
+    ids = result.ids;
+    header = `Workpieces in ${bin_arg}`;
+  } else if (match_arg) {
+    ids = [...findWorkpieceMatches(match_arg, lines).keys()];
+    header = `Workpieces matching "${match_arg}"`;
+  } else if (line_arg) {
+    ids = idsOnLine(requireLine(lines, line_arg));
+    header = `Workpieces on line ${line_arg}`;
+  } else {
+    ids = [...new Set(Object.values(lines).flatMap(idsOnLine))];
+  }
+
+  // --line narrows --bin / --match further.
+  if (line_arg && (bin_arg || match_arg)) {
+    const line_ids = new Set(idsOnLine(requireLine(lines, line_arg)));
+    ids = ids.filter((id) => line_ids.has(id));
+  }
+
+  ids.sort((a, b) => a.localeCompare(b));
+
+  const positioned = ids.map((id) => {
+    const pos = resolvePosition(id, lines);
+    return { id, pos, rel: pos ? workpieceRelDir(pos, id) : null };
+  });
+  const logs = loadLogs(factory, positioned.filter((p) => p.pos).map((p) => p.rel));
+
+  const rows = positioned.map(({ id, pos, rel }) => {
+    if (!pos) return { id, position: '(not on disk)', last_event: '—', folder: '—' };
+    return {
+      id,
+      position: positionShort(pos),
+      last_event: formatLastEventCompact(logs[rel] || []),
+      folder: workpieceLocation(factory, root, rel),
+    };
+  });
+
+  if (json) {
+    console.log(JSON.stringify({ header, workpieces: rows }, null, 2));
+    return;
+  }
+
+  if (rows.length === 0) {
+    console.log(`${header}: 0 workpieces.`);
+    return;
+  }
+
+  console.log(`${header} — ${rows.length} workpiece${rows.length === 1 ? '' : 's'}`);
+  console.log('');
+  console.log(formatTable(
+    ['WORKPIECE', 'POSITION', `LAST EVENT (${localTzLabel()})`],
+    rows.map((r) => [r.id, r.position, r.last_event]),
+  ));
+
+  console.log(formatSection('Folders'));
+  const id_w = Math.max(...rows.map((r) => r.id.length));
+  for (const r of rows) console.log(`  ${r.id.padEnd(id_w)}  ${r.folder}`);
+}
+
+function requireLine(lines, code) {
+  const ls = lines[code];
+  if (!ls) {
+    console.error(`Line "${code}" not found. Available: ${Object.keys(lines).sort().join(', ') || '(none)'}`);
+    process.exit(1);
+  }
+  return ls;
+}
+
+function positionShort(pos) {
+  // Show the sub-bin segment when the workpiece lives under one
+  // (HI3/output/invoices); the id itself is already the WORKPIECE column.
+  const sub = pos.subpath && pos.subpath.includes('/')
+    ? '/' + pos.subpath.slice(0, pos.subpath.lastIndexOf('/'))
+    : '';
+  if (pos.anomaly) return `${pos.station}/done${sub} (anomaly)`;
+  let suffix = '';
+  if (pos.bin === 'failed') suffix = ' (stuck)';
+  else if (pos.bin === 'output' && pos.terminal) suffix = ' (finished)';
+  else if (pos.bin === 'doing') suffix = ' (active)';
+  return `${pos.station}/${pos.bin}${sub}${suffix}`;
+}
+
+function formatLastEventCompact(events) {
+  if (events.length === 0) return '—';
+  const e = events[events.length - 1];
+  const ts = formatTime(e.ts).slice(0, 5); // HH:MM, local
+  let extra = '';
+  if (e.event === 'station_complete' || e.event === 'station_failed') {
+    for (let i = events.length - 2; i >= 0; i--) {
+      if (events[i].station === e.station && events[i].event === 'station_started') {
+        const ms = new Date(e.ts).getTime() - new Date(events[i].ts).getTime();
+        if (!Number.isNaN(ms) && ms >= 0) extra = ` (${formatElapsed(ms)})`;
+        break;
+      }
+    }
+  }
+  return `${ts}  ${e.station}  ${e.event}${extra}`;
+}

package/src/cli/workpieces/open.js

@@ -0,0 +1,25 @@
+import { spawnSync } from 'node:child_process';
+
+import { shell } from '../../transport.js';
+import { workpiecePath } from '../../utils/factory-data.js';
+import { resolveOneWorkpiece } from './_resolve.js';
+
+/**
+ * `al-control workpieces open <id> -f <factory>` — local: the folder in
+ * Finder (xdg-open on Linux). Remote: an interactive shell on the host,
+ * started in the folder; exit it to come back.
+ *
+ * @param {{id: string}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function openHandler(argv, factory) {
+  const { root, rel } = resolveOneWorkpiece(factory, argv.id);
+  const dir = workpiecePath(root, rel);
+  if (factory.host.is_local) {
+    const res = spawnSync(process.platform === 'darwin' ? 'open' : 'xdg-open', [dir], { stdio: 'inherit' });
+    if (res.error || res.status !== 0) console.log(dir);
+    return;
+  }
+  console.error(`Shell in ${dir} on ${factory.host.name} — exit to return.`);
+  shell(factory.host, dir);
+}