@cspeach/cli 1.1.14 → 1.1.15

package/dist/tools/filesystem/extract-document.js

@@ -3,6 +3,7 @@
 import { extractText, getDocumentProxy } from 'unpdf';
 import mammoth from 'mammoth';
 import TurndownService from 'turndown';
+import { extractXlsx } from './extract-xlsx.js';
 /** Thrown when a PDF exceeds the caller's page ceiling — checked before full extraction. */
 export class DocumentTooLargeError extends Error {
     pages;
@@ -20,6 +21,11 @@ export async function extractDocument(buffer, ext, opts) {
         return extractPdf(buffer, opts?.maxPages);
     if (ext === '.docx')
         return extractDocx(buffer);
+    // 2026-09-23 — specs and object lists arrive as spreadsheets (Glenn).
+    if (ext === '.xlsx') {
+        const x = extractXlsx(buffer);
+        return { text: x.text, sheets: x.sheets, warnings: x.warnings };
+    }
     throw new Error(`extractDocument: unsupported extension "${ext}"`);
 }
 async function extractPdf(buffer, maxPages) {

package/dist/tools/filesystem/extract-xlsx.js

@@ -0,0 +1,139 @@
+/**
+ * .xlsx text extraction (2026-09-23 — Glenn: "it cannot read the excel file").
+ *
+ * Specs and object lists arrive as spreadsheets, so read_document reads them
+ * like any other document. An .xlsx IS a zip of XML parts, and adm-zip already
+ * ships inside the tree (SAP's own @sap-ux packages pull it), so nothing new
+ * enters the product to do this.
+ *
+ * Output shape: one "## Sheet: <name>" heading per sheet, then one line per
+ * row, cells separated by tabs, empty trailing cells dropped and empty leading
+ * ones kept so columns still line up. A model reads that as a table; a human
+ * reading the transcript can too.
+ *
+ * Deliberately NOT done: formulas (the cached VALUE is used, which is what the
+ * sheet shows), formatting, merged-cell geometry, charts, images. Dates come
+ * out as the serial number Excel stores unless the cell is text — the caller is
+ * told, rather than us guessing a locale.
+ */
+import AdmZip from 'adm-zip';
+/** Hard ceilings so one huge workbook cannot fill a turn. */
+export const MAX_SHEET_ROWS = 2000;
+export const MAX_CELLS = 100_000;
+const decode = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'").replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/&amp;/g, '&'); // last: an encoded "&amp;lt;" must not become "<"
+/** All <t> text inside one shared-string <si>, joined (rich text is split across runs). */
+function siText(si) {
+    const parts = [...si.matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((m) => decode(m[1]));
+    return parts.join('');
+}
+export function sharedStrings(xml) {
+    if (!xml)
+        return [];
+    return [...xml.matchAll(/<si>([\s\S]*?)<\/si>/g)].map((m) => siText(m[1]));
+}
+/** Column letters → 0-based index: A→0, B→1, AA→26. */
+export function colIndex(ref) {
+    const letters = /^([A-Z]+)/.exec(ref.toUpperCase())?.[1] ?? 'A';
+    let n = 0;
+    for (const ch of letters)
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    return n - 1;
+}
+/** One worksheet's cells as a rectangular grid of strings. */
+export function sheetRows(xml, strings, budget) {
+    const rows = [];
+    for (const rowMatch of xml.matchAll(/<row[^>]*>([\s\S]*?)<\/row>/g)) {
+        if (rows.length >= MAX_SHEET_ROWS || budget.cells <= 0)
+            break;
+        const cells = [];
+        for (const cell of rowMatch[1].matchAll(/<c\b([^>]*)>([\s\S]*?)<\/c>|<c\b([^>]*)\/>/g)) {
+            const attrs = cell[1] ?? cell[3] ?? '';
+            const body = cell[2] ?? '';
+            const at = colIndex(/r="([A-Z]+\d+)"/.exec(attrs)?.[1] ?? 'A1');
+            const type = /t="([^"]+)"/.exec(attrs)?.[1];
+            let value = '';
+            if (type === 's') {
+                const idx = Number(/<v>([\s\S]*?)<\/v>/.exec(body)?.[1] ?? '-1');
+                value = strings[idx] ?? '';
+            }
+            else if (type === 'inlineStr') {
+                value = siText(body);
+            }
+            else {
+                // n (number), str (formula result), b, d, e — the cached value as shown.
+                value = decode(/<v>([\s\S]*?)<\/v>/.exec(body)?.[1] ?? '');
+            }
+            while (cells.length < at)
+                cells.push('');
+            cells[at] = value.replace(/[\t\r\n]+/g, ' ').trim();
+            budget.cells -= 1;
+            if (budget.cells <= 0)
+                break;
+        }
+        while (cells.length > 0 && cells[cells.length - 1] === '')
+            cells.pop();
+        rows.push(cells);
+    }
+    while (rows.length > 0 && rows[rows.length - 1].length === 0)
+        rows.pop();
+    return rows;
+}
+/** Sheet name → part path, in the workbook's own order. */
+export function sheetOrder(workbookXml, relsXml) {
+    if (!workbookXml)
+        return [];
+    const rels = new Map();
+    for (const m of (relsXml ?? '').matchAll(/<Relationship\b([^>]*)\/>/g)) {
+        const id = /Id="([^"]+)"/.exec(m[1])?.[1];
+        const target = /Target="([^"]+)"/.exec(m[1])?.[1];
+        if (id && target)
+            rels.set(id, target.replace(/^\/?xl\//, '').replace(/^\//, ''));
+    }
+    const out = [];
+    for (const m of workbookXml.matchAll(/<sheet\b([^>]*)\/>/g)) {
+        const attrs = m[1];
+        const name = decode(/name="([^"]*)"/.exec(attrs)?.[1] ?? `Sheet${out.length + 1}`);
+        const rid = /r:id="([^"]+)"/.exec(attrs)?.[1] ?? '';
+        out.push({ name, path: `xl/${rels.get(rid) ?? `worksheets/sheet${out.length + 1}.xml`}` });
+    }
+    return out;
+}
+export function extractXlsx(buffer) {
+    let zip;
+    try {
+        zip = new AdmZip(buffer);
+    }
+    catch {
+        return { text: '', sheets: 0, warnings: ['not a readable .xlsx (the file may be .xls, password-protected or damaged)'] };
+    }
+    const read = (p) => {
+        const entry = zip.getEntry(p);
+        return entry ? entry.getData().toString('utf-8') : null;
+    };
+    const strings = sharedStrings(read('xl/sharedStrings.xml'));
+    const sheets = sheetOrder(read('xl/workbook.xml'), read('xl/_rels/workbook.xml.rels'));
+    if (sheets.length === 0) {
+        return { text: '', sheets: 0, warnings: ['no sheets found — the file may be .xls (old format); save it as .xlsx'] };
+    }
+    const budget = { cells: MAX_CELLS };
+    const warnings = [];
+    const blocks = [];
+    for (const s of sheets) {
+        const xml = read(s.path);
+        if (xml === null)
+            continue;
+        const rows = sheetRows(xml, strings, budget);
+        if (rows.length >= MAX_SHEET_ROWS)
+            warnings.push(`sheet "${s.name}" was cut at ${MAX_SHEET_ROWS} rows`);
+        blocks.push(`## Sheet: ${s.name}\n\n${rows.map((r) => r.join('\t')).join('\n')}`.trimEnd());
+    }
+    if (budget.cells <= 0)
+        warnings.push('the workbook was cut short — it holds more cells than one read returns');
+    const text = blocks.join('\n\n').trim();
+    if (text.length === 0)
+        warnings.push('no cell text found — the workbook may be empty or hold only charts/images');
+    return { text, sheets: sheets.length, warnings };
+}

