@cspeach/cli 1.1.23 → 1.1.24

package/dist/tools/lane/app-lane-resolve.js

@@ -0,0 +1,329 @@
+// cspeach-cli/src/tools/lane/app-lane-resolve.ts
+//
+// App lane routing, slice 1, Task 5 — `app_lane_resolve`. The model fills the
+// signal sheet (values + evidence quotes); everything else is CLI code:
+//
+//   sheet check → spec text + quote strength → system facts, pin, standards
+//   → resolveLane → lane card (or the headless STOP) → runtime card when a CAP
+//   lane has no runtime → sha-pinned decision file → app-flow state → the CLI
+//   queues `/abap-plan --from @<specGap>` through the harness slot.
+//
+// Security posture:
+// - The sheet is validated with the strict schema before anything else runs;
+//   errors name only the bad keys (sanitised), never values.
+// - The spec path goes through readSpecText (string + realpath containment,
+//   denylist, size caps). Errors name the path only, never spec content.
+// - Card strings come from card.ts (sanitised, capped). STOP / summary text
+//   passes every model-influenced line through cardLine.
+// - The decision file is written only by store.ts (validated, never overwrites).
+// - The runtime answer is written only by writeRuntimeAnswer, from a card value.
+// - pendingDispatch gets a CLI-built string only: a fixed prefix plus the
+//   session's spec-gap path, through the shared chainFromToken (lane/chain-token.ts).
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool, isStandalone } from '../index.js';
+import { PathOutsideRootError } from '../_filesystem-shared.js';
+import { assertNotCliHome, containSpecPath, laneRootFor, specDisplayPath } from '../../lane/roots.js';
+import { signalSheetSchema, withStrength } from '../../lane/signals.js';
+import { factsFromStandalone, factsFromSystemInfo, findQuote, readLanePin, readSpecText, readStandardsLane, writeRuntimeAnswer, } from '../../lane/inputs.js';
+import { BUILT_LANES, resolveLane, uiFor } from '../../lane/resolve.js';
+import { writeLaneDecision } from '../../lane/store.js';
+import { getAppFlow, setLane } from '../../lane/app-flow.js';
+import { chainFromToken } from '../../lane/chain-token.js';
+import { cardLine, interactiveRunLine, laneCardRequest, quoteNotFoundFacts, runtimeCardRequest, shownToken, } from '../../lane/card.js';
+import { cardSlotEmitter } from '../../ui/card-slot.js';
+import { askConfirm } from '../../ui/confirm-request.js';
+import { isHeadless } from '../../renderer/tty.js';
+import { loadConfig } from '../../config/loader.js';
+import { getSapSystemInfo } from '../../sap/system-info.js';
+const fail = (message) => ({ content: `error: ${message}`, is_error: true });
+const NOT_CHOSEN = 'Lane not chosen. Nothing was saved.';
+const STOP = 'STOP — lane needs your choice.';
+const UNKNOWN_FACTS = { source: 'unknown', tier: 'unknown', label: 'unknown' };
+const RUNTIMES = ['btp', 'own-server', 'none'];
+/** A sheet key for an error line: identifier characters only, capped. */
+const keyName = (k) => String(k).replace(/[^A-Za-z0-9_]/g, '').slice(0, 40) || '(unnamed)';
+function sheetError(issues) {
+    const bad = new Set();
+    let notObject = false;
+    for (const i of issues) {
+        if (i.code === 'unrecognized_keys' && i.path.length === 0) {
+            for (const k of i.keys ?? [])
+                bad.add(`${keyName(k)} (unknown key)`);
+        }
+        else if (i.path.length === 0) {
+            notObject = true;
+        }
+        else {
+            bad.add(keyName(i.path[0]));
+        }
+    }
+    if (notObject && bad.size === 0)
+        return 'signals must be an object with one entry per signal key.';
+    return `the signal sheet is not valid. Fix these keys and call again: ${[...bad].join(', ')}.`;
+}
+async function defaultFacts(ctx) {
+    try {
+        if (isStandalone(ctx)) {
+            return factsFromStandalone((await loadConfig()).standalone);
+        }
+        return factsFromSystemInfo(await getSapSystemInfo(ctx.adt, ctx.sapAlias));
+    }
+    catch {
+        return { ...UNKNOWN_FACTS };
+    }
+}
+/** Headless, or no Ink card slot (classic REPL / one-shot): a card could never be answered. */
+function defaultHeadless() {
+    return isHeadless() || cardSlotEmitter.listenerCount('confirm') === 0;
+}
+/** M1 — a person is at the terminal but no card can be shown (the classic REPL). */
+function defaultNoCardTerminal() {
+    return !isHeadless() && cardSlotEmitter.listenerCount('confirm') === 0;
+}
+/**
+ * True when the app flow's `@spec` token and the given absolute path are the
+ * same real file inside cwd or the workspace folder (I3: the same containment
+ * as readSpecText).
+ */
+async function sameFile(cwd, token, abs) {
+    const tok = token.trim().replace(/^@/, '');
+    if (tok === '')
+        return false;
+    try {
+        const { real: a } = await containSpecPath(cwd, tok);
+        const b = await fs.realpath(abs);
+        const norm = (p) => (process.platform === 'win32' ? path.resolve(p).toLowerCase() : path.resolve(p));
+        return norm(a) === norm(b);
+    }
+    catch {
+        return false;
+    }
+}
+const LANE_WORDS = {
+    rap: 'on-stack RAP', cap: 'CAP (side-by-side)', none: 'UI only', 'abap-report': 'classic report', segw: 'SEGW',
+};
+function stopText(d, extra, specLine) {
+    const lines = [STOP, specLine];
+    if (d.needsRuntime && !d.neutral && !d.noAppLane) {
+        lines.push(`Recommended lane: ${LANE_WORDS.cap}. The CAP lane needs to know where the app will run.`);
+    }
+    else if (d.backend && !d.noAppLane) {
+        lines.push(`Recommended lane: ${LANE_WORDS[d.backend]}.`);
+    }
+    else {
+        lines.push('No app lane is available on this system.');
+    }
+    lines.push('Why:');
+    for (const r of [...d.reasons, ...extra])
+        lines.push(`- ${cardLine(r)}`);
+    if (d.needsRuntime && !d.neutral && !d.noAppLane) {
+        lines.push('To confirm: add `[app-lane] runtime = "btp|own-server|none"` to .cspeach/conventions.toml and run /abap-app again.');
+    }
+    else if (d.backend && !d.noAppLane) {
+        lines.push(`To confirm: Add \`[app-lane] backend = "${d.backend}"\` to .cspeach/conventions.toml and run /abap-app again.`);
+    }
+    else {
+        const choices = d.allowed.filter((l) => l !== 'segw').join(', ');
+        lines.push(`To choose: add \`[app-lane] backend = "<lane>"\` (one of: ${choices}) to .cspeach/conventions.toml and run /abap-app again.`);
+    }
+    lines.push('Nothing was saved.');
+    return lines.join('\n');
+}
+export async function appLaneResolveHandler(args, ctx, deps = {}) {
+    // 0. Task 7 review round 2 — inside an /abap-app flow the lane is chosen
+    // only at the lane step (after the spec-gap save, before the plan). Nothing
+    // else runs: no card, no file, the flow and the queue stay as they are.
+    // No flow at all → today's behaviour.
+    const step = getAppFlow(ctx.session)?.expect;
+    if (step !== undefined && step !== 'lane') {
+        return fail(step === 'spec-gap'
+            ? 'the app flow is not at the lane step yet: save the spec-gap first.'
+            : 'the app flow is not at the lane step: the lane is already chosen and the plan is next.');
+    }
+    // 1. The sheet, strictly, before anything else.
+    const parsed = signalSheetSchema.safeParse(args?.signals);
+    if (!parsed.success)
+        return fail(sheetError(parsed.error.issues));
+    if (typeof args?.specPath !== 'string' || args.specPath.trim() === '') {
+        return fail('specPath must be the spec file path, relative to the workspace.');
+    }
+    const specPath = args.specPath;
+    // 2. Spec text (contained) and signal strength.
+    let spec;
+    try {
+        spec = await readSpecText(ctx.cwd, specPath);
+    }
+    catch (e) {
+        if (e instanceof PathOutsideRootError)
+            return fail('the spec path must be inside the workspace.');
+        return fail(cardLine(e instanceof Error ? e.message : 'the spec file cannot be read.'));
+    }
+    const specSha = spec.sha256;
+    const specRel = specDisplayPath(ctx.cwd, spec.abs);
+    // The lane check must use the spec /abap-app was started with: a model may
+    // not match its quotes against some other workspace file (one it just wrote).
+    const flow = getAppFlow(ctx.session);
+    if (flow && !(await sameFile(ctx.cwd, flow.specToken, spec.abs))) {
+        return fail(cardLine(`This lane check must use the spec you started /abap-app with: ${flow.specToken}`));
+    }
+    const specLine = cardLine(`Spec: ${specRel}`);
+    const signals = withStrength(parsed.data, spec.text, findQuote, spec.normalise);
+    // 3–4. Facts, pin, standards.
+    const facts = await (deps.facts ?? defaultFacts)(ctx).catch(() => ({ ...UNKNOWN_FACTS }));
+    // R18 — the project pin lives on the lane root, next to .cspeach/lane.
+    const laneRoot = await laneRootFor(ctx.cwd);
+    // Final residual 2 — a lane root that is the CLI home is refused before any read or card.
+    try {
+        await assertNotCliHome(laneRoot);
+    }
+    catch (e) {
+        return fail(cardLine(e instanceof Error ? e.message : String(e)));
+    }
+    const [pinR, stdR] = await Promise.all([readLanePin(laneRoot), readStandardsLane(ctx.cwd)]);
+    const warnings = [pinR.warning, stdR.warning].filter((w) => !!w);
+    const runtimeKnown = !!pinR.pin?.runtime || !!stdR.pin?.runtime;
+    // 5. Resolve.
+    const decision = resolveLane({ signals, facts, pin: pinR.pin, standards: stdR.pin, runtimeKnown });
+    const extraFacts = [...quoteNotFoundFacts(signals), ...warnings.map(cardLine)];
+    const cardFacts = [specLine, ...extraFacts];
+    let finalLane;
+    let decidedBy = decision.decidedBy;
+    let runtime = pinR.pin?.runtime ?? stdR.pin?.runtime;
+    const headless = (deps.headless ?? defaultHeadless)();
+    if (headless) {
+        // 6. Headless: never a card. Choices that need a person stop here.
+        if (decision.neutral || decision.noAppLane || decision.needsRuntime || !decision.backend) {
+            return { content: stopText(decision, extraFacts, specLine) };
+        }
+        finalLane = { backend: decision.backend, ui: decision.ui, ...(decision.floorplan ? { floorplan: decision.floorplan } : {}) };
+    }
+    else {
+        // 7. The lane card.
+        const confirm = deps.confirm ?? ((req) => askConfirm(req));
+        const card = laneCardRequest(decision);
+        const res = await confirm({ ...card, facts: [...(card.facts ?? []), ...cardFacts] });
+        const value = res.value;
+        const offered = new Set(card.choices.map((c) => c.value));
+        if (!value || value === 'cancel' || !offered.has(value))
+            return { content: NOT_CHOSEN };
+        if (value === 'confirm') {
+            if (!decision.backend || decision.noAppLane)
+                return { content: NOT_CHOSEN };
+            finalLane = { backend: decision.backend, ui: decision.ui, ...(decision.floorplan ? { floorplan: decision.floorplan } : {}) };
+        }
+        else {
+            const lane = value.slice('switch:'.length);
+            if (!value.startsWith('switch:') || !BUILT_LANES.includes(lane) || !decision.allowed.includes(lane)) {
+                return { content: NOT_CHOSEN };
+            }
+            const usable = (p) => (p && (!p.backend || decision.allowed.includes(p.backend)) ? p : undefined);
+            const { ui, floorplan } = uiFor(lane, signals, usable(pinR.pin)?.ui ?? usable(stdR.pin)?.ui);
+            finalLane = { backend: lane, ui, ...(floorplan ? { floorplan } : {}) };
+            decidedBy = 'developer';
+        }
+        // 8. A CAP lane needs a runtime.
+        if (finalLane.backend === 'cap' && !runtime) {
+            const rr = await confirm(runtimeCardRequest());
+            const answer = rr.value;
+            if (!answer || !RUNTIMES.includes(answer))
+                return { content: 'Runtime not chosen. Nothing was saved.' };
+            try {
+                await assertNotCliHome(laneRoot);
+                await writeRuntimeAnswer(laneRoot, answer);
+            }
+            catch (e) {
+                const why = e instanceof Error ? e.message : 'the runtime answer could not be saved';
+                return {
+                    content: `${cardLine(why)}\nThe runtime is still unknown, so the lane was not saved. Nothing was saved. ` +
+                        'Add the runtime to .cspeach/conventions.toml, then run /abap-app again.',
+                };
+            }
+            runtime = answer;
+        }
+    }
+    // 9. The decision file, the flow state, the queued plan.
+    if (finalLane.backend === 'cap' && runtime)
+        finalLane = { ...finalLane, runtime };
+    // Task 7 review R10 — the shared chain token: CLI state only (the app flow's
+    // saved spec-gap path, never a tool argument), contained to cwd or the save root.
+    const gap = flow?.specGapPath ? await chainFromToken(ctx.cwd, flow.specGapPath) : undefined;
+    const planCmd = gap ? `/abap-plan --from ${gap.token}` : undefined;
+    let written;
+    try {
+        // I3 — one lane root for the write, every pinned read and from.lane.path.
+        await assertNotCliHome(laneRoot);
+        written = await writeLaneDecision(laneRoot, {
+            spec: { path: specRel, sha256: specSha },
+            ...(gap ? { specGap: { path: gap.path } } : {}),
+            recommendation: decision,
+            final: finalLane,
+            decidedBy,
+        });
+    }
+    catch (e) {
+        return fail(`the lane decision could not be saved: ${e instanceof Error ? cardLine(e.message) : 'write failed'}`);
+    }
+    setLane(ctx.session, written.path, written.sha256, planCmd);
+    const who = decidedBy === 'developer' ? 'the developer'
+        : decidedBy === 'pin' ? `project pin (${decision.decidedByPath ?? '.cspeach/conventions.toml'})`
+            : decidedBy === 'standards' ? `standards file (${decision.decidedByPath ?? 'unknown file'})`
+                : 'the spec and the rules';
+    const ui = finalLane.ui === 'none' ? '' : ` + ${finalLane.ui}${finalLane.floorplan ? ` (${finalLane.floorplan})` : ''}`;
+    const lines = [
+        `Lane: ${finalLane.backend}${ui}${finalLane.runtime ? `, runtime ${finalLane.runtime}` : ''}.`,
+        `Decided by: ${cardLine(who)}.`,
+        `Decision file: ${written.path}`,
+    ];
+    if (warnings.length)
+        lines.push(...warnings.map((w) => `Warning: ${cardLine(w)}`));
+    // M1 — the classic REPL has no card listener, so the rules took the lane:
+    // tell the person at the terminal in one plain line (no inquirer fallback).
+    if (headless && (deps.noCardTerminal ?? defaultNoCardTerminal)()) {
+        const shown = `${finalLane.backend}${ui}${finalLane.runtime ? `, runtime ${finalLane.runtime}` : ''}`;
+        ctx.chunkEmitter?.emit('info', `Lane chosen by the rules (no confirm card in this terminal): ${shown}.`);
+    }
+    if (flow?.specGapPath && planCmd) {
+        ctx.pendingDispatch?.set(planCmd);
+        lines.push('Next: the plan is being created.');
+    }
+    else if (flow?.specGapPath && headless) {
+        // I4(c) — headless / one-shot: no flow reaches a later run.
+        lines.push(interactiveRunLine(flow.specToken));
+    }
+    else if (flow?.specGapPath) {
+        // I4(b) — the flow is at the plan step: this typed command keeps it.
+        lines.push(`The spec-gap file path could not be used to queue the plan. To go on, run: /abap-plan --from ${shownToken(path.basename(flow.specGapPath), 'spec-gap file')}`);
+    }
+    else {
+        lines.push('No spec-gap file in this session yet, so no plan was queued.');
+        if (headless)
+            lines.push(interactiveRunLine(specRel));
+    }
+    return { content: lines.join('\n') };
+}
+registerTool({
+    name: 'app_lane_resolve',
+    description: 'App lane routing for /abap-app. Pass the spec file path and the signal sheet: for each fixed key a value and, ' +
+        'when the value is true / a service name, an evidence quote copied word for word from the spec (max 300 chars). ' +
+        'The CLI checks the quotes, reads the system facts, the project pin and the standards file, picks the lane, ' +
+        'shows the lane card, saves the decision file and queues the plan. Never guess a lane yourself. ' +
+        'Keys: app_requested, ui_only_service (string|null), report_only, analytical, transactional, custom_ui, ' +
+        'cap_external_users, cap_multi_system, cap_own_release_cycle, cap_ui_on_released_api.',
+    isMutating: false,
+    requiresSap: false,
+    category: 'project',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            specPath: { type: 'string', description: 'Spec file, relative to the workspace (.md, .txt, .docx, .pdf, .xlsx).' },
+            signals: {
+                type: 'object',
+                description: 'One entry per key: { value, evidence? }. evidence = an exact quote from the spec.',
+            },
+        },
+        required: ['specPath', 'signals'],
+    },
+    handler: (args, ctx) => appLaneResolveHandler(args, ctx),
+});

