@kentwynn/kgraph 0.2.32 → 0.2.34

package/README.md

@@ -253,9 +253,10 @@ kgraph repair
 kgraph uninstall
 kgraph uninstall --yes
 kgraph uninstall --keep-integrations --yes
+kgraph uninstall --yes --memory
 ```
 
-`uninstall` previews repo-local removal and does not delete anything unless `--yes` is passed. `uninstall --yes` removes `.kgraph/` and KGraph-managed integration blocks/files while preserving source files and user-authored text outside managed blocks. Use `--keep-integrations --yes` to remove only `.kgraph/` while leaving AI tool instruction files in place. After uninstalling, `kgraph init` can be run again for a fresh setup.
+`uninstall` previews repo-local removal and does not delete anything unless `--yes` is passed. `uninstall --yes` removes `.kgraph/` and KGraph-managed integration blocks/files while preserving source files and user-authored text outside managed blocks. Use `--keep-integrations --yes` to remove only `.kgraph/` while leaving AI tool instruction files in place. Add `--memory` to also remove the Copilot memory rule that `init` installs; without this flag the memory entry is preserved across uninstalls. After uninstalling, `kgraph init` can be run again for a fresh setup.
 
 ```bash
 kgraph impact "Button"

package/dist/cli/commands/init.js

@@ -1,4 +1,5 @@
-import { loadConfig, writeDefaultConfig } from '../../config/config.js';
+import { loadConfig, saveConfig, writeDefaultConfig, } from '../../config/config.js';
+import { installCopilotMemory } from '../../integrations/copilot-memory.js';
 import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
 import { addIntegrations } from '../../integrations/integration-store.js';
 import { ensureKnowledgeStore } from '../../knowledge/atom-store.js';
