aibridge-context 1.0.3 → 1.2.0

package/README.md

@@ -4,13 +4,28 @@
 
 Think of it as Git for AI context.
 
+## ⚠️ Public AI Access Warning
+
+When GitHub sync is enabled, your project context becomes publicly accessible via a URL.
+
+Do NOT use this tool with sensitive data.
+
 ## Quick Start
 
 ```bash
 npx aibridge-context init
+npx aibridge-context link-github
 npx aibridge-context start
 ```
 
+## How It Works
+
+1. Tracks project changes
+2. Generates structured AI context
+3. Syncs to GitHub (optional)
+4. Creates a public URL
+5. AI tools read this URL for context
+
 ## Usage
 
 This package exposes a CLI command:
@@ -29,6 +44,7 @@ After installing globally, you can use:
 
 ```bash
 aibridge init
+aibridge link-github
 ```
 
 ## Features
@@ -50,6 +66,7 @@ To use the local CLI in this repository:
 
 ```bash
 npx aibridge-context init
+npx aibridge-context link-github
 npx aibridge-context start
 ```
 
@@ -57,6 +74,37 @@ If published to npm, the package exposes the `aibridge` binary.
 
 `ai-context` is supported as a legacy alias.
 
+## Using With AI
+
+After enabling GitHub sync, use:
+
+```text
+https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/state.json
+```
+
+This URL always returns the latest project state.
+
+Paste this into any AI:
+
+```text
+Use this as source of truth:
+https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/state.json
+```
+
+You can also share:
+
+```text
+https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/brain.txt
+```
+
+Typical flow:
+
+```bash
+npx aibridge-context init
+aibridge link-github
+npx aibridge-context start
+```
+
 ## Commands
 
 ### `aibridge init`
@@ -83,6 +131,10 @@ Default server port: `3333`
 
 Triggers a manual context refresh and optional git sync.
 
+### `aibridge link-github`
+
+Prompts for a GitHub repository URL, links `origin`, pushes `main`, saves the repo URL to `.ai-context/config.json`, and enables public AI sync output.
+
 ## Generated files
 
 ### `.ai-context/state.json`
