@cspeach/cli 0.6.0

package/dist/tools/filesystem/glob.js

@@ -0,0 +1,177 @@
+/**
+ * glob — Phase 3 filesystem tool.
+ *
+ * Finds files in the project matching a pattern. Returns paths sorted by
+ * modification time descending (most recent first). Cap at 500 results;
+ * honors .gitignore and the shared sensitive-path denylist.
+ *
+ * Pattern support (deliberately minimal — Node fs + a hand-rolled regex,
+ * no external glob dependency):
+ *   *   — any chars within a single path segment
+ *   **  — any number of path segments (including zero)
+ *   ?   — single char within a single path segment
+ *
+ * Other glob features (character classes, brace expansion, !-negation) are
+ * not supported. The model can compose multiple glob calls if it needs them.
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_GLOB=on.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from '../index.js';
+import { resolveSafePath, PathOutsideRootError, isDenylistedPath } from '../_filesystem-shared.js';
+const MAX_RESULTS = 500;
+const MAX_FILES_TRAVERSED = 10_000;
+const ALWAYS_SKIPPED_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', '.cspeach', '.cspeach-design', '.abapforge',
+    '.next', '.turbo', 'target', '.vscode', '.idea',
+]);
+/**
+ * Convert a glob pattern to a regex.
+ *
+ *   * → [^/]*
+ *   ? → [^/]
+ *   ** → .*
+ *   any other char → escaped literal
+ *
+ * Anchors the regex with ^ and $.
+ */
+export function globToRegex(pattern) {
+    let out = '^';
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            if (pattern[i + 1] === '*') {
+                out += '.*';
+                i += 2;
+                // Eat an optional `/` after `**`
+                if (pattern[i] === '/')
+                    i++;
+            }
+            else {
+                out += '[^/]*';
+                i++;
+            }
+        }
+        else if (ch === '?') {
+            out += '[^/]';
+            i++;
+        }
+        else if (/[.+^${}()|[\]\\]/.test(ch)) {
+            out += '\\' + ch;
+            i++;
+        }
+        else {
+            out += ch;
+            i++;
+        }
+    }
+    out += '$';
+    return new RegExp(out);
+}
+export async function globHandler(args, ctx) {
+    // Validate args
+    if (!args.pattern || typeof args.pattern !== 'string') {
+        return { content: 'error: pattern is required (non-empty string)', is_error: true };
+    }
+    // Resolve search root — defaults to ctx.cwd
+    let searchRoot;
+    try {
+        searchRoot = args.cwd ? resolveSafePath(ctx.cwd, args.cwd) : path.resolve(ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    // Verify the search root exists
+    try {
+        const stat = await fs.stat(searchRoot);
+        if (!stat.isDirectory()) {
+            return { content: `error: search root "${args.cwd ?? '.'}" is not a directory`, is_error: true };
+        }
+    }
+    catch {
+        return { content: `error: search root "${args.cwd ?? '.'}" does not exist`, is_error: true };
+    }
+    const regex = globToRegex(args.pattern);
+    const collected = [];
+    let budget = MAX_FILES_TRAVERSED;
+    async function walk(dir, relPrefix) {
+        if (budget <= 0 || collected.length >= MAX_RESULTS * 4)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (budget <= 0 || collected.length >= MAX_RESULTS * 4)
+                return;
+            const relPath = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+            if (ent.isDirectory()) {
+                if (ALWAYS_SKIPPED_DIRS.has(ent.name))
+                    continue;
+                await walk(path.join(dir, ent.name), relPath);
+            }
+            else if (ent.isFile()) {
+                budget--;
+                if (!regex.test(relPath))
+                    continue;
+                // Denylist check on the matched path
+                const abs = path.join(dir, ent.name);
+                const denylist = isDenylistedPath(abs, ctx.cwd);
+                if (denylist.blocked)
+                    continue;
+                let mtime = 0;
+                try {
+                    const s = await fs.stat(abs);
+                    mtime = s.mtimeMs;
+                }
+                catch {
+                    // skip stat failure — file still included with mtime 0
+                }
+                collected.push({ relPath, mtime });
+            }
+        }
+    }
+    await walk(searchRoot, '');
+    // Sort by mtime descending, cap at MAX_RESULTS
+    collected.sort((a, b) => b.mtime - a.mtime);
+    const sample = collected.slice(0, MAX_RESULTS).map((f) => f.relPath);
+    if (sample.length === 0) {
+        return { content: `no files match "${args.pattern}"` };
+    }
+    const truncated = collected.length > MAX_RESULTS;
+    const trailer = truncated
+        ? `\n... (${collected.length - MAX_RESULTS} more matches — narrow the pattern)`
+        : '';
+    return { content: sample.join('\n') + trailer };
+}
+registerTool({
+    name: 'glob',
+    description: 'Find files in the project matching a pattern. Supports *, **, ?. Returns up to 500 paths ' +
+        'sorted by modification time (most recent first).',
+    isMutating: false,
+    category: 'filesystem',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            pattern: {
+                type: 'string',
+                description: 'Glob pattern, e.g. "src/**/*.ts" or "*.json".',
+            },
+            cwd: {
+                type: 'string',
+                description: 'Optional subdirectory to search relative to the project root. Defaults to project root.',
+            },
+        },
+        required: ['pattern'],
+    },
+    handler: globHandler,
+});

