@cspeach/cli 1.1.23 → 1.1.24

package/dist/lane/roots.js

@@ -0,0 +1,113 @@
+// App lane routing — final fix wave I3. The ONE root the lane decision folder
+// hangs off, and the spec containment rule, shared by every caller:
+//
+// - laneRootFor(cwd): the folder that contains the workspace `.cspeach` —
+//   the git root (or cwd) for the default workspace, the configured
+//   `workspace_folder` itself otherwise (R17; never the CLI home). The lane write, every pinned read
+//   and the relative `from.lane.path` (`.cspeach/lane/<id>.json`) all use it,
+//   so a lane written from a repo subfolder is found by a resume from the
+//   repo root (plans already resolve through the workspace folder).
+// - containSpecPath(cwd, p): a spec is accepted inside cwd OR the workspace
+//   folder, string-contained AND realpath-contained (no link escapes), and
+//   refused when ANY of those roots (or the lane root) would denylist it.
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveWorkspacePathFor } from '../projects/workspace.js';
+import { loadConfig } from '../config/loader.js';
+import { cspeachRoot } from '../config/paths.js';
+import { isDenylistedPath, PathOutsideRootError } from '../tools/_filesystem-shared.js';
+/** The workspace folder for this cwd (config override > git root > cwd), absolute. */
+export async function workspaceFolderFor(cwd) {
+    try {
+        return path.resolve(await resolveWorkspacePathFor(cwd));
+    }
+    catch {
+        return path.resolve(cwd, '.cspeach');
+    }
+}
+/**
+ * The folder whose `.cspeach/lane/` (and `.cspeach/conventions.toml`, R18)
+ * belong to this project.
+ * - R17: a configured `workspace_folder` is the root ITSELF
+ *   (`<workspace_folder>/.cspeach/lane`), never its parent — so `~/CSPeach`
+ *   never puts lane files in the CLI home `~/.cspeach`.
+ * - Default workspace (`<git-root or cwd>/.cspeach`): the git root (or cwd).
+ */
+export async function laneRootFor(cwd) {
+    let configured;
+    try {
+        configured = (await loadConfig()).workspace_folder?.trim() || undefined;
+    }
+    catch {
+        configured = undefined;
+    }
+    if (configured)
+        return workspaceFolderFor(cwd);
+    return path.dirname(await workspaceFolderFor(cwd));
+}
+/**
+ * R17 — refuse a lane root whose `.cspeach` is the CLI home (`~/.cspeach`,
+ * config + credentials): no lane or conventions file is ever written there.
+ */
+export async function assertNotCliHome(root) {
+    // Final residual 2 — compare REAL paths, so a junction / symlink to home
+    // (or to ~/.cspeach) cannot slip past a string compare. `.cspeach` may not
+    // exist yet: then the root itself must not be the home folder.
+    const key = async (p) => {
+        const r = await realOr(p);
+        return process.platform === 'win32' ? r.toLowerCase() : r;
+    };
+    const [dot, cliHome, rootReal, home] = await Promise.all([
+        key(path.join(root, '.cspeach')), key(cspeachRoot()), key(root), key(os.homedir()),
+    ]);
+    if (dot === cliHome || rootReal === home) {
+        throw new Error('the lane folder would be inside the cspeach home folder (~/.cspeach). Set workspace_folder to a project folder.');
+    }
+}
+const inside = (p, root) => {
+    const rel = path.relative(root, p);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+const realOr = async (p) => fs.realpath(p).catch(() => path.resolve(p));
+export class SpecProtectedError extends Error {
+    constructor(specPath) {
+        super(`spec file is in a protected location and cannot be read: ${specPath}`);
+        this.name = 'SpecProtectedError';
+    }
+}
+/**
+ * Contain a spec path to cwd or the workspace folder. Returns the absolute
+ * path and its real path. Throws PathOutsideRootError (outside both roots, or
+ * a link out of them), SpecProtectedError (denylisted under any root) or the
+ * realpath error (ENOENT when the file does not exist).
+ */
+export async function containSpecPath(cwd, specPath) {
+    if (typeof specPath !== 'string' || specPath.includes('\0'))
+        throw new PathOutsideRootError(String(specPath), cwd);
+    const absCwd = path.resolve(cwd);
+    const abs = path.isAbsolute(specPath) ? path.resolve(specPath) : path.resolve(absCwd, specPath);
+    const ws = await workspaceFolderFor(cwd);
+    const roots = [absCwd, ws];
+    if (!roots.some((r) => inside(abs, r)))
+        throw new PathOutsideRootError(specPath, cwd);
+    const real = await fs.realpath(abs);
+    const realRoots = await Promise.all(roots.map(realOr));
+    if (!realRoots.some((r) => inside(real, r)))
+        throw new PathOutsideRootError(specPath, cwd);
+    const guards = [...realRoots, await realOr(await laneRootFor(cwd))];
+    for (const r of guards) {
+        if (inside(real, r) && isDenylistedPath(real, r).blocked)
+            throw new SpecProtectedError(specPath);
+    }
+    return { abs, real };
+}
+/**
+ * The spec path as stored in the flow / the lane record and shown on the
+ * card: relative to cwd when inside it, else absolute — forward slashes.
+ */
+export function specDisplayPath(cwd, abs) {
+    const absCwd = path.resolve(cwd);
+    const p = inside(abs, absCwd) ? path.relative(absCwd, abs) : path.resolve(abs);
+    return p.split(path.sep).join('/');
+}

package/dist/lane/signals.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/** Fixed keys (spec §6). The model fills value + quote; strength is ours. */
+export const SIGNAL_KEYS = [
+    'app_requested', // the spec asks for an app (not only a report)
+    'ui_only_service', // string: the published OData service the spec names, when it asks only for a UI
+    'report_only', // classic list / ALV output, no app
+    'analytical', // charts / KPIs
+    'transactional', // create / update / delete
+    'custom_ui', // custom layouts / controls a standard floorplan cannot express
+    'cap_external_users', // users outside SAP
+    'cap_multi_system', // data from several systems
+    'cap_own_release_cycle', // own release cycle / scales on its own
+    'cap_ui_on_released_api', // mostly UI + logic on top of a released SAP API
+];
+const MIN_QUOTE = 8;
+const entry = (value) => z.object({ value, evidence: z.string().max(300).optional() }).strict();
+export const signalSheetSchema = z.object({
+    app_requested: entry(z.boolean()),
+    ui_only_service: entry(z.string().trim().min(1).max(200).nullable()),
+    report_only: entry(z.boolean()),
+    analytical: entry(z.boolean()),
+    transactional: entry(z.boolean()),
+    custom_ui: entry(z.boolean()),
+    cap_external_users: entry(z.boolean()),
+    cap_multi_system: entry(z.boolean()),
+    cap_own_release_cycle: entry(z.boolean()),
+    cap_ui_on_released_api: entry(z.boolean()),
+}).strict();
+/** Collapse whitespace runs to one space and trim. */
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+/** Curly quotes and en/em dashes to ASCII, so a quote copied from Word still matches. */
+const asciiPunct = (s) => s.replace(/[\u2018\u2019]/g, "'").replace(/[\u201C\u201D]/g, '"').replace(/[\u2013\u2014]/g, '-');
+/**
+ * Canonical quote matcher: whitespace collapsed and curly quotes / dashes mapped to
+ * ASCII on BOTH sides, then a case-sensitive substring check. No paraphrase tolerance.
+ */
+export function findNormalised(text, quote) {
+    const q = collapse(asciiPunct(quote));
+    if (q === '')
+        return false;
+    return collapse(asciiPunct(text)).includes(q);
+}
+/**
+ * Strong = a truthy value AND a quote of ≥ 8 chars (after whitespace collapse) found word for word in the spec.
+ *
+ * I2 (final review) — `normalise` is the strip that produced `specText` from
+ * the document (readSpecText's `normalise`; identity for plain text). Each
+ * quote and the `ui_only_service` value are checked as written AND after that
+ * same strip — never any looser — so a quote copied from the turndown text
+ * (`ZI\_SALES`, `**bold**`) matches the stripped spec text.
+ */
+export function withStrength(sheet, specText, find, normalise = (s) => s) {
+    const forms = (s) => {
+        const n = normalise(s);
+        return n === s ? [s] : [s, n];
+    };
+    const out = {};
+    for (const k of SIGNAL_KEYS) {
+        const e = sheet[k];
+        const quoteFound = forms(e.evidence ?? '').some((f) => {
+            const q = collapse(f);
+            return q.length >= MIN_QUOTE && find(specText, q);
+        });
+        const truthy = typeof e.value === 'string' ? e.value.trim() !== '' : e.value === true;
+        // ui_only_service: the named service must itself appear in the spec, so a real
+        // quote cannot carry a made-up service name. The value kept is the form found
+        // in the spec (a docx `ZSALES\_SRV` is stored as `ZSALES_SRV`).
+        let value = e.value;
+        let serviceNamed = k !== 'ui_only_service';
+        if (k === 'ui_only_service' && typeof e.value === 'string') {
+            const hit = forms(e.value).find((f) => findNormalised(specText, f));
+            if (hit !== undefined) {
+                serviceNamed = true;
+                value = hit;
+            }
+        }
+        out[k] = { value, evidence: e.evidence, quoteFound, strength: truthy && quoteFound && serviceNamed ? 'strong' : 'weak' };
+    }
+    return out;
+}

package/dist/lane/store.js

@@ -0,0 +1,232 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, writeFile } from 'node:fs/promises';
+import { join, posix, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { LANE_DIR, LANE_NAME_RE } from './paths.js';
+export class LaneShaMismatchError extends Error {
+    path;
+    expected;
+    actual;
+    constructor(path, expected, actual) {
+        super(`The lane decision file ${path} was changed after the lane card was confirmed, so it will not be used. Run /abap-app again to choose the lane.`);
+        this.path = path;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'LaneShaMismatchError';
+    }
+}
+const MAX_BYTES = 256 * 1024;
+const NAME = LANE_NAME_RE;
+const backendLane = z.enum(['rap', 'cap', 'none', 'abap-report', 'segw']);
+const uiLane = z.enum(['fiori-elements', 'freestyle', 'none']);
+const floorplan = z.enum(['listReport', 'worklist', 'ovp', 'alp']);
+const runtime = z.enum(['btp', 'own-server', 'none']);
+const decidedBy = z.enum(['pin', 'standards', 'rules', 'developer']);
+const tier = z.enum(['s4-2020-plus', 's4-before-2020', 'ecc-ehp7-plus', 'ecc-old', 'netweaver-740-plus', 'netweaver-old', 'unknown']);
+const laneDecisionSchema = z.object({
+    backend: backendLane.nullable(),
+    ui: uiLane,
+    floorplan: floorplan.optional(),
+    decidedBy,
+    decidedByPath: z.string().optional(),
+    neutral: z.boolean(),
+    noAppLane: z.boolean(),
+    needsRuntime: z.boolean(),
+    allowed: z.array(backendLane),
+    crossedOut: z.array(z.object({ lane: z.union([backendLane, z.literal('bopf-generated')]), reason: z.string() })),
+    reasons: z.array(z.string()),
+    weakHints: z.array(z.string()),
+    unverified: z.boolean(),
+    facts: z.object({ source: z.enum(['probed', 'declared', 'unknown']), tier, label: z.string() }),
+});
+const laneRecordSchema = z.object({
+    id: z.string().min(1),
+    createdAt: z.string().min(1),
+    spec: z.object({ path: z.string(), sha256: z.string() }),
+    specGap: z.object({ path: z.string() }).optional(),
+    recommendation: laneDecisionSchema,
+    final: z.object({ backend: backendLane, ui: uiLane, floorplan: floorplan.optional(), runtime: runtime.optional() }),
+    decidedBy,
+}).superRefine((r, ctx) => {
+    if (r.final.backend === 'segw') {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['final', 'backend'], message: 'segw is not a pickable lane yet' });
+    }
+    if (!r.recommendation.allowed.includes(r.final.backend)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['final', 'backend'], message: `${r.final.backend} is not an allowed lane on this system` });
+    }
+    const changed = r.final.backend !== r.recommendation.backend || r.final.ui !== r.recommendation.ui;
+    if (changed && r.decidedBy !== 'developer') {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['decidedBy'], message: 'a lane that differs from the recommendation must be decided by the developer' });
+    }
+});
+const shapeError = (rel, err) => {
+    const first = err.issues[0];
+    return new Error(`The lane decision file ${rel} is not a valid lane decision (${first?.path.join('.') || 'root'}: ${first?.message ?? 'bad shape'}).`);
+};
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** sha256 of the file bytes. */
+export async function laneFileSha(abs) {
+    return sha256(await readFile(abs));
+}
+const LANE_CHAIN = ['.cspeach', LANE_DIR];
+async function assertPlainDir(cwd, rel) {
+    const st = await lstat(join(cwd, rel));
+    if (st.isSymbolicLink() || !st.isDirectory()) {
+        throw new Error(`${rel} must be a plain folder, not a symlink.`);
+    }
+}
+/** Refuse when any part of the lane folder chain is a symlink / junction (or not a folder). */
+async function assertRealDirs(cwd) {
+    for (const rel of LANE_CHAIN)
+        await assertPlainDir(cwd, rel);
+}
+/**
+ * Create the lane folder chain one level at a time, checking each level BEFORE
+ * anything is created beneath it, so a linked `.cspeach` never gets a folder made
+ * inside its target.
+ */
+async function ensureLaneDir(cwd) {
+    for (const rel of LANE_CHAIN) {
+        try {
+            await mkdir(join(cwd, rel));
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+        await assertPlainDir(cwd, rel);
+    }
+}
+const today = () => new Date().toISOString().slice(0, 10).replace(/-/g, '');
+/**
+ * Write a new lane decision file. Never overwrites: flag `wx`, fresh random id.
+ * Returns the workspace-relative path (forward slashes) and the sha256 of the bytes written.
+ */
+export async function writeLaneDecision(cwd, rec) {
+    const probe = laneRecordSchema.safeParse({ id: 'lane-check', createdAt: new Date().toISOString(), ...rec });
+    if (!probe.success)
+        throw shapeError('(new)', probe.error);
+    await ensureLaneDir(cwd);
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const id = `lane-${today()}-${randomBytes(3).toString('hex')}`;
+        const full = laneRecordSchema.parse({ id, createdAt: new Date().toISOString(), ...rec });
+        const text = `${JSON.stringify(full, null, 2)}\n`;
+        const rel = `${LANE_DIR}/${id}.json`;
+        try {
+            await writeFile(join(cwd, rel), text, { encoding: 'utf8', flag: 'wx' });
+        }
+        catch (e) {
+            if (e.code === 'EEXIST')
+                continue;
+            throw e;
+        }
+        return { path: rel, sha256: sha256(Buffer.from(text, 'utf8')) };
+    }
+    throw new Error('Could not pick a free name for the lane decision file.');
+}
+/** Only `.cspeach/lane/<name>.json`; no backslashes, no `..`, no absolute paths, no subfolders. */
+function containedLanePath(relPath) {
+    const refuse = () => new Error(`Refused: a lane decision must be a file directly in ${LANE_DIR}/ (got ${JSON.stringify(relPath.slice(0, 200))}).`);
+    if (typeof relPath !== 'string' || relPath === '' || /[\\\u0000]/.test(relPath))
+        throw refuse();
+    if (posix.isAbsolute(relPath) || /^[A-Za-z]:/.test(relPath))
+        throw refuse();
+    if (relPath.split('/').includes('..'))
+        throw refuse();
+    const norm = posix.normalize(relPath);
+    if (!NAME.test(norm))
+        throw refuse();
+    return norm;
+}
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const tooLarge = (rel) => new Error(`Refused: ${rel} is too large (over 256 KB).`);
+/** Open once, fstat the handle, read at most MAX+1 bytes from that same handle. */
+async function readCapped(abs, rel) {
+    const fh = await open(abs, constants.O_RDONLY | NOFOLLOW);
+    try {
+        const st = await fh.stat();
+        if (!st.isFile())
+            throw new Error(`Refused: ${rel} is not a plain file.`);
+        if (st.size > MAX_BYTES)
+            throw tooLarge(rel);
+        const buf = Buffer.alloc(MAX_BYTES + 1);
+        let total = 0;
+        while (total < buf.length) {
+            const { bytesRead } = await fh.read(buf, total, buf.length - total, total);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+        }
+        if (total > MAX_BYTES)
+            throw tooLarge(rel);
+        return buf.subarray(0, total);
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Read a lane decision file. Refuses paths outside `.cspeach/lane/`, symlinks and
+ * files over 256 KB; validates the shape; throws LaneShaMismatchError when
+ * `expectedSha` is given and the file bytes differ. Internal / tests: callers
+ * that act on a lane use readPinnedLaneDecision.
+ */
+export async function readLaneDecision(cwd, relPath, expectedSha) {
+    const rel = containedLanePath(relPath);
+    const root = resolve(cwd, LANE_DIR);
+    const abs = resolve(cwd, rel);
+    if (!abs.startsWith(root + sep))
+        throw new Error(`Refused: ${rel} is outside ${LANE_DIR}/.`);
+    let st;
+    try {
+        st = await lstat(abs);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            throw new Error(`Lane decision file not found: ${rel}.`);
+        throw e;
+    }
+    if (st.isSymbolicLink())
+        throw new Error(`Refused: ${rel} is a symlink.`);
+    if (!st.isFile())
+        throw new Error(`Refused: ${rel} is not a plain file.`);
+    if (st.size > MAX_BYTES)
+        throw tooLarge(rel);
+    await assertRealDirs(cwd);
+    let bytes;
+    try {
+        bytes = await readCapped(abs, rel);
+    }
+    catch (e) {
+        if (e.code === 'ELOOP')
+            throw new Error(`Refused: ${rel} is a symlink.`);
+        throw e;
+    }
+    if (expectedSha !== undefined) {
+        const actual = sha256(bytes);
+        if (actual !== expectedSha)
+            throw new LaneShaMismatchError(rel, expectedSha, actual);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error(`The lane decision file ${rel} is not valid JSON.`);
+    }
+    const parsed = laneRecordSchema.safeParse(raw);
+    if (!parsed.success)
+        throw shapeError(rel, parsed.error);
+    return parsed.data;
+}
+/**
+ * The only read for callers that act on a lane (plan creation, plan resume):
+ * the sha256 from the plan is required, so a hand-edited file is always refused.
+ */
+export async function readPinnedLaneDecision(cwd, relPath, sha) {
+    if (typeof sha !== 'string' || !/^[0-9a-f]{64}$/.test(sha)) {
+        throw new Error('Refused: a pinned lane decision needs the sha256 recorded in the plan.');
+    }
+    return readLaneDecision(cwd, relPath, sha);
+}

package/dist/lane/types.js

@@ -0,0 +1 @@
+export {};

package/dist/one-shot.js

@@ -56,6 +56,7 @@ import './tools/cap/service-catalog.js';
 import './tools/cap/metadata-import.js';
 import './tools/cap/sap-link-tool.js';
 import './tools/cap/link-smoke.js';
+import './tools/lane/app-lane-resolve.js';
 import './tools/extend-model/tool.js';
 import './tools/capability/tool.js';
 import './tools/web/web_fetch.js';

package/dist/projects/extract-plan.js

@@ -1,5 +1,6 @@
 import { parsePlanContent, PLAN_PHASE_STATUSES } from './plan-schema.js';
 import { computeNextPhase, isPhaseSatisfied } from './plan-run.js';
+import { canonicalLanePath } from '../lane/paths.js';
 // E2 dual-read: accept BOTH the legacy `csforge:` prefix (old artifacts on
 // customer disks carry it forever) and the current `cspeach:` prefix. Legacy
 // acceptance is permanent.
@@ -103,14 +104,52 @@ function expandCompactContent(changedRaw, prior, rawStatuses) {
     };
     return { ...prior, phases, summary };
 }
+/** R6: a plan's lane is fixed at creation; an app flow never replaces it. */
+export const LANE_OTHER_PLAN = 'This plan was made for another lane decision. Start a new plan with /abap-app.';
+/** R16: a save whose app-flow lane differs from the title-matched prior plan starts a new plan. */
+export const LANE_NEW_FAMILY = 'This is a new plan for the new lane decision; the earlier plan is kept as it was.';
+/** True when the app-flow lane and the prior plan's lane are different decisions (canonical path + sha). */
+export function laneConflictsWithPrior(flowLane, priorContent) {
+    const prior = priorContent?.from.lane;
+    if (!flowLane || !prior)
+        return false;
+    return canonicalLanePath(flowLane.path) !== canonicalLanePath(prior.path) || flowLane.sha256 !== prior.sha256;
+}
 /**
- * Parse the LAST plan-manifest block out of the skill's markdown output.
- * `priorContent` is the validated content of the envelope being resumed —
- * required to expand the compact shape; on the full shape it is the source
- * of truth for per-phase `audit` fields (Task 6 review I-1 — audits are
- * harness-authored, never model-authored). Seed sessions pass nothing.
+ * `from.lane` is CLI-authored only. Precedence: the app-flow lane (plan
+ * creation) > the prior envelope's lane (resume / revision — the lane never
+ * changes mid-plan) > none (any model-written lane is stripped, the same rule
+ * as the specGap sha guard). Never mutates the prior content: the compact
+ * merge shares its `from` object with the prior.
  */
-export function extractPlan(markdown, priorContent) {
+function imposeLane(contentInput, priorContent, opts) {
+    if (typeof contentInput !== 'object' || contentInput === null || Array.isArray(contentInput))
+        return;
+    const ci = contentInput;
+    // R6 — never replace a prior plan's lane with a different app-flow lane.
+    if (laneConflictsWithPrior(opts.lane, priorContent))
+        throw new Error(LANE_OTHER_PLAN);
+    const lane = opts.lane
+        ? { path: canonicalLanePath(opts.lane.path), sha256: opts.lane.sha256 }
+        : priorContent?.from.lane
+            ? { ...priorContent.from.lane }
+            : undefined;
+    const from = ci.from;
+    if (lane) {
+        if (from === undefined)
+            ci.from = { lane };
+        else if (typeof from === 'object' && from !== null && !Array.isArray(from))
+            ci.from = { ...from, lane };
+        return;
+    }
+    // No CLI lane: strip a model-written one. Untouched when absent, so a
+    // lane-less plan stays byte-identical.
+    if (typeof from === 'object' && from !== null && !Array.isArray(from) && 'lane' in from) {
+        const { lane: _dropped, ...rest } = from;
+        ci.from = rest;
+    }
+}
+export function extractPlan(markdown, priorContent, opts = {}) {
     // Last block wins — defensive against a turn emitting more than one block.
     const re = new RegExp(MANIFEST_RE.source, MANIFEST_RE.flags);
     let m;
@@ -207,6 +246,7 @@ export function extractPlan(markdown, priorContent) {
     else {
         throw new Error('plan-manifest must carry either "content" (full shape) or "changed" (compact resume shape)');
     }
+    imposeLane(contentInput, priorContent, opts);
     const pc = parsePlanContent(contentInput);
     if (!pc.ok) {
         throw new Error(`plan-manifest content failed validation:\n  ${pc.errors.join('\n  ')}`);