aibridge-context 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BharatAdhana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# aibridge-context
+
+`aibridge-context` is a zero-config CLI and Node.js library that turns a project into an AI-readable workspace. It maintains a live `.ai-context/` folder, serves it locally, and can optionally sync context updates through git.
+
+Think of it as Git for AI context.
+
+## Features
+
+- Zero-config startup for Node.js projects
+- Debounced file watching powered by `chokidar`
+- Atomic writes to avoid corrupted JSON files
+- Local Express server for AI-friendly endpoints
+- Optional git auto-sync for `.ai-context/*`
+- Library exports for embedding in other tooling
+
+## Install
+
+```bash
+npm install
+```
+
+To use the local CLI in this repository:
+
+```bash
+npx aibridge init
+npx aibridge start
+```
+
+If published to npm, the package exposes the `aibridge` binary.
+
+`ai-context` is supported as a legacy alias.
+
+## Commands
+
+### `aibridge init`
+
+Creates `.ai-context/` and writes:
+
+- `state.json`
+- `brain.txt`
+- `context.md`
+- `changelog.json`
+- `config.json`
+
+### `aibridge start`
+
+Starts:
+
+- A debounced file watcher
+- A local Express server
+- Automatic state updates on add/change/delete events
+
+Default server port: `3333`
+
+### `aibridge update`
+
+Triggers a manual context refresh and optional git sync.
+
+## Generated files
+
+### `.ai-context/state.json`
+
+Tracks:
+
+- project name
+- version
+- last update time
+- change statistics
+- recent updates
+- project features
+- next steps
+
+### `.ai-context/brain.txt`
+
+Provides instructions any AI assistant should follow before responding.
+
+### `.ai-context/context.md`
+
+Stores a human-readable summary including:
+
+- project purpose
+- detected stack
+- AI usage guidance
+
+### `.ai-context/changelog.json`
+
+Stores historical change entries captured by the watcher.
+
+### `.ai-context/config.json`
+
+Default configuration:
+
+```json
+{
+  "port": 3333,
+  "debounceMs": 600,
+  "gitSync": {
+    "enabled": false,
+    "push": true,
+    "commitMessage": "auto: update AI context"
+  }
+}
+```
+
+## HTTP endpoints
+
+When `aibridge start` is running:
+
+- `GET /state.json`
+- `GET /brain.txt`
+- `GET /context.md`
+- `GET /changelog.json`
+
+## Example usage
+
+```bash
+npx aibridge init
+npx aibridge start
+```
+
+Then point your AI tool to:
+
+- `http://localhost:3333/state.json`
+- `http://localhost:3333/context.md`
+- `http://localhost:3333/changelog.json`
+- `http://localhost:3333/brain.txt`
+
+## Git sync
+
+Git sync is optional and controlled by `.ai-context/config.json`.
+
+Enable it like this:
+
+```json
+{
+  "gitSync": {
+    "enabled": true,
+    "push": true,
+    "commitMessage": "auto: update AI context"
+  }
+}
+```
+
+On every successful update, the tool will attempt to:
+
+```bash
+git add .ai-context
+git commit -m "auto: update AI context"
+git push
+```
+
+Failures are handled gracefully and will not stop the watcher or server.
+
+## Library usage
+
+```js
+const {
+  initProject,
+  startWatcher,
+  updateProjectState,
+  startServer,
+  syncContextToGit
+} = require('aibridge-context');
+```
+
+## Development notes
+
+- CommonJS is used for simplicity and broad compatibility.
+- The watcher ignores `node_modules`, `.git`, and `.ai-context`.
+- Writes are atomic via temporary-file rename.
+- Updates are debounced to reduce noisy file churn.