@@ -6,9 +7,10 @@ import { scanRepository } from '../../scanner/repo-scanner.js';
 import { ensureWorkspace } from '../../storage/kgraph-paths.js';
 import { readMaps, writeMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
-import { promptForInitIntegrations, shouldPromptForInitIntegrations, } from '../init-prompt.js';
+import { promptForInitIntegrations, promptScopeConfirmation, promptWorkspaceSetup, shouldPromptForInitIntegrations, } from '../init-prompt.js';
 import { detectMachineIntegrationRecommendations, recommendedIntegrationsForInit, } from '../init-recommendations.js';
 import { renderInitSummary } from '../init-summary.js';
+import { countScopeFiles, detectWorkspaces } from '../workspace-detection.js';
 export function registerInitCommand(program) {
     program
         .command('init')
@@ -33,6 +35,26 @@ export function registerInitCommand(program) {
             console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
         }
         let config = await loadConfig(workspace);
+        // Workspace detection — only for fresh init, non-destructive
+        const workspaceInfo = await detectWorkspaces(workspace.rootPath);
+        if (workspaceInfo && Object.keys(config.domainHints).length === 0) {
+            const result = await promptWorkspaceSetup(workspaceInfo);
+            if (result.applyDomains && result.domainHints) {
+                config = { ...config, domainHints: result.domainHints };
+                await saveConfig(workspace, config);
+            }
+        }
+        // Pre-scan scope check — fast file count before heavy scan
+        const fileCount = await countScopeFiles(workspace.rootPath, config);
+        const scopeResult = await promptScopeConfirmation(fileCount);
+        if (!scopeResult.proceed) {
+            console.log('Init cancelled. Edit .kgraph/config.yaml to adjust scope, then run `kgraph init` again.');
+            return;
+        }
+        if (scopeResult.narrowedInclude) {
+            config = { ...config, include: scopeResult.narrowedInclude };
+            await saveConfig(workspace, config);
+        }
         const previousMaps = await readMaps(workspace);
         const result = await scanRepository(workspace.rootPath, config, {
             files: previousMaps.fileMap.files,
@@ -64,6 +86,11 @@ export function registerInitCommand(program) {
                 });
             }
         }
+        // Install Copilot memory entry
+        const installed = await installCopilotMemory();
+        if (installed) {
+            console.log('Copilot memory rule installed.');
+        }
         console.log('');
         console.log(renderInitSummary({
             files: result.files,

package/dist/cli/commands/uninstall.js

@@ -1,6 +1,7 @@
 import { readdir, rm, rmdir } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfig } from '../../config/config.js';
+import { removeCopilotMemory } from '../../integrations/copilot-memory.js';
 import { removeIntegrations } from '../../integrations/integration-store.js';
 import { pathExists, resolveWorkspace } from '../../storage/kgraph-paths.js';
 import { runCommand } from '../errors.js';
@@ -15,6 +16,7 @@ export function registerUninstallCommand(program) {
         .description('Remove KGraph from this repository')
         .option('--yes', 'Apply the uninstall after previewing what will be removed')
         .option('--keep-integrations', 'Remove only .kgraph/ and preserve generated AI tool instruction files')
+        .option('--memory', 'Also remove the global Copilot memory entry for this repo')
         .action((options) => runCommand(async () => {
         const workspace = resolveWorkspace(process.cwd());
         const initialized = await pathExists(workspace.kgraphPath);
@@ -25,6 +27,7 @@ export function registerUninstallCommand(program) {
             initialized,
             integrations: configuredIntegrations,
             keepIntegrations: options.keepIntegrations === true,
+            removeMemory: options.memory === true,
             applying: options.yes === true,
         });
         if (!options.yes) {
@@ -39,6 +42,13 @@ export function registerUninstallCommand(program) {
         if (initialized) {
             await rm(workspace.kgraphPath, { recursive: true, force: true });
         }
+        // Remove Copilot memory entry only if --memory flag is set
+        if (options.memory) {
+            const memoryRemoved = await removeCopilotMemory();
+            if (memoryRemoved) {
+                console.log('Removed Copilot memory rule.');
+            }
+        }
         console.log('');
         console.log('KGraph uninstall complete.');
         console.log('Run `kgraph init` to set up this repository again.');
@@ -84,6 +94,9 @@ function printUninstallPreview(input) {
             console.log('- No configured integration blocks/files found');
         }
     }
+    if (input.removeMemory) {
+        console.log('- Copilot memory rule for this repo');
+    }
     console.log('');
     console.log('Will preserve:');
     console.log('- Repository source files');

package/dist/cli/help.js

@@ -11,7 +11,10 @@ export function renderRootHelp(useColor = supportsColor()) {
             ['purpose', 'durable engineering memory for AI coding tools'],
             ['storage', '.kgraph/ atoms, maps, indexes, and session history'],
             ['stance', 'local-first · deterministic-first · inspectable'],
-            ['agents', 'Codex · Copilot · Cursor · Claude Code · Gemini · Windsurf · Cline'],
+            [
+                'agents',
+                'Codex · Copilot · Cursor · Claude Code · Gemini · Windsurf · Cline',
+            ],
         ]),
         '',
         sectionTitle(theme, `${accent} Usage`),
@@ -49,6 +52,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('repair', 'Clean noisy stale atom references'),
         command('uninstall', 'Preview repo-local KGraph removal'),
         command('uninstall --yes', 'Remove .kgraph/ and managed integrations'),
+        command('uninstall --yes --memory', 'Also remove Copilot memory rule'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history "blog button"', 'Search processed cognition sessions'),
         '',

package/dist/cli/init-prompt.d.ts

@@ -1,8 +1,27 @@
-import type { IntegrationConfig, IntegrationName } from '../types/config.js';
+import type { DomainHint, IntegrationConfig, IntegrationName } from '../types/config.js';
 import type { InitIntegrationRecommendation } from './init-recommendations.js';
+import type { WorkspaceInfo } from './workspace-detection.js';
 export declare function shouldPromptForInitIntegrations(options: {
     explicitIntegrationsRequested: boolean;
     configuredIntegrations: Pick<IntegrationConfig, 'name'>[];
     interactive?: boolean;
 }): boolean;
 export declare function promptForInitIntegrations(recommendations: InitIntegrationRecommendation[]): Promise<IntegrationName[]>;
+export interface ScopeConfirmResult {
+    proceed: boolean;
+    narrowedInclude?: string[];
+}
+/**
+ * If file count exceeds threshold, ask user whether to proceed or narrow scope.
+ * For small repos, returns { proceed: true } without prompting.
+ */
+export declare function promptScopeConfirmation(fileCount: number, threshold?: number): Promise<ScopeConfirmResult>;
+export interface WorkspacePromptResult {
+    applyDomains: boolean;
+    domainHints?: Record<string, DomainHint>;
+}
+/**
+ * If a monorepo workspace is detected, offer to configure domain hints.
+ * For simple projects (no workspace detected), skips silently.
+ */
+export declare function promptWorkspaceSetup(info: WorkspaceInfo): Promise<WorkspacePromptResult>;

package/dist/cli/init-prompt.js

@@ -59,3 +59,60 @@ export async function promptForInitIntegrations(recommendations) {
 function isInteractiveTerminal() {
     return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
 }
+/**
+ * If file count exceeds threshold, ask user whether to proceed or narrow scope.
+ * For small repos, returns { proceed: true } without prompting.
+ */
+export async function promptScopeConfirmation(fileCount, threshold = 500) {
+    if (fileCount <= threshold || !isInteractiveTerminal()) {
+        return { proceed: true };
+    }
+    const action = await clack.select({
+        message: `Found ${fileCount.toLocaleString()} files in scope`,
+        options: [
+            { value: 'proceed', label: 'Continue with all files' },
+            {
+                value: 'narrow',
+                label: 'Narrow to src/ only',
+                hint: 'include: ["src/**"]',
+            },
+            { value: 'cancel', label: "Cancel — I'll edit config.yaml manually" },
+        ],
+    });
+    if (clack.isCancel(action) || action === 'cancel') {
+        return { proceed: false };
+    }
+    if (action === 'narrow') {
+        return { proceed: true, narrowedInclude: ['src/**'] };
+    }
+    return { proceed: true };
+}
+/**
+ * If a monorepo workspace is detected, offer to configure domain hints.
+ * For simple projects (no workspace detected), skips silently.
+ */
+export async function promptWorkspaceSetup(info) {
+    if (!isInteractiveTerminal()) {
+        return { applyDomains: false };
+    }
+    const packageNames = info.packages.map((p) => p.name).join(', ');
+    const action = await clack.select({
+        message: `Detected ${info.tool} workspace (${info.packages.length} packages: ${packageNames})`,
+        options: [
+            {
+                value: 'apply',
+                label: 'Configure domain hints from packages',
+                hint: 'context packs will prefer the active package',
+            },
+            { value: 'skip', label: 'Skip — scan everything flat' },
+        ],
+    });
+    if (clack.isCancel(action) || action === 'skip') {
+        return { applyDomains: false };
+    }
+    const hints = {};
+    for (const pkg of info.packages) {
+        hints[pkg.name] = { paths: [pkg.path + '/**'] };
+    }
+    return { applyDomains: true, domainHints: hints };
+}

package/dist/cli/workspace-detection.d.ts

@@ -0,0 +1,23 @@
+import type { DomainHint, KGraphConfig } from '../types/config.js';
+export interface WorkspaceInfo {
+    tool: string;
+    packages: WorkspacePackage[];
+}
+export interface WorkspacePackage {
+    name: string;
+    path: string;
+}
+/**
+ * Detect monorepo workspace tools and their packages.
+ * Returns null for simple single-package projects.
+ */
+export declare function detectWorkspaces(rootPath: string): Promise<WorkspaceInfo | null>;
+/**
+ * Convert detected workspace packages into domainHints.
+ */
+export declare function workspacesToDomainHints(info: WorkspaceInfo): Record<string, DomainHint>;
+/**
+ * Quick file count using fast-glob (no content read).
+ * Used to warn about large scopes before a full scan.
+ */
+export declare function countScopeFiles(rootPath: string, config: KGraphConfig): Promise<number>;

package/dist/cli/workspace-detection.js

@@ -0,0 +1,169 @@
+import fg from 'fast-glob';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildFastGlobIgnore, readGitignorePatterns, } from '../scanner/file-classifier.js';
+import { pathExists } from '../storage/kgraph-paths.js';
+/**
+ * Detect monorepo workspace tools and their packages.
+ * Returns null for simple single-package projects.
+ */
+export async function detectWorkspaces(rootPath) {
+    // pnpm
+    const pnpmPath = path.join(rootPath, 'pnpm-workspace.yaml');
+    if (await pathExists(pnpmPath)) {
+        const packages = await resolvePnpmPackages(rootPath, pnpmPath);
+        if (packages.length > 1)
+            return { tool: 'pnpm', packages };
+    }
+    // nx
+    const nxPath = path.join(rootPath, 'nx.json');
+    if (await pathExists(nxPath)) {
+        const packages = await resolveNxPackages(rootPath);
+        if (packages.length > 1)
+            return { tool: 'nx', packages };
+    }
+    // lerna
+    const lernaPath = path.join(rootPath, 'lerna.json');
+    if (await pathExists(lernaPath)) {
+        const packages = await resolveLernaPackages(rootPath, lernaPath);
+        if (packages.length > 1)
+            return { tool: 'lerna', packages };
+    }
+    // rush
+    const rushPath = path.join(rootPath, 'rush.json');
+    if (await pathExists(rushPath)) {
+        const packages = await resolveRushPackages(rootPath, rushPath);
+        if (packages.length > 1)
+            return { tool: 'rush', packages };
+    }
+    // npm/yarn workspaces (package.json)
+    const pkgPath = path.join(rootPath, 'package.json');
+    if (await pathExists(pkgPath)) {
+        const packages = await resolveNpmWorkspaces(rootPath, pkgPath);
+        if (packages.length > 1)
+            return { tool: 'npm', packages };
+    }
+    return null;
+}
+/**
+ * Convert detected workspace packages into domainHints.
+ */
+export function workspacesToDomainHints(info) {
+    const hints = {};
+    for (const pkg of info.packages) {
+        hints[pkg.name] = { paths: [pkg.path + '/**'] };
+    }
+    return hints;
+}
+/**
+ * Quick file count using fast-glob (no content read).
+ * Used to warn about large scopes before a full scan.
+ */
+export async function countScopeFiles(rootPath, config) {
+    const gitignorePatterns = await readGitignorePatterns(rootPath);
+    const allExcludes = [...config.exclude, ...gitignorePatterns];
+    const entries = await fg(config.include, {
+        cwd: rootPath,
+        dot: true,
+        onlyFiles: true,
+        unique: true,
+        ignore: buildFastGlobIgnore(allExcludes),
+        stats: false,
+    });
+    return entries.length;
+}
+// --- Resolvers ---
+async function resolvePnpmPackages(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        // Simple YAML parsing for packages: array
+        const lines = content.split(/\r?\n/);
+        const globs = [];
+        let inPackages = false;
+        for (const line of lines) {
+            if (/^packages:/i.test(line.trim())) {
+                inPackages = true;
+                continue;
+            }
+            if (inPackages) {
+                const match = line.match(/^\s+-\s+['"]?([^'"]+)['"]?\s*$/);
+                if (match) {
+                    globs.push(match[1]);
+                }
+                else if (/^\S/.test(line) && line.trim().length > 0) {
+                    break;
+                }
+            }
+        }
+        if (globs.length === 0)
+            globs.push('packages/*');
+        return await resolvePackageGlobs(rootPath, globs);
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveNxPackages(rootPath) {
+    // Nx projects live in common dirs
+    const candidates = ['apps/*', 'libs/*', 'packages/*'];
+    return await resolvePackageGlobs(rootPath, candidates);
+}
+async function resolveLernaPackages(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        const globs = Array.isArray(parsed.packages)
+            ? parsed.packages
+            : ['packages/*'];
+        return await resolvePackageGlobs(rootPath, globs);
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveRushPackages(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (!Array.isArray(parsed.projects))
+            return [];
+        return parsed.projects
+            .filter((p) => p.projectFolder)
+            .map((p) => ({
+            name: p.packageName || path.basename(p.projectFolder),
+            path: p.projectFolder,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function resolveNpmWorkspaces(rootPath, filePath) {
+    try {
+        const content = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(content);
+        const workspaces = parsed.workspaces;
+        if (!workspaces)
+            return [];
+        const globs = Array.isArray(workspaces)
+            ? workspaces
+            : (workspaces.packages ?? []);
+        if (globs.length === 0)
+            return [];
+        return await resolvePackageGlobs(rootPath, globs);
+    }
+    catch {
+        return [];
+    }
+}
+async function resolvePackageGlobs(rootPath, globs) {
+    const dirs = await fg(globs, {
+        cwd: rootPath,
+        onlyDirectories: true,
+        deep: 1,
+    });
+    return dirs.sort().map((dir) => ({
+        name: path.basename(dir),
+        path: dir.split(path.sep).join('/'),
+    }));
+}

package/dist/integrations/copilot-memory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve the Copilot memory-tool memories directory for the current OS.
+ * Returns undefined if the globalStorage root cannot be determined.
+ * Respects KGRAPH_COPILOT_MEMORY_DIR env override for testing.
+ */
+export declare function resolveCopilotMemoryDir(): string | undefined;
+/**
+ * Install the KGraph memory entry into the Copilot memory store.
+ * Returns true if written, false if the directory could not be resolved.
+ */
+export declare function installCopilotMemory(): Promise<boolean>;
+/**
+ * Remove the KGraph memory entry from the Copilot memory store.
+ * Returns true if removed or did not exist, false if the directory could not be resolved.
+ */
+export declare function removeCopilotMemory(): Promise<boolean>;
+/**
+ * Check whether the KGraph memory entry exists.
+ */
+export declare function hasCopilotMemory(): Promise<boolean>;
+/**
+ * Read the KGraph memory content, if it exists.
+ */
+export declare function readCopilotMemory(): Promise<string | undefined>;

package/dist/integrations/copilot-memory.js

@@ -0,0 +1,87 @@
+/**
+ * Manages the GitHub Copilot memory-tool entry for KGraph.
+ * Installs/removes a persistent preference so Copilot always follows the
+ * KGraph workflow in repos where KGraph is initialised.
+ */
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import path from 'node:path';
+import { pathExists } from '../storage/kgraph-paths.js';
+const MEMORY_FILE = 'kgraph.md';
+const MEMORY_CONTENT = `# KGraph
+
+- KGraph is installed. Follow the copilot-instructions.md and @kgraph agent for this repo.
+`;
+/**
+ * Resolve the Copilot memory-tool memories directory for the current OS.
+ * Returns undefined if the globalStorage root cannot be determined.
+ * Respects KGRAPH_COPILOT_MEMORY_DIR env override for testing.
+ */
+export function resolveCopilotMemoryDir() {
+    if (process.env['KGRAPH_COPILOT_MEMORY_DIR']) {
+        return process.env['KGRAPH_COPILOT_MEMORY_DIR'];
+    }
+    const home = homedir();
+    switch (platform()) {
+        case 'win32':
+            return path.join(process.env['APPDATA'] ?? path.join(home, 'AppData', 'Roaming'), 'Code', 'User', 'globalStorage', 'github.copilot-chat', 'memory-tool', 'memories');
+        case 'darwin':
+            return path.join(home, 'Library', 'Application Support', 'Code', 'User', 'globalStorage', 'github.copilot-chat', 'memory-tool', 'memories');
+        case 'linux':
+            return path.join(process.env['XDG_CONFIG_HOME'] ?? path.join(home, '.config'), 'Code', 'User', 'globalStorage', 'github.copilot-chat', 'memory-tool', 'memories');
+        default:
+            return undefined;
+    }
+}
+/**
+ * Install the KGraph memory entry into the Copilot memory store.
+ * Returns true if written, false if the directory could not be resolved.
+ */
+export async function installCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return false;
+    }
+    await mkdir(memoryDir, { recursive: true });
+    await writeFile(path.join(memoryDir, MEMORY_FILE), MEMORY_CONTENT, 'utf8');
+    return true;
+}
+/**
+ * Remove the KGraph memory entry from the Copilot memory store.
+ * Returns true if removed or did not exist, false if the directory could not be resolved.
+ */
+export async function removeCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return false;
+    }
+    const memoryFile = path.join(memoryDir, MEMORY_FILE);
+    if (await pathExists(memoryFile)) {
+        await rm(memoryFile, { force: true });
+    }
+    return true;
+}
+/**
+ * Check whether the KGraph memory entry exists.
+ */
+export async function hasCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return false;
+    }
+    return pathExists(path.join(memoryDir, MEMORY_FILE));
+}
+/**
+ * Read the KGraph memory content, if it exists.
+ */
+export async function readCopilotMemory() {
+    const memoryDir = resolveCopilotMemoryDir();
+    if (!memoryDir) {
+        return undefined;
+    }
+    const memoryFile = path.join(memoryDir, MEMORY_FILE);
+    if (!(await pathExists(memoryFile))) {
+        return undefined;
+    }
+    return readFile(memoryFile, 'utf8');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.32",
+  "version": "0.2.34",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {