@cspeach/cli 0.6.0

package/dist/projects/save-command.js

@@ -0,0 +1,124 @@
+import { extractSpecGap } from './extract-spec-gap.js';
+import { extractDesign } from './extract-design.js';
+import { extractEstimate } from './extract-estimate.js';
+import { extractUpgradeScan, extractUpgradeProgress, extractUpgradeReport } from './extract-upgrade.js';
+import { extractCcaAssessment } from './extract-cca.js';
+import { extractModernizeResult } from './extract-modernize.js';
+import { extractTestCoverage } from './extract-test-coverage.js';
+import { buildEnvelope } from './build.js';
+import { saveProject } from './save.js';
+import { renderEmailTemplate } from './email-template.js';
+import { ensureWorkspace } from './workspace.js';
+const SKILL_REGISTRY = {
+    'abap-spec-gap': {
+        artefactType: 'spec-gap',
+        extract: (md) => extractSpecGap(md),
+        itemNoun: 'questions',
+    },
+    'abap-design': {
+        artefactType: 'design',
+        extract: (md) => extractDesign(md),
+        itemNoun: 'objects',
+    },
+    'abap-estimate': {
+        artefactType: 'estimate',
+        extract: (md) => extractEstimate(md),
+        itemNoun: 'components',
+    },
+    'abap-upgrade-scan': {
+        artefactType: 'upgrade-scan',
+        extract: (md) => extractUpgradeScan(md),
+        itemNoun: 'findings',
+    },
+    'abap-upgrade-fix': {
+        artefactType: 'upgrade-progress',
+        extract: (md) => extractUpgradeProgress(md),
+        itemNoun: 'fixes',
+    },
+    'abap-upgrade-verify': {
+        artefactType: 'upgrade-report',
+        extract: (md) => extractUpgradeReport(md),
+        itemNoun: 'regressions',
+    },
+    'abap-upgrade-merge': {
+        // Merge produces a NEW upgrade-progress (consolidated) — same shape
+        // as a single dev's fix output, just reconciled across N slices.
+        artefactType: 'upgrade-progress',
+        extract: (md) => extractUpgradeProgress(md),
+        itemNoun: 'fixes',
+    },
+    'abap-cca': {
+        artefactType: 'cca-assessment',
+        extract: (md) => extractCcaAssessment(md),
+        itemNoun: 'classifications',
+    },
+    'abap-cca-merge': {
+        // Merge produces a NEW cca-assessment (consolidated) — same shape as
+        // a single consultant's slice, just reconciled across N parallel reviews.
+        artefactType: 'cca-assessment',
+        extract: (md) => extractCcaAssessment(md),
+        itemNoun: 'classifications',
+    },
+    'abap-modernize': {
+        artefactType: 'modernize-result',
+        extract: (md) => extractModernizeResult(md),
+        itemNoun: 'modernizations',
+    },
+    'abap-test': {
+        artefactType: 'test-coverage',
+        extract: (md) => extractTestCoverage(md),
+        itemNoun: 'tests',
+    },
+};
+export async function runSaveCommand(args) {
+    const spec = SKILL_REGISTRY[args.skillName];
+    if (!spec)
+        return null;
+    let extract;
+    try {
+        extract = spec.extract(args.skillOutput);
+    }
+    catch {
+        return null;
+    }
+    const answer = (await args.prompt('Save as project file? [y/N]: ')).trim().toLowerCase();
+    if (answer !== 'y' && answer !== 'yes')
+        return null;
+    const env = buildEnvelope({
+        artefactType: spec.artefactType,
+        extract,
+        author: args.author,
+        source: {
+            skill: args.skillName,
+            skillVersion: args.skillVersion,
+            input: args.skillInput,
+            tokensUsed: args.tokensUsed,
+            model: args.model,
+        },
+        promotedFrom: args.promotedFrom ?? null,
+    });
+    // Save into the workspace folder (~/CSPeach by default), not cwd. Falls
+    // back to args.cwd if the workspace can't be created (e.g. permission
+    // error on the home directory) — saving SOMEWHERE is better than losing
+    // the artefact.
+    let outDir;
+    try {
+        outDir = await ensureWorkspace();
+    }
+    catch {
+        outDir = args.cwd;
+    }
+    const path = await saveProject(env, { cwd: outDir });
+    args.log(`Saved: ${path}`);
+    args.log(`Share at: https://cspeach.dev/edit`);
+    args.log('');
+    args.log(renderEmailTemplate({
+        title: env.title,
+        artefactType: spec.artefactType,
+        filename: path.split(/[\\\/]/).pop(),
+        itemCount: env.interaction.items.length,
+        itemNoun: spec.itemNoun,
+        author: args.author.name,
+    }));
+    return path;
+}