package/dist/tools/filesystem/file-write.js

@@ -21,6 +21,25 @@ import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { registerTool } from '../index.js';
 import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath, blockedExecutableExtension, } from '../_filesystem-shared.js';
+/**
+ * 2026-09-23 (Glenn's first run) — a standalone run writes GUIDE.md and said
+ * nothing about it. He opened it in a text editor, then tried to drop it into
+ * an unrelated page on the site and got an error: "what does this file do …
+ * where would this enter back into the CSPEACH process?". Say it once, when
+ * the file appears, in the human stream.
+ */
+let guideNoteShown = false;
+export function __resetGuideNoteForTests() { guideNoteShown = false; }
+function noteGuideWritten(relPath, ctx) {
+    if (guideNoteShown)
+        return;
+    if (path.basename(relPath).toLowerCase() !== 'guide.md')
+        return;
+    guideNoteShown = true;
+    ctx.chunkEmitter?.emit('info', `${relPath} is your step-by-step list for applying these objects in SAP — `
+        + 'open it at https://cspeach.dev/guide, or in any text editor. '
+        + 'If a step fails, come back here and say "step N failed" with the error.');
+}
 export async function fileWriteHandler(args, ctx) {
     // 1. Path containment — sync phase (pure string math, catches .. traversals)
     let abs;
@@ -110,6 +129,7 @@ export async function fileWriteHandler(args, ctx) {
     }
     const relPath = path.relative(path.resolve(ctx.cwd), target).replace(/\\/g, '/');
     const bytes = Buffer.byteLength(args.content, 'utf-8');
+    noteGuideWritten(relPath, ctx);
     return { content: `wrote ${relPath} (${bytes} bytes)` };
 }
 registerTool({

package/dist/tools/filesystem/read-document.js

@@ -12,7 +12,7 @@ import { extractDocument, DocumentTooLargeError } from './extract-document.js';
 const MAX_LINES = 2000;
 const MAX_BYTES = 50 * 1024 * 1024; // 50 MB
 const MAX_PAGES = 150;
-const SUPPORTED = new Set(['.pdf', '.docx']);
+const SUPPORTED = new Set(['.pdf', '.docx', '.xlsx']);
 export async function readDocumentHandler(args, ctx) {
     if (args.offset !== undefined && args.offset < 0) {
         return { content: `error: offset must be non-negative (got ${args.offset})`, is_error: true };
@@ -32,7 +32,10 @@ export async function readDocumentHandler(args, ctx) {
     const ext = path.extname(abs).toLowerCase();
     if (!SUPPORTED.has(ext)) {
         return {
-            content: `error: read_document supports .pdf and .docx; convert "${args.path}" first (.doc/.pptx/scanned images are not supported)`,
+            content: ext === '.xls' || ext === '.csv'
+                ? `error: read_document reads .xlsx, not ${ext}; save "${args.path}" as .xlsx`
+                    + (ext === '.csv' ? ' — or read a .csv with file_read, it is plain text' : '')
+                : `error: read_document supports .pdf, .docx and .xlsx; convert "${args.path}" first (.doc/.pptx/scanned images are not supported)`,
             is_error: true,
         };
     }
@@ -74,8 +77,14 @@ export async function readDocumentHandler(args, ctx) {
         }
         return { content: `error: could not read "${args.path}": ${err instanceof Error ? err.message : String(err)}`, is_error: true };
     }
-    // 'document' is the intentional label for .docx: result.pages is PDF-only and undefined for Word files.
-    const header = `${args.path} — ${result.pages !== undefined ? `${result.pages} pages` : 'document'}`;
+    // 'document' is the intentional label for .docx: result.pages is PDF-only,
+    // result.sheets is .xlsx-only, and a Word file has neither.
+    const scale = result.pages !== undefined
+        ? `${result.pages} pages`
+        : result.sheets !== undefined
+            ? `${result.sheets} sheet${result.sheets === 1 ? '' : 's'}`
+            : 'document';
+    const header = `${args.path} — ${scale}`;
     const warnLines = result.warnings.map((w) => `[warning] ${w}`);
     const allLines = result.text.replace(/\n$/, '').split('\n');
     const offset = Math.max(0, args.offset ?? 0);
@@ -90,14 +99,14 @@ export async function readDocumentHandler(args, ctx) {
 }
 registerTool({
     name: 'read_document',
-    description: 'Read a .pdf or .docx and return its extracted text with page/heading markers and line numbers. Optional offset + limit for windowed reads of large documents.',
+    description: 'Read a .pdf, .docx or .xlsx and return its text with page/sheet/heading markers and line numbers. A spreadsheet comes back one sheet at a time, rows as tab-separated cells (cached values, not formulas). Optional offset + limit for windowed reads of large documents.',
     isMutating: false,
     category: 'filesystem',
     flagGated: true,
     input_schema: {
         type: 'object',
         properties: {
-            path: { type: 'string', description: 'Path to a .pdf or .docx, relative to the project root or absolute inside it.' },
+            path: { type: 'string', description: 'Path to a .pdf, .docx or .xlsx, relative to the project root or absolute inside it.' },
             offset: { type: 'number', description: 'Optional 0-based line offset into the extracted text.' },
             limit: { type: 'number', description: 'Optional max lines to return (cap 2000).' },
         },

package/dist/tools/include-snapshot.js

@@ -0,0 +1,24 @@
+/**
+ * Snapshot-store key for a class LOCAL INCLUDE (CCDEF / CCIMP / CCMAC / test
+ * classes). Pure — no fs, no SAP.
+ *
+ * Why a separate key (2026-09-21, found on the first clean-core fix): the
+ * include write used to snapshot the class MAIN source. For a RAP behaviour
+ * pool the main source is an 8-line shell and the change lives in CCIMP — so
+ * the Rule-7 backup never covered the change, and rewind wrote the unchanged
+ * main source back and reported success while the include change stayed.
+ *
+ * The include is stored under type `CLAS.<INCLUDE>` (e.g. `CLAS.LOCALS_IMP`),
+ * name = class name. A dot keeps the store's two-level type/name layout (no
+ * nested dirs) and can never collide with a real ABAP type code.
+ */
+const INCLUDE_TYPE_RE = /^CLAS\.(LOCALS_DEF|LOCALS_IMP|MACROS|TESTCLASSES)$/i;
+/** Snapshot type key for one include of a class. */
+export function includeSnapshotType(includeType) {
+    return `CLAS.${includeType.toUpperCase()}`;
+}
+/** The include a snapshot type key names, or null for an ordinary object type. */
+export function parseIncludeSnapshotType(type) {
+    const m = INCLUDE_TYPE_RE.exec(type);
+    return m ? m[1].toLowerCase() : null;
+}

package/dist/tools/sap-write.js

@@ -24,7 +24,8 @@
 import crypto from 'node:crypto';
 import { registerTool } from './index.js';
 import { verifyAndSpendApprovalId } from '../approvals/jwt.js';
-import { autoSnapshot } from './snapshot.js';
+import { autoSnapshot, autoSnapshotClassInclude } from './snapshot.js';
+import { includeSnapshotType } from './include-snapshot.js';
 import { buildWriteChainLine } from '../renderer/verify-chain.js';
 import { verifySyntax, verifyActive } from './verify.js';
 import { appendPending, finalizeToolCall } from '../session/pending.js';
@@ -663,9 +664,9 @@ registerTool({
 // Writes a class local-include source (CCDEF/CCIMP/CCMAC/test classes). This is
 // how RAP behaviour-pool handlers (which live in CCIMP / locals_imp) get landed.
 // AdtClient locks the CLASS object, tries a ladder of PUT URL/content-type
-// variants (first 2xx wins), and always unlocks. Snapshot is best-effort:
-// the include source may not be independently readable, so a failed snapshot
-// must not block the write (consistent with sap_delete_object).
+// variants (first 2xx wins), and always unlocks. The Rule-7 snapshot is of the
+// INCLUDE itself (autoSnapshotClassInclude). It is non-blocking — a fresh
+// class's include may not be readable yet — but a failed one warns loudly.
 registerTool({
     name: 'sap_set_class_include',
     description: 'Write a class local-include source (CCDEF locals_def, CCIMP locals_imp, '
@@ -713,15 +714,24 @@ registerTool({
         // The CCIMP piece (LIMU CINC) is exactly the kind of object that sits
         // locked in a request from earlier work — battery S1's 409 root cause.
         const resolved = await resolveWriteTransport(ctx, 'CLAS', args.className, effectiveTransport);
-        // ── Gate 2: Snapshot (Rule 7) — best-effort, include may not be readable ─
+        // ── Gate 2: Snapshot (Rule 7) — of the INCLUDE being overwritten ─────────
+        // Not the class main source: for a behaviour pool that is an empty shell and
+        // the change lives in CCIMP (2026-09-21 — the old main-source snapshot left
+        // the change with no restore point, and rewind "restored" the wrong thing).
+        // Still non-blocking (a fresh class's include may not be readable yet), but
+        // a missing restore point is now said out loud instead of swallowed.
         let snapOutcome;
         try {
-            snapOutcome = await autoSnapshot(args.className, 'CLAS', ctx.adt);
+            snapOutcome = await autoSnapshotClassInclude(args.className, args.includeType, ctx.adt);
         }
-        catch {
-            // Silently ignore — include source may not be independently readable.
+        catch (err) {
+            snapOutcome = { taken: false, reason: 'source_read_failed', detail: String(err) };
+        }
+        emitSnapshotNotice(ctx, snapOutcome, includeSnapshotType(args.includeType), args.className);
+        if (snapOutcome?.reason === 'source_read_failed') {
+            ctx.chunkEmitter?.emit('warn', `CLAS ${args.className} ${args.includeType}: could not snapshot the include before writing `
+                + `(${snapOutcome.detail ?? 'read failed'}) — this write has NO restore point; rewind cannot undo it`);
         }
-        emitSnapshotNotice(ctx, snapOutcome, 'CLAS', args.className);
         // ── WAL: record pending entry ────────────────────────────────────────────
         await appendPending(ctx.session, {
             tool_use_id: toolUseId,

package/dist/tools/snapshot.js

@@ -15,6 +15,7 @@
  */
 import { registerTool } from './index.js';
 import { snapshots, SapError } from '@cspeach/sap-client';
+import { includeSnapshotType } from './include-snapshot.js';
 /** True only for a genuine ADT 404 — the object does not exist. Any other
  *  failure (network, auth, 5xx, timeout) is a READ failure, not proof of
  *  absence, and must never be labelled "object not found". */
@@ -100,6 +101,32 @@ export async function autoSnapshot(objectName, objectType, adt) {
     const entry = await snapshots.take(objectType, objectName, src, 'before_write');
     return { taken: true, entry };
 }
+/**
+ * Rule-7 snapshot of ONE class local include, taken before sap_set_class_include
+ * overwrites it. Stored under includeSnapshotType(includeType) + class name so
+ * rewind can put the include (not the class main source) back.
+ *
+ *   404               → 'object_not_found' (include has no source yet — nothing to protect)
+ *   other read error  → 'source_read_failed' (+ detail) — caller decides; no restore point
+ *   read OK (even '') → snapshot taken
+ * A snapshots.take failure THROWS, like autoSnapshot.
+ */
+export async function autoSnapshotClassInclude(className, includeType, adt) {
+    let src;
+    try {
+        src = await adt.classIncludes(className, includeType);
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return { taken: false, reason: 'object_not_found' };
+        return { taken: false, reason: 'source_read_failed', detail: shortErrorMessage(err) };
+    }
+    if (typeof src !== 'string') {
+        return { taken: false, reason: 'source_read_failed', detail: 'include read returned no source text' };
+    }
+    const entry = await snapshots.take(includeSnapshotType(includeType), className, src, 'before_write');
+    return { taken: true, entry };
+}
 // ── sap_snapshot_list ─────────────────────────────────────────────────────────
 registerTool({
     name: 'sap_snapshot_list',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cspeach/cli",
-  "version": "1.1.14",
-  "description": "CSPeach — AI-assisted ABAP development CLI. Direct SAP access, 34 skills, safety gates.",
+  "version": "1.1.15",
+  "description": "CSPeach \u2014 AI-assisted ABAP development CLI. Direct SAP access, 34 skills, safety gates.",
   "keywords": [
     "abap",
     "sap",
@@ -32,7 +32,7 @@
     "prebuild": "tsx scripts/prebuild.ts",
     "build": "tsc && node scripts/make-bin-executable.js",
     "install:global": "tsx scripts/install-global.ts",
-    "pretest": "tsx scripts/sync-signing-key.ts || node -e \"console.warn('WARN: sync-signing-key skipped — using stub')\"",
+    "pretest": "tsx scripts/sync-signing-key.ts || node -e \"console.warn('WARN: sync-signing-key skipped \u2014 using stub')\"",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
@@ -44,22 +44,25 @@
     "bench:audit": "tsx scripts/bench-audit-task.ts",
     "fiori": "tsx src/tools/fiori/bin.ts",
     "prepare": "husky",
-    "prepublishOnly": "node -e \"const d=(require('./package.json').dependencies||{})['@cspeach/sap-client']||''; if(d.startsWith('file:')||d.startsWith('link:')){console.error('publish blocked: @cspeach/sap-client is a local link ('+d+') — point it at the published version before npm publish'); process.exit(1)}\""
+    "prepublishOnly": "node -e \"const deps=require('./package.json').dependencies||{}; for (const n of ['@cspeach/sap-client','@cspeach/register-core']) { const d=deps[n]||''; if(d.startsWith('file:')||d.startsWith('link:')){console.error('publish blocked: '+n+' is a local link ('+d+') \u2014 point it at the published version before npm publish'); process.exit(1)} }\""
   },
   "engines": {
     "node": ">=20.0.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.90.0",
-    "@cspeach/sap-client": "^0.1.11",
+    "@cspeach/register-core": "0.1.0",
+    "@cspeach/sap-client": "0.1.12",
     "@iarna/toml": "^2.2.5",
     "@inkjs/ui": "^2.0.0",
     "@inquirer/prompts": "^7.0.0",
+    "@napi-rs/keyring": "2.1.0",
     "@noble/ed25519": "2.1.0",
     "@noble/hashes": "1.4.0",
     "@sap-ux/fe-fpm-writer": "0.43.7",
     "@sap-ux/fiori-elements-writer": "^3.0.39",
     "@sap-ux/fiori-freestyle-writer": "3.0.12",
+    "adm-zip": "0.5.17",
     "chalk": "^5.3.0",
     "cli-highlight": "^2.1.11",
     "cli-table3": "^0.6.5",
@@ -71,7 +74,6 @@
     "ink": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "jose": "^5.9.0",
-    "@napi-rs/keyring": "2.1.0",
     "mammoth": "^1.8.0",
     "marked": "^11.2.0",
     "marked-terminal": "^6.2.0",
@@ -86,6 +88,7 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@types/adm-zip": "0.5.8",
     "@types/cross-spawn": "^6.0.6",
     "@types/diff": "^7.0.2",
     "@types/ejs": "^3.1.5",