package/bin/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { initProject } = require('../core/init');
+const { startWatcher } = require('../core/watcher');
+const { loadRuntimeConfig, updateProjectState } = require('../core/stateManager');
+const { syncContextToGit } = require('../core/gitSync');
+const { startServer } = require('../server/server');
+const { createLogger } = require('../utils/logger');
+
+async function run() {
+  const logger = createLogger();
+  const projectRoot = process.cwd();
+  const command = process.argv[2];
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (command === '--version' || command === '-v') {
+    // eslint-disable-next-line global-require
+    const packageJson = require(path.join(__dirname, '..', 'package.json'));
+    console.log(packageJson.version);
+    return;
+  }
+
+  try {
+    if (command === 'init') {
+      await initProject(projectRoot, { logger });
+      return;
+    }
+
+    if (command === 'update') {
+      await initProject(projectRoot, { logger });
+      const config = await loadRuntimeConfig(projectRoot);
+      await updateProjectState(
+        projectRoot,
+        {
+          timestamp: new Date().toISOString(),
+          action: 'manual_update',
+          file: '.'
+        },
+        {
+          logger,
+          syncCallback: async () => syncContextToGit(projectRoot, config.gitSync, logger)
+        }
+      );
+      logger.info('Manual AI context update completed.');
+      return;
+    }
+
+    if (command === 'start') {
+      await initProject(projectRoot, { logger });
+      const config = await loadRuntimeConfig(projectRoot);
+      const serverHandle = await startServer({
+        projectRoot,
+        port: Number(process.env.AI_CONTEXT_PORT || config.port || 3333),
+        logger
+      });
+      const watcherHandle = await startWatcher(projectRoot, { logger });
+
+      const shutdown = async (signal) => {
+        logger.info(`Received ${signal}; shutting down cleanly.`);
+        await watcherHandle.close();
+        await serverHandle.close();
+        process.exit(0);
+      };
+
+      process.on('SIGINT', () => {
+        shutdown('SIGINT').catch((error) => {
+          logger.error(`Shutdown failed: ${error.message}`);
+          process.exit(1);
+        });
+      });
+
+      process.on('SIGTERM', () => {
+        shutdown('SIGTERM').catch((error) => {
+          logger.error(`Shutdown failed: ${error.message}`);
+          process.exit(1);
+        });
+      });
+
+      return;
+    }
+
+    logger.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exitCode = 1;
+  } catch (error) {
+    logger.error(error.stack || error.message);
+    process.exitCode = 1;
+  }
+}
+
+function printHelp() {
+  console.log(`aibridge-context
+
+Usage:
+  aibridge init
+  aibridge start
+  aibridge update
+
+Commands:
+  init    Create .ai-context and initialize AI context files
+  start   Start the watcher and local server on port 3333
+  update  Trigger a manual state update
+`);
+}
+
+run();

package/core/gitSync.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+
+async function runGit(projectRoot, args) {
+  return execFileAsync('git', args, {
+    cwd: projectRoot,
+    windowsHide: true
+  });
+}
+
+async function isGitRepository(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, '.git'))) {
+    return true;
+  }
+
+  try {
+    const result = await runGit(projectRoot, ['rev-parse', '--is-inside-work-tree']);
+    return result.stdout.trim() === 'true';
+  } catch (error) {
+    return false;
+  }
+}
+
+async function hasRemote(projectRoot) {
+  try {
+    const result = await runGit(projectRoot, ['remote']);
+    return result.stdout.trim().length > 0;
+  } catch (error) {
+    return false;
+  }
+}
+
+async function hasStagedContextChanges(projectRoot) {
+  try {
+    await runGit(projectRoot, ['diff', '--cached', '--quiet', '--', '.ai-context']);
+    return false;
+  } catch (error) {
+    return true;
+  }
+}
+
+async function syncContextToGit(projectRoot, config, logger) {
+  const settings = Object.assign(
+    {
+      enabled: false,
+      push: true,
+      commitMessage: 'auto: update AI context'
+    },
+    config
+  );
+
+  if (!settings.enabled) {
+    return {
+      skipped: true,
+      reason: 'disabled'
+    };
+  }
+
+  const repositoryReady = await isGitRepository(projectRoot);
+
+  if (!repositoryReady) {
+    if (logger) {
+      logger.warn('Git sync skipped because this project is not a git repository.');
+    }
+
+    return {
+      skipped: true,
+      reason: 'not_a_repo'
+    };
+  }
+
+  try {
+    await runGit(projectRoot, ['add', '.ai-context']);
+
+    const hasChanges = await hasStagedContextChanges(projectRoot);
+    if (!hasChanges) {
+      return {
+        skipped: true,
+        reason: 'no_changes'
+      };
+    }
+
+    await runGit(projectRoot, ['commit', '-m', settings.commitMessage]);
+
+    if (settings.push) {
+      const remoteExists = await hasRemote(projectRoot);
+
+      if (!remoteExists) {
+        if (logger) {
+          logger.warn('Git sync committed locally, but no remote is configured for push.');
+        }
+
+        return {
+          ok: true,
+          pushed: false
+        };
+      }
+
+      await runGit(projectRoot, ['push']);
+    }
+
+    if (logger) {
+      logger.info('Synced .ai-context changes to git.');
+    }
+
+    return {
+      ok: true,
+      pushed: Boolean(settings.push)
+    };
+  } catch (error) {
+    if (logger) {
+      logger.warn(`Git sync failed gracefully: ${error.message}`);
+    }
+
+    return {
+      ok: false,
+      error: error.message
+    };
+  }
+}
+
+module.exports = {
+  isGitRepository,
+  syncContextToGit
+};

