@cspeach/cli 0.6.0

package/dist/skills/source-bundled.js

@@ -0,0 +1,20 @@
+import { BUNDLED_SKILLS } from './bundled-skills.js';
+export function createBundledSkillSource() {
+    return {
+        async getSkillBody(name) {
+            const body = BUNDLED_SKILLS[name];
+            if (!body) {
+                const avail = Object.keys(BUNDLED_SKILLS);
+                throw new Error(`skill '${name}' not bundled in this CLI build (local mode).` +
+                    ` This CLI ships ${avail.length} skills. Upgrade CLI for newer skills, or switch to byok/ai-hub mode for live manifest fetch.`);
+            }
+            return body;
+        },
+        async listAvailableSkills() {
+            return Object.keys(BUNDLED_SKILLS);
+        },
+        describe() {
+            return `bundled with CLI binary (${Object.keys(BUNDLED_SKILLS).length} skills)`;
+        },
+    };
+}

package/dist/skills/source-managed.js

@@ -0,0 +1,26 @@
+export function createManagedSkillSource(cfg, getBearer) {
+    const baseUrl = cfg.proxy_url.replace(/\/$/, '');
+    return {
+        async getSkillBody(name) {
+            const bearer = await getBearer();
+            const r = await fetch(`${baseUrl}/v1/skills/${encodeURIComponent(name)}`, {
+                headers: { Authorization: `Bearer ${bearer}` },
+            });
+            if (!r.ok)
+                throw new Error(`managed skill fetch: HTTP ${r.status} for ${name}`);
+            const j = await r.json();
+            return { name: j.name, body: j.body, sha256: j.sha256, signature: j.signature, signedAt: j.signedAt };
+        },
+        async listAvailableSkills() {
+            const bearer = await getBearer();
+            const r = await fetch(`${baseUrl}/v1/skills`, { headers: { Authorization: `Bearer ${bearer}` } });
+            if (!r.ok)
+                throw new Error(`managed skill list: HTTP ${r.status}`);
+            const j = await r.json();
+            return j.skills.map((s) => s.name);
+        },
+        describe() {
+            return `managed via ${cfg.proxy_url} (bearer-authenticated)`;
+        },
+    };
+}

package/dist/skills/source-manifest.js

@@ -0,0 +1,26 @@
+import { ManifestClient } from './manifest-client.js';
+export function createManifestSkillSource(manifestUrl) {
+    const client = new ManifestClient(manifestUrl);
+    let cachedManifest = null;
+    async function getManifest() {
+        if (!cachedManifest)
+            cachedManifest = await client.fetchAndVerifyManifest();
+        return cachedManifest;
+    }
+    return {
+        async getSkillBody(name) {
+            const m = await getManifest();
+            const entry = m.skills.find(s => s.name === name);
+            if (!entry)
+                throw new Error(`skill '${name}' not found in manifest (available: ${m.skills.map(s => s.name).join(', ')})`);
+            return client.fetchSkillBody(name, entry.body_url, { expectedSha256: entry.sha256 });
+        },
+        async listAvailableSkills() {
+            const m = await getManifest();
+            return m.skills.map(s => s.name);
+        },
+        describe() {
+            return `public signed manifest at ${manifestUrl}`;
+        },
+    };
+}

package/dist/tools/_command-shared.js

