@cspeach/cli 0.6.0

package/dist/project-context/git.js

@@ -0,0 +1,115 @@
+/**
+ * Git state extractor.
+ *
+ * Surfaces just enough VCS context for the agent to know "what branch
+ * are we on, is the working copy dirty, what just shipped." Shells out
+ * to the git CLI rather than pulling in a Git library — git is already
+ * available wherever a developer runs CSPeach.
+ *
+ * Discipline:
+ *
+ *  - Best-effort. If git isn't installed, the directory isn't a repo,
+ *    or any subprocess errors out, we return `isRepo: false` and the
+ *    rest of the fields zero/null. We never throw.
+ *
+ *  - Each subprocess has a short timeout (3s). Hung git processes (e.g.
+ *    waiting on a stuck lock) cannot block project-context computation.
+ *
+ *  - We do not run any commands that mutate state. Only `git rev-parse`,
+ *    `git status --porcelain`, `git log`. Read-only by construction.
+ */
+import { spawn } from 'node:child_process';
+const GIT_TIMEOUT_MS = 3000;
+const EMPTY_STATE = {
+    isRepo: false,
+    branch: null,
+    headSha: null,
+    dirtyFileCount: 0,
+    recentCommits: [],
+};
+/**
+ * Inspect the git state at `cwd`. Returns sane defaults on every error
+ * (no git, no repo, subprocess timeout, etc.) — never throws.
+ */
+export async function getGitState(cwd) {
+    // Check repo membership first; bails early on non-repos so we don't
+    // shell out four times unnecessarily.
+    const insideTree = await runGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    if (!insideTree.ok || insideTree.stdout.trim() !== 'true') {
+        return EMPTY_STATE;
+    }
+    const [branchResult, shaResult, statusResult, logResult] = await Promise.all([
+        runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']),
+        runGit(cwd, ['rev-parse', 'HEAD']),
+        runGit(cwd, ['status', '--porcelain']),
+        runGit(cwd, ['log', '-5', '--pretty=%h %s']),
+    ]);
+    const branch = branchResult.ok ? branchResult.stdout.trim() || null : null;
+    const headSha = shaResult.ok ? shaResult.stdout.trim() || null : null;
+    const dirtyFileCount = statusResult.ok
+        ? statusResult.stdout
+            .split('\n')
+            .filter((line) => line.trim().length > 0).length
+        : 0;
+    const recentCommits = logResult.ok
+        ? logResult.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+        : [];
+    return {
+        isRepo: true,
+        branch,
+        headSha,
+        dirtyFileCount,
+        recentCommits,
+    };
+}
+/**
+ * Run a single git subprocess with a hard timeout. Resolves with
+ * `{ ok: false, stdout: '' }` on any failure (non-zero exit, ENOENT,
+ * timeout). Never rejects.
+ */
+function runGit(cwd, args) {
+    return new Promise((resolve) => {
+        let resolved = false;
+        let stdout = '';
+        let child;
+        const finish = (ok) => {
+            if (resolved)
+                return;
+            resolved = true;
+            try {
+                child?.kill();
+            }
+            catch {
+                // ignore
+            }
+            resolve({ ok, stdout });
+        };
+        const timer = setTimeout(() => finish(false), GIT_TIMEOUT_MS);
+        try {
+            child = spawn('git', args, {
+                cwd,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+        }
+        catch {
+            clearTimeout(timer);
+            finish(false);
+            return;
+        }
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.on('error', () => {
+            clearTimeout(timer);
+            finish(false);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            finish(code === 0);
+        });
+    });
+}

package/dist/project-context/index-files.js

@@ -0,0 +1,235 @@
+/**
+ * Project file index walker.
+ *
+ * Walks the project tree and produces a FileIndex — counts + paths +
+ * top-level dirs — without ever reading file contents. The model gets
+ * a structural view of what exists; if it needs content, it uses
+ * `file_read` (Phase 3 tool) on demand.
+ *
+ * Discipline:
+ *
+ *  - Hard cap at 10,000 files traversed. Beyond that we mark the
+ *    project as `truncated` and surface that to the model. Larger
+ *    projects rely on on-demand glob/grep search rather than the
+ *    static index.
+ *
+ *  - At most 500 paths shipped in `FileIndex.paths`. Selected by
+ *    relevance — source files first, sorted by modification time
+ *    (most recent first) so the model sees what the user has been
+ *    working on.
+ *
+ *  - Honors .gitignore + .cspeachignore via a minimal in-tree parser.
+ *    No external dependencies. The parser handles the common cases —
+ *    name patterns, *.ext patterns, directory patterns. Edge-case
+ *    .gitignore wildcards (e.g. ! negation, glob stars) are not fully
+ *    supported; users with exotic ignore rules can lean on
+ *    .cspeachignore for project-context-specific exclusions.
+ *
+ *  - Always-skipped directories: node_modules, .git, dist, build,
+ *    .cspeach, .abapforge, .next, .turbo, target. The first wave of
+ *    walks before any .gitignore parse stage uses this safety net.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+/** Hard cap on files traversed. Beyond this the walk stops + truncated=true. */
+const MAX_FILES_TRAVERSED = 10_000;
+/** Cap on paths shipped in FileIndex. Selected by relevance. */
+const MAX_PATHS_IN_INDEX = 500;
+const ALWAYS_SKIPPED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.cspeach',
+    '.abapforge',
+    '.next',
+    '.turbo',
+    'target',
+    '.vscode',
+    '.idea',
+]);
+/**
+ * Source-shaped extensions, prioritized when selecting the top 500
+ * paths shipped in the index. The model cares about these more than
+ * generated assets / lock files.
+ */
+const SOURCE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.abap',
+    '.cds', '.ddls', '.ddlx', '.dcls', '.bdef', '.srvd', '.srvb',
+    '.xml',
+    '.yaml', '.yml',
+    '.json',
+    '.md',
+    '.properties',
+    '.py', '.go', '.rs', '.java',
+    '.css', '.scss',
+    '.html',
+]);
+/**
+ * Walk the project rooted at `cwd` and produce a FileIndex. Best-effort:
+ * IO errors during the walk are silently skipped (the offending dir/file
+ * just doesn't contribute to the count). Never throws.
+ */
+export async function indexFiles(cwd) {
+    const ignoreMatchers = await loadIgnoreMatchers(cwd);
+    /** Files collected with their stat info — used to rank for the path list. */
+    const collected = [];
+    const byExtension = {};
+    let totalFiles = 0;
+    let truncated = false;
+    async function walk(dir, relPrefix) {
+        if (truncated)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (truncated)
+                return;
+            const relPath = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+            if (ent.isDirectory()) {
+                if (ALWAYS_SKIPPED_DIRS.has(ent.name))
+                    continue;
+                if (matchesIgnore(ignoreMatchers, relPath, /* isDirectory */ true))
+                    continue;
+                await walk(path.join(dir, ent.name), relPath);
+            }
+            else if (ent.isFile()) {
+                if (matchesIgnore(ignoreMatchers, relPath, /* isDirectory */ false))
+                    continue;
+                if (totalFiles >= MAX_FILES_TRAVERSED) {
+                    truncated = true;
+                    return;
+                }
+                totalFiles++;
+                const ext = extOf(ent.name);
+                byExtension[ext] = (byExtension[ext] ?? 0) + 1;
+                // Read mtime cheaply; on error use 0 so the file sorts late.
+                let mtime = 0;
+                try {
+                    const s = await fs.stat(path.join(dir, ent.name));
+                    mtime = s.mtimeMs;
+                }
+                catch {
+                    // ignore
+                }
+                collected.push({ path: relPath, ext, mtime });
+            }
+        }
+    }
+    await walk(cwd, '');
+    // Top-level dirs that survived the walk (i.e. weren't skipped).
+    let topLevelDirs = [];
+    try {
+        const topLevel = await fs.readdir(cwd, { withFileTypes: true });
+        topLevelDirs = topLevel
+            .filter((e) => e.isDirectory() && !ALWAYS_SKIPPED_DIRS.has(e.name) && !matchesIgnore(ignoreMatchers, e.name, true))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        // leave empty
+    }
+    // Rank collected files: source files first, then by mtime descending.
+    collected.sort((a, b) => {
+        const aSource = SOURCE_EXTENSIONS.has(a.ext) ? 1 : 0;
+        const bSource = SOURCE_EXTENSIONS.has(b.ext) ? 1 : 0;
+        if (aSource !== bSource)
+            return bSource - aSource;
+        return b.mtime - a.mtime;
+    });
+    const paths = collected.slice(0, MAX_PATHS_IN_INDEX).map((f) => f.path);
+    return {
+        totalFiles,
+        byExtension,
+        topLevelDirs,
+        paths,
+        truncated,
+    };
+}
+async function loadIgnoreMatchers(cwd) {
+    const patterns = [];
+    for (const filename of ['.gitignore', '.cspeachignore']) {
+        const raw = await readFileSafe(path.join(cwd, filename));
+        if (raw === null)
+            continue;
+        for (const rawLine of raw.split('\n')) {
+            const pat = parseIgnoreLine(rawLine);
+            if (pat)
+                patterns.push(pat);
+        }
+    }
+    return { patterns };
+}
+function parseIgnoreLine(rawLine) {
+    const line = rawLine.replace(/^\s+|\s+$/g, '');
+    if (line.length === 0)
+        return null;
+    if (line.startsWith('#'))
+        return null;
+    // We don't support negation (!), root-anchored paths (/), or **.
+    // Anything more exotic than basename-or-glob is silently ignored —
+    // users who need that can rely on the ALWAYS_SKIPPED_DIRS hardcode
+    // or contribute back if needed.
+    if (line.startsWith('!'))
+        return null;
+    if (line.includes('/')) {
+        // Path-rooted patterns are partially handled — we treat "build/" or
+        // "logs" as a basename match. "a/b/c" is too specific for our v1.
+        if (!line.endsWith('/'))
+            return null;
+    }
+    const dirOnly = line.endsWith('/');
+    const pattern = dirOnly ? line.slice(0, -1) : line;
+    if (pattern.length === 0)
+        return null;
+    if (pattern.includes('*')) {
+        // Convert simple "*.ext" or "foo*" pattern to a regex.
+        // We only handle * (no ? no [..]).
+        const re = new RegExp('^' + pattern.split('*').map(escapeRegex).join('.*') + '$');
+        return {
+            source: rawLine,
+            dirOnly,
+            matches: (basename) => re.test(basename),
+        };
+    }
+    // Literal basename match.
+    return {
+        source: rawLine,
+        dirOnly,
+        matches: (basename) => basename === pattern,
+    };
+}
+function matchesIgnore(m, relPath, isDirectory) {
+    const basename = relPath.split('/').pop() ?? relPath;
+    for (const p of m.patterns) {
+        if (p.dirOnly && !isDirectory)
+            continue;
+        if (p.matches(basename))
+            return true;
+    }
+    return false;
+}
+function escapeRegex(s) {
+    return s.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+}
+/* ── Small helpers ─────────────────────────────────────────────────── */
+function extOf(filename) {
+    const idx = filename.lastIndexOf('.');
+    if (idx <= 0)
+        return '';
+    return filename.slice(idx).toLowerCase();
+}
+async function readFileSafe(p) {
+    try {
+        return await fs.readFile(p, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/project-context/index.js

@@ -0,0 +1,117 @@
+/**
+ * Project context module — public API.
+ *
+ * Phase 1 of Track B. As of Phase 1F this module is fully implemented;
+ * NOTHING IN THE EXISTING CLI IMPORTS IT YET. Phase 2 wires it into
+ * the agent's system prompt behind the CSPEACH_PROJECT_CONTEXT feature
+ * flag. Until then, this module is fully isolated — risk to existing
+ * CSPeach is zero by construction.
+ *
+ * Usage:
+ *
+ *     import { getProjectContext, renderProjectContext } from './project-context/index.js';
+ *
+ *     const ctx = await getProjectContext(process.cwd());
+ *     if (ctx) {
+ *       const block = renderProjectContext(ctx);
+ *       // splice `block` into the system prompt
+ *     }
+ *
+ * Returns null on any error or when nothing project-shaped is detected.
+ * Never throws — error handling is internal. See ./detect.ts for the
+ * detection priority order and ./types.ts for the structured shape.
+ */
+import { readConventions } from './conventions.js';
+import { detectProjectType } from './detect.js';
+import { extractAbapCloud } from './domain/abap-cloud.js';
+import { extractAbapGit } from './domain/abapgit.js';
+import { extractCap } from './domain/cap.js';
+import { extractFiori } from './domain/fiori.js';
+import { getGitState } from './git.js';
+import { indexFiles } from './index-files.js';
+export { renderProjectContext } from './render.js';
+/**
+ * Compute the full project context for a directory. Best-effort: returns
+ * null on hard failure (e.g. cwd doesn't exist), otherwise an envelope
+ * with whatever was detectable. Even projects of type 'unknown' return
+ * a non-null ProjectContext so callers can surface the SAP-only case
+ * (live ABAP work with no on-disk project).
+ *
+ * Phase 1F implementation. Phase 2 will wrap this in a feature-flag
+ * check at the agent loop's prompt assembly site.
+ */
+export async function getProjectContext(cwd, options = {}) {
+    // Detection runs first — if cwd is bogus we bail completely.
+    const detected = await detectProjectType(cwd);
+    if (detected === null) {
+        // Even with no on-disk project, a SAP connection alone is enough
+        // to return SOMETHING. Otherwise null.
+        if (options.sapConnection) {
+            return assembleSapOnlyContext(cwd, options.sapConnection);
+        }
+        return null;
+    }
+    // Run independent extractors in parallel — they share no state.
+    const [conventions, index, git, domainObjects] = await Promise.all([
+        readConventions(cwd),
+        indexFiles(cwd),
+        getGitState(cwd),
+        extractDomain(cwd, detected),
+    ]);
+    return {
+        type: detected,
+        root: cwd,
+        conventions,
+        index,
+        entryPoints: [], // Phase 2/3 will populate per-type entry-point lists
+        domainObjects,
+        git,
+        sapConnection: options.sapConnection ?? null,
+        detectedAt: new Date().toISOString(),
+    };
+}
+/* ── Internal helpers ──────────────────────────────────────────────── */
+/**
+ * Run the right domain extractor for the detected type. `mixed` is
+ * type-stubbed for now — recursive per-module assembly is a follow-up
+ * (the technical plan flags it as Phase 1F's "if you encounter it,
+ * type-stub it; assembly handles the recursion later" note).
+ */
+async function extractDomain(cwd, type) {
+    switch (type) {
+        case 'fiori-ui5':
+            return extractFiori(cwd);
+        case 'cap-node':
+            return extractCap(cwd);
+        case 'abapgit':
+            return extractAbapGit(cwd);
+        case 'abap-cloud':
+            return extractAbapCloud(cwd);
+        case 'mixed':
+            // Stub. Assembly of per-module sub-contexts is Phase 1F+.
+            return { type: 'mixed', modules: [] };
+        case 'unknown':
+        default:
+            return { type: 'unknown' };
+    }
+}
+/**
+ * Build a minimal ProjectContext for the SAP-only case (caller passed
+ * a sapConnection but cwd doesn't resolve to any project shape). This
+ * is the most common CSPeach use case today: a consultant connected
+ * to live SAP via ADT with no on-disk project at all.
+ */
+async function assembleSapOnlyContext(cwd, sapConnection) {
+    const conventions = await readConventions(cwd);
+    return {
+        type: 'unknown',
+        root: cwd,
+        conventions,
+        index: { totalFiles: 0, byExtension: {}, topLevelDirs: [], paths: [], truncated: false },
+        entryPoints: [],
+        domainObjects: { type: 'unknown' },
+        git: { isRepo: false, branch: null, headSha: null, dirtyFileCount: 0, recentCommits: [] },
+        sapConnection,
+        detectedAt: new Date().toISOString(),
+    };
+}