@cspeach/cli 0.6.0

package/dist/projects/extract-upgrade.js

@@ -0,0 +1,230 @@
+/**
+ * Shared parser for the `<!-- csforge:upgrade-manifest ... -->` block
+ * that all three /abap-upgrade-{scan,fix,verify} skills emit at the
+ * end of their markdown output. The block is hidden in human renderers
+ * (HTML comment) and structured enough for a deterministic extractor.
+ *
+ * Format:
+ *
+ *   <!-- csforge:upgrade-manifest
+ *   artefact: upgrade-scan
+ *   title: ZFI* — S/4HANA 2023 readiness
+ *   detail_path: .abapforge/upgrades/zfi-readiness-2023-baseline.json
+ *   atc_variant: S4HANA_READINESS_2023
+ *   scope: Z* in package ZFI*
+ *   total: 2847
+ *   auto_fixable: 344
+ *   manual_review: 136
+ *   suppressed: 26
+ *   findings:
+ *     finding-001 | ZFI_BP_SYNC | PROG | S4HANA_BUSINESS_PARTNER | E
+ *     finding-002 | ZCL_FI_DOC  | CLAS | PERF_DB_SEARCH         | W
+ *   -->
+ *
+ * Key-value pairs are `key: value` per line. Tabular sections use a
+ * trailing colon header (`findings:`) followed by `|`-separated rows.
+ *
+ * Three artefact types share the same parser and dispatch by `artefact:`:
+ *   - upgrade-scan      → findings table
+ *   - upgrade-progress  → fixes table + baseline_path / baseline_sha256
+ *   - upgrade-report    → regressions table + baseline + progress refs
+ *
+ * Parsing is permissive — missing optional fields produce defaults; a
+ * missing manifest block throws so callers know to surface the error.
+ */
+const MANIFEST_RE = /<!--\s*csforge:upgrade-manifest\s*\n([\s\S]*?)\n\s*-->/;
+function parseManifestBlock(markdown) {
+    const m = MANIFEST_RE.exec(markdown);
+    if (!m) {
+        throw new Error('No <!-- csforge:upgrade-manifest --> block found in skill output');
+    }
+    const body = m[1] ?? '';
+    const kv = {};
+    const tables = {};
+    let currentTable = null;
+    for (const rawLine of body.split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        if (line.trim().length === 0) {
+            currentTable = null;
+            continue;
+        }
+        if (currentTable !== null && /^\s+/.test(line)) {
+            // Indented row under a table header.
+            const cells = line.trim().split('|').map((c) => c.trim());
+            if (cells.length > 0) {
+                if (!tables[currentTable])
+                    tables[currentTable] = [];
+                tables[currentTable].push(cells);
+            }
+            continue;
+        }
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (value.length === 0) {
+            // Header with no value → starts a table.
+            currentTable = key;
+            tables[key] = [];
+        }
+        else {
+            kv[key] = value;
+            currentTable = null;
+        }
+    }
+    return { kv, tables };
+}
+function intOr(kv, key, fallback) {
+    const v = kv[key];
+    if (v === undefined)
+        return fallback;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : fallback;
+}
+function buildItems(count, defaultStatus) {
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        out.push({
+            id: paddedId(i + 1),
+            status: defaultStatus,
+            answer: null,
+            answeredBy: null,
+            answeredAt: null,
+            comments: [],
+        });
+    }
+    return out;
+}
+function paddedId(n) {
+    return `item-${String(n).padStart(3, '0')}`;
+}
+export function extractUpgradeScan(markdown) {
+    const { kv, tables } = parseManifestBlock(markdown);
+    if (kv.artefact !== 'upgrade-scan') {
+        throw new Error(`Manifest artefact mismatch: expected 'upgrade-scan', got '${kv.artefact}'`);
+    }
+    if (!kv.detail_path) {
+        throw new Error("upgrade-scan manifest missing required 'detail_path'");
+    }
+    const findings = (tables.findings ?? []).map((row, i) => ({
+        id: row[0] ?? `finding-${String(i + 1).padStart(3, '0')}`,
+        objectName: row[1] ?? '',
+        objectType: row[2] ?? '',
+        rule: row[3] ?? '',
+        severity: row[4] ?? '',
+    }));
+    const content = {
+        detailPath: kv.detail_path,
+        atcVariant: kv.atc_variant ?? '',
+        scope: kv.scope ?? '',
+        summary: {
+            total: intOr(kv, 'total', findings.length),
+            autoFixable: intOr(kv, 'auto_fixable', 0),
+            manualReview: intOr(kv, 'manual_review', 0),
+            suppressed: intOr(kv, 'suppressed', 0),
+        },
+        findings,
+    };
+    // One InteractionItem per finding, default status 'open'.
+    const items = findings.map((f) => ({
+        id: f.id,
+        status: 'open',
+        answer: null,
+        answeredBy: null,
+        answeredAt: null,
+        comments: [],
+    }));
+    return { title: kv.title ?? 'Upgrade Scan', content, items };
+}
+export function extractUpgradeProgress(markdown) {
+    const { kv, tables } = parseManifestBlock(markdown);
+    if (kv.artefact !== 'upgrade-progress') {
+        throw new Error(`Manifest artefact mismatch: expected 'upgrade-progress', got '${kv.artefact}'`);
+    }
+    if (!kv.detail_path) {
+        throw new Error("upgrade-progress manifest missing required 'detail_path'");
+    }
+    if (!kv.baseline_path) {
+        throw new Error("upgrade-progress manifest missing required 'baseline_path'");
+    }
+    const fixes = (tables.fixes ?? []).map((row, i) => ({
+        id: row[0] ?? paddedId(i + 1),
+        objectName: row[1] ?? '',
+        finding: row[2] ?? '',
+        status: row[3] ?? 'pending',
+    }));
+    const content = {
+        detailPath: kv.detail_path,
+        baselineRef: {
+            path: kv.baseline_path,
+            sha256: kv.baseline_sha256 ?? '',
+        },
+        transport: kv.transport && kv.transport !== '-' ? kv.transport : null,
+        summary: {
+            fixed: intOr(kv, 'fixed', 0),
+            skipped: intOr(kv, 'skipped', 0),
+            failed: intOr(kv, 'failed', 0),
+            pending: intOr(kv, 'pending', 0),
+        },
+        fixes,
+    };
+    const items = fixes.map((f) => {
+        const allowed = ['fixed', 'skipped', 'failed', 'pending'];
+        const status = (allowed.includes(f.status)
+            ? f.status
+            : 'pending');
+        return {
+            id: f.id,
+            status,
+            answer: null,
+            answeredBy: null,
+            answeredAt: null,
+            comments: [],
+        };
+    });
+    return { title: kv.title ?? 'Upgrade Progress', content, items };
+}
+export function extractUpgradeReport(markdown) {
+    const { kv, tables } = parseManifestBlock(markdown);
+    if (kv.artefact !== 'upgrade-report') {
+        throw new Error(`Manifest artefact mismatch: expected 'upgrade-report', got '${kv.artefact}'`);
+    }
+    if (!kv.detail_path) {
+        throw new Error("upgrade-report manifest missing required 'detail_path'");
+    }
+    if (!kv.baseline_path) {
+        throw new Error("upgrade-report manifest missing required 'baseline_path'");
+    }
+    if (!kv.progress_path) {
+        throw new Error("upgrade-report manifest missing required 'progress_path'");
+    }
+    const regressions = (tables.regressions ?? []).map((row, i) => ({
+        id: row[0] ?? `reg-${String(i + 1).padStart(3, '0')}`,
+        objectName: row[1] ?? '',
+        rule: row[2] ?? '',
+        reason: row[3] ?? '',
+    }));
+    const content = {
+        detailPath: kv.detail_path,
+        baselineRef: { path: kv.baseline_path, sha256: kv.baseline_sha256 ?? '' },
+        progressRef: { path: kv.progress_path, sha256: kv.progress_sha256 ?? '' },
+        summary: {
+            closed: intOr(kv, 'closed', 0),
+            regressions: intOr(kv, 'regressions', regressions.length),
+            pending: intOr(kv, 'pending', 0),
+        },
+        regressions,
+    };
+    // For terminal artefact, items track regression status — default
+    // 'regression' for entries that came in via the regressions table.
+    const items = regressions.map((r) => ({
+        id: r.id,
+        status: 'regression',
+        answer: null,
+        answeredBy: null,
+        answeredAt: null,
+        comments: [],
+    }));
+    return { title: kv.title ?? 'Upgrade Report', content, items };
+}