@@ -0,0 +1,110 @@
+// cspeach-cli/src/tools/_command-shared.ts
+/**
+ * Phase 3 / Chunk 3E — shared command-spawning helpers.
+ *
+ * Extracted from shell_exec.ts so background_run can reuse the same
+ * safelist + PATHEXT walk + env scrubbing without duplication. Pure
+ * refactor — every constant, every check, every limit is identical
+ * to what shell_exec used inline before this extraction.
+ *
+ * Importers: shell_exec.ts (Chunk 3B), background_run.ts (Chunk 3E).
+ * No tool runs the bare command name through any shell parser — argv
+ * arrays only, shell: false, every time.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { loadConfig } from '../config/loader.js';
+export const DEFAULT_SAFELIST = new Set([
+    'npm', 'pnpm', 'ui5', 'cds', 'git', 'abaplint', 'node',
+]);
+// Defense-in-depth caps on the argv array — neither matters for normal
+// build commands, but a pathological model output could otherwise consume
+// memory before spawn ever runs. Per-arg cap is far above any realistic
+// flag value; total cap is far above any realistic command-line length.
+export const MAX_ARGS = 1_000;
+export const MAX_ARG_BYTES = 100_000;
+export const KILL_GRACE_MS = 2_000; // SIGTERM → SIGKILL escalation grace
+// Env names that pass through to children. Everything else (including
+// CSPEACH_*, ANTHROPIC_*, SAP_*) is dropped. Both 'PATH' and 'Path'
+// appear because Node's process.env on Windows is case-insensitive at
+// read time but case-preserving at iteration — only one ends up in
+// process.env in practice, but accepting both keeps the whitelist
+// honest about what we'd let through if both ever co-existed.
+export const ENV_PASSTHROUGH = new Set([
+    'PATH', 'Path', 'PATHEXT', 'HOME', 'USERPROFILE', 'TEMP', 'TMP',
+    'SystemRoot', 'windir', 'COMSPEC', 'LANG', 'LC_ALL', 'TZ',
+]);
+export function buildSafeEnv() {
+    const out = {};
+    for (const k of Object.keys(process.env)) {
+        if (ENV_PASSTHROUGH.has(k))
+            out[k] = process.env[k];
+    }
+    return out;
+}
+export async function loadSafelist() {
+    try {
+        const cfg = await loadConfig();
+        const extras = cfg.shell_exec?.allow ?? [];
+        return new Set([...DEFAULT_SAFELIST, ...extras]);
+    }
+    catch {
+        return new Set(DEFAULT_SAFELIST);
+    }
+}
+/**
+ * Resolve a bare command name to an absolute executable path by walking
+ * PATH. Tries the bare name + PATHEXT extensions on Windows. Returns
+ * null if nothing matches anywhere on PATH. Identical to Chunk 3B's
+ * inlined function — extracted verbatim.
+ */
+export async function resolveExecutable(name) {
+    const PATH = process.env.PATH ?? process.env.Path ?? '';
+    const dirs = PATH.split(path.delimiter).filter((d) => d.length > 0);
+    let extensions;
+    if (process.platform === 'win32') {
+        const pathext = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').toLowerCase().split(';');
+        extensions = ['', ...pathext];
+    }
+    else {
+        extensions = [''];
+    }
+    for (const dir of dirs) {
+        for (const ext of extensions) {
+            const candidate = path.join(dir, name + ext);
+            try {
+                const stat = await fs.stat(candidate);
+                if (stat.isFile())
+                    return candidate;
+            }
+            catch { /* ENOENT — keep walking */ }
+        }
+    }
+    return null;
+}
+/**
+ * Returns null if argv is valid, or an error message describing the
+ * violation. Caller surfaces this as the tool's error envelope.
+ */
+export function validateArgv(argv) {
+    if (argv.length > MAX_ARGS) {
+        return `too many args (max ${MAX_ARGS}, got ${argv.length})`;
+    }
+    const oversized = argv.findIndex((a) => a.length > MAX_ARG_BYTES);
+    if (oversized !== -1) {
+        return `arg at index ${oversized} exceeds max length of ${MAX_ARG_BYTES} chars`;
+    }
+    return null;
+}
+/**
+ * Returns null if the bare command name is acceptable, or an error
+ * message if it contains a path separator OR is absolute. Closes the
+ * "model passes /bin/sh because /bin/sh's basename is in the safelist"
+ * class of attack.
+ */
+export function rejectPathSeparator(command) {
+    if (path.isAbsolute(command) || command.includes('/') || command.includes('\\')) {
+        return `command must be a bare name (no path separators / not absolute path) — got "${command}". safelist check refused.`;
+    }
+    return null;
+}

package/dist/tools/_filesystem-shared.js

