@nazty_labs/common-ground 0.5.1

package/dist/init.js

@@ -0,0 +1,150 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { version } from './version.js';
+import { parse, modify, applyEdits } from 'jsonc-parser';
+import { installHook } from './hooks.js';
+import { refreshKnowledgeExport } from './export.js';
+import { discover } from './discovery.js';
+import { GroundError, errorPayload } from './errors.js';
+export { discover } from './discovery.js';
+import { rules, startGuide, policy, bootstrapNext } from './guidance.js';
+export { rules } from './guidance.js';
+async function managed(store, relative, body) {
+    await store.safe(relative, true);
+    const file = path.join(store.root, relative);
+    let old = '';
+    try {
+        old = await fs.readFile(file, 'utf8');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const start = relative === '.gitignore' ? '# common-ground:start' : '<!-- common-ground:start -->', end = relative === '.gitignore' ? '# common-ground:end' : '<!-- common-ground:end -->';
+    if (old.includes(start) !== old.includes(end) || old.split(start).length > 2 || old.split(end).length > 2 || (old.includes(start) && old.indexOf(end) < old.indexOf(start)))
+        throw new Error(`Malformed managed block in ${relative}`);
+    const block = `${start}\n${body.trim()}\n${end}`;
+    const next = old.includes(start) ? old.slice(0, old.indexOf(start)) + block + old.slice(old.indexOf(end) + end.length) : old + (old && !old.endsWith('\n') ? '\n' : '') + (old ? '\n' : '') + block + '\n';
+    if (next !== old) {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, next);
+    }
+    return next !== old;
+}
+export async function initialize(store, options = {}) {
+    const steps = ['local-directory', 'registry', 'mcp-validation', ...Object.keys(guidanceFiles), '.gitignore', 'mcp-config', 'discovery', 'hook', 'markdown'];
+    const completed = [], skipped = [], failed = [];
+    const retry = 'Retry cground init after fixing the failed step; completed managed writes are safe to repeat and existing knowledge and bootstrap drafts are preserved. Use cground init --skip-hook to omit the advisory hook, or cground hook install later.';
+    async function step(name, work) {
+        try {
+            const result = await work();
+            completed.push(name);
+            return result;
+        }
+        catch (error) {
+            const cause = errorPayload(error);
+            throw new GroundError('INIT_INCOMPLETE', `Initialization failed at ${name}: ${cause.message}. Completed: ${completed.join(', ') || 'none'}.`, cause.fields, retry, { completed: completed.filter(id => !failed.some(f => f.step === id)), skipped: [...skipped], failed: [...failed, { step: name, error: cause }], pending: steps.slice(steps.indexOf(name) + 1), failedStepMayHaveWritten: true });
+        }
+    }
+    await step('local-directory', async () => { await store.safe('.common-ground/local', true); await fs.mkdir(store.file('local'), { recursive: true }); });
+    const exists = await step('registry', async () => { try {
+        await store.read();
+        return true;
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+        return false;
+    } });
+    const configFile = path.join(store.root, '.vscode/mcp.json');
+    let configText = '{}\n';
+    const nextConfig = await step('mcp-validation', async () => {
+        await store.safe('.vscode/mcp.json', true);
+        try {
+            configText = await fs.readFile(configFile, 'utf8');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        const errors = [];
+        const config = parse(configText, errors, { allowTrailingComma: true });
+        if (errors.length || !config || typeof config !== 'object' || Array.isArray(config) || (config.servers && (typeof config.servers !== 'object' || Array.isArray(config.servers))))
+            throw new Error('Invalid .vscode/mcp.json; refusing to overwrite.');
+        if (config.servers?.commonGround && config.servers.commonGround.command !== 'cground')
+            throw new Error('Existing commonGround MCP entry conflicts; resolve it before init.');
+        const entry = { type: 'stdio', command: 'cground', args: ['serve', '--root', '${workspaceFolder}'] };
+        return applyEdits(configText, modify(configText, ['servers', 'commonGround'], entry, { formattingOptions: { insertSpaces: true, tabSize: 2 } }));
+    });
+    for (const [file, body] of Object.entries(guidanceFiles))
+        await step(file, () => managed(store, file, body));
+    await step('.gitignore', () => managed(store, '.gitignore', '.common-ground/local/'));
+    await step('mcp-config', async () => { await fs.mkdir(path.dirname(configFile), { recursive: true }); if (configText !== nextConfig)
+        await fs.writeFile(configFile, nextConfig); });
+    const proposal = await step('discovery', async () => {
+        if (exists)
+            return { existingRegistry: true, message: 'Existing pillars preserved. No new discovery or pillar creation.' };
+        try {
+            const file = await store.safe('.common-ground/local/bootstrap.json');
+            if (!(await fs.stat(file)).isFile())
+                throw new Error('Existing bootstrap draft is not a regular file.');
+            return { existingDraft: true, proposalPath: '.common-ground/local/bootstrap.json', message: 'Existing bootstrap draft preserved. Read it before refining; cground scan can provide fresh signals.' };
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        const proposal = await discover(store);
+        await store.atomic('local/bootstrap.json', proposal);
+        return proposal;
+    });
+    let hook;
+    if (options.skipHook) {
+        skipped.push('hook');
+        hook = 'Advisory hook skipped. Run cground hook install later to enable it.';
+    }
+    else
+        hook = await step('hook', async () => {
+            try {
+                return await installHook(store);
+            }
+            catch (error) {
+                if (!['EROFS', 'EACCES', 'EPERM'].includes(error.code))
+                    throw error;
+                failed.push({ step: 'hook', error: errorPayload(error) });
+                return `Advisory hook unavailable: ${error.message}. Repository setup continues. Run cground hook install when Git metadata is writable.`;
+            }
+        });
+    const markdown = await step('markdown', () => refreshKnowledgeExport(store));
+    const setup = { status: failed.length ? 'complete-with-warnings' : 'complete', completed: completed.filter(name => !failed.some(f => f.step === name)), skipped, failed, pending: [], retry: failed.length ? retry : null };
+    return exists ? { ...proposal, hook, markdown, setup } : { ...proposal, state: 'bootstrap-required', next: bootstrapNext, hook, markdown, setup };
+}
+const guidanceFiles = {
+    'AGENTS.md': rules,
+    '.common-ground/START_HERE.md': startGuide,
+    '.common-ground/POLICY.md': policy,
+    '.github/copilot-instructions.md': 'Common Ground repository knowledge rules are in [AGENTS.md](../AGENTS.md). Follow its Common Ground section when reading or maintaining pillars.\nCode is the source of truth; these notes only help navigation.\nFor repository questions, consult Common Ground and verify source. If knowledge is missing or stale, answer from source and prompt to update it.\nIf the developer disputes the code, clarify current versus intended behavior together. Record only verified, durable knowledge under the note-taking rules.',
+};
+export async function guidanceStatus(store) {
+    const files = {};
+    for (const [file, body] of Object.entries(guidanceFiles)) {
+        try {
+            const text = (await fs.readFile(await store.safe(file), 'utf8')).replace(/\r\n/g, '\n');
+            const expected = `<!-- common-ground:start -->\n${body.trim()}\n<!-- common-ground:end -->`;
+            files[file] = text.includes(expected) && text.split('<!-- common-ground:start -->').length === 2 && text.split('<!-- common-ground:end -->').length === 2 ? 'current' : 'stale';
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            files[file] = 'missing';
+        }
+    }
+    return { installedVersion: version, basis: 'Managed content compared with installed guidance templates', status: Object.values(files).every(value => value === 'current') ? 'current' : 'outdated', files,
+        next: Object.values(files).every(value => value === 'current') ? null : 'Run cground refresh-guidance to update managed instructions while preserving surrounding text.' };
+}
+export async function refreshGuidance(store) {
+    const changedFiles = [], unchangedFiles = [];
+    for (const [file, body] of Object.entries(guidanceFiles))
+        (await managed(store, file, body) ? changedFiles : unchangedFiles).push(file);
+    return { writesKnowledge: false, changedFiles, unchangedFiles, ...await guidanceStatus(store) };
+}

package/dist/maintenance.d.ts

@@ -0,0 +1,126 @@
+import { Store } from './store.js';
+export declare function checkKnowledge(store: Store, target?: string, cleanup?: boolean, cursor?: string, limit?: number, expectedAffected?: unknown, allResults?: boolean): Promise<{
+    cleanup: {
+        targets: string[];
+        next: string;
+        tidyId: null;
+        instruction: string;
+        requiredChapters?: undefined;
+    } | {
+        targets: string[];
+        next: string;
+        tidyId: `${string}-${string}-${string}-${string}-${string}`;
+        requiredChapters: string[];
+        instruction: string;
+    } | null;
+    markdown: {
+        path: string;
+        changed: boolean;
+    };
+    items: {
+        dependencyIssues: {
+            recordChanged: boolean;
+            changedPaths: string[];
+            errors: string[];
+            factId: string;
+        }[];
+        locallyReviewed: boolean;
+        changedPaths: string[];
+        errors: string[];
+        factId: string;
+        chapterId: string;
+        status: string;
+    }[];
+    total: number;
+    nextCursor: string | null;
+    target: string;
+    writesKnowledge: boolean;
+    valid: boolean;
+    basis: string;
+    affected: {
+        pillars: string[];
+        chapters: string[];
+        facts: string[];
+    };
+    cleanupPrompt: string | null;
+    summary: {
+        selectedFacts: number;
+        checkedFacts: number;
+        needsReview: number;
+        unpopulatedChapters: string[];
+    };
+}>;
+export declare function startTidy(store: Store, target: string, cursor?: string, limit?: number): Promise<{
+    markdown: {
+        path: string;
+        changed: boolean;
+    };
+    tidyId: null;
+    instruction: string;
+    requiredChapters?: undefined;
+    target: string;
+    writesKnowledge: boolean;
+    agentActionRequired: boolean;
+    policy: string;
+    next: string;
+    requiredChapterCount: number;
+    chapters: {
+        items: {
+            chapterId: string;
+            revision: number;
+            factCount: number;
+            duplicateGroupCount: number;
+            duplicateHints: string[][];
+        }[];
+        total: number;
+        nextCursor: string | null;
+    };
+} | {
+    markdown: {
+        path: string;
+        changed: boolean;
+    };
+    tidyId: `${string}-${string}-${string}-${string}-${string}`;
+    requiredChapters: string[];
+    instruction: string;
+    target: string;
+    writesKnowledge: boolean;
+    agentActionRequired: boolean;
+    policy: string;
+    next: string;
+    requiredChapterCount: number;
+    chapters: {
+        items: {
+            chapterId: string;
+            revision: number;
+            factCount: number;
+            duplicateGroupCount: number;
+            duplicateHints: string[][];
+        }[];
+        total: number;
+        nextCursor: string | null;
+    };
+} | {
+    markdown: {
+        path: string;
+        changed: boolean;
+    };
+    target: string;
+    writesKnowledge: boolean;
+    agentActionRequired: boolean;
+    policy: string;
+    next: string;
+    requiredChapterCount: number;
+    chapters: {
+        items: {
+            chapterId: string;
+            revision: number;
+            factCount: number;
+            duplicateGroupCount: number;
+            duplicateHints: string[][];
+        }[];
+        total: number;
+        nextCursor: string | null;
+    };
+}>;
+export declare function staleMessage(result: Awaited<ReturnType<typeof checkKnowledge>>): string;

package/dist/maintenance.js

@@ -0,0 +1,23 @@
+import { same } from './store.js';
+import { validateKnowledge, tidyPlan } from './navigation.js';
+import { refreshKnowledgeExport } from './export.js';
+export async function checkKnowledge(store, target = 'all', cleanup = false, cursor, limit, expectedAffected, allResults = true) {
+    const registry = await store.read();
+    const result = await validateKnowledge(store, target, cursor, limit, allResults);
+    if (expectedAffected && !same(expectedAffected, result.affected))
+        throw new Error('Affected knowledge changed; rerun the check and confirm the new cleanup scope.');
+    if (!same(registry, await store.read()))
+        throw new Error('Knowledge changed; rerun the check.');
+    const cleanupPlan = cleanup && result.affected.chapters.length
+        ? { ...await store.requestTidy(result.affected.chapters, registry), targets: result.affected.chapters,
+            next: 'Start task_context if needed. Read every required chapter and source/documentation using read_knowledge checklist/review. Submit verified corrections with prepare_patch (or prepare_update) and tidyId, then commit_update. Re-run validate. Do not add facts or expand ownership without developer approval.' }
+        : null;
+    return { ...result, cleanup: cleanupPlan, markdown: await refreshKnowledgeExport(store) };
+}
+export async function startTidy(store, target, cursor, limit) {
+    const registry = await store.read();
+    return { ...await tidyPlan(store, target, cursor, limit), ...(!cursor ? await store.requestTidy(target, registry) : {}), markdown: await refreshKnowledgeExport(store) };
+}
+export function staleMessage(result) {
+    return ['pillars', 'chapters', 'facts'].filter(kind => result.affected[kind].length).map(kind => `The following ${kind.slice(0, -1).toUpperCase()} is out of date:\n${result.affected[kind].map(id => `  ${id}`).join('\n')}`).join('\n');
+}

package/dist/matching.d.ts

@@ -0,0 +1,17 @@
+/** Shared technical tokens. Versions remain atomic; identifiers split at camel-case boundaries. */
+export declare function words(text: string): string[];
+export declare const queryTerms: (text: string) => string[];
+export declare const isVersion: (term: string) => boolean;
+export declare function termMatch(text: string, term: string): number;
+/** Query weights derive from the current registry, never from durable search statistics. */
+export declare function termWeights(terms: string[], documents: string[]): {
+    weights: Map<string, number>;
+    commonTerms: string[];
+    distinctiveTerms: string[];
+};
+export declare function matchFields(terms: string[], topic: string, statement: string, weights?: Map<string, number>): {
+    matchedTerms: string[];
+    weight: number;
+};
+/** A literal path in query text gets the same priority as --path, without filesystem probing. */
+export declare function queryPath(query: string | undefined): string | undefined;

package/dist/matching.js

@@ -0,0 +1,32 @@
+/** Shared technical tokens. Versions remain atomic; identifiers split at camel-case boundaries. */
+export function words(text) {
+    const normalized = text.replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, '$1 $2').replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, '$1 $2').toLowerCase();
+    return [...new Set((normalized.match(/v?\d+(?:\.\d+)+(?:[-+][\p{L}\p{N}]+(?:[.-][\p{L}\p{N}]+)*)?|[\p{L}\p{N}]+/gu) ?? []).map(token => token.replace(/^v(?=\d+\.)/, '')))];
+}
+const stopWords = new Set(['a', 'an', 'the', 'and', 'or', 'of', 'to', 'in', 'on', 'for', 'from', 'with', 'by', 'is', 'are', 'was', 'be', 'this', 'that', 'it', 'its', 'how', 'what', 'where', 'which', 'when', 'does', 'do', 'can', 'our', 'my']);
+export const queryTerms = (text) => words(text).filter(term => !stopWords.has(term));
+export const isVersion = (term) => /^\d+(?:\.\d+)+(?:[-+].+)?$/.test(term);
+export function termMatch(text, term) {
+    const tokens = words(text);
+    if (tokens.includes(term))
+        return 2;
+    return !isVersion(term) && term.length > 3 && tokens.some(token => !isVersion(token) && token.includes(term)) ? 1 : 0;
+}
+/** Query weights derive from the current registry, never from durable search statistics. */
+export function termWeights(terms, documents) {
+    const frequencies = new Map(terms.map(term => [term, documents.filter(text => termMatch(text, term) > 0).length]));
+    const commonTerms = terms.filter(term => documents.length >= 3 && frequencies.get(term) / documents.length >= 0.6 && !isVersion(term));
+    const weights = new Map(terms.map(term => [term, commonTerms.includes(term) ? 0.2 : 1 + Math.log2((documents.length + 1) / (frequencies.get(term) + 1))]));
+    return { weights, commonTerms, distinctiveTerms: terms.filter(term => !commonTerms.includes(term)) };
+}
+export function matchFields(terms, topic, statement, weights) {
+    const strengths = terms.map(term => Math.max(termMatch(topic, term) * 2, termMatch(statement, term)));
+    return { matchedTerms: terms.filter((_, index) => strengths[index] > 0), weight: strengths.reduce((n, strength, index) => n + strength * (weights?.get(terms[index]) ?? 1), 0) };
+}
+/** A literal path in query text gets the same priority as --path, without filesystem probing. */
+export function queryPath(query) {
+    const candidate = query?.trim().replace(/^['"`]|['"`]$/g, '');
+    if (!candidate || !candidate.includes('/') || /\s/.test(candidate) || candidate.startsWith('/') || candidate.includes('\\') || candidate.split('/').some(p => !p || p === '.' || p === '..'))
+        return undefined;
+    return candidate;
+}