@assemblyline/al-control 0.0.0-stage → 0.1.0

package/src/cli/index.js

@@ -0,0 +1,273 @@
+/**
+ * CLI entry point.
+ *
+ * Pattern: al-control <resource> <action> [target] [-f <factory>] [--host <host>]
+ *
+ * One host at a time (`hosts use`, or `--host` per command). Commands about a
+ * single factory require `-f`; the current directory is never consulted.
+ */
+
+import { readFileSync } from 'node:fs';
+import yargs from 'yargs';
+
+import { resolveHost, resolveFactory, resolveFactories } from '../config.js';
+import { localOptions } from './_helpers.js';
+
+import { listHostsHandler, useHostHandler, currentHostHandler, showConfigHandler } from './hosts.js';
+import { listFactoriesHandler } from './factories/list.js';
+import { listLinesHandler } from './lines/list.js';
+import { showLineHandler } from './lines/show.js';
+import { statusLineHandler } from './lines/status.js';
+import { statusStationHandler } from './stations/status.js';
+import { listWorkpiecesHandler } from './workpieces/list.js';
+import { showWorkpieceHandler } from './workpieces/show.js';
+import { watchHandler } from './workpieces/watch.js';
+import { countWorkpiecesHandler } from './workpieces/count.js';
+import { errorsHandler } from './workpieces/errors.js';
+import { catHandler } from './workpieces/cat.js';
+import { openHandler } from './workpieces/open.js';
+import { clearHandler } from './workpieces/clear.js';
+import { listProcsHandler } from './procs/list.js';
+import {
+  startFactoryHandler,
+  stopFactoryHandler,
+  restartFactoryHandler,
+  logsFactoryHandler,
+  monitHandler,
+} from './procs/actions.js';
+
+const { version } = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+
+/**
+ * On a non-local host, say where the command is about to act — on stderr so
+ * `--json` stays parseable. Guards against operating on prod by accident.
+ */
+function banner(host, factory_name) {
+  if (!host.is_local) console.error(`→ ${host.name}${factory_name ? ` / ${factory_name}` : ''}`);
+}
+
+/**
+ * Wrap a handler that needs a `-f` factory: resolve it, print the banner,
+ * optionally frame human output with separator lines.
+ */
+function withFactory(handler, { frame = true } = {}) {
+  return async (argv) => {
+    if (argv.getYargsCompletions) return;
+    const factory = resolveFactory(argv);
+    banner(factory.host, factory.name);
+    if (!frame || argv.json) return handler(argv, factory);
+    console.log('='.repeat(60));
+    await handler(argv, factory);
+    console.log('='.repeat(60));
+  };
+}
+
+/** Wrap a host-level handler (no `-f`). */
+function withHost(handler) {
+  return async (argv) => {
+    if (argv.getYargsCompletions) return;
+    const host = resolveHost(argv);
+    banner(host);
+    return handler(argv, host);
+  };
+}
+
+/**
+ * Wrap a handler whose scope is every factory on the host, or just the `-f`
+ * one when given.
+ */
+function withFactories(handler) {
+  return async (argv) => {
+    if (argv.getYargsCompletions) return;
+    const scope = resolveFactories(argv);
+    banner(scope.host, argv.factory);
+    return handler(argv, scope);
+  };
+}
+
+function optionalFactoryOption(yargs) {
+  return localOptions(yargs).option('factory', {
+    alias: 'f',
+    describe: 'Only this factory (default: every factory on the host)',
+    type: 'string',
+  });
+}
+
+function factoryOption(yargs) {
+  return localOptions(yargs).option('factory', {
+    alias: 'f',
+    describe: 'Factory name on the current host (required)',
+    type: 'string',
+  });
+}
+
+const jsonOption = { describe: 'Output raw JSON', type: 'boolean' };
+const watchOptions = (yargs) => yargs
+  .option('watch', { describe: 'Re-render on an interval. Mutually exclusive with --json.', type: 'boolean' })
+  .option('interval', { describe: 'Watch refresh interval in seconds (default 1)', type: 'number' });
+const scopeOptions = (yargs) => yargs
+  .option('line', { describe: 'Scope to a single line (e.g. VM)', type: 'string' })
+  .option('bin', { describe: 'Scope to a specific bin (STATION/BIN, e.g. VM3/failed)', type: 'string' })
+  .option('match', { describe: 'Substring filter on workpiece id', type: 'string' });
+
+/**
+ * Build and run CLI
+ * @param {string[]} args
+ */
+export function run(args) {
+  const cli = yargs(args)
+    .scriptName('al-control')
+    .usage('$0 <resource> <action> [options]')
+    .option('host', { describe: 'Target host for this command (overrides current_host)', type: 'string', global: true })
+    .command('hosts', 'Configured hosts; pick the one commands target', (yargs) => yargs
+      .usage('$0 hosts <action>')
+      .command('list', 'List configured hosts', (y) => localOptions(y).option('json', jsonOption), listHostsHandler)
+      .command('use <name>', 'Set the current host', (y) => y.positional('name', { describe: 'Host name from the config', type: 'string' }), useHostHandler)
+      .command('current', 'Print the current host', {}, currentHostHandler)
+      .demandCommand(1, 'Specify an action: list, use, current'))
+    .command('factories', 'Factories configured on the current host', (yargs) => yargs
+      .usage('$0 factories <action>')
+      .command('list', 'Configured factories and whether each is running', (y) => localOptions(y).option('json', jsonOption), withHost(listFactoriesHandler))
+      .demandCommand(1, 'Specify an action: list'))
+    .command('lines', 'Inspect a factory\'s assembly lines', (yargs) => yargs
+      .usage('$0 lines <action> -f <factory> [options]')
+      .command('list', 'Lines and their stations (definitional)', (y) => factoryOption(y).option('json', jsonOption), withFactory(listLinesHandler))
+      .command(
+        'show <line>',
+        'Stations in dependency order + conveyor topology (definitional)',
+        (y) => factoryOption(y.positional('line', { describe: 'Line code (e.g. VM)', type: 'string' })).option('json', jsonOption),
+        withFactory(showLineHandler),
+      )
+      .command(
+        'status [line]',
+        'Live bin counts. No line = per-line summary.',
+        (y) => watchOptions(factoryOption(y.positional('line', { describe: 'Line code to drill into', type: 'string' })).option('json', jsonOption)),
+        withFactory(statusLineHandler),
+      )
+      .demandCommand(1, 'Specify an action: list, show, status'))
+    .command('stations', 'Inspect a factory\'s station bins', (yargs) => yargs
+      .usage('$0 stations <action> -f <factory> [options]')
+      .command(
+        'status <id>',
+        'One station\'s bins and the workpieces in them',
+        (y) => watchOptions(factoryOption(y.positional('id', { describe: 'Station short_code (e.g. VM3)', type: 'string' })).option('json', jsonOption)),
+        withFactory(statusStationHandler),
+      )
+      .demandCommand(1, 'Specify an action: status'))
+    .command('workpieces', 'Inspect a factory\'s workpieces', (yargs) => yargs
+      .usage('$0 workpieces <action> -f <factory> [options]')
+      .command('list', 'Workpieces on disk: position, last event, folder', (y) => scopeOptions(factoryOption(y)).option('json', jsonOption), withFactory(listWorkpiecesHandler))
+      .command(
+        'show <id>',
+        'One workpiece and its journey (a substring matching several shows the list)',
+        (y) => factoryOption(y.positional('id', { describe: 'Workpiece id (exact or substring)', type: 'string' })).option('json', jsonOption),
+        withFactory(showWorkpieceHandler),
+      )
+      .command(
+        'watch [id]',
+        'Live tail: bin moves and new log events',
+        (y) => scopeOptions(factoryOption(y.positional('id', { describe: 'Workpiece id (exact or substring)', type: 'string' })))
+          .option('interval', { describe: 'Poll interval in seconds (default 2)', type: 'number' }),
+        withFactory(watchHandler, { frame: false }),
+      )
+      .command(
+        'count [bin]',
+        'FAILED / DONE / FINISHED counts per factory, line or station (all factories unless -f)',
+        (y) => optionalFactoryOption(y.positional('bin', { describe: 'Only this count', choices: ['failed', 'done', 'finished'] }))
+          .option('by', { describe: 'Roll up to this level', choices: ['factory', 'line', 'station'], default: 'station' })
+          .option('json', jsonOption),
+        withFactories(countWorkpiecesHandler),
+      )
+      .command(
+        'errors',
+        'Failed workpieces grouped by error, most common first (all factories unless -f)',
+        (y) => optionalFactoryOption(y)
+          .option('line', { describe: 'Only this line', type: 'string' })
+          .option('station', { describe: 'Only this station', type: 'string' })
+          .option('json', jsonOption),
+        withFactories(errorsHandler),
+      )
+      .command(
+        'cat <id> <file>',
+        'Print one file from a workpiece folder (binary-safe when redirected)',
+        (y) => factoryOption(y
+          .positional('id', { describe: 'Workpiece id (exact or unique substring)', type: 'string' })
+          .positional('file', { describe: 'Path inside the workpiece folder (e.g. error.json)', type: 'string' })),
+        withFactory(catHandler, { frame: false }),
+      )
+      .command(
+        'open <id>',
+        'Open the workpiece folder: Finder locally, a shell in it on a remote host',
+        (y) => factoryOption(y.positional('id', { describe: 'Workpiece id (exact or unique substring)', type: 'string' })),
+        withFactory(openHandler, { frame: false }),
+      )
+      .command(
+        'clear [id]',
+        'Delete workpieces from done bins or terminal outputs (--bin), or one workpiece\'s (id). Dry run unless --yes.',
+        (y) => factoryOption(y.positional('id', { describe: 'One workpiece (exact or unique substring): its done and finished copies', type: 'string' }))
+          .option('bin', { describe: 'done = every done bin; finished = each line\'s terminal output', choices: ['done', 'finished'] })
+          .option('line', { describe: 'Only this line', type: 'string' })
+          .option('station', { describe: 'Only this station', type: 'string' })
+          .option('older-than', { describe: 'Only workpieces with no activity for this many days', type: 'number' })
+          .option('yes', { describe: 'Actually delete (default: dry run)', type: 'boolean' })
+          .check((a) => {
+            if (!a.id && !a.bin) throw new Error('Give --bin done|finished, or a workpiece id.');
+            if (a.olderThan !== undefined && !(a.olderThan >= 0)) throw new Error('--older-than takes a number of days (0 or more).');
+            return true;
+          }),
+        withFactory(clearHandler, { frame: false }),
+      )
+      .demandCommand(1, 'Specify an action: list, show, watch, count, errors, cat, open, clear'))
+    .command('procs', 'Factory processes on the current host (pm2)', (yargs) => yargs
+      .usage('$0 procs <action> [-f <factory>]')
+      .command('list', 'Every running factory on the host', (y) => localOptions(y).option('json', jsonOption), withHost(listProcsHandler))
+      .command('start', 'Start a factory under pm2', factoryOption, withFactory(startFactoryHandler, { frame: false }))
+      .command('stop', 'Stop a pm2-managed factory', factoryOption, withFactory(stopFactoryHandler, { frame: false }))
+      .command('restart', 'Restart a pm2-managed factory', factoryOption, withFactory(restartFactoryHandler, { frame: false }))
+      .command('logs', 'Tail a factory\'s pm2 logs (Ctrl-C to stop)', factoryOption, withFactory(logsFactoryHandler, { frame: false }))
+      .command('monit', 'pm2\'s interactive CPU/RAM monitor on the host', {}, withHost(monitHandler))
+      .demandCommand(1, 'Specify an action: list, start, stop, restart, logs, monit'))
+    .command('config', 'Show the al-control config', (yargs) => yargs
+      .usage('$0 config <action>')
+      .command('show', 'Config path, current host, hosts and factories', {}, showConfigHandler)
+      .demandCommand(1, 'Specify an action: show'))
+    .completion('completion', 'Generate shell completion script', (current, argv) => {
+      const ACTIONS = {
+        hosts: ['list', 'use', 'current'],
+        factories: ['list'],
+        lines: ['list', 'show', 'status'],
+        stations: ['status'],
+        workpieces: ['list', 'show', 'watch', 'count', 'errors', 'cat', 'open', 'clear'],
+        procs: ['list', 'start', 'stop', 'restart', 'logs', 'monit'],
+        config: ['show'],
+      };
+      // Drop the partial word being completed so `args` holds completed words only.
+      const words = argv._.slice(1).filter((a) => a !== '');
+      const done = current && words[words.length - 1] === current ? words.slice(0, -1) : words;
+      const startsWithCurrent = (list) => (current ? list.filter((c) => c.startsWith(current)) : list);
+      if (done.length === 0) return startsWithCurrent(Object.keys(ACTIONS));
+      if (done.length === 1) return startsWithCurrent(ACTIONS[done[0]] ?? []);
+      return [];
+    })
+    .demandCommand(1, 'Specify a resource: hosts, factories, lines, stations, workpieces, procs, config')
+    .strictCommands()
+    .help()
+    .version(version)
+    .alias('h', 'help')
+    .alias('v', 'version')
+    .group(['host', 'help', 'version'], 'Global Options:')
+    .wrap(process.stdout.columns || 100)
+    .fail((msg, err, yargs) => {
+      if (err) {
+        console.error(`Error: ${err.message}`);
+        if (process.env.DEBUG) console.error(err.stack);
+      } else {
+        console.error(msg);
+        console.error('');
+        yargs.showHelp();
+      }
+      process.exit(1);
+    });
+
+  cli.parse();
+}

