@cspeach/cli 1.1.52 → 1.1.54

package/dist/tools/project/spec_answers_record.js

@@ -0,0 +1,243 @@
+/**
+ * spec_answers_record — record blocker answers the developer gives in chat
+ * (Task 18, F-O, 2026-10-26).
+ *
+ * Live: after "ok go ahead" the model ran `node -e` to edit the spec-gap
+ * `.cspeach.json` itself, inventing an `answeredBy`, and tripped the risky
+ * command card. This tool is the proper way: it runs the blocker form's own
+ * save step (saveBlockerAnswers: applyBlockerAnswers with the session's
+ * signed-in identity → validateEnvelope → write in place), so an answer
+ * recorded here is the same as one typed into the form.
+ *
+ * Path: resolved like file_read (teamReadTarget), so the folder-relative path
+ * the blocker note gives (`.cspeach/<name>.cspeach.json`) opens and saves the
+ * same file — in a team folder that is the seat copy. Containment and
+ * real-path checks are file_read's. Fix round 1: only a saved result the CLI
+ * writes (`.cspeach/<name>.cspeach.json`, isReadOnlyProjectFile), never the
+ * shared team `.cspeach` (teamReadTarget's fallback there is read-only), and
+ * only a spec-gap envelope.
+ *
+ * 2026-10-28: a spec shared in a team build (`specs/<slug>/<name>.cspeach.json`)
+ * is answered with the blocker form's record mode: the revision is validated,
+ * each answer becomes its own record in `specs/<slug>/answers/`, and the
+ * author's file is never written.
+ *
+ * Every refusal is one line and writes nothing: a sub-agent or reader child,
+ * a path outside the project, a missing file, a file that is not a spec-gap
+ * envelope in `.cspeach/`, the shared team `.cspeach`, an unknown id, a blank
+ * answer or one over 2,000 characters, an id given twice, a revision that
+ * fails validation. Ruling R18: any question id in the file is accepted.
+ *
+ * Approvals: like file_write for project files — category 'filesystem', so no
+ * card and no Rule 8 batch count (isLocalProjectWork). Never touches SAP, so
+ * the chat lane allows it.
+ */
+import { promises as fs, realpathSync } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from '../index.js';
+import { resolveSafePath, assertRealPathContained, PathOutsideRootError, isReadOnlyProjectFile, } from '../_filesystem-shared.js';
+import { pointsIntoSharedCspeach, SHARED_CSPEACH_REFUSAL, teamReadTarget } from '../_team-work-path.js';
+import { SPEC_ANSWERS_RECORD_TOOL } from '../../projects/blocker-answers-note.js';
+import { readProjectFile } from '../../projects/status.js';
+import { applyBlockerAnswers, openBlockers, saveBlockerAnswers } from '../../projects/answer-blockers.js';
+import { validateEnvelope } from '../../projects/validate.js';
+import { composeSpec, isSharedSpecPath, readAnswers, sharedSpecTargetFor, specAuthorFor, writeAnswerRecord, SPECS_DIR, } from '../../projects/spec-share.js';
+export const SPEC_ANSWERS_RECORD = SPEC_ANSWERS_RECORD_TOOL;
+/** Fix round 1 (item 4): the longest answer recorded. */
+export const MAX_ANSWER = 2000;
+const QUESTION_MAX = 80;
+const NOTHING_SAVED = 'Nothing was saved.';
+const fail = (line) => ({ content: `error: ${line}`, is_error: true });
+function clip(text, max) {
+    const one = text.replace(/\s*[\r\n]+\s*/g, ' ').trim();
+    return one.length > max ? `${one.slice(0, max - 1).trimEnd()}…` : one;
+}
+/** The same identity loop.ts gives the blocker form (getAuthorIdentity). */
+async function sessionIdentity() {
+    const { getAuthorIdentity } = await import('../../agent/loop.js');
+    return getAuthorIdentity();
+}
+function realOr(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** The build project when `real` is a spec right inside `<team>/specs/<slug>/`, else null. */
+function sharedSpecFile(cwd, real) {
+    const target = sharedSpecTargetFor(cwd, 'spec-gap');
+    if (!target || !isSharedSpecPath(target.teamDir, real) || !/\.cspeach\.json$/i.test(real))
+        return null;
+    const rel = path.relative(realOr(path.join(target.teamDir, SPECS_DIR)), real);
+    return rel.split(path.sep).length === 2 ? { projectId: target.projectId } : null;
+}
+export async function specAnswersRecordHandler(args, ctx) {
+    // Fix round 1 (item 5): only the main conversation records answers (a child could race the form).
+    if (ctx.subagent || ctx.readerMode)
+        return fail(`answers are recorded in the main conversation only. ${NOTHING_SAVED}`);
+    if (typeof args.path !== 'string' || args.path.trim() === '') {
+        return fail(`give the path of the spec-gap file, for example .cspeach/<name>.cspeach.json. ${NOTHING_SAVED}`);
+    }
+    const given = args.path;
+    // The path as file_read opens it: in a team folder a saved result is the seat copy.
+    const t = teamReadTarget(ctx.cwd, given);
+    let real;
+    try {
+        real = await assertRealPathContained(resolveSafePath(t.root, t.path), t.root);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError)
+            return fail(`that path is outside the project folder. ${NOTHING_SAVED}`);
+        if (err.code === 'ENOENT')
+            return fail(`file not found: ${given}. ${NOTHING_SAVED}`);
+        return fail(`${err instanceof Error ? err.message : String(err)}. ${NOTHING_SAVED}`);
+    }
+    // Fix round 1 (item 2): never the shared team .cspeach — teamReadTarget's
+    // fallback to it is for reading only, as for the write tools.
+    if (pointsIntoSharedCspeach(ctx.cwd, real))
+        return fail(`${SHARED_CSPEACH_REFUSAL} ${NOTHING_SAVED}`);
+    // 2026-10-28 — a spec shared in a team build (specs/<slug>/<name>.cspeach.json)
+    // is answered like the blocker form answers it there: one answer record per
+    // question beside it, the author's file never rewritten.
+    const shared = sharedSpecFile(ctx.cwd, real);
+    // Fix round 1 (item 3): only a saved result the CLI writes (.cspeach/<name>.cspeach.json),
+    // the same shape file_read's denylist carve-out opens (lane files excluded).
+    if (!shared && (!isReadOnlyProjectFile(real, t.root) || !/\.cspeach\.json$/i.test(real))) {
+        return fail(`${given} is not a spec-gap file. ${NOTHING_SAVED}`);
+    }
+    if (!(await fs.stat(real)).isFile())
+        return fail(`${given} is not a spec-gap file. ${NOTHING_SAVED}`);
+    let env;
+    try {
+        env = readProjectFile(real);
+        // R11: only the answers recorded for this envelope.
+        if (shared)
+            env = composeSpec(env, readAnswers(path.dirname(real)).filter((a) => a.file === path.basename(real)));
+    }
+    catch {
+        return fail(`${given} is not a spec-gap file. ${NOTHING_SAVED}`);
+    }
+    if (env.artefactType !== 'spec-gap')
+        return fail(`${given} is not a spec-gap file. ${NOTHING_SAVED}`);
+    // The answers: every id must be a question in the file (ruling R18: any
+    // question, not only blockers), with a non-blank answer of at most MAX_ANSWER.
+    const list = Array.isArray(args.answers) ? args.answers : null;
+    if (!list || list.length === 0)
+        return fail(`give at least one answer as { id, answer }. ${NOTHING_SAVED}`);
+    const knownIds = new Set(env.interaction.items.map((it) => it.id));
+    const answers = new Map();
+    const order = [];
+    const problems = [];
+    for (const entry of list) {
+        const id = entry && typeof entry === 'object' && typeof entry.id === 'string'
+            ? entry.id.trim() : '';
+        const raw = entry && typeof entry === 'object' ? entry.answer : undefined;
+        const answer = typeof raw === 'string' ? raw.trim() : '';
+        if (!id) {
+            problems.push('an answer has no id');
+            continue;
+        }
+        if (order.includes(id)) {
+            problems.push(`${id}: given twice`);
+            continue;
+        }
+        order.push(id);
+        if (!knownIds.has(id)) {
+            problems.push(`${id}: no question with this id in the file`);
+            continue;
+        }
+        if (!answer) {
+            problems.push(`${id}: the answer is blank`);
+            continue;
+        }
+        if (answer.length > MAX_ANSWER) {
+            problems.push(`${id}: the answer is longer than 2,000 characters`);
+            continue;
+        }
+        answers.set(id, answer);
+    }
+    if (problems.length > 0)
+        return fail(`${problems.join('; ')}. ${NOTHING_SAVED}`);
+    const identity = await sessionIdentity();
+    const nowIso = new Date().toISOString();
+    let revised;
+    if (shared) {
+        // The blocker form's record mode: check the revision, write records, never the file.
+        revised = applyBlockerAnswers(env, answers, identity, nowIso);
+        const check = validateEnvelope(JSON.parse(JSON.stringify(revised)));
+        if (!check.ok)
+            return fail(`the revised file did not validate (${check.error.message}). ${NOTHING_SAVED}`);
+        const specDir = path.dirname(real);
+        const by = specAuthorFor(shared.projectId, identity.name);
+        const done = [];
+        try {
+            for (const [gapId, answer] of answers) {
+                writeAnswerRecord(specDir, {
+                    projectId: shared.projectId, slug: path.basename(specDir), file: path.basename(real), gapId, answer, by, at: nowIso,
+                });
+                done.push(gapId);
+            }
+        }
+        catch (err) {
+            // A shared folder can fail part-way (full, read-only, sync lock): say what was recorded.
+            const why = err instanceof Error ? err.message : String(err);
+            return fail(done.length === 0
+                ? `could not write the answer records (${why}). ${NOTHING_SAVED}`
+                : `could not write every answer record (${why}). Recorded: ${done.join(', ')}. The others were not saved.`);
+        }
+    }
+    else {
+        // The form's own save step: apply with the session identity, validate, write in place.
+        const saved = saveBlockerAnswers(real, env, answers, identity, nowIso);
+        if (!saved.ok)
+            return fail(`the revised file did not validate (${saved.error}). ${NOTHING_SAVED}`);
+        revised = saved.revised;
+    }
+    const rel = path.relative(realOr(t.root), real).split(path.sep).join('/');
+    const open = openBlockers(revised);
+    return {
+        content: [
+            shared ? `Recorded for ${rel} (the spec file itself is unchanged).` : `Saved in ${rel}.`,
+            ...order.map((id) => `${id}: recorded.`),
+            open.length === 0
+                ? 'No blockers are still open.'
+                : `Still open: ${open.map((b) => `${b.id} (${clip(b.text, QUESTION_MAX)})`).join(', ')}.`,
+        ].join('\n'),
+    };
+}
+registerTool({
+    name: SPEC_ANSWERS_RECORD,
+    description: 'Record answers the developer gives in chat to spec-gap questions, in the saved spec-gap file '
+        + '(.cspeach/<name>.cspeach.json, or in a team build specs/<slug>/<name>.cspeach.json): blockers or any question in the file. The file exists only once the document has been saved, after your turn. Give each question id as in the file '
+        + '(for example gap-004) with its answer, at most 2,000 characters. '
+        + 'Answering a question that already has an answer replaces it. Nothing is saved if any id or answer is refused. '
+        + 'Never edit .cspeach.json files with shell or file-edit tools. No SAP call.',
+    isMutating: true,
+    category: 'filesystem',
+    requiresSap: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Folder-relative path of the spec-gap file, for example .cspeach/<name>.cspeach.json.',
+            },
+            answers: {
+                type: 'array',
+                description: 'One entry per question answered.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string', description: 'The question id as in the file, for example gap-004.' },
+                        answer: { type: 'string', description: "The developer's answer, in their words." },
+                    },
+                    required: ['id', 'answer'],
+                },
+            },
+        },
+        required: ['path', 'answers'],
+    },
+    handler: (args, ctx) => specAnswersRecordHandler(args, ctx),
+});