package/dist/tools/filesystem/grep.js

@@ -0,0 +1,163 @@
+/**
+ * grep — Phase 3 filesystem tool.
+ *
+ * Searches file content in the project for a regex pattern. Returns
+ * matching lines up to a hard cap of 250 matches. Reuses glob.ts's
+ * globToRegex for the optional `glob` arg to scope which files get
+ * scanned. Three output modes:
+ *
+ *   "content"            — default. Lines like `path/foo.ts:42:matched line`
+ *   "files_with_matches" — just the filenames that had at least one hit
+ *   "count"              — count of matches per file
+ *
+ * Pure Node fs + RegExp — no ripgrep dependency. Acceptable for the
+ * CSPeach project sizes the file walker caps at (10K files). Skips
+ * files larger than 2 MB (likely binary). Honors the shared sensitive-
+ * path denylist + ALWAYS_SKIPPED_DIRS.
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_GREP=on.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { registerTool } from '../index.js';
+import { resolveSafePath, PathOutsideRootError, isDenylistedPath } from '../_filesystem-shared.js';
+import { globToRegex } from './glob.js';
+const MAX_MATCHES = 250;
+const MAX_FILES_TRAVERSED = 10_000;
+const MAX_FILE_BYTES = 2_000_000;
+const ALWAYS_SKIPPED_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', '.cspeach', '.cspeach-design', '.abapforge',
+    '.next', '.turbo', 'target', '.vscode', '.idea',
+]);
+export async function grepHandler(args, ctx) {
+    if (!args.pattern || typeof args.pattern !== 'string') {
+        return { content: 'error: pattern is required (non-empty string)', is_error: true };
+    }
+    let searchRegex;
+    try {
+        searchRegex = new RegExp(args.pattern, args.case_insensitive ? 'i' : '');
+    }
+    catch (err) {
+        return { content: `error: invalid regex — ${err.message}`, is_error: true };
+    }
+    let searchRoot;
+    try {
+        searchRoot = args.path ? resolveSafePath(ctx.cwd, args.path) : path.resolve(ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    try {
+        const stat = await fs.stat(searchRoot);
+        if (!stat.isDirectory()) {
+            return { content: `error: search root "${args.path ?? '.'}" is not a directory`, is_error: true };
+        }
+    }
+    catch {
+        return { content: `error: search root "${args.path ?? '.'}" does not exist`, is_error: true };
+    }
+    const fileFilter = args.glob ? globToRegex(args.glob) : null;
+    const outputMode = args.output_mode ?? 'content';
+    const matches = [];
+    const fileMatchCounts = new Map();
+    let budget = MAX_FILES_TRAVERSED;
+    async function walk(dir, relPrefix) {
+        if (budget <= 0 || matches.length >= MAX_MATCHES)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (budget <= 0 || matches.length >= MAX_MATCHES)
+                return;
+            const relPath = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+            if (ent.isDirectory()) {
+                if (ALWAYS_SKIPPED_DIRS.has(ent.name))
+                    continue;
+                await walk(path.join(dir, ent.name), relPath);
+            }
+            else if (ent.isFile()) {
+                budget--;
+                if (fileFilter && !fileFilter.test(relPath))
+                    continue;
+                const abs = path.join(dir, ent.name);
+                const denylist = isDenylistedPath(abs, ctx.cwd);
+                if (denylist.blocked)
+                    continue;
+                let stat;
+                try {
+                    stat = await fs.stat(abs);
+                    if (stat.size > MAX_FILE_BYTES)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                let raw;
+                try {
+                    raw = await fs.readFile(abs, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                const lines = raw.split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                    if (matches.length >= MAX_MATCHES)
+                        break;
+                    if (searchRegex.test(lines[i])) {
+                        matches.push({ file: relPath, line: i + 1, text: lines[i] });
+                        fileMatchCounts.set(relPath, (fileMatchCounts.get(relPath) ?? 0) + 1);
+                    }
+                }
+            }
+        }
+    }
+    await walk(searchRoot, '');
+    if (matches.length === 0) {
+        return { content: `no matches for /${args.pattern}/${args.case_insensitive ? 'i' : ''}` };
+    }
+    const truncated = matches.length >= MAX_MATCHES;
+    const trailer = truncated
+        ? `\n... (cap of ${MAX_MATCHES} matches reached — narrow the pattern or use a glob filter)`
+        : '';
+    if (outputMode === 'files_with_matches') {
+        const files = [...new Set(matches.map((m) => m.file))];
+        return { content: files.join('\n') + trailer };
+    }
+    if (outputMode === 'count') {
+        const entries = [...fileMatchCounts.entries()].sort((a, b) => b[1] - a[1]);
+        return { content: entries.map(([file, count]) => `${count}\t${file}`).join('\n') + trailer };
+    }
+    return { content: matches.map((m) => `${m.file}:${m.line}:${m.text}`).join('\n') + trailer };
+}
+registerTool({
+    name: 'grep',
+    description: 'Search file content in the project for a regex pattern. Returns matching lines (path + line number) up to 250 matches. ' +
+        'Optional glob filter and three output modes (content, files_with_matches, count).',
+    isMutating: false,
+    category: 'filesystem',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Regex pattern (ECMAScript flavor).' },
+            path: { type: 'string', description: 'Optional subdirectory to search relative to project root.' },
+            glob: { type: 'string', description: 'Optional glob filter on files to scan (e.g. "**/*.ts").' },
+            output_mode: {
+                type: 'string',
+                enum: ['content', 'files_with_matches', 'count'],
+                description: 'Output shape. Default: content.',
+            },
+            case_insensitive: { type: 'boolean', description: 'When true, match case-insensitively.' },
+        },
+        required: ['pattern'],
+    },
+    handler: grepHandler,
+});

