create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/api/landing.js

@@ -0,0 +1,403 @@
+'use strict';
+
+// WP-3 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §6.3, §8 WP-3): the
+// landing-queue HTTP surface.
+//
+//   GET  /api/landing/status?repo=<path>&session=<id>  -> { ok, repo, queue, runner, jobs, radar,
+//                                                          forSession }
+//   GET  /api/landing/status?session=<id>&cached=1     -> { ok, cached:true, repo, forSession } (no CLI)
+//   POST /api/landing/run    { repo }                  -> 202 { ok, started:true, pid }
+//                                                       | 409 { ok:false, error:'runner_live', runner }
+//   POST /api/landing/submit { session,                 -> 200 <the CLI's own --json payload>
+//                              priority?, reason? }       | 409 (CLI exit 1) | 400 (CLI exit 2)
+//   (WP-4 §6.4: `priority`/`reason` are optional passthrough flags — a non-string value is 400
+//    `priority_invalid` / `reason_invalid`; the level and the reason requirement are the CLI's own
+//    call, and its exit 2 is the 400 above.)
+//
+// D-1: the CLI is the single source of truth and the server never requires `lib/landing/*` on its
+// thread — those modules are synchronous (a radar sweep is N merge-trees) and this loop is the same
+// one that relays terminals. Every fact here comes from `process.execPath <...>/bin/land.js --json`
+// run as an ASYNC child, with a timeout and a maxBuffer. The parsing helpers are exported so the
+// probe can be exercised against a real scratch repository.
+//
+// `run` is the ONE detached launch: `land submit` starts its own runner when it wins the lease, but
+// a queue whose runner died with nothing to submit needs a way to be restarted, and that way must
+// never be "run the drain loop inside the server".
+//
+// Like lib/api/host-stats.js this is NEW surface: the handler bodies live here, so there is no
+// legacy handleApi branch to delete and tests-integration/api-router-parity.test.js's no-dual-
+// dispatch rule is satisfied by construction. Auth is NOT evaluated here: lib/auth-rules.js carries
+// the three rows (all `{ loopbackOnly: true }`) and a route with no rule is 403 auth_rule_missing by
+// design, so the rule rows and this registration must land together.
+
+const path = require('node:path');
+const { execFile, spawn } = require('node:child_process');
+const { registerApiRoutes } = require('../api-router');
+const { landingStatusForRepo } = require('../landing/ctm-view');
+
+// Resolved from THIS file: lib/api/ -> coding-task-manager/bin/land.js.
+const CLI_PATH = path.join(__dirname, '..', '..', 'bin', 'land.js');
+// A radar probe is merge-base + merge-tree per uncached pair; a submit does a handful of git reads.
+// Both are bounded, and the bound is what makes an async child safe to hold on the request path.
+const PROBE_TIMEOUT_MS = 30000;
+const SUBMIT_TIMEOUT_MS = 60000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+// §4 / bin/git-test-env.js GIT_CONTEXT_ENV_KEYS. COPIED, not required: lib/ must not depend on bin/
+// (its files are pinned by the test-broker protocol manifest). A test in
+// tests-integration/landing-ctm-api.test.js asserts this list still equals the CLI's own scrub list,
+// so drift is caught instead of assumed.
+const GIT_CONTEXT_ENV_KEYS = Object.freeze([
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_PREFIX',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_COMMON_DIR',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+]);
+
+let _deps = null;
+
+function configure({
+  probeLanding,
+  liveSessions,
+  sessionById,
+  worktreePathForSession,
+  runLandSubmit,
+  spawnRunner,
+  sendJsonResponse,
+  readJsonRequestBody,
+  onRunnerError,
+  cachedLandingForSession,
+} = {}) {
+  _deps = {
+    probeLanding, liveSessions, sessionById, worktreePathForSession,
+    runLandSubmit, spawnRunner, sendJsonResponse, readJsonRequestBody, onRunnerError, cachedLandingForSession,
+  };
+}
+
+function _dep(name) {
+  return _deps ? _deps[name] : null;
+}
+
+function _send(res, status, payload) {
+  const send = _dep('sendJsonResponse');
+  if (typeof send === 'function') return send(res, status, payload);
+  const body = JSON.stringify(payload || {});
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function _query(url, name) {
+  const value = url && url.searchParams ? url.searchParams.get(name) : null;
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+async function _readBody(req) {
+  const read = _dep('readJsonRequestBody');
+  if (typeof read !== 'function') return {};
+  const body = await read(req);
+  return body && typeof body === 'object' ? body : {};
+}
+
+// --- the CLI child ------------------------------------------------------------------------------
+
+// process.env minus the §4 GIT_* list. The CLI scrubs again for its own git children
+// (lib/landing/git.js#childEnv); this scrub is for the CLI process itself, whose `cwd` is the
+// repository we were asked about and whose inherited GIT_DIR would otherwise point somewhere else.
+function cliEnv(extra) {
+  const env = { ...process.env };
+  for (const key of GIT_CONTEXT_ENV_KEYS) delete env[key];
+  if (extra) Object.assign(env, extra);
+  return env;
+}
+
+// One result shape for every exit path, so no caller parses stdout or stderr itself. Exit codes are
+// the CLI's own contract (§6.2): 0 ok · 1 typed refusal (JSON `error.code`) · 2 usage · 75 timeout.
+function interpretCliResult(error, stdout, stderr) {
+  const out = typeof stdout === 'string' ? stdout : String(stdout || '');
+  const err = (typeof stderr === 'string' ? stderr : String(stderr || '')).trim();
+  let payload = null;
+  try {
+    payload = JSON.parse(out);
+  } catch {
+    // expected: a non-JSON stdout. The CLI writes USAGE to stderr and nothing to stdout on a usage
+    // error, and a killed child may write nothing at all; the exit code and stderr below carry the
+    // answer in both cases.
+    payload = null;
+  }
+  if (error) {
+    if (error.killed === true || error.signal || error.code === 'ETIMEDOUT') {
+      return { ok: false, exitCode: null, error: { code: 'cli_timeout', message: err || 'the land CLI did not finish in time' } };
+    }
+    if (typeof error.code === 'number') {
+      const failure = payload && payload.ok === false && payload.error && typeof payload.error.code === 'string'
+        ? payload.error
+        : { code: 'cli_refused', message: err || `land exited ${error.code}` };
+      return { ok: false, exitCode: error.code, error: { code: failure.code, message: failure.message || '' } };
+    }
+    return { ok: false, exitCode: null, error: { code: 'cli_spawn_failed', message: err || error.message } };
+  }
+  if (!payload || typeof payload !== 'object') {
+    return { ok: false, exitCode: null, error: { code: 'cli_output_invalid', message: out.trim().slice(0, 500) } };
+  }
+  if (payload.ok === false && payload.error && typeof payload.error.code === 'string') {
+    return { ok: false, exitCode: 1, error: payload.error };
+  }
+  return { ok: true, exitCode: 0, payload };
+}
+
+// The async child (D-1). `execFile`'s callback is the only exit path — the promise never rejects —
+// so every caller gets the same result object without a try/catch of its own.
+function runCli(args, options = {}) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI_PATH, ...args], {
+      cwd: options.cwd || CLI_PATH,
+      env: cliEnv(options.env),
+      timeout: options.timeoutMs || PROBE_TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER,
+      encoding: 'utf8',
+    }, (error, stdout, stderr) => resolve(interpretCliResult(error, stdout, stderr)));
+  });
+}
+
+/**
+ * A full (non-cache-only) `land status --json` for one repository, restricted to the given branches
+ * (§8 WP-3). The flag is always passed: plain `land status` carries no radar, and `branches`
+ * empty/absent is an empty restriction — no worktree swept, no pair — which is the honest answer
+ * for a repository with no live session on any branch: there is no pair to join to a session.
+ */
+function probeRepoWithCli({ repo, branches }) {
+  const names = Array.isArray(branches) ? branches : [];
+  const args = ['status', '--json', '--repo', repo, '--radar-for', names.join(',')];
+  return runCli(args, { cwd: repo, timeoutMs: PROBE_TIMEOUT_MS });
+}
+
+/**
+ * §6.4 (WP-4): the two optional passthrough flags, built in ONE pure place so the exact argv is
+ * assertable without a child process. Only non-empty strings count — and with neither flag the array
+ * is the historical `['submit', '--json']` byte-for-byte, so no existing caller's CLI invocation
+ * changes. The server does NOT validate the level or the reason: the CLI is the one validator, and
+ * its exit 2 already maps to HTTP 400 below.
+ */
+function landSubmitArgv({ priority, reason } = {}) {
+  const optional = (name, value) => (typeof value === 'string' && value ? [`--${name}`, value] : []);
+  return ['submit', '--json', ...optional('priority', priority), ...optional('reason', reason)];
+}
+
+function submitWithCli({ cwd, sessionId, priority, reason }) {
+  return runCli(landSubmitArgv({ priority, reason }), {
+    cwd,
+    timeoutMs: SUBMIT_TIMEOUT_MS,
+    env: sessionId ? { CTM_SESSION_ID: String(sessionId) } : null,
+  });
+}
+
+/**
+ * The detached runner (§6.3 / the "Run queue" button): `land run --once` in its own process group,
+ * unref'd, stdio ignored — it claims the per-repository lease itself, so a racing second child
+ * simply exits. Never in-process: the drain loop runs gates for as long as they take.
+ */
+function spawnDetachedRunner({ repo }) {
+  const child = spawn(process.execPath, [CLI_PATH, 'run', '--once'], {
+    cwd: repo,
+    env: cliEnv(),
+    detached: true,
+    stdio: 'ignore',
+  });
+  // A detached child reports a bad cwd/executable as an 'error' EVENT, not a throw; without a
+  // listener it would be an uncaught exception in the server. The caller has already answered 202,
+  // so this path can only report.
+  child.on('error', (error) => {
+    const report = _dep('onRunnerError');
+    if (typeof report === 'function') report(error);
+  });
+  child.unref();
+  return { pid: typeof child.pid === 'number' ? child.pid : null };
+}
+
+// --- handlers -----------------------------------------------------------------------------------
+
+function _probe(args) {
+  const probe = _dep('probeLanding');
+  return (typeof probe === 'function' ? probe : probeRepoWithCli)(args);
+}
+
+function _describedSessions() {
+  const list = _dep('liveSessions');
+  const entries = typeof list === 'function' ? list() : null;
+  return (Array.isArray(entries) ? entries : [])
+    .filter((entry) => entry && entry.id !== undefined && entry.id !== null && entry.repo)
+    .map((entry) => ({
+      id: String(entry.id),
+      repo: entry.repo,
+      branch: typeof entry.branch === 'string' ? entry.branch : null,
+      // The session's WORK TREE (`describeSession().path`). A caller may name either the repository's
+      // common dir or one of its worktree paths (`?repo=` accepts both), and the two must resolve to
+      // the same session set for the chip to be attributable.
+      path: typeof entry.path === 'string' && entry.path ? entry.path : null,
+    }));
+}
+
+// The sessions CTM will say are "on" this repository — the ones a landing chip can be attributed to.
+// A caller may name the repository by its common dir OR by one of its worktree paths, and the probe
+// echoes the repository's real common dir back, so the caller's names and the probe's answer are both
+// consulted: only one of them has to line up for every session of that repository to be included.
+// Comparison is textual first (the runtime keys its own cache the same way) with a resolved-path
+// fallback for the caller's own spelling.
+function _sessionsForRepo(...repos) {
+  const wanted = repos.filter((value) => typeof value === 'string' && value);
+  if (!wanted.length) return [];
+  const sessions = _describedSessions();
+  const names = (entry) => [entry.repo, entry.path].filter((value) => typeof value === 'string' && value);
+  const exact = sessions.filter((entry) => names(entry).some((value) => wanted.includes(value)));
+  const matching = exact.length
+    ? exact
+    : sessions.filter((entry) => names(entry).some((value) => wanted.some((repo) => path.resolve(value) === path.resolve(repo))));
+  return matching.map((entry) => ({ id: entry.id, branch: entry.branch }));
+}
+
+// `?session=<id>` with no `?repo=`: the repository comes from the session's own git snapshot. A
+// session CTM cannot describe yet falls back to its worktree path, which the CLI resolves itself
+// (`git rev-parse --show-toplevel`) — the same arm as an explicit `?repo=` path.
+function _repoForSession(sessionId) {
+  if (!sessionId) return null;
+  const described = _describedSessions().find((entry) => entry.id === String(sessionId));
+  if (described) return described.repo;
+  const lookup = _dep('sessionById');
+  const session = typeof lookup === 'function' ? lookup(sessionId) : null;
+  if (!session) return null;
+  const dir = _dep('worktreePathForSession');
+  const candidate = typeof dir === 'function' ? dir(session) : (session.worktree_path || session.cwd);
+  return typeof candidate === 'string' && candidate ? candidate : null;
+}
+
+async function handleLandingStatus(req, res, url) {
+  // `?session=<id>&cached=1` (the Wall-E context hint): the session's view exactly as the last sweep
+  // left it, with no CLI child — a preflight on every agent turn must not start a radar probe.
+  if (_query(url, 'cached') === '1') return _sendCachedLanding(res, _query(url, 'session'));
+  const repo = _query(url, 'repo') || _repoForSession(_query(url, 'session'));
+  if (!repo) return _send(res, 404, { ok: false, error: 'repo_unknown' });
+  const probe = await _probe({ repo, sessions: _describedSessions() });
+  if (!probe || probe.ok !== true) {
+    const code = probe && probe.error ? probe.error.code : 'landing_probe_failed';
+    // `not_a_repo` is the CLI's own refusal for a path git cannot resolve — the one case the caller
+    // can fix by naming a different repository, so it is a 404 and not a server fault.
+    if (code === 'not_a_repo') return _send(res, 404, { ok: false, error: 'repo_unknown', detail: probe.error });
+    return _send(res, 502, { ok: false, error: 'landing_probe_failed', detail: (probe && probe.error) || null });
+  }
+  const payload = probe.payload || {};
+  // The probe answers with the repository's real common dir, which is how every session description
+  // names it; the caller's own spelling is consulted too, so `?repo=<worktree path>` attributes the
+  // whole repository rather than only the worktree it happened to name.
+  const body = landingStatusForRepo(payload, _sessionsForRepo(repo, payload.repo));
+  return _send(res, 200, { ok: true, repo: payload.repo || repo, ...body });
+}
+
+function _sendCachedLanding(res, sessionId) {
+  if (!sessionId) return _send(res, 400, { ok: false, error: 'session_required' });
+  const read = _dep('cachedLandingForSession');
+  const cached = typeof read === 'function' ? read(String(sessionId)) : null;
+  if (!cached) return _send(res, 404, { ok: false, error: 'session_unknown' });
+  const forSession = cached.view ? { [String(sessionId)]: cached.view } : {};
+  return _send(res, 200, { ok: true, cached: true, repo: cached.repo || null, forSession });
+}
+
+async function handleLandingRun(req, res) {
+  let body;
+  try {
+    body = await _readBody(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const repo = typeof body.repo === 'string' && body.repo
+    ? body.repo
+    : (body.session ? _repoForSession(String(body.session)) : null);
+  if (!repo) return _send(res, 404, { ok: false, error: 'repo_unknown' });
+  // The lease is the queue's own truth, and it is read from the same probe the status route uses:
+  // one runner per repository means "is one live?" is answered by the record holder, not by a guess.
+  const probe = await _probe({ repo, sessions: _describedSessions() });
+  if (!probe || probe.ok !== true) {
+    const code = probe && probe.error ? probe.error.code : 'landing_probe_failed';
+    if (code === 'not_a_repo') return _send(res, 404, { ok: false, error: 'repo_unknown', detail: probe.error });
+    return _send(res, 502, { ok: false, error: 'landing_probe_failed', detail: (probe && probe.error) || null });
+  }
+  const runner = probe.payload && probe.payload.runner ? probe.payload.runner : null;
+  if (runner && runner.alive === true) return _send(res, 409, { ok: false, error: 'runner_live', runner });
+  const spawnRunner = _dep('spawnRunner');
+  const started = (typeof spawnRunner === 'function' ? spawnRunner : spawnDetachedRunner)({ repo });
+  return _send(res, 202, { ok: true, started: true, pid: started ? started.pid : null });
+}
+
+// §6.4 (WP-4): `priority` / `reason` are optional and unvalidated here (the CLI owns level-validity
+// and the reason requirement). A key that is absent (or null, how JSON spells "not sent") is simply
+// left out of the call, so a request without them reaches the run dependency — and the CLI argv —
+// exactly as it did before this WP. A key that is present with a non-string value is the one thing
+// the server can answer itself: the CLI would see a coerced `[object Object]`, so it is a 400 here.
+function _optionalSubmitField(body, name) {
+  const value = body[name];
+  if (value === undefined || value === null) return { invalid: false, present: false };
+  if (typeof value !== 'string') return { invalid: true, present: true };
+  return { invalid: false, present: true, value };
+}
+
+async function handleLandingSubmit(req, res) {
+  let body;
+  try {
+    body = await _readBody(req);
+  } catch {
+    return _send(res, 400, { ok: false, error: 'invalid_json' });
+  }
+  const fields = {};
+  for (const name of ['priority', 'reason']) {
+    const field = _optionalSubmitField(body, name);
+    if (field.invalid) return _send(res, 400, { ok: false, error: `${name}_invalid` });
+    if (field.present) fields[name] = field.value;
+  }
+  const sessionId = body.session === undefined || body.session === null ? null : String(body.session);
+  if (!sessionId) return _send(res, 400, { ok: false, error: 'session_required' });
+  const lookup = _dep('sessionById');
+  const session = typeof lookup === 'function' ? lookup(sessionId) : null;
+  if (!session) return _send(res, 404, { ok: false, error: 'session_unknown' });
+  const dir = _dep('worktreePathForSession');
+  const cwd = typeof dir === 'function' ? dir(session) : (session.worktree_path || session.cwd);
+  if (typeof cwd !== 'string' || !cwd) return _send(res, 409, { ok: false, error: 'session_has_no_worktree' });
+  const run = _dep('runLandSubmit');
+  const result = await (typeof run === 'function' ? run : submitWithCli)({ cwd, sessionId, ...fields });
+  if (result && result.ok === true) return _send(res, 200, result.payload);
+  const exitCode = result ? result.exitCode : null;
+  const payload = { ok: false, error: result && result.error ? result.error : { code: 'cli_failed', message: '' } };
+  // The CLI's two refusal classes are genuinely different: 1 = a typed refusal the caller can read
+  // and act on (duplicate submitter, unmerged paths, missing gates), 2 = a usage error in what we
+  // asked for. Anything else (the child timed out, could not be started) is our fault, not theirs.
+  if (exitCode === 2) return _send(res, 400, payload);
+  if (exitCode === 1) return _send(res, 409, payload);
+  return _send(res, 502, payload);
+}
+
+function register() {
+  registerApiRoutes('landing', [
+    { method: 'GET', path: '/api/landing/status', handler: (req, res, url) => handleLandingStatus(req, res, url) },
+    { method: 'POST', path: '/api/landing/run', handler: (req, res) => handleLandingRun(req, res) },
+    { method: 'POST', path: '/api/landing/submit', handler: (req, res) => handleLandingSubmit(req, res) },
+  ]);
+}
+
+module.exports = {
+  configure,
+  register,
+  handleLandingStatus,
+  handleLandingRun,
+  handleLandingSubmit,
+  probeRepoWithCli,
+  submitWithCli,
+  landSubmitArgv,
+  spawnDetachedRunner,
+  interpretCliResult,
+  cliEnv,
+  GIT_CONTEXT_ENV_KEYS,
+  CLI_PATH,
+  PROBE_TIMEOUT_MS,
+  SUBMIT_TIMEOUT_MS,
+};