@aakrit512/gatekeep 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# Gatekeep
+
+A local, browser-based coding agent for reviewing and exploring projects with an OpenAI-compatible chat model. It runs on your machine, keeps project metadata and chat history in a local SQLite database, and gives the model a small set of read/review tools for inspecting a repository.
+
+## What It Does
+
+- Starts a local web UI for saved projects and project chat.
+- Initializes a project by creating `docs/intro.md` inside the target repository.
+- Stores project metadata, chat messages, tool traces, token usage, and estimated costs locally.
+- Lets you run provider/config/project doctor checks from the browser.
+- Supports OpenAI-compatible providers through `AI_API_KEY`, `AI_BASE_URL`, and `MODEL_NAME`.
+
+## Quick Start
+
+```sh
+pnpm install
+pnpm run build
+pnpm link --global
+gatekeep start --project /path/to/repo
+```
+
+The UI starts at:
+
+```txt
+http://127.0.0.1:9808
+```
+
+You can also launch it for the current directory:
+
+```sh
+gatekeep start --project .
+```
+
+After publishing to npm, install and run it globally:
+
+```sh
+npm install --global @aakrit512/gatekeep
+gatekeep start
+```
+
+## Configuration
+
+Create a local `.env` file or configure values in the browser UI:
+
+```sh
+AI_API_KEY=your_api_key
+AI_BASE_URL=https://api.openai.com/v1
+MODEL_NAME=gpt-4o
+```
+
+Project metadata and chat history are stored in your OS app-support/config directory, not in the project being reviewed. API keys are masked in UI responses and are not stored in the project database.
+
+## Folder Structure
+
+```txt
+.
+├── src/
+│   ├── ai/          OpenAI client setup, chat completion calls, context trimming, summarization helpers.
+│   ├── cli/         User config storage and validation/doctor checks.
+│   ├── functions/   Tool definitions and local tool execution used by the agent.
+│   ├── prompts/     System and initialization prompts that guide repository review behavior.
+│   ├── ui/          Local HTTP server, project database layer, and browser-agent workflow.
+│   ├── cli.ts       CLI entry point that starts the web UI.
+│   └── config.ts    Shared runtime configuration defaults and helpers.
+├── ui/
+│   └── app.html     Browser UI document, styles, and client-side JavaScript.
+├── package.json     Package metadata, scripts, dependencies, and publish file list.
+├── tsconfig.json    TypeScript settings for development type checks.
+├── tsconfig.build.json
+│                  TypeScript build settings for emitted `dist/` output.
+├── pnpm-lock.yaml   Locked dependency graph.
+└── pnpm-workspace.yaml
+                   pnpm workspace declaration.
+```
+
+`dist/`, `node_modules/`, local `.env` files, and SQLite runtime files are generated locally and intentionally ignored by git.
+
+## Scripts
+
+```sh
+pnpm run start      # Run the TypeScript CLI directly with tsx.
+pnpm run build      # Compile TypeScript into dist/.
+pnpm pack           # Build and create the installable npm tarball.
+pnpm run typecheck  # Type-check without emitting files.
+```
+
+## Development Notes
+
+The browser UI is intentionally plain HTML so the package stays small and the server can serve it without a frontend build step. The server injects the curated fallback model list into `ui/app.html` at request time.
+
+The agent tools are scoped to repository inspection and project initialization. During normal review/chat workflows, the model is guided to inspect files and diffs before answering.

package/dist/ai/chat.js

@@ -0,0 +1,33 @@
+import { getClient, getModelName } from './openAiClient.js';
+import { tools } from '../functions/toolDefinitions.js';
+import { preprocessMessages, estimateTokens } from './contextUtils.js';
+import { numericEnv } from '../config.js';
+const MAX_OUTPUT_TOKENS = numericEnv('AGENT_MAX_OUTPUT_TOKENS', 4096);
+const MIN_OUTPUT_TOKENS = 512;
+const TOKEN_BUDGET = numericEnv('AGENT_TOKEN_BUDGET', 32000);
+// Exact prompt token count reported by the provider on the last call.
+// null on the first call — falls back to the chars/4 estimate until the API tells us the real number.
+let lastPromptTokens = null;
+function computeMaxTokens(messages) {
+    // Prefer the exact value from the previous API response over the rough estimate.
+    // The next call will have slightly more tokens (new messages appended), so this is a
+    // conservative lower-bound — safe to use as the baseline for the remaining budget.
+    const inputTokens = lastPromptTokens ?? estimateTokens(messages);
+    const remaining = TOKEN_BUDGET - inputTokens;
+    return Math.max(MIN_OUTPUT_TOKENS, Math.min(MAX_OUTPUT_TOKENS, remaining));
+}
+export async function createChatCompletion(messages) {
+    const processed = preprocessMessages(messages);
+    const response = await getClient().chat.completions.create({
+        model: getModelName(),
+        messages: processed,
+        tools,
+        tool_choice: 'auto',
+        max_tokens: computeMaxTokens(processed),
+    });
+    // Store exact provider-reported prompt token count for the next call.
+    if (response.usage?.prompt_tokens) {
+        lastPromptTokens = response.usage.prompt_tokens;
+    }
+    return response;
+}