package/dist/projects/save.js

@@ -0,0 +1,21 @@
+import { writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { projectFilename } from './filename.js';
+export async function saveProject(env, opts) {
+    const baseName = projectFilename({
+        title: env.title,
+        artefactType: env.artefactType,
+        id: env.id,
+        version: env.version,
+    });
+    let target = join(opts.cwd, baseName);
+    if (existsSync(target)) {
+        const stem = baseName.replace(/\.cspeach\.json$/, '');
+        let n = 2;
+        while (existsSync(join(opts.cwd, `${stem}-${n}.cspeach.json`)))
+            n++;
+        target = join(opts.cwd, `${stem}-${n}.cspeach.json`);
+    }
+    writeFileSync(target, JSON.stringify(env, null, 2), 'utf8');
+    return target;
+}

package/dist/projects/status.js

@@ -0,0 +1,170 @@
+import { readFileSync } from 'node:fs';
+import { validateEnvelope } from './validate.js';
+import { canonicalSha256 } from './canonicalize.js';
+export function readProjectFile(path) {
+    const raw = readFileSync(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Not valid JSON. Did the file get truncated in email? (${path})`);
+    }
+    const result = validateEnvelope(parsed);
+    if (!result.ok) {
+        throw new Error(`Invalid project file at ${path}: ${result.error.message}`);
+    }
+    return result.envelope;
+}
+const STATUS_BY_TYPE = {
+    'spec-gap': ['answered', 'open', 'deferred', 'n-a'],
+    'design': ['keep', 'redesign', 'defer'],
+    'estimate': ['confirmed', 'disputed', 'deferred'],
+    'cca': ['keep', 'fix', 'retire', 'redesign'],
+    'incident': ['pending', 'done'],
+};
+const PRIMARY_BY_TYPE = {
+    'spec-gap': 'answered',
+    'design': 'keep',
+    'estimate': 'confirmed',
+    'cca': 'keep',
+    'incident': 'done',
+};
+const PROMOTE_HINT_BY_TYPE = {
+    'spec-gap': '/abap-design --from',
+    'design': '/abap-estimate --from',
+    'estimate': null,
+    'cca': null,
+    'incident': null,
+};
+export function renderStatus(env) {
+    const items = env.interaction.items;
+    const total = items.length;
+    const enums = STATUS_BY_TYPE[env.artefactType] ?? [];
+    const primary = PRIMARY_BY_TYPE[env.artefactType];
+    const counts = {};
+    for (const s of enums)
+        counts[s] = 0;
+    for (const it of items) {
+        if (counts[it.status] !== undefined)
+            counts[it.status]++;
+    }
+    const lines = [];
+    lines.push(`${env.title} — ${env.artefactType} (v${env.version})`);
+    const primaryCount = primary ? counts[primary] ?? 0 : 0;
+    const summaryParts = [`${primaryCount} / ${total} ${primary ?? 'items'}`];
+    for (const s of enums) {
+        if (s === primary)
+            continue;
+        const c = counts[s] ?? 0;
+        if (c > 0)
+            summaryParts.push(`${c} ${displayStatus(s)}`);
+    }
+    lines.push(`   ${summaryParts.join('  ·  ')}`);
+    lines.push(`   Last edited by ${env.lastEditedBy.name} (${env.lastEditedBy.role}) — ${formatDate(env.lastEditedAt)}`);
+    lines.push('');
+    // Open-list section: only meaningful for artefactTypes that have an "open"
+    // status (spec-gap). Design/estimate use kept/confirmed as "decided" — there
+    // is no "still pending" state; every item has a terminal status from the start.
+    if (env.artefactType === 'spec-gap' && counts.open > 0) {
+        lines.push(`Open (${counts.open}):`);
+        const stillOpen = items.filter((i) => i.status === 'open');
+        const gapMap = new Map();
+        const content = env.content;
+        for (const s of content.sections)
+            for (const g of s.gaps)
+                gapMap.set(g.id, { severity: g.severity, text: g.text });
+        for (const it of stillOpen.slice(0, 10)) {
+            const g = gapMap.get(it.id);
+            if (g)
+                lines.push(`  [${g.severity}] ${it.id}: ${truncate(g.text, 80)}`);
+            else
+                lines.push(`  ${it.id}: <text not found in content>`);
+        }
+        if (stillOpen.length > 10)
+            lines.push(`  ... ${stillOpen.length - 10} more`);
+        lines.push('');
+    }
+    // Promote hint fires whenever a "next phase" exists for this artefactType.
+    // Unlike the v1 implementation we no longer gate on `primaryCount > 0` —
+    // a design with zero `keep` items (all `redesign` / `defer`) is still a
+    // legitimate input for `--from`, and the user can decide whether to act on
+    // the hint. The hint is informational, not a guard.
+    const hint = PROMOTE_HINT_BY_TYPE[env.artefactType];
+    if (hint) {
+        lines.push(`Ready to promote? Run:`);
+        lines.push(`  ${hint} @<this-file>`);
+    }
+    return lines.join('\n');
+}
+function displayStatus(s) {
+    if (s === 'n-a')
+        return 'n/a';
+    return s;
+}
+function formatDate(iso) {
+    return iso.slice(0, 16).replace('T', ' ');
+}
+function truncate(s, n) {
+    return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+/**
+ * Spec §9: two files are treated as having the same source iff they share the
+ * same `id` AND their `history` arrays agree up to the most recent entry that
+ * pre-dates the divergence. We implement this by checking that all envelopes
+ * share the same id, then verifying their history arrays share a common prefix
+ * of length >= 1 (the create entry). Same source + same version + different
+ * canonical SHAs → parallel edit warning.
+ */
+function shareCommonAncestor(envs) {
+    const firstId = envs[0].id;
+    if (!envs.every((e) => e.id === firstId))
+        return false;
+    // Find the longest common prefix of history arrays.
+    const minLen = Math.min(...envs.map((e) => e.history.length));
+    let prefix = 0;
+    outer: for (let i = 0; i < minLen; i++) {
+        const ref = JSON.stringify(envs[0].history[i]);
+        for (let j = 1; j < envs.length; j++) {
+            if (JSON.stringify(envs[j].history[i]) !== ref)
+                break outer;
+        }
+        prefix++;
+    }
+    // At least the 'created' entry must be shared for them to be the same source.
+    return prefix >= 1;
+}
+export async function renderMultiFileStatus(envs) {
+    if (envs.length === 1)
+        return renderStatus(envs[0]);
+    const firstVer = envs[0].version;
+    const allSameVersion = envs.every((e) => e.version === firstVer);
+    const sameSource = shareCommonAncestor(envs);
+    if (sameSource && allSameVersion) {
+        const shas = await Promise.all(envs.map(canonicalSha256));
+        const distinct = new Set(shas);
+        if (distinct.size > 1) {
+            const lines = [];
+            lines.push(`⚠ Two v${firstVer} files received from same source, with conflicting changes.`);
+            for (let i = 0; i < envs.length; i++) {
+                const e = envs[i];
+                const items = e.interaction.items;
+                const counts = { answered: 0, deferred: 0, comments: 0 };
+                for (const it of items) {
+                    if (it.status === 'answered')
+                        counts.answered++;
+                    if (it.status === 'deferred')
+                        counts.deferred++;
+                    counts.comments += it.comments.length;
+                }
+                lines.push(`   v${e.version} from ${e.lastEditedBy.name}: ${counts.answered} answered, ${counts.deferred} deferred, ${counts.comments} comments  (sha ${shas[i].slice(0, 6)}...)`);
+            }
+            lines.push('');
+            lines.push('This is a parallel edit. Reconcile manually — open each in the editor,');
+            lines.push('copy answers across, save as v' + (firstVer + 1) + ' with merged content.');
+            return lines.join('\n');
+        }
+    }
+    // Otherwise just print each individually
+    return envs.map(renderStatus).join('\n\n');
+}

package/dist/projects/types.js

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

package/dist/projects/validate.js

@@ -0,0 +1,146 @@
+const SUPPORTED_SCHEMA_MAJOR = 1;
+const SUPPORTED_SCHEMA_MINOR = 0;
+const KNOWN_ARTEFACT_TYPES = [
+    'spec-gap', 'design', 'estimate', 'cca', 'incident',
+    'upgrade-scan', 'upgrade-progress', 'upgrade-report',
+    'cca-assessment',
+    'modernize-result', 'test-coverage',
+];
+const STATUS_BY_TYPE = {
+    'spec-gap': ['open', 'answered', 'deferred', 'n-a'],
+    'design': ['keep', 'redesign', 'defer'],
+    'estimate': ['confirmed', 'disputed', 'deferred'],
+    'cca': ['keep', 'fix', 'retire', 'redesign'],
+    'incident': ['pending', 'done'],
+    'upgrade-scan': ['open', 'auto-fix', 'manual', 'suppress'],
+    'upgrade-progress': ['fixed', 'skipped', 'failed', 'pending'],
+    'upgrade-report': ['closed', 'regression', 'pending'],
+    'cca-assessment': ['open', 'reviewed', 'classified', 'archived'],
+    'modernize-result': ['applied', 'skipped', 'failed', 'pending'],
+    'test-coverage': ['generated', 'skipped', 'failed', 'pending'],
+};
+const REQUIRED_TOP_LEVEL = [
+    'schemaVersion', 'artefactType', 'id', 'title',
+    'createdAt', 'createdBy', 'lastEditedAt', 'lastEditedBy',
+    'version', 'source', 'promotedFrom', 'content', 'interaction', 'history',
+];
+const REQUIRED_IDENTITY = ['name', 'role'];
+const REQUIRED_ITEM = ['id', 'status', 'answer', 'answeredBy', 'answeredAt', 'comments'];
+const REQUIRED_HISTORY_ENTRY = ['at', 'by', 'action'];
+/** Spec §9: missing means absent OR null OR (for strings) empty string. */
+function isMissing(v) {
+    if (v === undefined || v === null)
+        return true;
+    if (typeof v === 'string' && v.length === 0)
+        return true;
+    return false;
+}
+function fail(code, field, message, warnings) {
+    return { ok: false, error: { code, field, message }, warnings };
+}
+/** Returns null on parse failure; otherwise [major, minor] tuple. */
+function parseSchemaVersion(v) {
+    if (typeof v !== 'string')
+        return null;
+    const m = /^(\d+)\.(\d+)(?:\.\d+)?$/.exec(v);
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2])];
+}
+export function validateEnvelope(input) {
+    const warnings = [];
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return fail('NOT_OBJECT', '<root>', 'Expected a JSON object', warnings);
+    }
+    const env = input;
+    for (const f of REQUIRED_TOP_LEVEL) {
+        // promotedFrom is allowed to be null; handle it explicitly
+        if (f === 'promotedFrom') {
+            if (!(f in env)) {
+                return fail('MISSING_FIELD', f, `Missing required field: ${f}`, warnings);
+            }
+            continue;
+        }
+        if (!(f in env) || isMissing(env[f])) {
+            return fail('MISSING_FIELD', f, `Missing required field: ${f}`, warnings);
+        }
+    }
+    const sv = parseSchemaVersion(env.schemaVersion);
+    if (sv === null) {
+        return fail('INVALID_VALUE', 'schemaVersion', `Malformed schemaVersion: ${String(env.schemaVersion)} (expected "<int>.<int>")`, warnings);
+    }
+    const [major, minor] = sv;
+    if (major > SUPPORTED_SCHEMA_MAJOR ||
+        (major === SUPPORTED_SCHEMA_MAJOR && minor > SUPPORTED_SCHEMA_MINOR)) {
+        warnings.push('SCHEMA_TOO_NEW');
+    }
+    else if (major !== SUPPORTED_SCHEMA_MAJOR || minor !== SUPPORTED_SCHEMA_MINOR) {
+        return fail('INVALID_VALUE', 'schemaVersion', `Unsupported schemaVersion: ${String(env.schemaVersion)}`, warnings);
+    }
+    if (typeof env.artefactType !== 'string' || !KNOWN_ARTEFACT_TYPES.includes(env.artefactType)) {
+        return fail('INVALID_VALUE', 'artefactType', `Unknown artefactType: ${String(env.artefactType)}`, warnings);
+    }
+    if (typeof env.version !== 'number' || !Number.isInteger(env.version) || env.version < 1) {
+        return fail('INVALID_VALUE', 'version', `version must be a positive integer`, warnings);
+    }
+    if (!Array.isArray(env.history) || env.history.length !== env.version) {
+        return fail('VERSION_MISMATCH', 'version', `version (${env.version}) must equal history.length (${Array.isArray(env.history) ? env.history.length : 'n/a'})`, warnings);
+    }
+    for (const idField of ['createdBy', 'lastEditedBy']) {
+        const id = env[idField];
+        if (typeof id !== 'object' || id === null) {
+            return fail('MISSING_FIELD', idField, `${idField} must be an object`, warnings);
+        }
+        for (const f of REQUIRED_IDENTITY) {
+            const idObj = id;
+            if (!(f in idObj) || isMissing(idObj[f])) {
+                return fail('MISSING_FIELD', `${idField}.${f}`, `Missing ${idField}.${f}`, warnings);
+            }
+        }
+    }
+    if (typeof env.interaction !== 'object' || env.interaction === null
+        || !Array.isArray(env.interaction.items)) {
+        return fail('MISSING_FIELD', 'interaction.items', 'interaction.items must be an array', warnings);
+    }
+    const items = env.interaction.items;
+    const validStatuses = STATUS_BY_TYPE[env.artefactType];
+    const seenIds = new Set();
+    for (let i = 0; i < items.length; i++) {
+        const raw = items[i];
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            return fail('INVALID_VALUE', `interaction.items[${i}]`, `interaction.items[${i}] must be an object`, warnings);
+        }
+        const item = raw;
+        for (const f of REQUIRED_ITEM) {
+            if (!(f in item)) {
+                return fail('MISSING_FIELD', `interaction.items[${i}].${f}`, `Missing items[${i}].${f}`, warnings);
+            }
+        }
+        if (typeof item.id !== 'string' || item.id.length === 0) {
+            return fail('INVALID_VALUE', `interaction.items[${i}].id`, `Item id must be a non-empty string`, warnings);
+        }
+        if (seenIds.has(item.id)) {
+            return fail('INVALID_VALUE', `interaction.items[${i}].id`, `Duplicate item id: ${item.id}`, warnings);
+        }
+        seenIds.add(item.id);
+        if (!validStatuses.includes(item.status)) {
+            return fail('INVALID_VALUE', `interaction.items[${i}].status`, `Status '${String(item.status)}' not valid for ${env.artefactType}; allowed: ${validStatuses.join(', ')}`, warnings);
+        }
+    }
+    for (let i = 0; i < env.history.length; i++) {
+        const raw = env.history[i];
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            return fail('INVALID_HISTORY', `history[${i}]`, `history[${i}] must be an object`, warnings);
+        }
+        const h = raw;
+        for (const f of REQUIRED_HISTORY_ENTRY) {
+            if (!(f in h)) {
+                return fail('INVALID_HISTORY', `history[${i}].${f}`, `Missing history[${i}].${f}`, warnings);
+            }
+        }
+        if (h.action !== 'created' && h.action !== 'edited') {
+            return fail('INVALID_HISTORY', `history[${i}].action`, `action must be 'created' or 'edited', got ${String(h.action)}`, warnings);
+        }
+    }
+    return { ok: true, envelope: env, warnings };
+}