@nazty_labs/common-ground 0.5.1

package/dist/server.js

@@ -0,0 +1,105 @@
+import { operations, runOperation } from './operations.js';
+import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
+import { ReadKnowledge, readKnowledge, listPillars, listChapters, readChapter, readFact, search, reviewChecklist } from './retrieval.js';
+export { ReadKnowledge, readKnowledge, listPillars, listChapters, readChapter, readFact, search, reviewChecklist } from './retrieval.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { Update, Fact, chapterKey, relativePath } from './model.js';
+import { Workflow, Patch } from './workflow.js';
+import { page } from './paging.js';
+export { page } from './paging.js';
+import { ownershipMap, pillarGraph, startHere, tidyPlan } from './navigation.js';
+import { version } from './version.js';
+import { GroundError, errorPayload } from './errors.js';
+const result = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data) }] });
+export function createFullServer(store) {
+    const server = new McpServer({ name: 'common-ground', version });
+    const paging = { cursor: z.string().optional(), limit: z.number().int().min(1).max(20).optional() };
+    const register = (name, description, inputSchema, readOnly, fn) => server.registerTool(name, { description, inputSchema, annotations: { readOnlyHint: readOnly, destructiveHint: name === 'commit_update', openWorldHint: false } }, async (args) => { try {
+        return result(await fn(args));
+    }
+    catch (e) {
+        return { ...result({ error: e.message }), isError: true };
+    } });
+    const routing = { path: relativePath.optional(), signal: z.string().trim().min(1).optional(), ...paging };
+    register('start_here', 'Start with a failing command, symptom, or source path. Returns an agent workflow and bounded ownership candidates; it does not diagnose bugs.', routing, true, args => startHere(store, args));
+    register('ownership_map', 'Map registered paths or keyword signals to owning pillars and chapters. Signal matches are hints; verify code.', routing, true, args => ownershipMap(store, args));
+    register('pillar_graph', 'Read the recorded pillar dependency graph derived from fact references. Direction is dependent to dependency; missing edges are unknown.', { pillarId: z.string().optional(), ...paging }, true, ({ pillarId, cursor, limit }) => pillarGraph(store, pillarId, cursor, limit));
+    register('tidy_plan', 'Preview cleanup scope for all knowledge, a pillar, chapter, or fact. No changes or approval are made; the calling agent must verify source and documentation.', { target: z.string().min(1), ...paging }, true, ({ target, cursor, limit }) => tidyPlan(store, target, cursor, limit));
+    register('review_checklist', 'List current source and documentation files to open before review, including no-op outcomes. Attest only after reading them this session; deleted files require a live absence check.', { chapterIds: z.array(chapterKey), touchedPaths: z.array(relativePath), ...paging }, true, ({ chapterIds, touchedPaths, cursor, limit }) => reviewChecklist(store, chapterIds, touchedPaths, cursor, limit));
+    register('list_pillars', 'List repository responsibility boundaries without loading facts.', paging, true, ({ cursor, limit }) => listPillars(store, cursor, limit));
+    register('list_chapters', 'Read a pillar chapter index; skim scopes to select the relevant chapter. Returns no facts.', { pillarId: z.string(), ...paging }, true, ({ pillarId, cursor, limit }) => listChapters(store, pillarId, cursor, limit));
+    register('read_chapter', 'Read one chapter in bounded fact pages. Follow nextCursor to review every fact before an update. Use read_fact for evidence.', { chapterId: chapterKey, ...paging }, true, ({ chapterId, cursor, limit }) => readChapter(store, chapterId, cursor, limit));
+    register('read_fact', 'Fetch the exact evidence for one fact, with chapter freshness.', { chapterId: chapterKey, factId: z.string() }, true, ({ chapterId, factId }) => readFact(store, chapterId, factId));
+    register('search_knowledge', 'Find relevant fact summaries; optional chapter scope. Fetch evidence with read_fact.', { query: z.string().min(1), limit: paging.limit, chapterId: chapterKey.optional() }, true, ({ query, limit, chapterId }) => search(store, query, limit, chapterId));
+    register('review_plan', 'List required chapter reviews, by tracing fact dependencies and dependents. Select factIds to narrow the impact graph. It does not authorize rewriting valid facts.', { chapterId: chapterKey, factIds: Update.shape.factIds }, true, ({ chapterId, factIds }) => store.reviewPlan(chapterId, factIds));
+    register('prepare_update', 'After authorized work: submit complete reviews for the chapter and every linked chapter from review_plan. Correct invalidated facts in place; explicitly reasoned maintenance may merge, remove, or tighten existing facts. Read source and documentation this session and supply verification. Uncertainty requires developer input.', Update.shape, false, args => store.prepare(args));
+    register('commit_update', 'Atomically publish changed chapters in a prepared review transaction. Rechecks evidence, source snapshots, and registry revision.', { proposalId: z.string() }, false, ({ proposalId }) => store.commit(proposalId));
+    registerOperations(server, store);
+    return server;
+}
+export async function serve(store, profile = 'compact') { await createServer(store, profile).connect(new StdioServerTransport()); }
+export function createServer(store, profile = 'compact') {
+    if (profile === 'full')
+        return createFullServer(store);
+    if (profile !== 'compact')
+        throw new Error('Unknown MCP profile; use compact or full.');
+    const server = new McpServer({ name: 'common-ground', version }), workflow = new Workflow(store);
+    const register = (name, description, inputSchema, readOnly, fn) => server.registerTool(name, { description, inputSchema, annotations: { readOnlyHint: readOnly, destructiveHint: name === 'commit_update', openWorldHint: false } }, async (args) => { try {
+        return result(await fn(args));
+    }
+    catch (e) {
+        return { ...result({ error: e.message }), isError: true };
+    } });
+    register('task_context', 'Optional context for deferred additions and aggregate reporting. For routine work use cground lookup and assess without a task. If started, assess touched paths and finish once. Without a taskId, follow returned setup guidance and continue from source. Local state only.', {
+        action: z.enum(['start', 'assess', 'finish']), taskId: z.string().uuid().optional(), paths: z.array(relativePath).optional(), signal: z.string().optional(), refresh: z.boolean().optional(), ...paging,
+    }, false, async ({ action, taskId, paths, signal, cursor, limit, refresh }) => {
+        if (action === 'start')
+            return workflow.start(paths, signal);
+        if (!taskId)
+            throw new Error('taskId is required.');
+        if (action === 'finish')
+            return workflow.finish(taskId, cursor, limit);
+        if (!paths)
+            throw new Error('Supply actual task-touched paths (including new/deleted files).');
+        return workflow.assess(taskId, paths, cursor, limit, refresh);
+    });
+    register('read_knowledge', 'Read bounded knowledge. target is a pillar/chapter/fact ID. chapter + evidence:true batches full facts; read every page before editing. refresh:true resends cached context.', ReadKnowledge.shape, false, args => readKnowledge(store, args));
+    register('prepare_patch', 'Quiet existing-fact maintenance only; taskId is optional. Read POLICY.md, all required chapter pages and source first. reviewedAllFacts attests the whole revision. Send only changed records; unchanged records are preserved.', Patch.shape, false, args => workflow.prepare(args));
+    register('commit_update', 'Write a prepared correction to the Git working tree after rechecking revisions, source and documentation. Report at task completion.', { proposalId: z.string().uuid() }, false, ({ proposalId }) => store.commit(proposalId));
+    register('propose_facts', 'Queue verified new facts locally; no shared write. Batch for developer approval after task_context finish. Dependencies must already be admitted.', { taskId: z.string().uuid(), chapterId: chapterKey, facts: z.array(Fact).min(1) }, false, ({ taskId, chapterId, facts }) => workflow.propose(taskId, chapterId, facts));
+    registerOperations(server, store);
+    return server;
+}
+const paging = { cursor: z.string().optional(), limit: z.number().int().min(1).max(20).optional() };
+export function registerOperations(server, store) {
+    const catalog = operations(store);
+    server.registerTool('cground', {
+        description: 'All Common Ground CLI workflows via structured MCP, no shell needed. Call operation:help for a paginated catalog or help with args.operation for its exact input schema. Use lookup for cheap stateless facts/source locations and assess for task-touched changes; neither requires start/finish. Supports check/validate/tidy, onboarding, approved admission, task workflows, hooks and export. Host approval settings apply. approved:true declares actual developer approval, never grants it. Cleanup verifies existing facts only; the calling agent reads source and submits reviewed corrections.',
+        inputSchema: { operation: z.enum(['help', ...Object.keys(catalog)]), args: z.record(z.unknown()).default({}) },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, async ({ operation, args }) => {
+        try {
+            let value;
+            if (operation === 'help') {
+                const request = z.object({ operation: z.string().optional(), ...paging }).strict().parse(args);
+                if (request.operation) {
+                    const entry = catalog[request.operation];
+                    if (!entry)
+                        throw new Error('Unknown operation.');
+                    value = { operation: request.operation, description: entry.description, inputSchema: toJsonSchemaCompat(entry.schema) };
+                }
+                else {
+                    value = { ...page(Object.entries(catalog).map(([operation, entry]) => ({ operation, description: entry.description })), request.cursor, request.limit), transport: 'serve is the process entry point, not a nested operation. Repository root is fixed by the host configuration.' };
+                }
+            }
+            else
+                value = await runOperation(store, operation, args);
+            return { content: [{ type: 'text', text: JSON.stringify(value) }] };
+        }
+        catch (e) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: e.message, ...(e instanceof GroundError && e.code === 'INIT_INCOMPLETE' ? { diagnostic: errorPayload(e) } : {}) }) }], isError: true };
+        }
+    });
+}