@@ -124,7 +176,10 @@ Default configuration:
   "gitSync": {
     "enabled": false,
     "push": true,
-    "commitMessage": "auto: update AI context"
+    "commitMessage": "auto: update AI context",
+    "remote": "origin",
+    "branch": "main",
+    "repoUrl": ""
   }
 }
 ```

package/bin/cli.js

@@ -2,10 +2,16 @@
 'use strict';
 
 const path = require('path');
+const readline = require('readline/promises');
+const { stdin, stdout } = require('process');
 const { initProject } = require('../core/init');
 const { startWatcher } = require('../core/watcher');
-const { loadRuntimeConfig, updateProjectState } = require('../core/stateManager');
-const { syncContextToGit } = require('../core/gitSync');
+const {
+  loadRuntimeConfig,
+  updateProjectState,
+  updateRuntimeConfig
+} = require('../core/stateManager');
+const { linkGithubRepository, syncContextToGit } = require('../core/gitSync');
 const { startServer } = require('../server/server');
 const { createLogger } = require('../utils/logger');
 
@@ -28,7 +34,12 @@ async function run() {
 
   try {
     if (command === 'init') {
-      await initProject(projectRoot, { logger });
+      await initProject(projectRoot, {
+        logger,
+        requestPublicSyncConsent: true,
+        promptForPublicSyncConsent: () =>
+          promptYesNo('[aibridge] Do you want to enable GitHub sync and public AI access? (y/n) ')
+      });
       return;
     }
 
@@ -51,14 +62,67 @@ async function run() {
       return;
     }
 
+    if (command === 'link-github') {
+      await initProject(projectRoot, { logger });
+      logger.warn('You are about to connect a GitHub repository.');
+      logger.info('This will:');
+      logger.info('* Push .ai-context to GitHub');
+      logger.info('* Make project context publicly accessible');
+      logger.info('* Allow AI systems to read your project state');
+
+      const shouldContinue = await promptYesNo('[aibridge] Continue? (y/n) ');
+
+      if (!shouldContinue) {
+        logger.info('GitHub linking cancelled. Public sync remains unchanged.');
+        return;
+      }
+
+      const repoUrl = process.argv[3] || (await promptForRepoUrl());
+
+      if (!repoUrl) {
+        logger.error('A GitHub repository URL is required.');
+        process.exitCode = 1;
+        return;
+      }
+
+      const nextConfig = await updateRuntimeConfig(projectRoot, {
+        gitSync: {
+          enabled: true,
+          push: true,
+          repoUrl: repoUrl.trim()
+        }
+      });
+      const linkResult = await linkGithubRepository(projectRoot, repoUrl.trim(), logger);
+
+      if (!linkResult.ok) {
+        process.exitCode = 1;
+        return;
+      }
+
+      await syncContextToGit(projectRoot, nextConfig.gitSync, logger);
+      return;
+    }
+
     if (command === 'start') {
       await initProject(projectRoot, { logger });
       const config = await loadRuntimeConfig(projectRoot);
+      const port = Number(process.env.AI_CONTEXT_PORT || config.port || 3333);
+      logger.info('Watching project for changes...');
       const serverHandle = await startServer({
         projectRoot,
-        port: Number(process.env.AI_CONTEXT_PORT || config.port || 3333),
+        port,
         logger
       });
+      logger.info(`Local server: http://localhost:${port}`);
+
+      if (config.gitSync.enabled) {
+        logger.info('Auto-sync to GitHub is ENABLED');
+        logger.warn('Changes will be publicly available to AI');
+      } else {
+        logger.info('GitHub sync is DISABLED');
+        logger.info('Data is only available locally');
+      }
+
       const watcherHandle = await startWatcher(projectRoot, { logger });
 
       const shutdown = async (signal) => {
@@ -97,16 +161,47 @@ async function run() {
 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
+  init           Initialize AI context (with optional public sync)
+  link-github    Connect GitHub for public AI access
+  start          Start watcher and server
+  update         Manually update context
+
+Description:
+  This tool creates an AI-readable version of your project and can expose it via a public URL for AI tools.
 `);
 }
 
+async function promptForRepoUrl() {
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout
+  });
+
+  try {
+    const response = await rl.question('[aibridge] GitHub repository URL: ');
+    return response.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptYesNo(question) {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    return false;
+  }
+
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout
+  });
+
+  try {
+    const response = await rl.question(question);
+    return response.trim().toLowerCase() === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
 run();

package/core/gitSync.js

@@ -29,13 +29,42 @@ async function isGitRepository(projectRoot) {
 
 async function hasRemote(projectRoot) {
   try {
-    const result = await runGit(projectRoot, ['remote']);
+    const result = await runGit(projectRoot, ['remote', 'get-url', 'origin']);
     return result.stdout.trim().length > 0;
   } catch (error) {
     return false;
   }
 }
 
+async function getRemoteOriginUrl(projectRoot) {
+  try {
+    const result = await runGit(projectRoot, ['remote', 'get-url', 'origin']);
+    return result.stdout.trim();
+  } catch (error) {
+    return '';
+  }
+}
+
+async function getCurrentBranch(projectRoot) {
+  try {
+    const result = await runGit(projectRoot, ['branch', '--show-current']);
+    return result.stdout.trim();
+  } catch (error) {
+    return '';
+  }
+}
+
+async function ensureMainBranch(projectRoot) {
+  const currentBranch = await getCurrentBranch(projectRoot);
+
+  if (currentBranch === 'main') {
+    return 'main';
+  }
+
+  await runGit(projectRoot, ['branch', '-M', 'main']);
+  return 'main';
+}
+
 async function hasStagedContextChanges(projectRoot) {
   try {
     await runGit(projectRoot, ['diff', '--cached', '--quiet', '--', '.ai-context']);
@@ -45,12 +74,159 @@ async function hasStagedContextChanges(projectRoot) {
   }
 }
 
+function formatGitError(error) {
+  const stderr = typeof error.stderr === 'string' ? error.stderr.trim() : '';
+  const stdout = typeof error.stdout === 'string' ? error.stdout.trim() : '';
+  const message = stderr || stdout || error.message || 'Unknown git error.';
+  return message.split('\n')[0];
+}
+
+async function ensureGitInitialized(projectRoot, logger) {
+  const repositoryReady = await isGitRepository(projectRoot);
+
+  if (repositoryReady) {
+    return {
+      initialized: false
+    };
+  }
+
+  try {
+    await runGit(projectRoot, ['init']);
+    await runGit(projectRoot, ['add', '.']);
+    try {
+      await runGit(projectRoot, ['commit', '-m', 'initial commit']);
+    } catch (error) {
+      if (!/nothing to commit/i.test(error.stderr || error.message)) {
+        throw error;
+      }
+    }
+
+    await ensureMainBranch(projectRoot);
+
+    if (logger) {
+      logger.info('Git initialized');
+    }
+
+    return {
+      initialized: true
+    };
+  } catch (error) {
+    if (logger) {
+      logger.warn(`Git initialization failed gracefully: ${formatGitError(error)}`);
+    }
+
+    return {
+      initialized: false,
+      error: error.message
+    };
+  }
+}
+
+function parseGitHubRepo(repoUrl) {
+  if (!repoUrl) {
+    return null;
+  }
+
+  const cleanedUrl = repoUrl.trim().replace(/\.git$/, '');
+  let match = cleanedUrl.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)$/i);
+
+  if (!match) {
+    match = cleanedUrl.match(/^git@github\.com:([^/]+)\/([^/]+)$/i);
+  }
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    owner: match[1],
+    repo: match[2]
+  };
+}
+
+function buildPublicAiUrls(repoUrl, branch) {
+  const parsedRepo = parseGitHubRepo(repoUrl);
+
+  if (!parsedRepo) {
+    return null;
+  }
+
+  const baseUrl = `https://raw.githubusercontent.com/${parsedRepo.owner}/${parsedRepo.repo}/${branch}`;
+
+  return {
+    stateUrl: `${baseUrl}/.ai-context/state.json`,
+    brainUrl: `${baseUrl}/.ai-context/brain.txt`
+  };
+}
+
+function logMissingRemoteInstructions(logger) {
+  if (!logger) {
+    return;
+  }
+
+  logger.warn('GitHub remote not found.');
+  logger.info('Run:');
+  logger.info('git remote add origin <repo-url>');
+  logger.info('git push -u origin main');
+}
+
+function logPublicAiEndpoints(logger, urls) {
+  if (!logger || !urls) {
+    return;
+  }
+
+  logger.info('\u2705 AI Context Synced Successfully');
+  logger.info('\u{1F310} Public AI Endpoint:');
+  logger.info(urls.stateUrl);
+  logger.info('\u{1F9E0} AI Instructions Endpoint:');
+  logger.info(urls.brainUrl);
+  logger.warn('\u26A0\uFE0F IMPORTANT:');
+  logger.warn('This data is PUBLIC. Anyone with this link can access it.');
+  logger.info('\u{1F916} To use with AI:');
+  logger.info('"Use this URL as the source of truth for my project."');
+}
+
+async function linkGithubRepository(projectRoot, repoUrl, logger) {
+  const normalizedRepoUrl = repoUrl.trim();
+  await ensureGitInitialized(projectRoot, logger);
+
+  try {
+    const existingRemoteUrl = await getRemoteOriginUrl(projectRoot);
+
+    if (!existingRemoteUrl) {
+      await runGit(projectRoot, ['remote', 'add', 'origin', normalizedRepoUrl]);
+    } else if (existingRemoteUrl !== normalizedRepoUrl) {
+      await runGit(projectRoot, ['remote', 'set-url', 'origin', normalizedRepoUrl]);
+    }
+
+    await ensureMainBranch(projectRoot);
+    await runGit(projectRoot, ['push', '-u', 'origin', 'main']);
+
+    return {
+      ok: true,
+      urls: buildPublicAiUrls(normalizedRepoUrl, 'main')
+    };
+  } catch (error) {
+    if (logger) {
+      logger.warn(`GitHub link failed gracefully: ${formatGitError(error)}`);
+    }
+
+    return {
+      ok: false,
+      error: error.message
+    };
+  }
+}
+
 async function syncContextToGit(projectRoot, config, logger) {
   const settings = Object.assign(
     {
       enabled: false,
       push: true,
-      commitMessage: 'auto: update AI context'
+      commitMessage: 'auto: update AI context',
+      remote: 'origin',
+      branch: 'main',
+      repoUrl: ''
     },
     config
   );
@@ -76,10 +252,25 @@ async function syncContextToGit(projectRoot, config, logger) {
   }
 
   try {
-    await runGit(projectRoot, ['add', '.ai-context']);
+    const branchName = await ensureMainBranch(projectRoot);
+    const remoteUrl = (await getRemoteOriginUrl(projectRoot)) || settings.repoUrl;
+
+    if (!remoteUrl) {
+      logMissingRemoteInstructions(logger);
+      return {
+        skipped: true,
+        reason: 'missing_remote'
+      };
+    }
+
+    await runGit(projectRoot, ['add', '-f', '.ai-context']);
 
     const hasChanges = await hasStagedContextChanges(projectRoot);
     if (!hasChanges) {
+      if (logger) {
+        logger.info('No .ai-context changes to sync.');
+      }
+
       return {
         skipped: true,
         reason: 'no_changes'
@@ -92,9 +283,7 @@ async function syncContextToGit(projectRoot, config, logger) {
       const remoteExists = await hasRemote(projectRoot);
 
       if (!remoteExists) {
-        if (logger) {
-          logger.warn('Git sync committed locally, but no remote is configured for push.');
-        }
+        logMissingRemoteInstructions(logger);
 
         return {
           ok: true,
@@ -102,20 +291,20 @@ async function syncContextToGit(projectRoot, config, logger) {
         };
       }
 
-      await runGit(projectRoot, ['push']);
+      await runGit(projectRoot, ['push', '-u', settings.remote || 'origin', branchName]);
     }
 
-    if (logger) {
-      logger.info('Synced .ai-context changes to git.');
-    }
+    const urls = buildPublicAiUrls(remoteUrl, branchName);
+    logPublicAiEndpoints(logger, urls);
 
     return {
       ok: true,
-      pushed: Boolean(settings.push)
+      pushed: Boolean(settings.push),
+      urls
     };
   } catch (error) {
     if (logger) {
-      logger.warn(`Git sync failed gracefully: ${error.message}`);
+      logger.warn(`Git sync failed gracefully: ${formatGitError(error)}`);
     }
 
     return {
@@ -126,6 +315,10 @@ async function syncContextToGit(projectRoot, config, logger) {
 }
 
 module.exports = {
+  buildPublicAiUrls,
+  ensureGitInitialized,
+  getRemoteOriginUrl,
   isGitRepository,
+  linkGithubRepository,
   syncContextToGit
 };

package/core/init.js

@@ -11,12 +11,22 @@ const {
   getContextPaths,
   readJsonFile,
   renderTemplate,
+  updateRuntimeConfig,
   writeJsonAtomic,
   writeTextAtomic
 } = require('./stateManager');
+const { ensureGitInitialized } = require('./gitSync');
 
 async function initProject(projectRoot, options) {
-  const settings = Object.assign({ logger: null, force: false }, options);
+  const settings = Object.assign(
+    {
+      logger: null,
+      force: false,
+      requestPublicSyncConsent: false,
+      promptForPublicSyncConsent: null
+    },
+    options
+  );
   const logger = settings.logger;
   const contextDir = await ensureContextDirectory(projectRoot);
   const paths = getContextPaths(projectRoot);
@@ -34,6 +44,7 @@ async function initProject(projectRoot, options) {
   const existingChangelog = await readJsonFile(paths.changelogFile, null);
   const templateState = JSON.parse(stateTemplate);
   const templateChangelog = JSON.parse(changelogTemplate);
+  let enableGitSync = false;
 
   const initialState = Object.assign({}, templateState, existingState || createDefaultState(projectRoot), {
     project: metadata.project,
@@ -60,18 +71,21 @@ async function initProject(projectRoot, options) {
     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 (!existingConfig && settings.requestPublicSyncConsent) {
+    enableGitSync = await requestPublicSyncConsent(
+      logger,
+      settings.promptForPublicSyncConsent
+    );
   }
 
+  await updateRuntimeConfig(projectRoot, existingConfig ? null : {
+    gitSync: {
+      enabled: enableGitSync
+    }
+  });
+
+  await ensureGitInitialized(projectRoot, logger);
+
   if (logger) {
     logger.info(`Initialized AI context in ${contextDir}`);
   }
@@ -82,6 +96,29 @@ async function initProject(projectRoot, options) {
   };
 }
 
+async function requestPublicSyncConsent(logger, promptForPublicSyncConsent) {
+  if (logger) {
+    logger.warn('This tool can make parts of your project publicly accessible for AI tools.');
+    logger.info('It will:');
+    logger.info('* Track project changes');
+    logger.info('* Generate AI-readable context');
+    logger.info('* Optionally sync to GitHub');
+    logger.info('* Create a PUBLIC URL accessible by AI systems');
+    logger.warn('WARNING:');
+    logger.warn('Anyone with the URL can read this data.');
+  }
+
+  if (typeof promptForPublicSyncConsent !== 'function') {
+    if (logger) {
+      logger.info('GitHub sync will remain disabled until you explicitly enable it.');
+    }
+
+    return false;
+  }
+
+  return Boolean(await promptForPublicSyncConsent());
+}
+
 async function fileExists(filePath) {
   try {
     await fsp.access(filePath);

package/core/stateManager.js

@@ -14,7 +14,10 @@ const DEFAULT_CONFIG = {
   gitSync: {
     enabled: false,
     push: true,
-    commitMessage: 'auto: update AI context'
+    commitMessage: 'auto: update AI context',
+    remote: 'origin',
+    branch: 'main',
+    repoUrl: ''
   }
 };
 
@@ -181,6 +184,16 @@ async function loadRuntimeConfig(projectRoot) {
   return deepMerge(DEFAULT_CONFIG, userConfig);
 }
 
+async function updateRuntimeConfig(projectRoot, updates) {
+  const { configFile } = getContextPaths(projectRoot);
+  const currentConfig = await readJsonFile(configFile, {});
+  const mergedCurrentConfig = deepMerge(DEFAULT_CONFIG, currentConfig);
+  const nextConfig = deepMerge(mergedCurrentConfig, updates || {});
+
+  await writeJsonAtomic(configFile, nextConfig);
+  return nextConfig;
+}
+
 async function updateProjectState(projectRoot, changeEvent, options) {
   const settings = Object.assign(
     {
@@ -321,6 +334,7 @@ module.exports = {
   loadRuntimeConfig,
   readJsonFile,
   renderTemplate,
+  updateRuntimeConfig,
   updateProjectState,
   writeJsonAtomic,
   writeTextAtomic

package/index.js

@@ -2,15 +2,28 @@
 
 const { initProject } = require('./core/init');
 const { startWatcher } = require('./core/watcher');
-const { updateProjectState, loadRuntimeConfig } = require('./core/stateManager');
+const {
+  updateProjectState,
+  loadRuntimeConfig,
+  updateRuntimeConfig
+} = require('./core/stateManager');
 const { startServer } = require('./server/server');
-const { syncContextToGit } = require('./core/gitSync');
+const {
+  buildPublicAiUrls,
+  ensureGitInitialized,
+  linkGithubRepository,
+  syncContextToGit
+} = require('./core/gitSync');
 
 module.exports = {
+  buildPublicAiUrls,
+  ensureGitInitialized,
   initProject,
+  linkGithubRepository,
   startWatcher,
   updateProjectState,
   loadRuntimeConfig,
+  updateRuntimeConfig,
   startServer,
   syncContextToGit
 };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "aibridge-context",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "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-context": "./bin/cli.js",
     "aibridge": "./bin/cli.js",
     "ai-context": "./bin/cli.js"
   },

package/server/server.js

@@ -22,10 +22,6 @@ async function startServer(options) {
     instance.on('error', reject);
   });
 
-  if (settings.logger) {
-    settings.logger.info(`AI context server is running on http://localhost:${settings.port}`);
-  }
-
   return {
     app,
     server,