@@ -0,0 +1,81 @@
+// cspeach-cli/src/tools/_filesystem-shared.ts
+/**
+ * Phase 3 — shared filesystem-tool helpers.
+ *
+ * Centralizes path containment so individual tools (file_read, file_edit,
+ * file_write, glob, grep) cannot drift on their own security checks.
+ * Every Phase 3 filesystem tool MUST resolve user-supplied paths through
+ * resolveSafePath before doing any IO.
+ */
+import * as path from 'node:path';
+import { promises as fsPromises } from 'node:fs';
+/** Phase 3 sensitive in-root paths — refused by all filesystem tools. */
+export const BLOCKED_PREFIXES = ['.cspeach', '.env', '.git', '.cspeach-design'];
+/**
+ * True if `realAbsPath` falls under one of BLOCKED_PREFIXES relative to root.
+ * Caller should refuse the operation when `blocked` is true.
+ */
+export function isDenylistedPath(realAbsPath, root) {
+    const relFromRoot = path.relative(path.resolve(root), realAbsPath).replace(/\\/g, '/');
+    for (const prefix of BLOCKED_PREFIXES) {
+        if (relFromRoot === prefix || relFromRoot.startsWith(prefix + '/')) {
+            return { blocked: true, relFromRoot };
+        }
+    }
+    return { blocked: false, relFromRoot };
+}
+export class PathOutsideRootError extends Error {
+    constructor(givenPath, root) {
+        super(`Path "${givenPath}" resolves outside the project root "${root}"`);
+        this.name = 'PathOutsideRootError';
+    }
+}
+/**
+ * Resolve `userPath` relative to `root` (the project cwd) and verify the
+ * result is INSIDE root. Throws PathOutsideRootError otherwise.
+ *
+ * Sync by design: the work is pure path-string math (no IO). If a future
+ * caller wants symlink-aware resolution they should fs.realpath the result;
+ * adding async to this helper today would mislead callers about what it does.
+ *
+ * Accepts:
+ *   - relative paths (foo, foo/bar.ts, ./foo, '', '.', 'subdir/..')
+ *   - absolute paths that already resolve inside root
+ *
+ * Rejects:
+ *   - any path containing a null byte (hostile input)
+ *   - any path that, after resolution, sits outside root
+ *   - `..` traversals that escape root
+ */
+export function resolveSafePath(root, userPath) {
+    if (userPath.includes('\0'))
+        throw new PathOutsideRootError(userPath, root);
+    const absRoot = path.resolve(root);
+    const absInput = path.isAbsolute(userPath) ? path.resolve(userPath) : path.resolve(absRoot, userPath);
+    const rel = path.relative(absRoot, absInput);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new PathOutsideRootError(userPath, root);
+    }
+    return absInput;
+}
+/**
+ * Resolve symlinks via fs.realpath and verify the real path is still
+ * inside root. Throws PathOutsideRootError on symlink escape. Returns
+ * the realpath on success.
+ *
+ * Use this AFTER resolveSafePath when the path will actually be opened
+ * for read — pure path-string math doesn't catch symlink escapes.
+ *
+ * If the file doesn't exist (ENOENT), the underlying realpath rejects;
+ * the caller should let that error propagate as a normal "file not
+ * found" condition.
+ */
+export async function assertRealPathContained(absInputPath, root) {
+    const absRoot = path.resolve(root);
+    const real = await fsPromises.realpath(absInputPath);
+    const rel = path.relative(absRoot, real);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new PathOutsideRootError(absInputPath, root);
+    }
+    return real;
+}

package/dist/tools/_flag.js

@@ -0,0 +1,39 @@
+// cspeach-cli/src/tools/_flag.ts
+/**
+ * Phase 3 of Track B — per-tool feature-flag gate.
+ *
+ * Each new Phase 3 tool is gated behind CSPEACH_TOOL_<UPPERCASE_NAME>=on.
+ * Default OFF means the tool is invisible to listTools() and therefore
+ * to the model. Removed in a separate commit per tool after dogfooding
+ * validates it.
+ *
+ * Misconfiguration surface: a one-shot stderr warning fires the first
+ * time we see a flag that is SET but not exactly "on" (after trim).
+ * Catches the common .env mistakes — `=true`, `=1`, leading whitespace
+ * — without making the on-test forgiving.
+ */
+export const TOOL_FLAG_PREFIX = 'CSPEACH_TOOL_';
+/** One-shot per process — set of flag-names we've already warned about. */
+const warnedFlags = new Set();
+export function isToolFlagOn(toolName) {
+    const flag = `${TOOL_FLAG_PREFIX}${toolName.toUpperCase()}`;
+    const raw = process.env[flag];
+    if (raw === undefined)
+        return false;
+    const trimmed = raw.trim();
+    if (trimmed === 'on')
+        return true;
+    // Set but not "on" — warn ONCE so a misconfigured flag is visible.
+    if (!warnedFlags.has(flag)) {
+        warnedFlags.add(flag);
+        try {
+            process.stderr.write(`[tools] ${flag} is set to "${raw}" — did you mean ${flag}=on? Tool stays disabled.\n`);
+        }
+        catch { /* stderr write itself failed — nothing more we can do */ }
+    }
+    return false;
+}
+/** Test-only — clear the warned-once set so successive tests can re-trigger warnings. */
+export function __resetFlagWarningsForTests() {
+    warnedFlags.clear();
+}

package/dist/tools/approval.js