package/dist/source-search.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import type { Store } from './store.js';
+export declare const SourceSearch: z.ZodObject<{
+    query: z.ZodString;
+    paths: z.ZodArray<z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEffects<z.ZodString, string, string>>, "many">;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    paths: string[];
+    query: string;
+    limit: number;
+}, {
+    paths: string[];
+    query: string;
+    limit?: number | undefined;
+}>;
+/** Pure eligibility check for suggestions; actual searches additionally reject symlinks. */
+export declare function isSourceSearchPathAllowed(file: string): boolean;
+/** Read-only lexical source evidence, intentionally separate from stored-knowledge lookup. */
+export declare function sourceSearch(store: Store, input: unknown): Promise<{
+    kind: string;
+    state: string;
+    writesKnowledge: boolean;
+    query: string;
+    paths: string[];
+    items: {
+        path: string;
+        line: number;
+        excerpt: string;
+        matchedTerms: string[];
+        relevance: string;
+    }[];
+    total: number;
+    resultLimit: number;
+    resultsTruncated: boolean;
+    downweightedTerms: string[];
+    suppressedSharedTermMatches: number;
+    scan: {
+        truncated: boolean;
+        reachedLimits: string[];
+        limits: {
+            entries: number;
+            files: number;
+            fileBytes: number;
+            totalBytes: number;
+            excerptChars: number;
+        };
+        entries: number;
+        files: number;
+        bytes: number;
+        textFiles: number;
+        skipped: {
+            excluded: number;
+            symlinks: number;
+            binary: number;
+            oversize: number;
+            unreadable: number;
+            changed: number;
+            nonRegular: number;
+            missing: number;
+        };
+    };
+    basis: string;
+}>;

