aibridge-context 1.1.0 → 1.2.0

package/README.md

@@ -4,6 +4,12 @@
 
 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
@@ -12,6 +18,14 @@ 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:
@@ -60,7 +74,7 @@ If published to npm, the package exposes the `aibridge` binary.
 
 `ai-context` is supported as a legacy alias.
 
-## Use With AI
+## Using With AI
 
 After enabling GitHub sync, use:
 
@@ -70,6 +84,13 @@ 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
@@ -155,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

@@ -34,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;
     }
 
@@ -59,6 +64,19 @@ async function run() {
 
     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) {
@@ -88,11 +106,23 @@ async function run() {
     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) => {
@@ -131,17 +161,14 @@ async function run() {
 function printHelp() {
   console.log(`aibridge-context
 
-Usage:
-  aibridge init
-  aibridge link-github
-  aibridge start
-  aibridge update
-
 Commands:
-  init    Create .ai-context and initialize AI context files
-  link-github  Connect a GitHub remote and enable public AI sync
-  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.
 `);
 }
 
@@ -152,11 +179,29 @@ async function promptForRepoUrl() {
   });
 
   try {
-    const response = await rl.question('GitHub repository URL: ');
+    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

@@ -74,6 +74,13 @@ 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);
 
@@ -93,6 +100,7 @@ async function ensureGitInitialized(projectRoot, logger) {
         throw error;
       }
     }
+
     await ensureMainBranch(projectRoot);
 
     if (logger) {
@@ -104,7 +112,7 @@ async function ensureGitInitialized(projectRoot, logger) {
     };
   } catch (error) {
     if (logger) {
-      logger.warn(`Git initialization failed gracefully: ${error.message}`);
+      logger.warn(`Git initialization failed gracefully: ${formatGitError(error)}`);
     }
 
     return {
@@ -156,7 +164,7 @@ function logMissingRemoteInstructions(logger) {
     return;
   }
 
-  logger.warn('No GitHub remote detected.');
+  logger.warn('GitHub remote not found.');
   logger.info('Run:');
   logger.info('git remote add origin <repo-url>');
   logger.info('git push -u origin main');
@@ -167,10 +175,15 @@ function logPublicAiEndpoints(logger, urls) {
     return;
   }
 
-  logger.info('Public AI endpoint:');
+  logger.info('\u2705 AI Context Synced Successfully');
+  logger.info('\u{1F310} Public AI Endpoint:');
   logger.info(urls.stateUrl);
-  logger.info('Use this with AI:');
+  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) {
@@ -189,16 +202,13 @@ async function linkGithubRepository(projectRoot, repoUrl, logger) {
     await ensureMainBranch(projectRoot);
     await runGit(projectRoot, ['push', '-u', 'origin', 'main']);
 
-    const urls = buildPublicAiUrls(normalizedRepoUrl, 'main');
-    logPublicAiEndpoints(logger, urls);
-
     return {
       ok: true,
-      urls
+      urls: buildPublicAiUrls(normalizedRepoUrl, 'main')
     };
   } catch (error) {
     if (logger) {
-      logger.warn(`GitHub link failed gracefully: ${error.message}`);
+      logger.warn(`GitHub link failed gracefully: ${formatGitError(error)}`);
     }
 
     return {
@@ -211,7 +221,7 @@ async function linkGithubRepository(projectRoot, repoUrl, logger) {
 async function syncContextToGit(projectRoot, config, logger) {
   const settings = Object.assign(
     {
-      enabled: true,
+      enabled: false,
       push: true,
       commitMessage: 'auto: update AI context',
       remote: 'origin',
@@ -285,11 +295,6 @@ async function syncContextToGit(projectRoot, config, logger) {
     }
 
     const urls = buildPublicAiUrls(remoteUrl, branchName);
-
-    if (logger) {
-      logger.info('Synced .ai-context changes to git.');
-    }
-
     logPublicAiEndpoints(logger, urls);
 
     return {
@@ -299,7 +304,7 @@ async function syncContextToGit(projectRoot, config, logger) {
     };
   } catch (error) {
     if (logger) {
-      logger.warn(`Git sync failed gracefully: ${error.message}`);
+      logger.warn(`Git sync failed gracefully: ${formatGitError(error)}`);
     }
 
     return {

package/core/init.js

@@ -18,7 +18,15 @@ const {
 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);
@@ -36,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,
@@ -62,18 +71,18 @@ async function initProject(projectRoot, options) {
     await writeTextAtomic(paths.contextFile, initialContext);
   }
 
-  await updateRuntimeConfig(
-    projectRoot,
-    existingConfig
-      ? null
-      : {
-          gitSync: {
-            enabled: true,
-            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);
 
@@ -87,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

@@ -12,7 +12,7 @@ const DEFAULT_CONFIG = {
   port: 3333,
   debounceMs: 600,
   gitSync: {
-    enabled: true,
+    enabled: false,
     push: true,
     commitMessage: 'auto: update AI context',
     remote: 'origin',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aibridge-context",
-  "version": "1.1.0",
+  "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": {

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,