@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/capture.js

@@ -1,481 +1,7 @@
 #!/usr/bin/env node
-// Capture an idea into idea_inbox (the structured replacement for
-// generative-ideas.md).
-//
-// Usage:
-//   node scripts/gds/capture.js "title" \
-//     [--kind feature] \
-//     [--body-file path] \
-//     [--version V1|PMS-V2|GDS-V3] \
-//     [--priority N] \
-//     [--goal N | --goal none] \
-//     [--spark] \
-//     [--full --fields-file path.json] \
-//     [--no-prompt]
-//
-// THE GRADE AXIS (task 1002927 / BV1.R151, goal 1000062). Three grades exist and
-// this CLI reaches all three, but NOT symmetrically, because they are not
-// symmetrical acts:
-//   quick  — the default. Title + body. Unchanged.
-//   full   — `--full --fields-file f.json`, the five R141 fields. One request.
-//   spark  — `--spark`, which is TWO requests: capture, then mark. The route
-//            deliberately REFUSES grade='spark' at capture (R144: an idea does not
-//            arrive pre-marked; sparking is the author's later act on an existing
-//            idea), and that invariant is not being worked around here — the
-//            author is simply performing both acts in one command, and the mark
-//            still goes through the author-only route that checks captured_by.
-//
-// THE POST-CAPTURE OFFER, and the one thing that must not break: after a plain
-// quick capture, an interactive terminal is asked whether to develop the thought
-// into a Full Idea. It is TTY-GATED. capture.js is run by agents and scripts with
-// no terminal (and reads its BODY from stdin when --body-file is absent), so an
-// unguarded prompt would hang every non-interactive caller. No TTY, or
-// --no-prompt, means the offer never appears and the behaviour is exactly what it
-// was before this task.
-//
-// Defaults:
-//   --kind     → server auto-classifies from title+body (keyword heuristics
-//                today; replaced by the real classifier when task B1 ships)
-//   --version  → most recent version with status='building' (queried from
-//                /api/bongos/versions); leave null if there isn't one
-//   --priority → null (set later at triage time)
-//   --goal     → capture-time ROUTING (task 1003070, R09 of goal 1000071,
-//                interview decision 4). Naming a goal turns this filing into a
-//                task IN that goal in the same request (POST /inbox's own
-//                landing matrix — task 1003065 — still decides whether it
-//                hard-lands 'ready' or soft-lands 'backlog'; this CLI duplicates
-//                none of that, it only decides WHICH goal to send). Three ways:
-//                  --goal N     → route to goal N, verbatim.
-//                  --goal none  → explicitly homeless: no goal_id is sent, and
-//                                 the active-claim default below is skipped —
-//                                 an opt-out that still guessed a goal would not
-//                                 be an opt-out.
-//                  (neither)    → default to the ACTIVE CLAIM's goal — but ONLY
-//                                 when the captured text and the claimed task
-//                                 share a subject word (task 1003859); an
-//                                 unrelated filing says so and stays homeless.
-//                                 Applies if this builder holds a claim and its
-//                                 task has a goal
-//                                 ("capturing mid-work almost always concerns
-//                                 the work" — the interview's own words). With
-//                                 no default to offer, the R07 suggester
-//                                 (GET /goals/suggestions) prints its best guess
-//                                 as a one-line hint — never an auto-pick; C5 is
-//                                 "the system OFFERS the home", not chooses it.
-//                Both the active-claim lookup and the suggester are best-effort:
-//                either failing degrades to "no goal", never to a fatal error.
-//
-// Exit codes:
-//   0  captured
-//   1  api / network error
-//   2  bad invocation
-//
-// Acceptance examples (from task #34 spec):
-//   $ node scripts/gds/capture.js "we should add a 'last 24 hours' filter to the public dashboard"
-//   📥 Captured idea #12: kind=feature (auto), version=PMS-V2, priority=null
-//   Inbox now: 8 open
-
-const fs = require('node:fs/promises');
-const readline = require('node:readline');
-const { cliClient, requireSession, arg, hasFlag } = require('./cli-lib');
-
-
-// task 1003166 (G02): the selection rule moved to version-select.js so the nine
-// scripts that used to hardcode a version id share ONE implementation. Kept as a
-// local name so every call site below reads unchanged.
-const { resolveDefaultVersion } = require('./version-select.js');
-
-// Full JSON, not console.error's depth-2 inspect — a validation 400's nested
-// details otherwise print as "[ [Object] ]" and hide which field failed.
-function formatCaptureFailure(status, data) {
-  let rendered;
-  try {
-    rendered = JSON.stringify(data, null, 2);
-  } catch {
-    rendered = String(data);
-  }
-  return `capture failed (${status}): ${rendered}`;
-}
-
-// parseGoalArg — pure parse of --goal's raw value (task 1003070 / R09). 'none'
-// (case-insensitive) is the explicit opt-out; anything else must be a positive
-// integer id. Never throws — a bad value comes back as { kind: 'invalid' } so
-// main() can print one usage line and exit 2, same shape as the --priority check
-// above it.
-function parseGoalArg(raw) {
-  if (raw == null) return { kind: 'unset' };
-  const trimmed = String(raw).trim();
-  if (trimmed.toLowerCase() === 'none') return { kind: 'none' };
-  const n = Number(trimmed);
-  if (Number.isInteger(n) && n > 0) return { kind: 'id', id: n };
-  return { kind: 'invalid' };
-}
-
-// resolveActiveClaimGoal — the active-claim default (interview decision 4). /me's
-// active_claims rows (the same read claim.js/release.js already use to find "the
-// claim I'm holding") carry the task's title but not its goal, so this adds one
-// GET /tasks/:id to read it. Returns null — never throws — on no session, no
-// active claim, or a claimed task with no goal: a claim-lookup hiccup must not
-// block a capture that would otherwise have filed fine with no goal at all.
-async function resolveActiveClaimGoal({ client = cliClient } = {}) {
-  try {
-    const api = await client();
-    const me = await api.me.getMe();
-    if (!me.ok || !me.data) return null;
-    const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
-    const claim = claims[0];
-    if (!claim || claim.task_id == null) return null;
-    const t = await api.tasks.getTasksId({ id: claim.task_id });
-    if (!t.ok || !t.data || !t.data.task) return null;
-    const goalId = Number(t.data.task.goal_id);
-    if (!Number.isInteger(goalId) || goalId <= 0) return null;
-    return { goalId, taskId: claim.task_id, taskTitle: claim.title || t.data.task.title };
-  } catch (_) {
-    return null;
-  }
-}
-
-// fetchGoalSuggestion — the R07 suggester (GET /goals/suggestions), consulted
-// only when nothing else named a goal: criterion C5's "the filer never has to
-// know the goal map" promise. Returns the top candidate or null — no confident
-// match, no version to rank against, and any outage all degrade the same way,
-// because a suggester hiccup must never block a capture that would otherwise
-// file fine with no goal.
-async function fetchGoalSuggestion({ client = cliClient, version, title, kind } = {}) {
-  if (!version) return null;
-  try {
-    const api = await client();
-    // The GENERATED typed method (triage.js's precedent) — a path/param rename
-    // reds the client build instead of failing silently at runtime.
-    const r = await api.goals.getGoalsSuggestions({ query: { version, title: title || '', kind, limit: 1 } });
-    const top = r.ok && r.data && Array.isArray(r.data.suggestions) ? r.data.suggestions[0] : null;
-    return top ? { id: top.id, title: top.title, score: top.score } : null;
-  } catch (_) {
-    return null;
-  }
-}
-
-// sanitizeForTerminal — strip C0 control bytes (ANSI escapes among them) before
-// a builder/goal TITLE reaches the terminal unescaped. A title is user-authored
-// text this CLI does not own, and printing it raw would let one embed
-// cursor-control sequences in output a caller reads as plain status text
-// (grader finding, task 1003070).
-function sanitizeForTerminal(s) {
-  return String(s == null ? '' : s).replace(/[\x00-\x1f\x7f]/g, '');
-}
-
-// claimShareSubject — does the captured text have ANYTHING in common with the
-// task I happen to be holding? (task 1003859)
-//
-// WHY THE DEFAULT NEEDED A GUARD. The active-claim default is a convenience for
-// the ordinary case: you are working on X and you file something about X. But it
-// fired unconditionally, so filing an UNRELATED bug mid-session minted it into
-// the claim's goal — this very bug was filed from a session holding a security
-// task and landed in Working area 10 (Security), which has nothing to do with it,
-// and had to be moved by hand. ADR 0234's owner-interview decision is that a
-// guess must not mint work into a goal, and an inherited goal with no subject in
-// common is exactly a guess.
-//
-// Reuses criterion-suggest's tokenize — the same notion of 'these two texts are
-// about the same thing' the goal suggester ranks with, so the guard and the
-// suggester cannot disagree about what a subject word is.
-const { tokenize } = require('../../modules/lifecycle/criterion-suggest.js');
-
-function claimShareSubject(capturedText, claimTitle) {
-  const theirs = new Set(tokenize(claimTitle));
-  if (theirs.size === 0) return true; // nothing to disagree with — keep the old behaviour
-  return tokenize(capturedText).some((t) => theirs.has(t));
-}
-
-// resolveGoalForCapture — the WHOLE of --goal resolution for one capture, in the
-// interview's own precedence: an explicit id wins outright; 'none' is a hard
-// opt-out (no default, no hint); otherwise the active-claim default runs, and
-// only when THAT yields nothing does the suggester offer a hint. `lines` are
-// ready-to-print strings rather than direct console.log calls, so the decision
-// is testable without capturing stdout. Never throws (both collaborators above
-// already degrade to null on their own).
-async function resolveGoalForCapture({ goalArg, version, title, kind, client = cliClient } = {}) {
-  const claimLines = [];
-  const parsed = parseGoalArg(goalArg);
-  if (parsed.kind === 'id') return { goalId: parsed.id, lines: [] };
-  if (parsed.kind === 'none') return { goalId: null, lines: [] };
-
-  const defaulted = await resolveActiveClaimGoal({ client });
-  if (defaulted) {
-    // Only inherit when the two are actually about the same thing. When they are
-    // not, say so and fall through to the suggester — which ranks on what was
-    // WRITTEN rather than on what happens to be open — instead of filing silently
-    // into the wrong goal.
-    if (claimShareSubject(title, defaulted.taskTitle)) {
-      return {
-        goalId: defaulted.goalId,
-        lines: [`↪ defaulting --goal to ${defaulted.goalId} from your active claim on task #${defaulted.taskId} ("${sanitizeForTerminal(defaulted.taskTitle)}") — override with --goal <id>, or --goal none to file homeless.`],
-      };
-    }
-    claimLines.push(`↪ NOT defaulting to your active claim's goal: task #${defaulted.taskId} ("${sanitizeForTerminal(defaulted.taskTitle)}") shares no subject with what you filed — pass --goal ${defaulted.goalId} if it really belongs there.`);
-  }
-
-  const hint = await fetchGoalSuggestion({ client, version, title, kind });
-  if (hint) {
-    return {
-      goalId: null,
-      lines: [...claimLines, `💡 possible home: goal ${hint.id} "${sanitizeForTerminal(hint.title)}" (score ${hint.score}) — re-run with --goal ${hint.id} (or --goal none to stay homeless on purpose).`],
-    };
-  }
-  return { goalId: null, lines: claimLines };
-}
-
-// DEFAULT IS NO, and only an explicit yes counts. Extracted so the done-when
-// ("declinable in one keystroke") is a testable predicate rather than a regex
-// buried in a readline callback: a bare Enter, a stray space, an EOF (null), or
-// anything that is not y/yes all decline.
-function acceptsOffer(answer) {
-  return /^y(es)?$/i.test(String(answer == null ? '' : answer).trim());
-}
-
-// The offer. DEFAULT IS NO: a bare Enter declines and leaves a plain quick idea,
-// which is the done-when. It prints the command rather than launching an
-// interactive five-field interview — the fields are prose, the terminal is a bad
-// place to write five paragraphs, and the two surfaces built for it (the hall
-// form and /ideate) are better at it than a readline loop would ever be. So the
-// offer's job is to make the NEXT step obvious, not to become that step.
-async function offerToDevelop(ideaId) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = await new Promise((resolve) => {
-      rl.question('\nDevelop this into a Full Idea? It gets a completeness score and can earn on the ideator lane. [y/N] ', resolve);
-    });
-    if (!acceptsOffer(answer)) {
-      // Declined. Nothing further happens — the quick idea stands exactly as filed.
-      console.log('Left as a quick idea.');
-      return;
-    }
-    console.log('\nTwo ways to write it:');
-    console.log(`  in the hall:      /builders/ideas   (a live completeness meter as you type)`);
-    console.log(`  in the terminal:  node scripts/gds/spark.js --template   (then --fields-file)`);
-    console.log(`\nOr offer it up for someone else to develop:`);
-    console.log(`  node scripts/gds/spark.js ${ideaId}`);
-  } finally {
-    rl.close();
-  }
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const title = args[0];
-  if (!title || title.startsWith('--')) {
-    console.error('usage: node scripts/gds/capture.js "title" [--kind feature] [--body-file path] [--version V1|PMS-V2] [--priority N]');
-    console.error('       ... [--goal N | --goal none]        route into goal N; "none" files homeless on purpose');
-    console.error('       ... [--spark]                       offer it up for someone else to develop');
-    console.error('       ... [--full --fields-file f.json]   file a Full Idea (five fields; see spark.js --template)');
-    console.error('       ... [--no-prompt]                   never ask anything (default when not a terminal)');
-    console.error('       ... [--via planning]                a planning session\'s capture — the sky records the door (task 1004233)');
-    process.exit(2);
-  }
-
-  const kindFromArg = arg('--kind', args);
-  const bodyFile = arg('--body-file', args);
-  const versionFromArg = arg('--version', args);
-  const priorityStr = arg('--priority', args);
-  const wantSpark = hasFlag('--spark', args);
-  const wantFull = hasFlag('--full', args);
-  const fieldsFile = arg('--fields-file', args);
-  const noPrompt = hasFlag('--no-prompt', args);
-  const goalArg = arg('--goal', args);
-  // task 1004233 (sky part 5): WHICH DOOR. The server reads 'cli' off this
-  // session's token, so this CLI names nothing — except a planning session's
-  // capture, which no session can tell from any other CLI filing. Only that one
-  // value is accepted here; the server refuses every other claim the same way.
-  const viaFromArg = arg('--via', args);
-  if (viaFromArg !== null && viaFromArg !== 'planning') {
-    console.error(`--via "${viaFromArg}" is not a door this CLI may name. Where a filing came from is read off your session; the one value you may add is --via planning.`);
-    process.exit(2);
-  }
-
-  // A BAD --kind used to reach the server and come back a 400 (task 1003694).
-  // That is not merely late, it is invisible where it matters: a SCHEDULED routine
-  // filing its findings gets the 400 into a log nobody reads, the audit work still
-  // runs, and only the step that turns a finding into a durable row fails — so no
-  // queue accumulates to make the absence noticeable. dep-audit-nightly filed with
-  // `--kind security`, which is not a kind, and had therefore NEVER filed anything.
-  //
-  // Refusing here makes the same typo surface at authoring time, on the machine of
-  // whoever wrote the command, with the valid list in the message.
-  if (kindFromArg !== null) {
-    const { VALID_KINDS } = require('../../modules/ideas/inbox.js');
-    if (!VALID_KINDS.includes(kindFromArg)) {
-      console.error(`--kind "${kindFromArg}" is not a valid kind. The server would refuse this with a 400.`);
-      console.error(`Valid kinds: ${VALID_KINDS.join(', ')}`);
-      console.error('Adding a new kind is a schema change (the idea_inbox CHECK constraint) and needs its own migration + ADR.');
-      process.exit(2);
-    }
-  }
-
-  if (parseGoalArg(goalArg).kind === 'invalid') {
-    console.error(`--goal must be a positive goal id, or the literal "none" to file homeless (got "${goalArg}").`);
-    process.exit(2);
-  }
-
-  // Refused rather than resolved: --spark and --full are contradictory requests
-  // (a spark is a thought offered up BECAUSE it is not developed), and silently
-  // picking one would file something the caller did not ask for.
-  if (wantSpark && wantFull) {
-    console.error('--spark and --full are contradictory: a spark is a thought you are NOT developing yet. Pick one.');
-    process.exit(2);
-  }
-  if (wantFull && !fieldsFile) {
-    console.error('--full needs --fields-file PATH (a JSON object of the five fields).');
-    console.error('Run: node scripts/gds/spark.js --template   to see them.');
-    process.exit(2);
-  }
-  if (fieldsFile && !wantFull) {
-    console.error('--fields-file only means something with --full.');
-    process.exit(2);
-  }
-
-  let fieldValues = null;
-  if (wantFull) {
-    try {
-      fieldValues = JSON.parse(await fs.readFile(fieldsFile, 'utf8'));
-    } catch (err) {
-      console.error(`failed to read --fields-file as JSON: ${err.message}`);
-      process.exit(2);
-    }
-  }
-
-  let bodyMd = '';
-  if (bodyFile) {
-    try {
-      bodyMd = await fs.readFile(bodyFile, 'utf8');
-    } catch (err) {
-      console.error(`failed to read --body-file: ${err.message}`);
-      process.exit(2);
-    }
-  }
-
-  let priority = null;
-  if (priorityStr != null) {
-    const p = Number(priorityStr);
-    if (!Number.isInteger(p) || p < 1 || p > 5) {
-      console.error(`--priority must be an integer 1..5 (got ${priorityStr})`);
-      process.exit(2);
-    }
-    priority = p;
-  }
-
-  // The session is demanded HERE, not at the top of main(): every exit above this
-  // line is an argument error, and answering "you are not signed in" to a mistyped
-  // flag sends the caller to /builder-reauth for a session that is fine — while a
-  // builder who is NOT signed in cannot read the usage block to find out how to
-  // sign in. resolveDefaultVersion() is the first call that actually needs a token.
-  await requireSession();
-
-  const version = versionFromArg || (await resolveDefaultVersion());
-
-  // --goal resolution (task 1003070 / R09): explicit id, explicit 'none', the
-  // active-claim default, or a suggester hint — see resolveGoalForCapture's own
-  // header for the precedence. Printed before the capture call so the operator
-  // sees the routing decision as context, not an afterthought.
-  const goalResolution = await resolveGoalForCapture({ goalArg, version, title, kind: kindFromArg });
-  for (const line of goalResolution.lines) console.log(line);
-
-  const payload = {
-    title,
-    body_md: bodyMd,
-    suggested_version: version,
-    suggested_priority: priority,
-  };
-  if (kindFromArg) payload.kind = kindFromArg;
-  if (viaFromArg) payload.filed_via = viaFromArg;
-  if (goalResolution.goalId != null) payload.goal_id = goalResolution.goalId;
-  if (wantFull) {
-    // The server validates these against the R141 declaration and scores them
-    // with R142 — this CLI sends them and states nothing about their shape.
-    payload.grade = 'full';
-    payload.field_values = fieldValues;
-  }
-
-  const api = await cliClient();
-  const r = await api.inbox.postInbox({ body: payload });
-  if (!r.ok) {
-    // Surfaced verbatim, on purpose (task 1003070): the server-side rank matrix
-    // (task 1003066) is the one place that decides whether a routed filing is
-    // authorized, and this CLI does not re-derive or soften its refusal.
-    console.error(formatCaptureFailure(r.status, r.data));
-    process.exit(1);
-  }
-
-  const { idea, open_count, kind_auto, routed_task } = r.data;
-  const kindLabel = kind_auto ? `${idea.kind} (auto)` : idea.kind;
-  const versionLabel = idea.suggested_version || 'none';
-  const priorityLabel = idea.suggested_priority == null ? 'null' : `P${idea.suggested_priority}`;
-
-  const gradeLabel = idea.grade && idea.grade !== 'quick' ? `, grade=${idea.grade}` : '';
-  console.log(
-    `Captured idea #${idea.id}: kind=${kindLabel}, version=${versionLabel}, priority=${priorityLabel}${gradeLabel}`
-  );
-  // task 1003070 (R09): say where a named goal actually landed. `idea.routing`
-  // is always present when goal_id was sent (routed, or a named reason it
-  // wasn't — POST /inbox's own landing matrix decides, not this CLI).
-  if (routed_task) {
-    console.log(`  → routed into goal ${idea.routing?.goal_id ?? goalResolution.goalId} as task #${routed_task.id} (${idea.routing?.status || routed_task.status})`);
-  } else if (goalResolution.goalId != null) {
-    const reason = idea.routing?.reason;
-    console.log(`  (goal ${goalResolution.goalId} named, but filed to the inbox instead${reason ? ` — ${reason}` : ''})`);
-  }
-  if (wantFull) {
-    // The server is the authority on whether the grade write landed: capture is
-    // FAIL-OPEN on grading (R143), so an idea can land as quick with a warning.
-    // Reporting what was ASKED for instead of what happened is how a builder
-    // ends up believing they filed a Full Idea when they did not.
-    if (idea.grade === 'full') {
-      const s = idea.completeness_score;
-      console.log(`Filed as a Full Idea — completeness ${Number.isInteger(s) ? `${s}/100` : 'unscored'}.`);
-    } else {
-      console.log('NOTE: stored as a QUICK idea — the grade could not be written. The text is safe; re-file the fields when you can.');
-    }
-  }
-  console.log(`Inbox now: ${open_count} open`);
-
-  // --spark: capture, then MARK. Two requests by design, not a workaround — the
-  // capture route refuses grade='spark' (R144) because an idea does not arrive
-  // pre-marked, and the mark still goes through the author-only route.
-  if (wantSpark) {
-    const sp = await api.inbox.postInboxIdSpark({ id: idea.id, body: {} });
-    if (sp.ok) {
-      console.log('Marked as a Big Idea Spark — it is in the queue at /builders/ideas for someone to develop.');
-    } else {
-      // The idea is filed and that is the part that mattered. Say plainly that
-      // only the mark failed, and how to retry just the mark.
-      console.error(`Filed, but the spark mark failed (${sp.status}). The idea is safe; retry with:`);
-      console.error(`  node scripts/gds/spark.js ${idea.id}`);
-      process.exitCode = 1;
-    }
-    return;
-  }
-
-  // THE POST-CAPTURE OFFER (the brief: "Claude asks if you would like to submit
-  // as a full idea after a quick idea is made"). Only for a plain quick capture,
-  // only at a real terminal, and declinable with a single Enter.
-  if (!wantFull && !noPrompt && process.stdin.isTTY && process.stdout.isTTY) {
-    await offerToDevelop(idea.id);
-  }
-
-  // Migration detection lives only on the server now (POST /api/bongos/tasks sets
-  // tasks.needs_migration from the title/description on create — migration 081,
-  // task 876). Ideas carry no touches[] and aren't tasks, so the old CLI-side
-  // "keep 'migrations/' in touches[]" hint was removed with the sentinel it
-  // referred to; promotion to a task re-runs the detection automatically.
-}
-
-module.exports = {
-  resolveDefaultVersion, formatCaptureFailure, acceptsOffer,
-  parseGoalArg, resolveActiveClaimGoal, fetchGoalSuggestion, resolveGoalForCapture, sanitizeForTerminal,
-};
-
-if (require.main === module) {
-  main().catch((err) => {
-    console.error('fatal:', err);
-    process.exit(1);
-  });
-}
+// scripts/gds/capture.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/capture.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'capture.js');