package/dist/tools/local-build.js

@@ -82,6 +82,8 @@ export const LOCAL_BUILD_TOOLS = [
     'sap_link',
     // CAP phase 2 (Task 11) — S/4 link check: live read vs direct S/4, dev-only update-then-restore.
     'cap_link_smoke',
+    // App lane routing (slice 1, Task 5) — reads the spec file like read_document; writes only .cspeach/lane + [app-lane].
+    'app_lane_resolve',
     'extend_model_insert',
     'system_capability',
     'agent_run',
@@ -109,6 +111,8 @@ export const STANDALONE_FILE_TOOLS = [
     'file_edit',
     'glob',
     'grep',
+    // App lane routing — /abap-app in standalone mode decides the lane on declared facts.
+    'app_lane_resolve',
 ];
 export function applyStandaloneFileTools(cwd) {
     enableToolFlags([...STANDALONE_FILE_TOOLS]);

package/dist/tools/tool-loading.js

@@ -53,6 +53,8 @@ export const SKILL_STARTERS = Object.freeze({
     'abap-transport': TRANSPORT_FAMILY,
     'abap-transport-analysis': [...TRANSPORT_FAMILY, 'sap_atc_run', 'sap_usage_references'],
     'abap-cap': ['fiori_scaffold_fe', 'fiori_render_smoke', 'fiori_draft_smoke'],
+    // 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'],
     'abap-cca': ['sap_atc_run', 'sap_usage_references', 'sap_api_state'],
     'abap-clean-core': ['sap_api_state', 'sap_atc_run', 'sap_usage_references'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cspeach/cli",
-  "version": "1.1.23",
+  "version": "1.1.24",
   "description": "CSPeach — AI-assisted ABAP development CLI. Direct SAP access, 34 skills, safety gates.",
   "keywords": [
     "abap",