create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/bin/ctm-machine-pair.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+'use strict';
+
+// WP-3 (docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.3, §9 S-23): the pairing CLI.
+//
+//   ctm-machine-pair offer [--port <n>] [--json]
+//
+// Mints a pairing offer on the LOCAL CTM (`POST /api/machine-pairing/offers`) and prints the code,
+// the expiry and the whole `ctmpair1:` pairing string, so a terminal user can pair a machine without
+// opening the Machines page.
+//
+// IT NEVER PRINTS A TOKEN. The offer response carries a CODE (a single-use, TTL-bounded, 20^8-space
+// secret) and nothing else secret; the pool token only ever travels member -> box. The response body
+// is re-projected field by field rather than echoed, so a future response field can never leak
+// through this CLI by accident.
+//
+// AUTH. The route is admin + step-up remote (lib/auth-rules.js), and a LOOPBACK request is already
+// admin-scoped with no step-up (`hasScope`/`authorize`: loopback satisfies every scope and
+// `stepUp === 'remote'` is skipped for loopback), so no cookie, bearer or device token is needed —
+// this is the same posture every other loopback drivetool has. `--port` (or `CTM_PORT`, default
+// 3456) is the only knob; the request always goes to 127.0.0.1 so it can never mint an offer on a
+// remote machine.
+//
+// argv parsing only, no prompts: this is meant to be scriptable.
+
+const http = require('node:http');
+// CTM_PORT is read through lib/env-flags.js (the one truthiness/number parser) rather than
+// `process.env` directly: bin/flag-lint.js fails a new raw read of a CTM_* flag outside that module,
+// and CTM_PORT is a genuinely shared knob (bin/dev.sh, lib/hosted-primary-runtime.js).
+const { intFlag } = require('../lib/env-flags');
+
+const DEFAULT_PORT = 3456;
+
+function parseArgs(argv) {
+  const envPort = intFlag('CTM_PORT', DEFAULT_PORT);
+  const out = { command: '', port: envPort > 0 ? envPort : DEFAULT_PORT, json: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--port' || arg === '-p') {
+      const value = Number(argv[++i]);
+      if (Number.isInteger(value) && value > 0) out.port = value;
+    } else if (arg === '--json') {
+      out.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      out.help = true;
+    } else if (!out.command) {
+      out.command = arg;
+    }
+  }
+  return out;
+}
+
+function usage(out) {
+  out.write('usage: ctm-machine-pair offer [--port <n>] [--json]\n');
+  out.write('\n');
+  out.write('  offer      mint a pairing code on the local CTM and print it\n');
+  out.write('\n');
+  out.write('  --port <n> CTM port (default: CTM_PORT, else 3456)\n');
+  out.write('  --json     print the offer as JSON instead of a human report\n');
+}
+
+/**
+ * One loopback POST. `127.0.0.1` is hard-coded on purpose: a pairing offer must never be mintable on
+ * a machine other than the one this process is on.
+ */
+function postLoopback(port, pathname, body) {
+  return new Promise((resolve, reject) => {
+    const payload = Buffer.from(JSON.stringify(body || {}));
+    const req = http.request({
+      host: '127.0.0.1',
+      port,
+      path: pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': payload.length,
+        Accept: 'application/json',
+      },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed = null;
+        try {
+          parsed = raw ? JSON.parse(raw) : null;
+        } catch {
+          parsed = null; // expected: a non-JSON error page is reported by status alone
+        }
+        resolve({ status: Number(res.statusCode) || 0, body: parsed, raw });
+      });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+function formatExpiry(expiresAt) {
+  const at = Number(expiresAt);
+  if (!Number.isFinite(at) || at <= 0) return 'unknown';
+  const seconds = Math.max(0, Math.round((at - Date.now()) / 1000));
+  return `${new Date(at).toISOString()} (in ${seconds}s)`;
+}
+
+async function main(argv, io) {
+  const out = io.out;
+  const err = io.err;
+  const args = parseArgs(argv);
+  if (args.help || !args.command) {
+    usage(args.command ? out : err);
+    return args.command ? 0 : 2;
+  }
+  if (args.command !== 'offer') {
+    err.write(`ctm-machine-pair: unknown command '${args.command}'\n`);
+    usage(err);
+    return 2;
+  }
+  let res = null;
+  try {
+    res = await postLoopback(args.port, '/api/machine-pairing/offers', {});
+  } catch (error) {
+    err.write(`ctm-machine-pair: cannot reach CTM on 127.0.0.1:${args.port} — ${error && error.message ? error.message : error}\n`);
+    return 1;
+  }
+  if (res.status !== 201 || !res.body || res.body.ok !== true) {
+    const code = (res.body && (res.body.error || res.body.code)) || `http_${res.status}`;
+    err.write(`ctm-machine-pair: offer refused — ${code}\n`);
+    if (code === 'pool_member_exists') err.write('  this machine is already in a pool; leave it first\n');
+    if (code === 'pairing_offer_limit') err.write('  three offers are already live; wait for one to expire\n');
+    if (code === 'auth_rule_missing' || code === 'unauthorized') err.write(`  is CTM running on port ${args.port}?\n`);
+    return 1;
+  }
+  // Field-by-field projection: the response is NOT echoed, so a token added to it later cannot leak.
+  const offer = {
+    code: String(res.body.code || ''),
+    expiresAt: Number(res.body.expiresAt) || 0,
+    pairingString: String(res.body.pairingString || ''),
+    candidates: Array.isArray(res.body.candidates) ? res.body.candidates.map((url) => String(url || '')) : [],
+  };
+  if (args.json) {
+    out.write(`${JSON.stringify(offer, null, 2)}\n`);
+    return 0;
+  }
+  out.write(`Pairing code:   ${offer.code}\n`);
+  out.write(`Expires:        ${formatExpiry(offer.expiresAt)}\n`);
+  if (offer.candidates.length) out.write(`Reachable at:   ${offer.candidates.join(', ')}\n`);
+  out.write(`Pairing string: ${offer.pairingString}\n`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2), { out: process.stdout, err: process.stderr })
+    .then((code) => { process.exitCode = code; })
+    .catch((error) => {
+      process.stderr.write(`ctm-machine-pair: ${error && error.stack ? error.stack : error}\n`);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { parseArgs, postLoopback, main };