package/dist/tools/index.js

@@ -0,0 +1,32 @@
+/**
+ * Tool registry — central store for all CSPeach CLI tools.
+ *
+ * ToolContext carries the live AdtClient plus session/runtime state.
+ */
+import { isToolFlagOn } from './_flag.js';
+const registry = new Map();
+export function registerTool(tool) {
+    // Default category to 'sap' for back-compat with the existing 30+ tools
+    // that register without setting it. Spread to avoid mutating the
+    // caller's object — getTool() then always returns a normalised value.
+    registry.set(tool.name, { ...tool, category: tool.category ?? 'sap' });
+}
+export function getTool(name) {
+    return registry.get(name);
+}
+export function listTools() {
+    // Phase 3 visibility gate: flag-gated tools are filtered out unless
+    // their env flag is on. Non-flag-gated tools (the existing 30+) are
+    // always returned, preserving today's listTools() semantics exactly.
+    return Array.from(registry.values()).filter((t) => !t.flagGated || isToolFlagOn(t.name));
+}
+export function getToolsByCategory(category) {
+    return listTools().filter((t) => t.category === category);
+}
+export function toAnthropicTools(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.input_schema,
+    }));
+}

package/dist/tools/project/convention_get.js

@@ -0,0 +1,91 @@
+/**
+ * convention_get — Phase 3 / Chunk 3D.
+ *
+ * Thin slice over getProjectContext().conventions. Returns the full
+ * conventions object as JSON when field='all' (default), or a single
+ * field's value as a primitive/JSON when one of the named fields is
+ * requested.
+ *
+ * Reuses the project-context module's existing per-process cache —
+ * conventions are read by readConventions() inside getProjectContext()
+ * and re-rendering is cheap once the underlying cache is warm.
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_CONVENTION_GET=on. isMutating: false — reads only.
+ */
+import { registerTool } from '../index.js';
+import { getProjectContext } from '../../project-context/index.js';
+const VALID_FIELDS = new Set([
+    'all', 'freeText', 'namingPatterns', 'indentSize', 'indentChar', 'eol',
+]);
+const FALLBACK_CONVENTIONS = {
+    freeText: null,
+    namingPatterns: { classes: [], interfaces: [], cdsViews: [] },
+    style: { indentSize: 2, indentChar: 'space', eol: 'lf' },
+};
+export async function conventionGetHandler(args, ctx) {
+    const field = (args.field ?? 'all');
+    if (!VALID_FIELDS.has(field)) {
+        return {
+            content: `error: unknown field '${field}'. Valid fields: ${Array.from(VALID_FIELDS).join(', ')}.`,
+            is_error: true,
+        };
+    }
+    let conventions;
+    try {
+        const pc = await getProjectContext(ctx.cwd);
+        conventions = pc?.conventions ?? FALLBACK_CONVENTIONS;
+    }
+    catch {
+        // getProjectContext is documented as never-throws (see
+        // project-context/index.ts header). Reaching this catch means a
+        // contract violation upstream. Falling back to defaults keeps the
+        // tool responsive — surfacing the error to the model isn't useful
+        // because the model can't fix a CSPeach internal regression.
+        conventions = FALLBACK_CONVENTIONS;
+    }
+    if (field === 'all') {
+        return { content: JSON.stringify(conventions, null, 2) };
+    }
+    if (field === 'freeText') {
+        return { content: conventions.freeText ?? '' };
+    }
+    if (field === 'namingPatterns') {
+        return { content: JSON.stringify(conventions.namingPatterns, null, 2) };
+    }
+    if (field === 'indentSize') {
+        return { content: String(conventions.style.indentSize) };
+    }
+    if (field === 'indentChar') {
+        return { content: conventions.style.indentChar };
+    }
+    if (field === 'eol') {
+        return { content: conventions.style.eol };
+    }
+    // Compile-time exhaustiveness guard: any future ConventionField value
+    // added without a matching `if` branch above narrows `field` to a
+    // non-never type here and breaks the build. The runtime return below
+    // is unreachable.
+    const _exhaustive = field;
+    return { content: `error: unhandled field ${String(_exhaustive)}`, is_error: true };
+}
+registerTool({
+    name: 'convention_get',
+    description: "Read project conventions (indent size, EOL, naming patterns, free-text). " +
+        "Pass `field` to retrieve a single value; default 'all' returns the full structured object as JSON. " +
+        "Valid fields: 'all' | 'freeText' | 'namingPatterns' | 'indentSize' | 'indentChar' | 'eol'.",
+    isMutating: false,
+    category: 'project',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            field: {
+                type: 'string',
+                enum: ['all', 'freeText', 'namingPatterns', 'indentSize', 'indentChar', 'eol'],
+                description: "Which field to return. Defaults to 'all'.",
+            },
+        },
+    },
+    handler: (args, ctx) => conventionGetHandler(args, ctx),
+});