package/core/init.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const path = require('path');
+const fsp = require('fs/promises');
+
+const {
+  createDefaultChangelog,
+  createDefaultState,
+  detectProjectMetadata,
+  ensureContextDirectory,
+  getContextPaths,
+  readJsonFile,
+  renderTemplate,
+  writeJsonAtomic,
+  writeTextAtomic
+} = require('./stateManager');
+
+async function initProject(projectRoot, options) {
+  const settings = Object.assign({ logger: null, force: false }, options);
+  const logger = settings.logger;
+  const contextDir = await ensureContextDirectory(projectRoot);
+  const paths = getContextPaths(projectRoot);
+  const metadata = detectProjectMetadata(projectRoot);
+  const templateDir = path.join(__dirname, '..', 'templates');
+  const stateTemplate = await fsp.readFile(path.join(templateDir, 'state.template.json'), 'utf8');
+  const changelogTemplate = await fsp.readFile(
+    path.join(templateDir, 'changelog.template.json'),
+    'utf8'
+  );
+  const brainTemplate = await fsp.readFile(path.join(templateDir, 'brain.template.txt'), 'utf8');
+  const contextTemplate = await fsp.readFile(path.join(templateDir, 'context.template.md'), 'utf8');
+  const existingConfig = await readJsonFile(paths.configFile, null);
+  const existingState = await readJsonFile(paths.stateFile, null);
+  const existingChangelog = await readJsonFile(paths.changelogFile, null);
+  const templateState = JSON.parse(stateTemplate);
+  const templateChangelog = JSON.parse(changelogTemplate);
+
+  const initialState = Object.assign({}, templateState, existingState || createDefaultState(projectRoot), {
+    project: metadata.project,
+    version: metadata.version
+  });
+
+  const initialContext = renderTemplate(contextTemplate, {
+    PROJECT_NAME: metadata.project,
+    PROJECT_VERSION: metadata.version,
+    STACK_LABEL: metadata.stackLabel,
+    PACKAGE_MANAGER: metadata.packageManager
+  });
+  const shouldWriteBrain = settings.force || !(await fileExists(paths.brainFile));
+  const shouldWriteContext = settings.force || !(await fileExists(paths.contextFile));
+
+  await writeJsonAtomic(paths.stateFile, initialState);
+  await writeJsonAtomic(paths.changelogFile, existingChangelog || templateChangelog || createDefaultChangelog());
+
+  if (shouldWriteBrain) {
+    await writeTextAtomic(paths.brainFile, brainTemplate);
+  }
+
+  if (shouldWriteContext) {
+    await writeTextAtomic(paths.contextFile, initialContext);
+  }
+
+  if (!existingConfig) {
+    await writeJsonAtomic(paths.configFile, {
+      port: 3333,
+      debounceMs: 600,
+      gitSync: {
+        enabled: false,
+        push: true,
+        commitMessage: 'auto: update AI context'
+      }
+    });
+  }
+
+  if (logger) {
+    logger.info(`Initialized AI context in ${contextDir}`);
+  }
+
+  return {
+    contextDir,
+    metadata
+  };
+}
+
+async function fileExists(filePath) {
+  try {
+    await fsp.access(filePath);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+module.exports = {
+  initProject
+};

package/core/stateManager.js

@@ -0,0 +1,327 @@
+'use strict';
+
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+
+const CONTEXT_DIR_NAME = '.ai-context';
+const MAX_RECENT_UPDATES = 50;
+const MAX_CHANGELOG_ENTRIES = 200;
+
+const DEFAULT_CONFIG = {
+  port: 3333,
+  debounceMs: 600,
+  gitSync: {
+    enabled: false,
+    push: true,
+    commitMessage: 'auto: update AI context'
+  }
+};
+
+function getContextPaths(projectRoot) {
+  const contextDir = path.join(projectRoot, CONTEXT_DIR_NAME);
+
+  return {
+    contextDir,
+    stateFile: path.join(contextDir, 'state.json'),
+    brainFile: path.join(contextDir, 'brain.txt'),
+    contextFile: path.join(contextDir, 'context.md'),
+    changelogFile: path.join(contextDir, 'changelog.json'),
+    configFile: path.join(contextDir, 'config.json')
+  };
+}
+
+function deepMerge(baseValue, overrideValue) {
+  if (Array.isArray(baseValue) || Array.isArray(overrideValue)) {
+    return overrideValue === undefined ? baseValue : overrideValue;
+  }
+
+  if (isObject(baseValue) && isObject(overrideValue)) {
+    const merged = Object.assign({}, baseValue);
+
+    for (const [key, value] of Object.entries(overrideValue)) {
+      merged[key] = deepMerge(baseValue[key], value);
+    }
+
+    return merged;
+  }
+
+  return overrideValue === undefined ? baseValue : overrideValue;
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function detectProjectMetadata(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const packageManager = detectPackageManager(projectRoot);
+  const metadata = {
+    project: path.basename(projectRoot),
+    version: '0.1.0',
+    stackLabel: 'Node.js project',
+    packageManager
+  };
+
+  if (!fs.existsSync(packageJsonPath)) {
+    return metadata;
+  }
+
+  try {
+    const rawPackage = fs.readFileSync(packageJsonPath, 'utf8');
+    const parsedPackage = JSON.parse(rawPackage);
+    const dependencies = Object.assign(
+      {},
+      parsedPackage.dependencies || {},
+      parsedPackage.devDependencies || {}
+    );
+
+    metadata.project = parsedPackage.name || metadata.project;
+    metadata.version = parsedPackage.version || metadata.version;
+    metadata.stackLabel = describeStack(dependencies);
+    metadata.packageManager = packageManager;
+  } catch (error) {
+    metadata.stackLabel = 'Node.js project';
+  }
+
+  return metadata;
+}
+
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+
+  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) {
+    return 'yarn';
+  }
+
+  return 'npm';
+}
+
+function describeStack(dependencies) {
+  if (dependencies.next) {
+    return 'Node.js + Next.js';
+  }
+
+  if (dependencies.react) {
+    return 'Node.js + React';
+  }
+
+  if (dependencies.express) {
+    return 'Node.js + Express';
+  }
+
+  if (dependencies.typescript) {
+    return 'Node.js + TypeScript';
+  }
+
+  return 'Node.js project';
+}
+
+async function ensureContextDirectory(projectRoot) {
+  const { contextDir } = getContextPaths(projectRoot);
+  await fsp.mkdir(contextDir, { recursive: true });
+  return contextDir;
+}
+
+async function readJsonFile(filePath, fallbackValue) {
+  try {
+    const raw = await fsp.readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (error) {
+    return fallbackValue;
+  }
+}
+
+async function writeJsonAtomic(filePath, value) {
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  await writeTextAtomic(filePath, content);
+}
+
+async function writeTextAtomic(filePath, content) {
+  const tempFilePath = `${filePath}.tmp`;
+  await fsp.writeFile(tempFilePath, content, 'utf8');
+  await fsp.rename(tempFilePath, filePath);
+}
+
+function createDefaultState(projectRoot) {
+  const metadata = detectProjectMetadata(projectRoot);
+
+  return {
+    project: metadata.project,
+    version: metadata.version,
+    last_updated: new Date(0).toISOString(),
+    stats: {
+      files_changed: 0,
+      last_file: ''
+    },
+    recent_updates: [],
+    features: [],
+    next_steps: []
+  };
+}
+
+function createDefaultChangelog() {
+  return {
+    entries: []
+  };
+}
+
+function renderTemplate(template, variables) {
+  return Object.entries(variables).reduce((accumulator, [key, value]) => {
+    const safeValue = value == null ? '' : String(value);
+    return accumulator.split(`{{${key}}}`).join(safeValue);
+  }, template);
+}
+
+async function loadRuntimeConfig(projectRoot) {
+  const { configFile } = getContextPaths(projectRoot);
+  const userConfig = await readJsonFile(configFile, {});
+  return deepMerge(DEFAULT_CONFIG, userConfig);
+}
+
+async function updateProjectState(projectRoot, changeEvent, options) {
+  const settings = Object.assign(
+    {
+      logger: null,
+      syncCallback: null
+    },
+    options
+  );
+  const logger = settings.logger;
+  const contextPaths = getContextPaths(projectRoot);
+  const state = await readJsonFile(contextPaths.stateFile, createDefaultState(projectRoot));
+  const changelog = await readJsonFile(contextPaths.changelogFile, createDefaultChangelog());
+  const normalizedEvents = Array.isArray(changeEvent) ? changeEvent : [changeEvent];
+  const validEvents = normalizedEvents.filter(Boolean);
+
+  if (validEvents.length === 0) {
+    return state;
+  }
+
+  const latestEvent = validEvents[validEvents.length - 1];
+  const timestamp = latestEvent.timestamp || new Date().toISOString();
+  const recentUpdates = Array.isArray(state.recent_updates) ? state.recent_updates.slice() : [];
+  const changelogEntries = Array.isArray(changelog.entries) ? changelog.entries.slice() : [];
+
+  for (const event of validEvents) {
+    const normalizedEvent = {
+      timestamp: event.timestamp || timestamp,
+      action: event.action || 'updated',
+      file: event.file || ''
+    };
+
+    recentUpdates.push(normalizedEvent);
+    changelogEntries.push(normalizedEvent);
+  }
+
+  const nextState = {
+    project: state.project || createDefaultState(projectRoot).project,
+    version: state.version || createDefaultState(projectRoot).version,
+    last_updated: timestamp,
+    stats: {
+      files_changed: (state.stats && typeof state.stats.files_changed === 'number'
+        ? state.stats.files_changed
+        : 0) + validEvents.length,
+      last_file: latestEvent.file || ''
+    },
+    recent_updates: recentUpdates.slice(-MAX_RECENT_UPDATES),
+    features: Array.isArray(state.features) ? state.features : [],
+    next_steps: Array.isArray(state.next_steps) ? state.next_steps : []
+  };
+
+  const nextChangelog = {
+    entries: changelogEntries.slice(-MAX_CHANGELOG_ENTRIES)
+  };
+
+  await writeJsonAtomic(contextPaths.stateFile, nextState);
+  await writeJsonAtomic(contextPaths.changelogFile, nextChangelog);
+
+  if (logger) {
+    logger.debug(`Updated AI context for ${validEvents.length} change(s).`);
+  }
+
+  if (typeof settings.syncCallback === 'function') {
+    await settings.syncCallback();
+  }
+
+  return nextState;
+}
+
+function createDebouncedStateUpdater(projectRoot, options) {
+  const settings = Object.assign(
+    {
+      debounceMs: DEFAULT_CONFIG.debounceMs,
+      logger: null,
+      syncCallback: null
+    },
+    options
+  );
+
+  let timer = null;
+  let pendingEvents = [];
+  let activeFlush = Promise.resolve();
+
+  async function flush() {
+    if (pendingEvents.length === 0) {
+      return;
+    }
+
+    const events = pendingEvents.slice();
+    pendingEvents = [];
+
+    activeFlush = activeFlush.then(() =>
+      updateProjectState(projectRoot, events, {
+        logger: settings.logger,
+        syncCallback: settings.syncCallback
+      })
+    );
+
+    await activeFlush;
+  }
+
+  return {
+    enqueue(event) {
+      pendingEvents.push(event);
+
+      if (timer) {
+        clearTimeout(timer);
+      }
+
+      timer = setTimeout(() => {
+        timer = null;
+        flush().catch((error) => {
+          if (settings.logger) {
+            settings.logger.error(`Failed to flush AI context updates: ${error.message}`);
+          }
+        });
+      }, settings.debounceMs);
+    },
+    async flushNow() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+
+      await flush();
+    }
+  };
+}
+
+module.exports = {
+  CONTEXT_DIR_NAME,
+  DEFAULT_CONFIG,
+  createDebouncedStateUpdater,
+  createDefaultChangelog,
+  createDefaultState,
+  detectProjectMetadata,
+  ensureContextDirectory,
+  getContextPaths,
+  loadRuntimeConfig,
+  readJsonFile,
+  renderTemplate,
+  updateProjectState,
+  writeJsonAtomic,
+  writeTextAtomic
+};

package/core/watcher.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const path = require('path');
+const chokidar = require('chokidar');
+
+const { syncContextToGit } = require('./gitSync');
+const {
+  createDebouncedStateUpdater,
+  loadRuntimeConfig,
+  updateProjectState
+} = require('./stateManager');
+
+function normalizeFilePath(projectRoot, filePath) {
+  return path.relative(projectRoot, filePath).split(path.sep).join('/');
+}
+
+async function startWatcher(projectRoot, options) {
+  const settings = Object.assign({ logger: null }, options);
+  const logger = settings.logger;
+  const config = await loadRuntimeConfig(projectRoot);
+  const syncCallback = async () =>
+    syncContextToGit(projectRoot, config.gitSync, logger);
+  const debouncedUpdater = createDebouncedStateUpdater(projectRoot, {
+    debounceMs: config.debounceMs,
+    logger,
+    syncCallback
+  });
+
+  const watcher = chokidar.watch(projectRoot, {
+    ignored: [
+      /(^|[\\/])\.git([\\/]|$)/,
+      /(^|[\\/])node_modules([\\/]|$)/,
+      /(^|[\\/])\.ai-context([\\/]|$)/
+    ],
+    ignoreInitial: true,
+    persistent: true
+  });
+
+  function handleEvent(action, filePath) {
+    const normalizedPath = normalizeFilePath(projectRoot, filePath);
+
+    if (!normalizedPath || normalizedPath.startsWith('.ai-context/')) {
+      return;
+    }
+
+    if (logger) {
+      logger.info(`${action} ${normalizedPath}`);
+    }
+
+    debouncedUpdater.enqueue({
+      timestamp: new Date().toISOString(),
+      action,
+      file: normalizedPath
+    });
+  }
+
+  watcher.on('add', (filePath) => handleEvent('add', filePath));
+  watcher.on('change', (filePath) => handleEvent('change', filePath));
+  watcher.on('unlink', (filePath) => handleEvent('delete', filePath));
+  watcher.on('error', (error) => {
+    if (logger) {
+      logger.error(`Watcher error: ${error.message}`);
+    }
+  });
+
+  await updateProjectState(
+    projectRoot,
+    {
+      timestamp: new Date().toISOString(),
+      action: 'watcher_started',
+      file: '.'
+    },
+    {
+      logger,
+      syncCallback
+    }
+  );
+
+  return {
+    watcher,
+    async close() {
+      await debouncedUpdater.flushNow();
+      await watcher.close();
+    },
+    async flush() {
+      await debouncedUpdater.flushNow();
+    }
+  };
+}
+
+module.exports = {
+  startWatcher
+};

package/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { initProject } = require('./core/init');
+const { startWatcher } = require('./core/watcher');
+const { updateProjectState, loadRuntimeConfig } = require('./core/stateManager');
+const { startServer } = require('./server/server');
+const { syncContextToGit } = require('./core/gitSync');
+
+module.exports = {
+  initProject,
+  startWatcher,
+  updateProjectState,
+  loadRuntimeConfig,
+  startServer,
+  syncContextToGit
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "aibridge-context",
+  "version": "1.0.1",
+  "description": "Zero-config CLI and library for generating AI-readable project context, serving it locally, and syncing it with git.",
+  "main": "./index.js",
+  "bin": {
+    "aibridge": "./bin/cli.js",
+    "ai-context": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "core",
+    "server",
+    "templates",
+    "utils",
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node ./bin/cli.js start",
+    "init:context": "node ./bin/cli.js init",
+    "update:context": "node ./bin/cli.js update"
+  },
+  "keywords": [
+    "ai",
+    "context",
+    "cli",
+    "watcher",
+    "express",
+    "developer-tools",
+    "git"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "express": "^5.1.0"
+  }
+}

package/server/routes.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const path = require('path');
+const express = require('express');
+const { getContextPaths } = require('../core/stateManager');
+
+function createRoutes(projectRoot, logger) {
+  const router = express.Router();
+  const paths = getContextPaths(projectRoot);
+
+  function sendFile(filePath, contentType) {
+    return function routeHandler(request, response) {
+      response.type(contentType);
+      response.sendFile(
+        path.resolve(filePath),
+        {
+          dotfiles: 'allow'
+        },
+        (error) => {
+          if (!error) {
+            return;
+          }
+
+          if (logger) {
+            logger.error(`Failed to serve ${request.path}: ${error.message}`);
+          }
+
+          if (response.headersSent) {
+            return;
+          }
+
+          response.status(error.statusCode || 500).json({
+            error: 'Unable to read AI context file.'
+          });
+        }
+      );
+    };
+  }
+
+  router.get('/state.json', sendFile(paths.stateFile, 'application/json'));
+  router.get('/brain.txt', sendFile(paths.brainFile, 'text/plain'));
+  router.get('/context.md', sendFile(paths.contextFile, 'text/markdown'));
+  router.get('/changelog.json', sendFile(paths.changelogFile, 'application/json'));
+
+  return router;
+}
+
+module.exports = {
+  createRoutes
+};

package/server/server.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const express = require('express');
+const { createRoutes } = require('./routes');
+
+async function startServer(options) {
+  const settings = Object.assign(
+    {
+      port: 3333,
+      projectRoot: process.cwd(),
+      logger: null
+    },
+    options
+  );
+  const app = express();
+
+  app.disable('x-powered-by');
+  app.use(createRoutes(settings.projectRoot, settings.logger));
+
+  const server = await new Promise((resolve, reject) => {
+    const instance = app.listen(settings.port, () => resolve(instance));
+    instance.on('error', reject);
+  });
+
+  if (settings.logger) {
+    settings.logger.info(`AI context server is running on http://localhost:${settings.port}`);
+  }
+
+  return {
+    app,
+    server,
+    async close() {
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+
+          resolve();
+        });
+      });
+    }
+  };
+}
+
+module.exports = {
+  startServer
+};