package/dist/ai/contextUtils.js

@@ -0,0 +1,79 @@
+import { numericEnv } from '../config.js';
+// Strategy 1: per-message character caps (tool results capped tighter since they can be huge)
+const MAX_MESSAGE_CHARS = numericEnv('AGENT_MAX_MESSAGE_CHARS', 8000);
+const MAX_TOOL_RESULT_CHARS = numericEnv('AGENT_MAX_TOOL_RESULT_CHARS', 4000);
+function truncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, maxChars)}\n… [truncated ${text.length - maxChars} chars]`;
+}
+// Strategy 5: normalize whitespace to eliminate noise before it reaches the model
+function normalizeText(text) {
+    return text
+        .replace(/[^\S\n]+$/gm, '') // strip trailing spaces per line
+        .replace(/\n{3,}/g, '\n\n') // collapse 3+ blank lines to 2
+        .trim();
+}
+function transformContent(content, fn) {
+    if (typeof content === 'string')
+        return fn(content);
+    if (Array.isArray(content)) {
+        return content.map(part => part.type === 'text' && typeof part.text === 'string'
+            ? { ...part, text: fn(part.text) }
+            : part);
+    }
+    return content;
+}
+function normalizeMessage(msg) {
+    // Keep system messages pristine — they carry the reviewer's critical instructions
+    if (msg.role === 'system' || !msg.content)
+        return msg;
+    return { ...msg, content: transformContent(msg.content, normalizeText) };
+}
+function truncateMessage(msg) {
+    if (msg.role === 'system' || !msg.content)
+        return msg;
+    const limit = msg.role === 'tool' ? MAX_TOOL_RESULT_CHARS : MAX_MESSAGE_CHARS;
+    return { ...msg, content: transformContent(msg.content, t => truncate(t, limit)) };
+}
+// Strategy 2/5: deduplicate identical tool results across history (e.g. the same file read twice)
+function deduplicateToolResults(messages) {
+    const seen = new Set();
+    return messages.map(msg => {
+        if (msg.role !== 'tool')
+            return msg;
+        const key = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+        if (seen.has(key)) {
+            return { ...msg, content: '[duplicate tool result omitted — identical to a prior call]' };
+        }
+        seen.add(key);
+        return msg;
+    });
+}
+/**
+ * Preprocessing pipeline applied to the full message history before each API call.
+ *   1. Normalize whitespace  (collapse blank lines, strip trailing spaces)
+ *   2. Deduplicate tool results  (avoid re-sending identical file reads)
+ *   3. Truncate oversized messages  (tool results capped tighter than user/assistant turns)
+ *
+ * System messages are never modified — they contain critical reviewer instructions.
+ */
+export function preprocessMessages(messages) {
+    return deduplicateToolResults(messages.map(normalizeMessage)).map(truncateMessage);
+}
+/** Rough token estimate: ~4 chars per token (used for dynamic max_tokens computation). */
+export function estimateTokens(messages) {
+    let chars = 0;
+    for (const msg of messages) {
+        if (typeof msg.content === 'string') {
+            chars += msg.content.length;
+        }
+        else if (Array.isArray(msg.content)) {
+            for (const part of msg.content) {
+                if (part.type === 'text' && part.text)
+                    chars += part.text.length;
+            }
+        }
+    }
+    return Math.ceil(chars / 4);
+}

package/dist/ai/openAiClient.js

@@ -0,0 +1,72 @@
+import { OpenAI } from 'openai';
+import { withHeadroom } from 'headroom-ai/openai';
+import { HeadroomClient } from 'headroom-ai';
+import { floatEnv, getAppConfig, numericEnv } from '../config.js';
+let cachedClient = null;
+let cachedClientKey = '';
+export function getModelName() {
+    return getAppConfig().model;
+}
+const headroomConfig = {
+    cacheAligner: {
+        enabled: true,
+        datePatterns: [
+            'Today is \\w+ \\d+, \\d{4}',
+            'Current date: .*',
+            'Current time: .*',
+            'Session ID: [a-f0-9-]+',
+        ],
+        normalizeWhitespace: true,
+        collapseBlankLines: true,
+    },
+    cacheOptimizer: {
+        enabled: true,
+        autoDetectProvider: true,
+        minCacheableTokens: numericEnv('AGENT_MIN_CACHEABLE_TOKENS', 1024),
+    },
+    intelligentContext: {
+        enabled: true,
+        keepSystem: true,
+        keepLastTurns: numericEnv('AGENT_IC_KEEP_LAST_TURNS', 6),
+        outputBufferTokens: numericEnv('AGENT_IC_OUTPUT_BUFFER_TOKENS', 4000),
+        useImportanceScoring: true,
+        scoringWeights: {
+            recency: 0.2,
+            semanticSimilarity: 0.2,
+            toinImportance: 0.25,
+            errorIndicator: 0.15,
+            forwardReference: 0.15,
+            tokenDensity: 0.05,
+        },
+        toinIntegration: true,
+        recencyDecayRate: floatEnv('AGENT_RECENCY_DECAY_RATE', 0.1),
+        compressThreshold: floatEnv('AGENT_COMPRESS_THRESHOLD', 0.1),
+    },
+    rollingWindow: {
+        enabled: true,
+        keepSystem: true,
+        keepLastTurns: numericEnv('AGENT_RW_KEEP_LAST_TURNS', 3),
+        outputBufferTokens: numericEnv('AGENT_RW_OUTPUT_BUFFER_TOKENS', 4000),
+    },
+};
+export function getClient() {
+    const config = getAppConfig();
+    const clientKey = `${config.apiKey}:${config.baseUrl}:${config.model}`;
+    if (cachedClient && cachedClientKey === clientKey) {
+        return cachedClient;
+    }
+    const baseClient = new OpenAI({
+        apiKey: config.apiKey,
+        baseURL: config.baseUrl,
+    });
+    cachedClient = withHeadroom(baseClient, {
+        model: config.model,
+        tokenBudget: numericEnv('AGENT_TOKEN_BUDGET', 32000),
+        client: new HeadroomClient({
+            config: headroomConfig,
+            fallback: true,
+        }),
+    });
+    cachedClientKey = clientKey;
+    return cachedClient;
+}

package/dist/ai/summarizer.js

@@ -0,0 +1,65 @@
+import { getClient, getModelName } from './openAiClient.js';
+import { preprocessMessages } from './contextUtils.js';
+import { numericEnv } from '../config.js';
+// Number of recent messages (not turn-pairs) to keep verbatim for conversational continuity.
+// Generous multiplier: each turn can be user + assistant + N tool messages.
+const KEEP_RECENT_MESSAGES = numericEnv('AGENT_SUMMARY_KEEP_RECENT_MESSAGES', 12);
+const SUMMARIZE_SYSTEM_PROMPT = `You are a conversation compressor for a read-only code reviewer agent.
+Your output replaces the full conversation history to cut token usage — it must preserve every piece of actionable context a reviewer needs to continue work seamlessly.
+
+Include ALL of the following that appear in the history:
+- **Files examined**: path, inferred purpose, key structural findings
+- **Tool calls and outcomes**: what was called, what was returned (material facts only)
+- **Review findings issued**: severity, file:line, concise description, recommended fix
+- **Reviewer decisions and positions**: architectural opinions, standards violations flagged
+- **Unresolved items**: files not yet examined, pending follow-ups, open questions
+
+Format rules:
+- Use bullet points under clear ## headings
+- Be exhaustive on facts; ruthless on prose — omit filler, summaries of summaries, and pleasantries
+- Output ONLY the summary body — no preamble, no sign-off`;
+/**
+ * Compresses conversation history by summarising older turns with the AI model.
+ *
+ * Preservation order:
+ *   1. All original system messages (reviewer persona + project intro) — never touched
+ *   2. A generated [Condensed History] system message replacing older turns
+ *   3. The most recent AGENT_SUMMARY_KEEP_RECENT_MESSAGES messages verbatim
+ *
+ * If summarisation fails (network error, empty response, etc.) the original history
+ * is returned unchanged — callers should not crash on summarisation failure.
+ */
+export async function summarizeHistory(messages) {
+    const systemMessages = messages.filter(m => m.role === 'system');
+    const turnMessages = messages.filter(m => m.role !== 'system');
+    const toSummarize = turnMessages.slice(0, -KEEP_RECENT_MESSAGES);
+    const recentMessages = turnMessages.slice(-KEEP_RECENT_MESSAGES);
+    // Not enough older history to justify an API call
+    if (toSummarize.length < 4)
+        return messages;
+    const payload = [
+        { role: 'system', content: SUMMARIZE_SYSTEM_PROMPT },
+        ...preprocessMessages(toSummarize),
+        { role: 'user', content: 'Produce the condensed history now.' },
+    ];
+    let summaryText;
+    try {
+        const response = await getClient().chat.completions.create({
+            model: getModelName(),
+            messages: payload,
+            max_tokens: numericEnv('AGENT_SUMMARY_MAX_TOKENS', 2048),
+        });
+        summaryText = response.choices[0].message.content?.trim() ?? '';
+        if (!summaryText)
+            return messages; // empty response — degrade gracefully
+    }
+    catch {
+        // Summarisation failed — return original history unchanged
+        return messages;
+    }
+    const summaryMessage = {
+        role: 'system',
+        content: `[Condensed History — replaces ${toSummarize.length} earlier messages]\n\n${summaryText}`,
+    };
+    return [...systemMessages, summaryMessage, ...recentMessages];
+}

package/dist/cli/configStore.js

@@ -0,0 +1,68 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { cleanString, DEFAULT_BASE_URL, DEFAULT_MODEL, DEFAULT_PROVIDER, } from '../config.js';
+export const CONFIG_KEYS = ['provider', 'apiKey', 'model', 'baseUrl'];
+export function appConfigDir() {
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'gatekeep');
+    }
+    if (process.platform === 'win32') {
+        return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'gatekeep');
+    }
+    return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'gatekeep');
+}
+export function getConfigPath() {
+    return path.join(appConfigDir(), 'config.json');
+}
+function isProvider(value) {
+    return value === DEFAULT_PROVIDER;
+}
+function normalizeConfig(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    const raw = value;
+    const config = {};
+    if (isProvider(raw.provider))
+        config.provider = raw.provider;
+    if (typeof raw.apiKey === 'string')
+        config.apiKey = raw.apiKey;
+    if (typeof raw.model === 'string')
+        config.model = raw.model;
+    if (typeof raw.baseUrl === 'string')
+        config.baseUrl = raw.baseUrl;
+    return config;
+}
+export function readUserConfig() {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath))
+        return {};
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    return normalizeConfig(JSON.parse(raw));
+}
+export function writeUserConfig(config) {
+    const configPath = getConfigPath();
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    const minimal = normalizeConfig(config);
+    fs.writeFileSync(configPath, `${JSON.stringify(minimal, null, 2)}\n`, {
+        encoding: 'utf-8',
+        mode: 0o600,
+    });
+}
+export function resolveConfig(flags, stored = readUserConfig()) {
+    return {
+        provider: stored.provider || DEFAULT_PROVIDER,
+        apiKey: cleanString(flags.apiKey) || cleanString(process.env.AI_API_KEY) || cleanString(stored.apiKey) || '',
+        model: cleanString(flags.model) || cleanString(process.env.MODEL_NAME) || cleanString(stored.model) || DEFAULT_MODEL,
+        baseUrl: cleanString(flags.baseUrl) || cleanString(process.env.AI_BASE_URL) || cleanString(stored.baseUrl) || DEFAULT_BASE_URL,
+    };
+}
+export function setConfigValue(config, key, value) {
+    if (key === 'provider') {
+        if (!isProvider(value)) {
+            throw new Error(`Unsupported provider "${value}". Only "${DEFAULT_PROVIDER}" is supported.`);
+        }
+        return { ...config, provider: value };
+    }
+    return { ...config, [key]: value };
+}

package/dist/cli/validation.js

@@ -0,0 +1,45 @@
+import * as fs from 'fs';
+import * as path from 'path';
+export function maskSecret(value) {
+    if (!value)
+        return '(not set)';
+    const visible = value.slice(-4);
+    const prefix = value.includes('-') ? `${value.split('-')[0]}-` : '';
+    return `${prefix}...${visible}`;
+}
+export function validateConfig(config) {
+    const errors = [];
+    if (!config.apiKey.trim()) {
+        errors.push('API key is missing. Add it in the web UI settings.');
+    }
+    if (!config.model.trim()) {
+        errors.push('Model is missing. Add it in the web UI settings.');
+    }
+    try {
+        const url = new URL(config.baseUrl);
+        if (!['http:', 'https:'].includes(url.protocol)) {
+            errors.push('Base URL must start with http:// or https://.');
+        }
+    }
+    catch {
+        errors.push(`Base URL is invalid: ${config.baseUrl}`);
+    }
+    return errors;
+}
+export function validateProject(project) {
+    const errors = [];
+    const resolved = path.resolve(project);
+    if (!fs.existsSync(resolved)) {
+        errors.push(`Project path does not exist: ${resolved}`);
+    }
+    else if (!fs.statSync(resolved).isDirectory()) {
+        errors.push(`Project path is not a directory: ${resolved}`);
+    }
+    return errors;
+}
+export function validateNodeRuntime() {
+    const major = Number(process.versions.node.split('.')[0]);
+    if (Number.isFinite(major) && major >= 18)
+        return [];
+    return [`Node.js 18 or newer is required. Current version: ${process.versions.node}`];
+}

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { startUiServer } from './ui/server.js';
+const LEGACY_COMMANDS = new Set(['ui', 'init', 'config', 'doctor', 'run']);
+const START_COMMAND = 'start';
+function printUsage() {
+    console.log(`gatekeep
+
+Starts the local web UI.
+
+Usage:
+  gatekeep start [--project PATH] [--port PORT] [--host HOST]
+  gatekeep [--project PATH] [--port PORT] [--host HOST]
+
+All setup, config, doctor checks, initialization, and chat workflows are available in the browser UI.
+`);
+}
+function parseArgs(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h' || arg === 'help') {
+            options.help = true;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            if (arg === START_COMMAND)
+                continue;
+            if (LEGACY_COMMANDS.has(arg))
+                continue;
+            if (!options.project)
+                options.project = arg;
+            continue;
+        }
+        const [rawKey, inlineValue] = arg.slice(2).split('=', 2);
+        const value = inlineValue ?? argv[++index];
+        if (!value || value.startsWith('--')) {
+            throw new Error(`Flag --${rawKey} requires a value.`);
+        }
+        if (rawKey === 'project') {
+            options.project = value;
+        }
+        else if (rawKey === 'port') {
+            const port = Number(value);
+            if (!Number.isInteger(port) || port <= 0) {
+                throw new Error(`Invalid port "${value}".`);
+            }
+            options.port = port;
+        }
+        else if (rawKey === 'host') {
+            options.host = value;
+        }
+        else {
+            throw new Error(`Unknown flag --${rawKey}. Use --help for web launcher options.`);
+        }
+    }
+    return options;
+}
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printUsage();
+        return;
+    }
+    await startUiServer({
+        project: options.project,
+        port: options.port,
+        host: options.host,
+    });
+}
+main().catch(error => {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/config.js

@@ -0,0 +1,36 @@
+export const DEFAULT_PROVIDER = 'openai-compatible';
+export const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+export const DEFAULT_MODEL = 'gpt-4o';
+export function cleanString(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/** Parse a strictly-positive integer/float from an environment variable. */
+export function numericEnv(name, fallback) {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+/** Parse any finite float from an environment variable (allows 0 and negatives). */
+export function floatEnv(name, fallback) {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) ? v : fallback;
+}
+function readEnvConfig() {
+    return {
+        provider: DEFAULT_PROVIDER,
+        apiKey: cleanString(process.env.AI_API_KEY) || '',
+        baseUrl: cleanString(process.env.AI_BASE_URL) || DEFAULT_BASE_URL,
+        model: cleanString(process.env.MODEL_NAME) || DEFAULT_MODEL,
+    };
+}
+let activeConfig = readEnvConfig();
+export function configureApp(config) {
+    activeConfig = {
+        ...activeConfig,
+        ...config,
+        provider: config.provider ?? activeConfig.provider,
+    };
+}
+export function getAppConfig() {
+    return activeConfig;
+}

package/dist/functions/toolCallHandler.js

@@ -0,0 +1,25 @@
+import { executeTool } from './toolExecutor.js';
+function parseToolArguments(rawArguments) {
+    try {
+        const parsed = JSON.parse(rawArguments);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function isFunctionToolCall(toolCall) {
+    return toolCall.type === 'function';
+}
+export function runToolCall(toolCall) {
+    const args = parseToolArguments(toolCall.function.arguments);
+    const content = executeTool(toolCall.function.name, args);
+    return {
+        args,
+        message: {
+            role: 'tool',
+            tool_call_id: toolCall.id,
+            content,
+        },
+    };
+}