package/src/cli/lines/list.js

@@ -0,0 +1,72 @@
+import { topoSortStations, codeOf } from '../../utils/line-state.js';
+import { loadDefs } from '../../utils/factory-data.js';
+import { formatTable } from '../../utils/format.js';
+
+/**
+ * `al-control lines list -f <factory>` — lines derived from the factory's
+ * station JSON files: name, location (from `.orchestrator/lines/<CODE>.json`),
+ * station count and members. Definitional; `lines status` has live counts.
+ *
+ * @param {{json?: boolean}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function listLinesHandler(argv, factory) {
+  const { json } = argv;
+  const { stations, lines: line_defs } = loadDefs(factory);
+
+  if (stations.length === 0) {
+    if (json) {
+      console.log(JSON.stringify({}, null, 2));
+      return;
+    }
+    console.log(`No station files in ${factory.name}/.orchestrator/stations/.`);
+    console.log('Run "al-orc stations pull --all" in the factory repo to fetch them.');
+    return;
+  }
+
+  // Stations without a line field group under '(unassigned)'.
+  const groups = new Map();
+  for (const s of stations) {
+    const key = s.line ?? '(unassigned)';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(s);
+  }
+  // A line file with no stations yet still exists as a definition.
+  for (const code of Object.keys(line_defs)) {
+    if (!groups.has(code)) groups.set(code, []);
+  }
+
+  if (json) {
+    const out = {};
+    for (const [line, members] of groups) {
+      const def = line_defs[line] || null;
+      out[line] = {
+        name: def?.name ?? null,
+        location: def?.location ?? null,
+        stations: topoSortStations(members).map((m) => ({ short_code: m.data.short_code, id: m.data.id, name: m.data.name })),
+      };
+    }
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  const rows = [...groups.keys()].sort().map((line) => {
+    const members = groups.get(line);
+    const def = line_defs[line];
+    return [
+      line,
+      def?.name && def.name !== line ? def.name : '—',
+      def?.location ?? '(no line file)',
+      String(members.length),
+      topoSortStations(members).map(codeOf).join(', ') || '—',
+    ];
+  });
+
+  console.log(formatTable(['LINE', 'NAME', 'LOCATION', 'STATIONS', 'MEMBERS'], rows));
+  console.log('');
+  console.log(`Total: ${groups.size} lines, ${stations.length} stations`);
+  if (Object.keys(line_defs).length === 0) {
+    console.log('No line files in .orchestrator/lines/ — run "al-orc lines pull --all" in the factory repo.');
+  }
+  console.log(`Run \`al-control lines status ${factory.flags}\` for live bin counts.`);
+}

package/src/cli/lines/show.js

@@ -0,0 +1,76 @@
+import {
+  topoSortStations,
+  codeOf,
+  dependencyRef,
+  resolveStationRef,
+  indexStationsByRef,
+} from '../../utils/line-state.js';
+import { loadDefs } from '../../utils/factory-data.js';
+import { formatHeader, formatField, formatTable, formatSection } from '../../utils/format.js';
+import { conveyorMoves } from '../../utils/conveyors.js';
+
+/**
+ * `al-control lines show <line> -f <factory>` — definitional view of a line:
+ * stations in dependency order plus conveyor topology.
+ *
+ * @param {{line: string, json?: boolean}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function showLineHandler(argv, factory) {
+  const { line: line_arg, json } = argv;
+  const { stations, lines: line_defs } = loadDefs(factory);
+  const line_def = line_defs[line_arg] || null;
+
+  const members = stations.filter((s) => s.line === line_arg);
+  if (members.length === 0 && !line_def) {
+    console.error(`Line not found: ${line_arg}`);
+    console.error(`Run "al-control lines list ${factory.flags}" to see available lines.`);
+    process.exit(1);
+  }
+
+  const ordered = topoSortStations(members);
+
+  if (json) {
+    console.log(JSON.stringify({ line: line_def, stations: ordered.map((m) => m.data) }, null, 2));
+    return;
+  }
+
+  console.log(formatHeader('Line', line_arg));
+  if (line_def?.name && line_def.name !== line_arg) console.log(formatField('Name', line_def.name, 12));
+  console.log(formatField('Location', line_def?.location ?? '(no line file — run "al-orc lines pull --all")', 12));
+  if (line_def?.description) console.log(formatField('Description', line_def.description, 12));
+  console.log(formatField('Stations', String(members.length), 12));
+  console.log('');
+
+  // Resolve dependency refs against every station, not just this line's — a
+  // cross-line edge should still render as a short_code.
+  const by_ref = indexStationsByRef(stations);
+  const rows = ordered.map((m) => {
+    const deps = (m.data.dependencies || [])
+      .map((d) => resolveStationRef(dependencyRef(d), by_ref))
+      .join(', ') || '—';
+    return [
+      codeOf(m),
+      m.data.name || '—',
+      String(Array.isArray(m.data.steps) ? m.data.steps.length : 0),
+      deps,
+      m.data.is_enabled === false ? 'no' : 'yes',
+    ];
+  });
+  console.log(formatTable(['STATION', 'NAME', 'STEPS', 'DEPENDS ON', 'ENABLED'], rows));
+
+  // move_files steps describe the source → target bin flow.
+  const conveyors = [];
+  for (const m of ordered) {
+    for (const move of conveyorMoves(m.data)) {
+      conveyors.push([codeOf(m), move.source_bin, move.target_bin || '—', move.mode || '—']);
+    }
+  }
+  if (conveyors.length > 0) {
+    console.log(formatSection('Conveyors'));
+    console.log(formatTable(['AT STATION', 'FROM BIN', 'TO BIN', 'MODE'], conveyors));
+  }
+
+  console.log('');
+  console.log(`Run \`al-control lines status ${line_arg} ${factory.flags}\` for live bin counts.`);
+}

package/src/cli/lines/status.js

@@ -0,0 +1,121 @@
+import { formatTable, formatHeader, formatField } from '../../utils/format.js';
+import { summarizeLine, 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 lines status [line] -f <factory>` — live bin state.
+ *
+ * No line: per-line IN-FLIGHT / STUCK / FINISHED / HEALTH summary. With a
+ * line: station × live-bin table; `done` shown in parens and excluded from
+ * totals (a receipt of a forward move, not a position).
+ *
+ * `--watch [--interval=N]` re-renders in place; exclusive with `--json`.
+ *
+ * @param {{line?: string, json?: boolean, watch?: boolean, interval?: number}} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function statusLineHandler(argv, factory) {
+  const { line: line_arg, 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);
+
+    if (Object.keys(lines).length === 0) {
+      if (json) console.log(JSON.stringify({}, null, 2));
+      else console.log(`No lines in ${factory.name}/.orchestrator/stations/. Run "al-orc stations pull --all" in the factory repo.`);
+      return;
+    }
+
+    if (!line_arg) {
+      renderLineSummary(lines, json);
+      return;
+    }
+
+    const ls = lines[line_arg];
+    if (!ls) {
+      const msg = `Line "${line_arg}" not found. Available: ${Object.keys(lines).sort().join(', ')}`;
+      // In watch mode the line may appear later, so surface and retry.
+      if (watch) {
+        console.log(msg);
+        return;
+      }
+      console.error(msg);
+      process.exit(1);
+    }
+    renderLineDrilldown(ls, json, factory);
+  };
+
+  if (watch) {
+    await watchRender({ render: renderOnce, interval_secs });
+    return;
+  }
+  renderOnce();
+}
+
+function renderLineSummary(lines, json) {
+  const summaries = {};
+  for (const ls of Object.values(lines)) summaries[ls.code] = summarizeLine(ls);
+
+  if (json) {
+    console.log(JSON.stringify(summaries, null, 2));
+    return;
+  }
+
+  const rows = Object.keys(summaries).sort().map((code) => {
+    const s = summaries[code];
+    let health;
+    if (s.stuck > 0) health = `⚠ ${s.stuck_locations.join(', ')}`;
+    else if (s.in_flight === 0 && s.finished === 0) health = 'idle';
+    else if (s.in_flight === 0) health = `${s.finished} finished, drained`;
+    else health = `flowing, biggest at ${s.biggest_flow.at}`;
+    return [code, String(s.in_flight), String(s.stuck), String(s.finished), health];
+  });
+  console.log(formatTable(['LINE', 'IN-FLIGHT', 'STUCK', 'FINISHED', 'HEALTH'], rows));
+}
+
+function renderLineDrilldown(ls, json, factory) {
+  if (json) {
+    const out = { code: ls.code, terminal: ls.terminal, stations: {} };
+    for (const station of ls.stations) {
+      out.stations[station] = {};
+      for (const bin of [...LIVE_BINS, 'done']) {
+        const map = ls.bins[station][bin];
+        out.stations[station][bin] = map ? [...map.keys()].sort() : null;
+      }
+    }
+    out.summary = summarizeLine(ls);
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  console.log(formatHeader('Line', ls.code));
+  console.log(formatField('Stations', ls.stations.join(' → '), 12));
+  console.log(formatField('Terminal', ls.terminal, 12));
+  console.log('');
+
+  const cell = (map) => (map === null ? '—' : String(map.size));
+  const rows = ls.stations.map((station) => {
+    const b = ls.bins[station];
+    return [station, cell(b.input), cell(b.doing), cell(b.output), cell(b.failed), b.done === null ? '—' : `(${b.done.size})`];
+  });
+
+  const totals = { input: 0, doing: 0, output: 0, failed: 0 };
+  for (const station of ls.stations) {
+    for (const bin of LIVE_BINS) {
+      const map = ls.bins[station][bin];
+      if (map) totals[bin] += map.size;
+    }
+  }
+  rows.push(['live', String(totals.input), String(totals.doing), String(totals.output), String(totals.failed), '']);
+
+  console.log(formatTable(['STATION', 'INPUT', 'DOING', 'OUTPUT', 'FAILED', '(DONE)'], rows));
+  console.log('');
+  console.log('`(done)` shown in parens for audit; excluded from live totals.');
+  console.log(`Run \`al-control workpieces list --line ${ls.code} ${factory.flags}\` for per-workpiece positions.`);
+}

package/src/cli/procs/actions.js

@@ -0,0 +1,95 @@
+import path from 'node:path';
+
+import { probe, pm2, pm2Hint } from '../../transport.js';
+
+/**
+ * The factory's resolved root on its host, its package.json `main`, and the
+ * running process for it (if any) — one probe round trip.
+ *
+ * pm2 process name = directory basename of the factory root, the same name
+ * `al-factory procs start` and the control-room app use, so a factory started by
+ * one is recognised by the others.
+ *
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+function inspectFactory(factory) {
+  const { factories: [w], procs, pm2_found } = probe(factory.host, { type: 'factories', paths: { [factory.name]: factory.path } });
+  if (!w.exists) throw new Error(`Factory directory does not exist on ${factory.host.name}: ${w.root}`);
+  if (!pm2_found) throw new Error(`pm2 not found on ${factory.host.name}. ${pm2Hint(factory.host)}`);
+  const pm2_name = path.posix.basename(w.root);
+  const running = procs.find((r) => r.cwd === w.root || r.pm2 === pm2_name) ?? null;
+  return { root: w.root, main: w.main, pm2_name, running };
+}
+
+/**
+ * The factory's pm2-managed process, or exit with why it can't be managed.
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+function requirePm2Process(factory) {
+  const { running } = inspectFactory(factory);
+  if (!running) {
+    console.error(`Factory "${factory.name}" is not running on ${factory.host.name}.`);
+    process.exit(1);
+  }
+  if (running.mode !== 'pm2') {
+    console.error(`Factory "${factory.name}" (pid ${running.pid}) is running directly, not under pm2 — can't manage it this way.`);
+    console.error(`Stop it on ${factory.host.name} manually: kill ${running.pid}`);
+    process.exit(1);
+  }
+  return running;
+}
+
+/**
+ * `al-control procs start -f <factory>` — start under pm2 from the factory root.
+ * @param {object} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function startFactoryHandler(argv, factory) {
+  const { root, main, pm2_name, running } = inspectFactory(factory);
+  if (!main) {
+    console.error(`${root} on ${factory.host.name} doesn't look like a factory repo (missing @assemblyline/lib-factory dependency or package.json "main").`);
+    process.exit(1);
+  }
+  if (running) {
+    console.error(`Factory "${factory.name}" is already running on ${factory.host.name} (pid ${running.pid}, mode ${running.mode}).`);
+    console.error(`Use "al-control procs restart ${factory.flags}" instead.`);
+    process.exit(1);
+  }
+  pm2(factory.host, ['start', main, '--name', pm2_name], { cwd: root });
+}
+
+/**
+ * `al-control procs stop -f <factory>`
+ * @param {object} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function stopFactoryHandler(argv, factory) {
+  pm2(factory.host, ['stop', requirePm2Process(factory).pm2]);
+}
+
+/**
+ * `al-control procs restart -f <factory>`
+ * @param {object} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function restartFactoryHandler(argv, factory) {
+  pm2(factory.host, ['restart', requirePm2Process(factory).pm2]);
+}
+
+/**
+ * `al-control procs logs -f <factory>` — tail until Ctrl-C.
+ * @param {object} argv
+ * @param {import('../../config.js').FactoryContext} factory
+ */
+export async function logsFactoryHandler(argv, factory) {
+  pm2(factory.host, ['logs', requirePm2Process(factory).pm2], { interactive: true });
+}
+
+/**
+ * `al-control procs monit` — pm2's interactive CPU/RAM monitor on the host.
+ * @param {object} argv
+ * @param {import('../../config.js').HostContext} host
+ */
+export async function monitHandler(argv, host) {
+  pm2(host, ['monit'], { interactive: true });
+}

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]),
+  ));
+}