package/templates/brain.template.txt

@@ -0,0 +1,9 @@
+You are assisting in this project.
+
+Before responding:
+
+1. Read /state.json
+2. Read /context.md
+3. Read /changelog.json
+
+Use them as source of truth.

package/templates/changelog.template.json

@@ -0,0 +1,3 @@
+{
+  "entries": []
+}

package/templates/context.template.md

@@ -0,0 +1,18 @@
+# AI Context for {{PROJECT_NAME}}
+
+## Project purpose
+
+This project is tracked by aibridge-context so AI tools can reason about the current codebase state with minimal setup.
+
+## Stack detection
+
+- Detected stack: {{STACK_LABEL}}
+- Package manager: {{PACKAGE_MANAGER}}
+- Project version: {{PROJECT_VERSION}}
+
+## Instructions for AI usage
+
+1. Read `/state.json` before making changes.
+2. Read `/changelog.json` to understand recent edits.
+3. Use `/context.md` as the durable project summary.
+4. Treat these files as the current source of truth unless the repository clearly indicates otherwise.

package/templates/state.template.json

@@ -0,0 +1,12 @@
+{
+  "project": "",
+  "version": "",
+  "last_updated": "1970-01-01T00:00:00.000Z",
+  "stats": {
+    "files_changed": 0,
+    "last_file": ""
+  },
+  "recent_updates": [],
+  "features": [],
+  "next_steps": []
+}

package/utils/logger.js

@@ -0,0 +1,46 @@
+'use strict';
+
+function createLogger(options) {
+  const settings = Object.assign({ level: 'info' }, options);
+  const levels = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40
+  };
+
+  function shouldLog(level) {
+    return levels[level] >= levels[settings.level];
+  }
+
+  function format(level, message) {
+    return `[ai-context] ${new Date().toISOString()} ${level.toUpperCase()} ${message}`;
+  }
+
+  return {
+    debug(message) {
+      if (shouldLog('debug')) {
+        console.debug(format('debug', message));
+      }
+    },
+    info(message) {
+      if (shouldLog('info')) {
+        console.log(format('info', message));
+      }
+    },
+    warn(message) {
+      if (shouldLog('warn')) {
+        console.warn(format('warn', message));
+      }
+    },
+    error(message) {
+      if (shouldLog('error')) {
+        console.error(format('error', message));
+      }
+    }
+  };
+}
+
+module.exports = {
+  createLogger
+};