package/dist/source-search.js

@@ -0,0 +1,245 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { GroundError } from './errors.js';
+import { relativePath } from './model.js';
+import { isVersion, queryTerms, termMatch } from './matching.js';
+export const SourceSearch = z.object({
+    query: z.string().trim().min(1).max(500),
+    paths: z.array(relativePath).min(1).max(20).describe('Explicit source files or directories to search; repository-wide and excluded paths are not supported.'),
+    limit: z.number().int().min(1).max(5).default(5),
+}).strict();
+const limits = { entries: 2000, files: 200, fileBytes: 1024 * 1024, totalBytes: 4 * 1024 * 1024, excerptChars: 300 };
+const excluded = new Set(['node_modules', 'dist', 'build', 'target', 'out', 'coverage', 'generated', 'vendor', 'vendored', 'bundled', 'dep', 'deps', 'dependencies', 'third_party', 'third-party', 'thirdparty', 'external', 'extern', 'venv', '__pycache__', 'pods', 'carthage', 'deriveddata', 'bin', 'obj']);
+const generated = /^(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|Gemfile\.lock|composer\.lock)$|(?:\.min\.(?:js|css)|\.map|\.generated\.[^.]+)$/i;
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const within = (file, scope) => file === scope || file.startsWith(`${scope}/`);
+const excludedPath = (file) => file.split('/').some(part => (part.startsWith('.') && part !== '.github') || excluded.has(part.toLowerCase()) || generated.test(part));
+/** Pure eligibility check for suggestions; actual searches additionally reject symlinks. */
+export function isSourceSearchPathAllowed(file) {
+    const parsed = relativePath.safeParse(file);
+    return parsed.success && !excludedPath(parsed.data);
+}
+function matchOffset(text, terms) {
+    let offset = 0;
+    // Keep original offsets while applying the same camel boundaries and technical
+    // token grammar as words(). Check each token before locating a substring: 1.40
+    // must not anchor 1.4, and "special" must not anchor the short token "ci".
+    for (const segment of text.split(/(?<=[\p{Ll}\p{N}])(?=\p{Lu})|(?<=\p{Lu})(?=\p{Lu}\p{Ll})/gu)) {
+        for (const token of segment.matchAll(/v?\d+(?:\.\d+)+(?:[-+][\p{L}\p{N}]+(?:[.-][\p{L}\p{N}]+)*)?|[\p{L}\p{N}]+/giu)) {
+            const matched = terms.filter(term => termMatch(token[0], term) > 0);
+            if (matched.length) {
+                const positions = matched.map(term => token[0].toLowerCase().indexOf(term)).filter(index => index >= 0);
+                return offset + token.index + (positions.length ? Math.min(...positions) : 0);
+            }
+        }
+        offset += segment.length;
+    }
+    return 0;
+}
+function excerpt(line, terms) {
+    const text = line.replace(/[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, ' ').trim();
+    if (text.length <= limits.excerptChars)
+        return text;
+    const versions = terms.filter(isVersion);
+    const start = Math.max(0, matchOffset(text, versions.length ? versions : terms) - 80);
+    return `${start ? '…' : ''}${text.slice(start, start + limits.excerptChars)}${start + limits.excerptChars < text.length ? '…' : ''}`;
+}
+/** Read-only lexical source evidence, intentionally separate from stored-knowledge lookup. */
+export async function sourceSearch(store, input) {
+    const args = SourceSearch.parse(input), terms = queryTerms(args.query);
+    if (!terms.length || terms.length > 32)
+        throw new GroundError('SOURCE_SEARCH_QUERY', 'Use between one and 32 technical search terms.', ['query'], 'Narrow the query to a few source identifiers, concepts or versions.');
+    const requested = [...new Set(args.paths)].sort(compare);
+    for (const scope of requested) {
+        if (excludedPath(scope))
+            throw new GroundError('SOURCE_SEARCH_PATH_EXCLUDED', `Excluded source-search path: ${scope}`, ['paths'], 'Select source files or directories outside dependencies, generated output and hidden configuration. .github is supported.');
+        await store.safe(scope, true);
+    }
+    const scopes = requested.filter(scope => !requested.some(other => other !== scope && within(scope, other)));
+    const stats = { entries: 0, files: 0, bytes: 0, textFiles: 0, skipped: { excluded: 0, symlinks: 0, binary: 0, oversize: 0, unreadable: 0, changed: 0, nonRegular: 0, missing: 0 } };
+    const reached = new Set(), sources = [];
+    const stop = () => reached.has('entries') || reached.has('files') || reached.has('totalBytes');
+    const read = async (relative) => {
+        if (stats.files >= limits.files) {
+            reached.add('files');
+            return;
+        }
+        stats.files++;
+        let handle;
+        try {
+            const file = await store.safe(relative);
+            handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const before = await handle.stat();
+            if (!before.isFile()) {
+                stats.skipped.nonRegular++;
+                return;
+            }
+            if (before.size > limits.fileBytes) {
+                stats.skipped.oversize++;
+                return;
+            }
+            if (before.size > limits.totalBytes - stats.bytes) {
+                reached.add('totalBytes');
+                return;
+            }
+            const buffer = Buffer.alloc(Math.min(before.size + 1, limits.totalBytes - stats.bytes));
+            let size = 0;
+            while (size < buffer.length) {
+                const { bytesRead } = await handle.read(buffer, size, buffer.length - size, null);
+                if (!bytesRead)
+                    break;
+                size += bytesRead;
+                stats.bytes += bytesRead;
+            }
+            const after = await handle.stat();
+            if (before.size !== size || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+                stats.skipped.changed++;
+                return;
+            }
+            const bytes = buffer.subarray(0, size);
+            let text;
+            try {
+                text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            }
+            catch {
+                stats.skipped.binary++;
+                return;
+            }
+            if (bytes.includes(0)) {
+                stats.skipped.binary++;
+                return;
+            }
+            stats.textFiles++;
+            sources.push({ path: relative, text, matchedTerms: terms.filter(term => termMatch(`${relative}\n${text}`, term) > 0) });
+        }
+        catch (error) {
+            if (error.code === 'ELOOP' || String(error.message).startsWith('Symlinks are not supported'))
+                stats.skipped.symlinks++;
+            else if (error.code === 'ENOENT')
+                stats.skipped.missing++;
+            else
+                stats.skipped.unreadable++;
+        }
+        finally {
+            await handle?.close();
+        }
+    };
+    const visit = async (relative, enumerated = false) => {
+        if (stop())
+            return;
+        if (!enumerated) {
+            if (stats.entries >= limits.entries) {
+                reached.add('entries');
+                return;
+            }
+            stats.entries++;
+        }
+        if (excludedPath(relative)) {
+            stats.skipped.excluded++;
+            return;
+        }
+        let stat;
+        try {
+            stat = await fs.lstat(path.join(store.root, relative));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                stats.skipped.missing++;
+            else
+                stats.skipped.unreadable++;
+            return;
+        }
+        if (stat.isSymbolicLink()) {
+            stats.skipped.symlinks++;
+            return;
+        }
+        if (stat.isFile()) {
+            await read(relative);
+            return;
+        }
+        if (!stat.isDirectory()) {
+            stats.skipped.nonRegular++;
+            return;
+        }
+        // Buffer only a bounded, complete directory listing before sorting. An overfull
+        // directory is not searched in filesystem-dependent enumeration order.
+        const children = [];
+        try {
+            const directory = await fs.opendir(await store.safe(relative));
+            try {
+                while (true) {
+                    const entry = await directory.read();
+                    if (!entry)
+                        break;
+                    if (stats.entries >= limits.entries) {
+                        reached.add('entries');
+                        return;
+                    }
+                    stats.entries++;
+                    children.push(`${relative}/${entry.name}`);
+                }
+            }
+            finally {
+                await directory.close();
+            }
+        }
+        catch (error) {
+            if (String(error.message).startsWith('Symlinks are not supported'))
+                stats.skipped.symlinks++;
+            else
+                stats.skipped.unreadable++;
+            return;
+        }
+        for (const child of children.sort(compare)) {
+            await visit(child, true);
+            if (stop())
+                break;
+        }
+    };
+    for (const scope of scopes) {
+        await visit(scope);
+        if (stop())
+            break;
+    }
+    const frequency = new Map(terms.map(term => [term, sources.filter(source => source.matchedTerms.includes(term)).length]));
+    const broad = new Set(terms.filter(term => !isVersion(term) && sources.length >= 3 && (frequency.get(term) ?? 0) / sources.length >= 0.75));
+    const weights = new Map(terms.map(term => [term, 1 + Math.log((sources.length + 1) / ((frequency.get(term) ?? 0) + 1))]));
+    const direct = [], shared = [];
+    let directCount = 0, sharedCount = 0;
+    const rank = (a, b) => b.score - a.score || compare(a.path, b.path) || a.line - b.line;
+    for (const source of sources) {
+        if (!source.matchedTerms.length)
+            continue;
+        let start = 0, lineNumber = 1;
+        while (start < source.text.length) {
+            const end = source.text.indexOf('\n', start), line = source.text.slice(start, end < 0 ? undefined : end);
+            const matched = terms.filter(term => termMatch(line, term) > 0);
+            if (matched.length) {
+                const distinctive = matched.some(term => !broad.has(term));
+                const score = matched.reduce((total, term) => total + (weights.get(term) ?? 1) * (termMatch(line, term) + termMatch(source.path, term)), 0);
+                const candidate = { path: source.path, line: lineNumber, excerpt: excerpt(line, matched), matchedTerms: matched, relevance: distinctive ? 'query-match' : 'shared-terms-only', score };
+                const candidates = distinctive ? direct : shared;
+                if (distinctive)
+                    directCount++;
+                else
+                    sharedCount++;
+                candidates.push(candidate);
+                candidates.sort(rank);
+                if (candidates.length > args.limit)
+                    candidates.pop();
+            }
+            if (end < 0)
+                break;
+            start = end + 1;
+            lineNumber++;
+        }
+    }
+    const candidates = directCount ? direct : shared, total = directCount || sharedCount;
+    return { kind: 'live-source-evidence', state: candidates.length ? 'matches' : 'no-matches', writesKnowledge: false, query: args.query, paths: scopes,
+        items: candidates.map(({ score, ...item }) => item), total, resultLimit: args.limit, resultsTruncated: total > args.limit,
+        downweightedTerms: [...broad], suppressedSharedTermMatches: directCount ? sharedCount : 0,
+        scan: { ...stats, truncated: reached.size > 0, reachedLimits: [...reached], limits },
+        basis: 'Live local source lines from a bounded lexical search, separate from stored facts. Matches are navigation evidence, not an architectural answer; open the surrounding code and documentation. No project code was executed.',
+    };
+}