package/dist/tools/project/playbook_get.js

@@ -0,0 +1,132 @@
+/**
+ * playbook_get — Phase 3 / Chunk 3D.
+ *
+ * Fetches a SKILL.md body via ctx.skillSource (the managed / manifest /
+ * bundled SkillSource abstraction the agent loop already uses). Lets the
+ * agent inspect another skill's playbook for orchestration patterns
+ * (e.g. /abap-incident calling /abap-dump-analyze inline) without
+ * triggering a full skill dispatch.
+ *
+ * Caching: in-process Map-based LRU. Keyed by validated skill name.
+ * 5-minute TTL (skills don't change mid-session). Hard cap 50 entries.
+ *
+ * Error envelope discipline: SkillSource throws on 404 / network /
+ * signature-mismatch; we catch and convert to a structured error
+ * envelope. API key values from CSPEACH_API_KEY / ANTHROPIC_API_KEY are
+ * scrubbed at the envelope edge as defense-in-depth.
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_PLAYBOOK_GET=on. isMutating: false — reads only.
+ */
+import { registerTool } from '../index.js';
+const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9:_-]{0,63}$/;
+const DEFAULT_TTL_MS = 300_000;
+const MAX_CACHE_ENTRIES = 50;
+const cache = new Map();
+let cacheTtlMs = DEFAULT_TTL_MS;
+/** Test-only: clear the cache between cases. */
+export function __resetPlaybookCacheForTests() {
+    cache.clear();
+}
+/** Test-only: shorten the TTL so the "TTL expired" test can be deterministic. */
+export function __setPlaybookCacheTtlForTests(ms) {
+    cacheTtlMs = ms;
+}
+function lookupCache(name) {
+    const entry = cache.get(name);
+    if (!entry)
+        return null;
+    if (entry.expiresAt < Date.now()) {
+        cache.delete(name);
+        return null;
+    }
+    // Move to end (LRU touch).
+    cache.delete(name);
+    cache.set(name, entry);
+    return entry.body;
+}
+function storeCache(name, body) {
+    if (cache.size >= MAX_CACHE_ENTRIES) {
+        const firstKey = cache.keys().next().value;
+        if (firstKey !== undefined)
+            cache.delete(firstKey);
+    }
+    cache.set(name, { body, expiresAt: Date.now() + cacheTtlMs });
+}
+/**
+ * Defense-in-depth: scrub any known-secret env values from `message`
+ * before it ships in an error envelope. Plain string ops — no regex
+ * metachar risk on the key itself.
+ */
+function scrubSecrets(message) {
+    const candidates = [
+        process.env.ANTHROPIC_API_KEY,
+        process.env.CSPEACH_API_KEY,
+        process.env.CSPEACH_BRAVE_SEARCH_KEY,
+    ].filter((v) => typeof v === 'string' && v.length > 8);
+    let out = message;
+    for (const key of candidates) {
+        if (out.includes(key)) {
+            out = out.split(key).join('***');
+        }
+    }
+    return out;
+}
+export async function playbookGetHandler(args, ctx) {
+    if (!args.name || typeof args.name !== 'string' || args.name.trim().length === 0) {
+        return { content: 'error: skill name is required (non-empty string).', is_error: true };
+    }
+    const name = args.name.trim();
+    if (!NAME_PATTERN.test(name)) {
+        return {
+            content: `error: invalid skill name '${name}'. Names must match ${NAME_PATTERN.source}.`,
+            is_error: true,
+        };
+    }
+    if (!ctx.skillSource) {
+        return {
+            content: 'error: playbook_get requires ctx.skillSource — not wired into this ToolContext. ' +
+                'This is a CSPeach internal wiring issue; the REPL and one-shot entry points provide one automatically.',
+            is_error: true,
+        };
+    }
+    const cached = lookupCache(name);
+    if (cached !== null) {
+        return { content: cached };
+    }
+    let body;
+    try {
+        const skill = await ctx.skillSource.getSkillBody(name);
+        body = skill.body;
+    }
+    catch (err) {
+        const raw = err instanceof Error ? err.message : String(err);
+        // Scrub the full composed envelope, not just `raw`. Defense in depth
+        // against the theoretical case where a crafted env-var value could
+        // slip through NAME_PATTERN (alphanumerics + `:_-`, ≤64 chars) and
+        // appear in the interpolated `name` segment.
+        return {
+            content: scrubSecrets(`error: failed to fetch playbook '${name}': ${raw}`),
+            is_error: true,
+        };
+    }
+    storeCache(name, body);
+    return { content: body };
+}
+registerTool({
+    name: 'playbook_get',
+    description: "Fetch a SKILL.md body by skill name (e.g. 'abap-review', 'abap-rap'). " +
+        "Useful when one skill needs to inspect another's playbook pattern. " +
+        "Returns the full SKILL.md body verbatim. Cached in-process for 5 minutes.",
+    isMutating: false,
+    category: 'project',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'Skill name without leading slash, e.g. abap-review.' },
+        },
+        required: ['name'],
+    },
+    handler: (args, ctx) => playbookGetHandler(args, ctx),
+});