package/dist/tools/project/team_findings.js

@@ -30,7 +30,7 @@ import { registerTool } from '../index.js';
 import { findingsByObject, shownUpTo } from '../../register/findings.js';
 import { registerFor } from '../../register/picture.js';
 import { ruleProposalOf } from '../../register/decision-rules.js';
-import { activeProject, readProjectFile } from '../../register/store.js';
+import { activeProject, coreProject, readProjectFile } from '../../register/store.js';
 import { shown } from '../../register/atc-file.js';
 import { journeyPage } from '../../journey/flow.js';
 import { NOT_JOINED_LINE } from './_team-tool-shared.js';
@@ -98,7 +98,7 @@ export async function teamFindingsHandler(args, ctx) {
         const laneId = args.lane?.trim();
         const patterns = (args.packages ?? '').split(',').map((s) => s.trim()).filter(Boolean);
         // The project view, built once: the scope, its parts and every row read it.
-        const view = projectView(register, project);
+        const view = projectView(register, coreProject(project));
         let objects = view.all.objects;
         let scope = { kind: 'project', name: project.name };
         if (laneId) {

package/dist/tools/seat-gate.js

@@ -0,0 +1,41 @@
+import { WRITE_TOOLS } from './write-mode.js';
+export const SEAT_READ_ONLY_REASON = 'This seat reads SAP and never changes it. Describe the change in plain words, or write it up for the developer as cspeach-out/developer-request-<topic>.md. Do not call SAP write, transport, lock, run, test, ATC or approval tools.';
+/**
+ * Refused beyond the generic rule: the two smokes write SAP data over OData
+ * although requiresSap is false; unit tests and ATC runs execute on SAP;
+ * team_lane_move writes the team project's lanes; fiori_deploy uploads an app.
+ * shell_exec and background_run (ruling R8): their safelist runs npm, pnpm,
+ * ui5 and node, a deploy route around the fiori_deploy refusal.
+ */
+export const SEAT_EXTRA_REFUSED = new Set([
+    'fiori_draft_smoke',
+    'cap_link_smoke',
+    'sap_run_unit_test',
+    'team_lane_move',
+    'sap_atc_run',
+    'fiori_deploy',
+    'shell_exec',
+    'background_run',
+]);
+export function isSeatRefusedTool(tool) {
+    return WRITE_TOOLS.has(tool.name) || tool.name === 'request_approval' || SEAT_EXTRA_REFUSED.has(tool.name)
+        || (tool.isMutating === true && tool.requiresSap === true);
+}
+/** The model-facing refusal for this call on this seat, or null when it may run. */
+export function seatRefusal(kind, tool, args) {
+    if (kind !== 'functional')
+        return null;
+    if (isSeatRefusedTool(tool))
+        return SEAT_READ_ONLY_REASON;
+    // No approval minted elsewhere can ever be replayed from a functional seat.
+    if (args && typeof args === 'object'
+        && (Object.prototype.hasOwnProperty.call(args, 'approval_id') || Object.prototype.hasOwnProperty.call(args, 'approval_ids')))
+        return SEAT_READ_ONLY_REASON;
+    return null;
+}
+/** The tools this seat is offered. Developers: the same array, untouched. */
+export function toolsForSeat(tools, kind) {
+    if (kind !== 'functional')
+        return tools;
+    return tools.filter((t) => !isSeatRefusedTool(t));
+}

package/dist/tools/tool-loading.js

@@ -63,6 +63,8 @@ export const SKILL_STARTERS = Object.freeze({
     // Both flag-gated (LOCAL_BUILD_TOOLS / STANDALONE_FILE_TOOLS): skipped when off.
     'abap-app': ['app_lane_resolve', 'read_document'],
     'abap-atc-fix': ['sap_atc_run'],
+    // Task 18 (F-O): blocker answers given in chat are recorded with this tool, never a file edit.
+    'abap-spec-gap': ['spec_answers_record'],
     'abap-cca': ['team_estate', 'sap_atc_run', 'sap_usage_references', 'sap_api_state'],
     'abap-clean-core': ['sap_api_state', 'sap_atc_run', 'sap_usage_references', 'team_findings', 'team_lane_move'],
     'abap-data-model': ['sap_create_domain', 'sap_create_data_element', ...SESSION_TRANSPORT],

package/dist/ui/approval-modal.js

@@ -17,6 +17,7 @@ import { useReclaimRawStdin } from './widgets/reclaim-raw-stdin.js';
 import { getLook } from '../renderer/look.js';
 import { roleProps, inkChip, legacyInkColor } from './role-props.js';
 import { wrapRows } from '../renderer/wrap-rows.js';
+import { decodeDisplayBlock } from '../renderer/html-entities.js';
 import { uiWidth } from '../renderer/ui-width.js';
 import { cardBorderStyle } from './ascii-chars.js';
 /**
@@ -109,7 +110,7 @@ export function ApprovalModal({ change, effectiveRisk, transport, onApply, onSki
     const backAt = useRef(0);
     const back = () => { backAt.current = Date.now(); setViewing(false); };
     const viewLines = viewing && aff && change.diff
-        ? (aff.key === 'd' ? change.diff.split('\n') : toSourceLines(change.diff))
+        ? (aff.key === 'd' ? decodeDisplayBlock(change.diff).split('\n') : toSourceLines(change.diff))
         : [];
     const lastTop = Math.max(0, viewLines.length - viewRows);
     useInput((input, key) => {