@@ -0,0 +1,228 @@
+import { registerTool } from './index.js';
+import { effectiveRisk } from '../approvals/risk-floor.js';
+import { mintApprovalId } from '../approvals/jwt.js';
+import { renderPlanGate, renderPerChangeApprovalV3 } from '../approvals/render.js';
+import { loadConfig } from '../config/loader.js';
+import { maybeShowAutoApproveNag } from '../approvals/approval-prompt.js';
+import { renderAdvisoryProposal, } from '../approvals/advisory-render.js';
+import { promptAdvisory } from '../approvals/advisory-prompt.js';
+import { markPlanGateApproved } from '../repl/rule8-detector.js';
+/**
+ * Advisory-only replacement for the per-change approval gauntlet.
+ *
+ * Renders the proposal, prompts the developer (who applies manually in ADT),
+ * and returns a JSON-encoded envelope carrying the outcome plus an AI-directive
+ * string. Never mints approval IDs.
+ *
+ * `_ctx` is accepted to match the shape of the main handler (and to leave room
+ * for future use of `sapAlias` in the rendered directive), but is currently
+ * unused — the prompt and render are sapAlias-agnostic.
+ */
+export async function handleAdvisoryApproval(args, _ctx) {
+    const render = renderAdvisoryProposal(args);
+    const outcome = await promptAdvisory({
+        displayText: render.displayText,
+        clipboardText: render.clipboardText,
+    });
+    let ai_directive = '';
+    switch (outcome) {
+        case 'applied':
+            ai_directive =
+                'Advisory mode: the change has been proposed to the developer and the developer reports it was applied manually in ADT. Do not attempt any sap_set_source, sap_create_object, sap_activate, or other write operations for this change. Summarise what you proposed and continue.';
+            break;
+        case 'skipped':
+            ai_directive =
+                'Advisory mode: the developer skipped this proposal. Do not attempt to write. Summarise and move on.';
+            break;
+        case 'aborted':
+            ai_directive =
+                'Advisory mode: the developer aborted. Stop current workflow. Do not attempt any writes.';
+            break;
+    }
+    return {
+        content: JSON.stringify({
+            advisory_outcome: outcome,
+            ai_directive,
+        }),
+    };
+}
+registerTool({
+    name: 'request_approval',
+    description: 'Request user approval for one or more SAP mutations. Returns approval_ids (one per change) to be passed as approval_id on matching mutating tool calls.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            summary: { type: 'string', description: 'One-line description of the planned change set' },
+            risk: { type: 'string', enum: ['low', 'medium', 'high'] },
+            transport: { type: 'string', description: 'Target transport ID, if applicable' },
+            changes: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        op: { type: 'string', enum: ['create', 'modify', 'delete', 'activate', 'release'] },
+                        object: { type: 'string' },
+                        type: { type: 'string' },
+                        diff: { type: 'string', description: 'Unified diff for modify/create ops (optional)' },
+                    },
+                    required: ['op', 'object', 'type'],
+                },
+            },
+        },
+        required: ['summary', 'risk', 'changes'],
+    },
+    handler: async (args, ctx) => {
+        let cfg = await loadConfig();
+        // Advisory-only short-circuit — never mint approval_ids.
+        // The developer applies the change manually in ADT; the AI gets an
+        // ai_directive telling it not to attempt any SAP write tools.
+        if (cfg.write_mode === 'advisory-only') {
+            return handleAdvisoryApproval(args, { sapAlias: ctx.sapAlias });
+        }
+        let sapCfg = cfg.sap[ctx.sapAlias];
+        const riskCtx = {
+            sapAlias: ctx.sapAlias,
+            autoApprovePolicy: sapCfg?.auto_approve ?? 'never',
+        };
+        const changes = args.changes;
+        const declared = args.risk;
+        const eff = effectiveRisk(declared, changes, riskCtx);
+        // Progressive-disclosure: offer to upgrade never→low on first low-risk encounter.
+        await maybeShowAutoApproveNag({ sapAlias: ctx.sapAlias, effectiveRisk: eff.level });
+        // Refresh cfg so this approval benefits from a just-enabled auto_approve.
+        cfg = await loadConfig();
+        sapCfg = cfg.sap[ctx.sapAlias];
+        riskCtx.autoApprovePolicy = sapCfg?.auto_approve ?? 'never';
+        // Auto-approve caps — never auto-approve at high, cap change count per risk level.
+        const autoApproveAllowed = ((sapCfg?.auto_approve === 'low' && eff.level === 'low' && changes.length <= 5) ||
+            (sapCfg?.auto_approve === 'medium' && (eff.level === 'low' || eff.level === 'medium') && changes.length <= 2));
+        if (autoApproveAllowed) {
+            const ids = [];
+            for (const c of changes) {
+                ids.push(await mintApprovalId({
+                    object: c.object,
+                    type: c.type,
+                    op: c.op,
+                    session_id: ctx.session.id,
+                }));
+            }
+            // Tell Rule 8 the user has already covered this batch — they
+            // configured auto-approve, so no per-dispatch re-prompts.
+            markPlanGateApproved();
+            return {
+                content: JSON.stringify({
+                    approved: true,
+                    auto_approved: true,
+                    approval_ids: ids,
+                    effective_risk: eff.level,
+                    raised_by: eff.raisedBy,
+                }),
+            };
+        }
+        // Plan-gate: for multi-change requests, ask once whether to apply all,
+        // review each, or cancel. Apply-all is the default and the happy path —
+        // it skips the redundant per-change prompts that produced the "3 prompts
+        // for one task" complaint. Review-each falls back to the per-change
+        // gate. Cancel rejects the whole plan.
+        let skipPerChangeGates = false;
+        if (changes.length > 1) {
+            const mode = await renderPlanGate(args.summary, changes, args.transport, eff);
+            if (mode === 'cancel') {
+                return {
+                    content: JSON.stringify({
+                        approved: false,
+                        reason: 'plan_rejected',
+                        effective_risk: eff.level,
+                        raised_by: eff.raisedBy,
+                    }),
+                };
+            }
+            skipPerChangeGates = (mode === 'apply_all');
+        }
+        // Per-change approvals — skipped when the user picked "Apply all" at the
+        // plan gate. Mint approval_ids directly for every change in that case.
+        //
+        // 2026-05-01: in Review mode, tie activate decisions to the matching
+        // write decision on the same object. activate is never an independent
+        // call — it's the implicit follow-on of a modify/create. Three rules:
+        //   - sibling write APPROVED → activate auto-approved (no re-prompt).
+        //   - sibling write SKIPPED  → activate auto-skipped (activating a
+        //     write you just rejected would re-activate stale code, which the
+        //     user never asked for and produces the worst kind of confusion).
+        //   - no sibling write       → activate prompted on its own (rare —
+        //     user explicitly asked the model to activate something already
+        //     written by another flow).
+        // Approval IDs are still minted on the approved path so sap_activate's
+        // JWT verification stays intact.
+        const approvalIds = [];
+        const rejections = [];
+        const autoApproveActivateFor = new Set();
+        const autoSkipActivateFor = new Set();
+        const writeKeys = new Set();
+        for (const c of changes) {
+            if (c.op === 'modify' || c.op === 'create')
+                writeKeys.add(`${c.type}:${c.object}`);
+        }
+        for (const c of changes) {
+            const objKey = `${c.type}:${c.object}`;
+            let outcome;
+            if (skipPerChangeGates) {
+                outcome = { approved: true };
+            }
+            else if (c.op === 'activate' && autoApproveActivateFor.has(objKey)) {
+                outcome = { approved: true };
+            }
+            else if (c.op === 'activate' && autoSkipActivateFor.has(objKey)) {
+                outcome = { approved: false, reason: 'sibling_write_skipped' };
+            }
+            else {
+                outcome = await renderPerChangeApprovalV3(c, eff, args.transport);
+            }
+            if (outcome.approved) {
+                if (c.op === 'modify' || c.op === 'create')
+                    autoApproveActivateFor.add(objKey);
+                approvalIds.push(await mintApprovalId({
+                    object: c.object,
+                    type: c.type,
+                    op: c.op,
+                    session_id: ctx.session.id,
+                }));
+            }
+            else {
+                if (outcome.reason === '__cancel_turn__') {
+                    return {
+                        content: JSON.stringify({
+                            approved: false,
+                            reason: 'user_cancelled_turn',
+                            effective_risk: eff.level,
+                            raised_by: eff.raisedBy,
+                        }),
+                    };
+                }
+                // Skipping a write means the matching activate should auto-skip
+                // rather than fire a separate prompt offering to activate stale
+                // code. Only applies when there's actually a sibling activate in
+                // the plan — otherwise this is a no-op flag.
+                if ((c.op === 'modify' || c.op === 'create') && writeKeys.has(objKey)) {
+                    autoSkipActivateFor.add(objKey);
+                }
+                rejections.push({ object: c.object, op: c.op, reason: outcome.reason ?? 'skipped' });
+            }
+        }
+        // Tell Rule 8 the user has explicitly approved (some/all of) this
+        // batch via the plan-gate / per-change flow. Suppresses the redundant
+        // Rule 8 prompt at every subsequent dispatch this turn.
+        if (approvalIds.length > 0)
+            markPlanGateApproved();
+        return {
+            content: JSON.stringify({
+                approved: approvalIds.length > 0,
+                approval_ids: approvalIds,
+                skipped: rejections,
+                effective_risk: eff.level,
+                raised_by: eff.raisedBy,
+            }),
+        };
+    },
+});