aibridge-context 1.0.3 → 1.1.0

package/README.md

@@ -8,6 +8,7 @@ Think of it as Git for AI context.
 
 ```bash
 npx aibridge-context init
+npx aibridge-context link-github
 npx aibridge-context start
 ```
 
@@ -29,6 +30,7 @@ After installing globally, you can use:
 
 ```bash
 aibridge init
+aibridge link-github
 ```
 
 ## Features
@@ -50,6 +52,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 +60,30 @@ If published to npm, the package exposes the `aibridge` binary.
 
 `ai-context` is supported as a legacy alias.
 
+## Use 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.
+
+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 +110,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`

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');
 
@@ -51,6 +57,34 @@ async function run() {
       return;
     }
 
+    if (command === 'link-github') {
+      await initProject(projectRoot, { logger });
+      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);
@@ -99,14 +133,30 @@ function printHelp() {
 
 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
 `);
 }
 
+async function promptForRepoUrl() {
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout
+  });
+
+  try {
+    const response = await rl.question('GitHub repository URL: ');
+    return response.trim();
+  } 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,149 @@ async function hasStagedContextChanges(projectRoot) {
   }
 }
 
+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: ${error.message}`);
+    }
+
+    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('No GitHub remote detected.');
+  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('Public AI endpoint:');
+  logger.info(urls.stateUrl);
+  logger.info('Use this with AI:');
+  logger.info(urls.brainUrl);
+}
+
+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']);
+
+    const urls = buildPublicAiUrls(normalizedRepoUrl, 'main');
+    logPublicAiEndpoints(logger, urls);
+
+    return {
+      ok: true,
+      urls
+    };
+  } catch (error) {
+    if (logger) {
+      logger.warn(`GitHub link failed gracefully: ${error.message}`);
+    }
+
+    return {
+      ok: false,
+      error: error.message
+    };
+  }
+}
+
 async function syncContextToGit(projectRoot, config, logger) {
   const settings = Object.assign(
     {
-      enabled: false,
+      enabled: true,
       push: true,
-      commitMessage: 'auto: update AI context'
+      commitMessage: 'auto: update AI context',
+      remote: 'origin',
+      branch: 'main',
+      repoUrl: ''
     },
     config
   );
@@ -76,10 +242,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 +273,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,16 +281,21 @@ async function syncContextToGit(projectRoot, config, logger) {
         };
       }
 
-      await runGit(projectRoot, ['push']);
+      await runGit(projectRoot, ['push', '-u', settings.remote || 'origin', branchName]);
     }
 
+    const urls = buildPublicAiUrls(remoteUrl, branchName);
+
     if (logger) {
       logger.info('Synced .ai-context changes to git.');
     }
 
+    logPublicAiEndpoints(logger, urls);
+
     return {
       ok: true,
-      pushed: Boolean(settings.push)
+      pushed: Boolean(settings.push),
+      urls
     };
   } catch (error) {
     if (logger) {
@@ -126,6 +310,10 @@ async function syncContextToGit(projectRoot, config, logger) {
 }
 
 module.exports = {
+  buildPublicAiUrls,
+  ensureGitInitialized,
+  getRemoteOriginUrl,
   isGitRepository,
+  linkGithubRepository,
   syncContextToGit
 };

package/core/init.js

@@ -11,9 +11,11 @@ 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);
@@ -60,17 +62,20 @@ 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'
-      }
-    });
-  }
+  await updateRuntimeConfig(
+    projectRoot,
+    existingConfig
+      ? null
+      : {
+          gitSync: {
+            enabled: true,
+            push: true,
+            commitMessage: 'auto: update AI context'
+          }
+        }
+  );
+
+  await ensureGitInitialized(projectRoot, logger);
 
   if (logger) {
     logger.info(`Initialized AI context in ${contextDir}`);

package/core/stateManager.js

@@ -12,9 +12,12 @@ const DEFAULT_CONFIG = {
   port: 3333,
   debounceMs: 600,
   gitSync: {
-    enabled: false,
+    enabled: true,
     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.1.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"
   },