package/dist/projects/filename.js

@@ -0,0 +1,18 @@
+const SLUG_MAX = 60;
+export function titleSlug(title) {
+    return title
+        .normalize('NFKD').replace(/[̀-ͯ]/g, '') // strip combining diacritics
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '') // strip punctuation
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .slice(0, SLUG_MAX)
+        .replace(/-+$/, ''); // trim trailing hyphen if slice cut mid-word
+}
+export function shortId(uuid) {
+    return uuid.slice(0, 4);
+}
+export function projectFilename(args) {
+    return `${titleSlug(args.title)}-${args.artefactType}-${shortId(args.id)}-v${args.version}.cspeach.json`;
+}

package/dist/projects/index.js

@@ -0,0 +1,8 @@
+export { validateEnvelope } from './validate.js';
+export { canonicalSha256 } from './canonicalize.js';
+export { titleSlug, shortId, projectFilename } from './filename.js';
+export { runSaveCommand } from './save-command.js';
+export { extractDesign } from './extract-design.js';
+export { extractEstimate } from './extract-estimate.js';
+export { buildPromotedFromSnapshot, validatePromotionSource } from './promote.js';
+export { runPromoteCommand } from './promote-command.js';

package/dist/projects/migration.js

@@ -0,0 +1,111 @@
+/**
+ * One-time workspace-default migration prompt.
+ *
+ * Why this exists: until 2026-05-07 the default workspace was `~/CSPeach/`
+ * — a single global folder per user. As of 2026-05-08 the default is
+ * project-rooted (`<git-root>/.cspeach/`), so a consultant working on
+ * customer A and customer B no longer has both customers' artefacts
+ * piling into one folder.
+ *
+ * For users with files already in `~/CSPeach/`, the switch needs to ask
+ * once: keep the old global, move into the new project, or leave both
+ * alone. The answer is recorded in `config.migration_prompted`; the
+ * prompt fires exactly once.
+ *
+ * Three branches:
+ *   - "move":         renameSync every artefact from ~/CSPeach/ into the
+ *                     resolved project workspace. Old folder cleaned.
+ *   - "keep_global":  set workspace_folder = '~/CSPeach', preserving the
+ *                     pre-2026-05-08 behaviour for users who liked it.
+ *   - "leave":        do nothing — old folder stays as-is, new artefacts
+ *                     go to the project workspace. User can manually
+ *                     copy whatever they want later.
+ *
+ * The prompt is interactive (via the supplied async prompt callback);
+ * one-shot mode skips it entirely (caller passes a no-op).
+ */
+import { existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { loadConfig, saveConfig } from '../config/loader.js';
+import { defaultWorkspaceFor } from './workspace.js';
+/**
+ * Run the migration prompt if and only if it hasn't run before AND
+ * there's actually something to migrate. No-op otherwise. Always sets
+ * `migration_prompted: true` after running so the next invocation
+ * skips this whole module.
+ */
+export async function maybePromptWorkspaceMigration(deps) {
+    const cfg = await loadConfig();
+    if (cfg.migration_prompted === true)
+        return;
+    // If user already pinned workspace_folder, they've already chosen —
+    // mark prompted, skip the dialog. The pin survives.
+    if (cfg.workspace_folder !== undefined && cfg.workspace_folder.trim().length > 0) {
+        await saveConfig({ ...cfg, migration_prompted: true });
+        return;
+    }
+    const oldWorkspace = join(os.homedir(), 'CSPeach');
+    if (!existsSync(oldWorkspace)) {
+        await saveConfig({ ...cfg, migration_prompted: true });
+        return;
+    }
+    let oldFiles;
+    try {
+        oldFiles = readdirSync(oldWorkspace).filter((f) => f.endsWith('.cspeach.json') || f.endsWith('.txt') || f.endsWith('.md'));
+    }
+    catch {
+        await saveConfig({ ...cfg, migration_prompted: true });
+        return;
+    }
+    if (oldFiles.length === 0) {
+        await saveConfig({ ...cfg, migration_prompted: true });
+        return;
+    }
+    const newWorkspace = defaultWorkspaceFor(process.cwd());
+    let choice;
+    try {
+        choice = await deps.prompt({
+            fileCount: oldFiles.length,
+            oldWorkspace,
+            newWorkspace,
+        });
+    }
+    catch {
+        // User Ctrl+C'd the prompt — leave migration_prompted unset so the
+        // dialog re-fires next session. Better than silently committing to
+        // a default they never saw.
+        return;
+    }
+    if (choice === 'move') {
+        try {
+            mkdirSync(newWorkspace, { recursive: true });
+            for (const f of oldFiles) {
+                const src = join(oldWorkspace, f);
+                const dst = join(newWorkspace, f);
+                if (existsSync(dst)) {
+                    deps.log(`(skipping ${f} — already exists in new workspace)`);
+                    continue;
+                }
+                renameSync(src, dst);
+            }
+            deps.log(`Moved ${oldFiles.length} file(s) → ${newWorkspace}`);
+        }
+        catch (err) {
+            deps.log(`Migration failed: ${err.message}. Old folder left untouched.`);
+        }
+    }
+    else if (choice === 'keep_global') {
+        await saveConfig({
+            ...cfg,
+            workspace_folder: oldWorkspace,
+            migration_prompted: true,
+        });
+        deps.log(`Workspace pinned to ${oldWorkspace}.`);
+        return; // saveConfig already done
+    }
+    else {
+        deps.log(`Leaving ${oldWorkspace} alone. New artefacts go to ${newWorkspace}.`);
+    }
+    await saveConfig({ ...cfg, migration_prompted: true });
+}

package/dist/projects/promote-command.js

@@ -0,0 +1,96 @@
+import { readProjectFile } from './status.js';
+import { buildPromotedFromSnapshot, validatePromotionSource } from './promote.js';
+import { resolveAtTokenAsync, formatProjectFileList } from './workspace.js';
+/**
+ * Per-skill predecessor map. v0.7 admits multi-source via array values —
+ * e.g. /abap-upgrade-fix accepts BOTH upgrade-scan (the existing chain
+ * from /abap-upgrade-scan) AND cca-assessment (the v0.7 chain from
+ * /abap-cca, with an adapter that reads CCA's detail file). Order in
+ * the array doesn't matter; validatePromotionSource just checks
+ * membership.
+ */
+const PREDECESSOR_BY_TARGET = {
+    'abap-design': 'spec-gap',
+    'abap-estimate': 'design',
+    'abap-generate': 'design',
+    'abap-rap': 'design',
+    'abap-upgrade-fix': ['upgrade-scan', 'cca-assessment'], // v0.7: multi-source
+    'abap-upgrade-verify': 'upgrade-progress',
+    'abap-modernize': 'cca-assessment', // v0.7: new chain
+    'abap-test': 'cca-assessment', // v0.7: new chain
+};
+function affirmative(reply) {
+    const v = reply.trim().toLowerCase();
+    return v === 'y' || v === 'yes';
+}
+function buildExtendedInput(p) {
+    const lines = [
+        `Promoted from ${p.artefactType} (v${p.version}) — "${p.title}".`,
+        `Source items below; use the answers/decisions as primary context.`,
+        '',
+    ];
+    for (const it of p.snapshot.items) {
+        const sevPart = it.severity ? `[${it.severity}] ` : '';
+        const trail = it.answer ? it.answer : (it.status === 'open' ? '<open>' : it.status);
+        lines.push(`${sevPart}${it.id}: ${it.text} → ${trail}`);
+    }
+    return lines.join('\n');
+}
+export async function runPromoteCommand(args) {
+    const expectedPredecessor = PREDECESSOR_BY_TARGET[args.targetSkill];
+    if (!expectedPredecessor) {
+        args.log(`--from: unknown target skill: ${args.targetSkill}`);
+        return null;
+    }
+    // Resolve the @<token> against the workspace folder. Absolute paths are
+    // returned as-is; bare names are looked up in `~/CSPeach/` (or the
+    // configured workspace_folder). Ambiguous bare names abort with the
+    // candidate list so the user can disambiguate, rather than silently
+    // picking the wrong file.
+    const resolved = await resolveAtTokenAsync(args.sourcePath, process.cwd());
+    let resolvedPath;
+    if (resolved.kind === 'path') {
+        resolvedPath = resolved.path;
+    }
+    else if (resolved.kind === 'notFound') {
+        args.log(`--from: no file matching '${resolved.token}' in workspace ${resolved.workspace}`);
+        args.log(`Run /files to see available .cspeach.json files.`);
+        return null;
+    }
+    else {
+        args.log(`--from: '${args.sourcePath}' is ambiguous — multiple matches:`);
+        args.log(formatProjectFileList(resolved.matches, ''));
+        args.log(`Use a more specific @<fragment> to disambiguate.`);
+        return null;
+    }
+    let env;
+    try {
+        env = readProjectFile(resolvedPath);
+    }
+    catch (e) {
+        args.log(`--from source error: ${String(e instanceof Error ? e.message : e)}`);
+        return null;
+    }
+    const validation = validatePromotionSource(env, expectedPredecessor);
+    if (!validation.ok) {
+        args.log(`--from: ${validation.error ?? 'source validation failed.'}`);
+        return null;
+    }
+    for (const w of validation.warnings) {
+        if (w.kind === 'ZERO_ANSWERED') {
+            const reply = await args.prompt(`Source has no answered items (${w.count} still open). Continue anyway? [y/N]: `);
+            if (!affirmative(reply))
+                return null;
+        }
+        else if (w.kind === 'PARTIAL_OPEN') {
+            const sample = w.openIds.slice(0, 5).join(', ');
+            const more = w.openIds.length > 5 ? `, ... ${w.openIds.length - 5} more` : '';
+            const reply = await args.prompt(`${w.openIds.length} item(s) still open (${sample}${more}). Promote anyway? [y/N]: `);
+            if (!affirmative(reply))
+                return null;
+        }
+    }
+    const promotedFrom = await buildPromotedFromSnapshot(env);
+    const extendedSkillInput = buildExtendedInput(promotedFrom);
+    return { promotedFrom, extendedSkillInput };
+}

package/dist/projects/promote.js

@@ -0,0 +1,107 @@
+import { canonicalSha256 } from './canonicalize.js';
+function itemTextFor(env, itemId) {
+    if (env.artefactType === 'spec-gap') {
+        for (const s of env.content.sections) {
+            for (const g of s.gaps) {
+                if (g.id === itemId)
+                    return { text: g.text, severity: g.severity };
+            }
+        }
+        return { text: '<text not found>' };
+    }
+    if (env.artefactType === 'design') {
+        const o = env.content.objects.find((x) => x.id === itemId);
+        return o ? { text: `${o.name} (${o.type})` } : { text: '<text not found>' };
+    }
+    if (env.artefactType === 'estimate') {
+        const c = env.content.components.find((x) => x.id === itemId);
+        return c ? { text: `${c.name} — ${c.hoursOptimistic}/${c.hoursRealistic}/${c.hoursPessimistic} h` } : { text: '<text not found>' };
+    }
+    if (env.artefactType === 'upgrade-scan') {
+        const f = env.content.findings.find((x) => x.id === itemId);
+        return f ? { text: `${f.objectName} (${f.objectType}) — ${f.rule} [${f.severity}]` } : { text: '<text not found>' };
+    }
+    if (env.artefactType === 'upgrade-progress') {
+        const fx = env.content.fixes.find((x) => x.id === itemId);
+        return fx ? { text: `${fx.objectName} — ${fx.finding} → ${fx.status}` } : { text: '<text not found>' };
+    }
+    if (env.artefactType === 'upgrade-report') {
+        const r = env.content.regressions.find((x) => x.id === itemId);
+        return r ? { text: `${r.objectName} — ${r.rule}: ${r.reason}` } : { text: '<text not found>' };
+    }
+    if (env.artefactType === 'cca-assessment') {
+        const c = env.content.classifications.find((x) => x.id === itemId);
+        return c ? { text: `${c.objectName} (${c.objectType}) — ${c.classification} [${c.confidence}]` } : { text: '<text not found>' };
+    }
+    if (env.artefactType === 'modernize-result') {
+        const m = env.content.modernizations.find((x) => x.id === itemId);
+        return m ? { text: `${m.objectName} (${m.objectType}) — ${m.fromArchitecture} → ${m.toArchitecture} [${m.status}]` } : { text: '<text not found>' };
+    }
+    if (env.artefactType === 'test-coverage') {
+        const t = env.content.tests.find((x) => x.id === itemId);
+        return t ? { text: `${t.targetObjectName} (${t.targetObjectType}) — ${t.testClassName} (${t.methodCount} methods) [${t.status}]` } : { text: '<text not found>' };
+    }
+    return { text: '<unsupported artefactType>' };
+}
+export async function buildPromotedFromSnapshot(source) {
+    const sha = await canonicalSha256(source);
+    const items = source.interaction.items.map((it) => {
+        const tx = itemTextFor(source, it.id);
+        const out = {
+            id: it.id,
+            text: tx.text,
+            status: it.status,
+            answer: it.answer,
+        };
+        if (tx.severity)
+            out.severity = tx.severity;
+        return out;
+    });
+    return {
+        id: source.id,
+        title: source.title,
+        artefactType: source.artefactType,
+        version: source.version,
+        sha256: sha,
+        snapshottedAt: new Date().toISOString(),
+        snapshot: { items },
+    };
+}
+export function validatePromotionSource(source, expectedPredecessor) {
+    // v0.7 — accept either a single predecessor or an array (multi-source).
+    // /abap-upgrade-fix accepts both upgrade-scan AND cca-assessment, etc.
+    const allowed = Array.isArray(expectedPredecessor)
+        ? expectedPredecessor
+        : [expectedPredecessor];
+    if (!allowed.includes(source.artefactType)) {
+        // Preserve the natural "a <type> source" phrasing for single-predecessor
+        // case (matches existing test expectations + reads better in CLI output);
+        // multi-source case explicitly lists the alternatives.
+        const expectedDesc = allowed.length === 1
+            ? `a ${allowed[0]}`
+            : `one of [${allowed.join(', ')}]`;
+        return {
+            ok: false,
+            warnings: [],
+            error: `--from expects ${expectedDesc} source; got ${source.artefactType}.`,
+        };
+    }
+    const warnings = [];
+    const items = source.interaction.items;
+    const openIds = items.filter((i) => i.status === 'open').map((i) => i.id);
+    const answeredCount = items.filter((i) => i.status !== 'open' && (source.artefactType === 'spec-gap'
+        ? i.status === 'answered'
+        : true)).length;
+    if (source.artefactType === 'spec-gap') {
+        if (answeredCount === 0) {
+            warnings.push({ kind: 'ZERO_ANSWERED', count: items.length });
+        }
+        else if (openIds.length > 0) {
+            warnings.push({ kind: 'PARTIAL_OPEN', openIds });
+        }
+    }
+    // For design / estimate, status is always terminal (no "open" enum), so no
+    // partial-open warning applies. They are always either decided or not-yet-decided
+    // via redesign/defer/disputed; that nuance is a v0.6+ check.
+    return { ok: true, warnings };
+}