botrun-mcli 0.1.0

package/README.md

@@ -0,0 +1,234 @@
+# bm — Git-backed Memory CLI for Agents
+
+`bm` manages persistent memory for AI agents across ephemeral VMs. Memories are stored as files in Git repos (GitHub / GitLab), and `bm` handles the git plumbing — clone, sync, and scope management. Agents read/write memory files directly using their own tools.
+
+## Install
+
+```bash
+npx bm --help
+```
+
+## Quick Start
+
+```bash
+# 1. Add a memory scope (bind token via env var name)
+npx bm config add-scope my-notes \
+  --repo github.com/your-org/agent-memory \
+  --token-env MY_GITHUB_TOKEN \
+  --description "My personal notes" \
+  --access readwrite
+
+# 2. Set the token
+export MY_GITHUB_TOKEN=ghp_xxxxx
+
+# 3. Clone the repo
+npx bm memory init
+
+# 4. Agent reads/writes files at the local path...
+
+# 5. Push changes back
+npx bm memory sync
+```
+
+## Concepts
+
+### Scope
+
+A **scope** is a logical name that maps to a git repo. Each agent can have multiple scopes pointing to different repos.
+
+```bash
+npx bm config add-scope my-notes \
+  --repo github.com/org/my-memory \
+  --token-env BM_TOKEN_NOTES \
+  --description "Personal research notes" \
+  --access readwrite
+```
+
+### Multi-Repo Architecture
+
+Different scopes can point to different repos. Permissions are controlled by Git provider tokens — not by `bm`. Each scope binds to its own token via `--token-env`, enabling per-repo permission control.
+
+```bash
+# Director agent setup:
+# Read-write token for personal repo
+npx bm config add-scope director \
+  --repo github.com/org/director-memory \
+  --token-env BM_TOKEN_DIRECTOR \
+  --description "Director personal research" \
+  --access readwrite
+
+# Read-only token for team repos
+npx bm config add-scope team1 \
+  --repo github.com/org/team1-memory \
+  --token-env BM_TOKEN_TEAMS \
+  --description "Team 1 memory" \
+  --access readonly
+
+npx bm config add-scope team2 \
+  --repo github.com/org/team2-memory \
+  --token-env BM_TOKEN_TEAMS \
+  --description "Team 2 memory" \
+  --access readonly
+```
+
+Create separate GitHub Fine-grained PATs with different permissions:
+- `BM_TOKEN_DIRECTOR` → Contents: Read and write (only `director-memory` repo)
+- `BM_TOKEN_TEAMS` → Contents: Read-only (only `team1-memory` + `team2-memory` repos)
+
+This way, even if a user modifies the config, they can't write to repos their token doesn't allow.
+
+## Config
+
+### Base Path
+
+All `bm` data lives under a single base directory:
+
+```
+~/.botrun/bm/              ← default base path
+├── config.json            ← scope definitions
+└── data/
+    ├── my-notes/          ← git clone of my-notes scope
+    ├── team1/             ← git clone of team1 scope
+    └── team2/             ← git clone of team2 scope
+```
+
+Override with CLI option or environment variable:
+
+```bash
+npx bm --bm-path /tmp/test-bm memory init    # CLI option (highest priority)
+BM_PATH=/custom/path npx bm memory init       # environment variable
+```
+
+Priority: `--bm-path` > `BM_PATH` > `~/.botrun/bm/`
+
+### Config File
+
+Located at `<BM_PATH>/config.json` (default: `~/.botrun/bm/config.json`).
+
+Override config path independently with: `BM_CONFIG=/path/to/config.json`
+
+```json
+{
+  "scopes": {
+    "my-notes": {
+      "repo": "github.com/org/member1-memory",
+      "token_env": "BM_TOKEN_NOTES",
+      "description": "Personal research notes",
+      "access": "readwrite"
+    },
+    "team1": {
+      "repo": "github.com/org/team1-memory",
+      "branch": "dev",
+      "token_env": "BM_TOKEN_TEAMS",
+      "description": "Team 1 memory",
+      "access": "readonly"
+    }
+  }
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `repo` | yes | Git repo URL (without `https://`) |
+| `branch` | no | Git branch to use. Omit = repo default branch |
+| `token_env` | no | Env var name for this scope's token (for per-repo permission control) |
+| `description` | no | Description for agent context |
+| `access` | no | Access hint for agent: `readwrite` or `readonly` (default: `readwrite`) |
+| `provider` | no | `github` or `gitlab`. Auto-detected from URL |
+
+### Config Commands
+
+```bash
+npx bm config add-scope <name> --repo <url> [--branch <branch>] [--token-env <envVar>] [--description <text>] [--access <mode>]
+npx bm config remove-scope <name>
+npx bm config show
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `BM_PATH` | Base directory for all bm data (default: `~/.botrun/bm`) |
+| `BM_CONFIG` | Config file path (overrides `<BM_PATH>/config.json`) |
+
+Each scope's token is configured via `--token-env`, which points to an environment variable name. There are no global token variables — every scope must declare its own.
+
+## Memory Commands
+
+### `npx bm memory init`
+
+Clones all configured scope repos to `<BM_PATH>/data/<scope-name>/`. If already cloned, pulls latest.
+
+```json
+{
+  "scopes": {
+    "my-notes": { "local": "/root/.botrun/bm/data/my-notes" },
+    "team1": { "local": "/root/.botrun/bm/data/team1" }
+  }
+}
+```
+
+### `npx bm memory scopes`
+
+Lists all scopes with their repo, description, access, and local filesystem path.
+
+```json
+{
+  "scopes": {
+    "my-notes": {
+      "repo": "github.com/org/member1-memory",
+      "description": "Personal research notes",
+      "access": "readwrite",
+      "local": "/root/.botrun/bm/data/my-notes"
+    },
+    "team1": {
+      "repo": "github.com/org/team1-memory",
+      "description": "Team 1 memory",
+      "access": "readonly",
+      "local": "/root/.botrun/bm/data/team1"
+    }
+  }
+}
+```
+
+### `npx bm memory sync`
+
+Commits and pushes all changed memory files back to remote repos.
+
+```json
+{
+  "synced": ["my-notes"],
+  "skipped": ["team1"]
+}
+```
+
+## JSON Output
+
+All commands output structured JSON, including `--help`:
+
+```bash
+npx bm --help
+npx bm config --help
+npx bm memory --help
+```
+
+## Agent Lifecycle
+
+```
+VM starts
+  → npx bm memory init          # clone repos to <BM_PATH>/data/
+  → agent reads/writes files     # using native tools (Read, Write, grep)
+  → npx bm memory sync          # push changes
+VM destroyed
+```
+
+## Development
+
+```bash
+npm install
+npm test        # 41 tests
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "botrun-mcli",
+  "version": "0.1.0",
+  "description": "Git-backed memory CLI for AI agents",
+  "type": "module",
+  "bin": {
+    "bm": "./src/bin.mjs"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "find test -name '*.test.mjs' | xargs node --test"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "git",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/botrun/botrun-memory-cli.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.0.0"
+  }
+}

package/src/bin.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { getConfigPath } from './config.mjs';
+import { addScope } from './commands/config/add-scope.mjs';
+import { removeScope } from './commands/config/remove-scope.mjs';
+import { showConfig } from './commands/config/show.mjs';
+import { initMemory } from './commands/memory/init.mjs';
+import { syncMemory } from './commands/memory/sync.mjs';
+import { listScopes } from './commands/memory/scopes.mjs';
+
+function jsonHelp(cmd) {
+  const commands = cmd.commands.map(c => ({
+    name: c.name(),
+    description: c.description(),
+  }));
+  const options = cmd.options.map(o => ({
+    flags: o.flags,
+    description: o.description,
+    required: o.required,
+  }));
+  return { name: cmd.name(), description: cmd.description(), commands, options };
+}
+
+const program = new Command();
+
+program
+  .name('bm')
+  .description('Git-backed memory management for agents')
+  .version('0.1.0')
+  .helpCommand(false)
+  .option('--bm-path <path>', 'Base directory for all bm data')
+  .configureHelp({ formatHelp: (cmd) => JSON.stringify(jsonHelp(cmd), null, 2) })
+  .hook('preAction', (thisCommand) => {
+    const bmPath = thisCommand.opts().bmPath;
+    if (bmPath) process.env.BM_PATH = bmPath;
+  });
+
+// --- config ---
+const configCmd = program.command('config').description('Manage configuration');
+configCmd.configureHelp({ formatHelp: (cmd) => JSON.stringify(jsonHelp(cmd), null, 2) });
+
+configCmd
+  .command('add-scope <name>')
+  .description('Add a scope to the configuration')
+  .requiredOption('--repo <url>', 'Git repo URL')
+  .option('--branch <branch>', 'Git branch to use')
+  .option('--token-env <envVar>', 'Environment variable name for this scope token')
+  .option('--description <text>', 'Description of this scope for agent context')
+  .option('--access <mode>', 'Access mode hint for agent: readwrite or readonly', 'readwrite')
+  .action(async (name, opts) => {
+    const result = await addScope(name, opts, getConfigPath());
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+configCmd
+  .command('remove-scope <name>')
+  .description('Remove a scope from the configuration')
+  .action(async (name) => {
+    const result = await removeScope(name, getConfigPath());
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+configCmd
+  .command('show')
+  .description('Show current configuration')
+  .action(async () => {
+    const result = await showConfig(getConfigPath());
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+// --- memory ---
+const memoryCmd = program.command('memory').description('Manage memory repos');
+memoryCmd.configureHelp({ formatHelp: (cmd) => JSON.stringify(jsonHelp(cmd), null, 2) });
+
+memoryCmd
+  .command('init')
+  .description('Clone all scope repos')
+  .action(async () => {
+    const result = await initMemory({ configPath: getConfigPath() });
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+memoryCmd
+  .command('sync')
+  .description('Sync memory changes to remote repos')
+  .action(async () => {
+    const result = await syncMemory({ configPath: getConfigPath() });
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+memoryCmd
+  .command('scopes')
+  .description('List available scopes and local paths')
+  .action(async () => {
+    const result = await listScopes({ configPath: getConfigPath() });
+    console.log(JSON.stringify(result, null, 2));
+  });
+
+program.parse();

package/src/commands/config/add-scope.mjs

@@ -0,0 +1,13 @@
+import { loadConfig, saveConfig } from '../../config.mjs';
+
+export async function addScope(name, options, configPath) {
+  const config = await loadConfig(configPath);
+  const scopeEntry = { repo: options.repo };
+  if (options.branch) scopeEntry.branch = options.branch;
+  if (options.tokenEnv) scopeEntry.token_env = options.tokenEnv;
+  if (options.description) scopeEntry.description = options.description;
+  if (options.access) scopeEntry.access = options.access;
+  config.scopes[name] = scopeEntry;
+  await saveConfig(configPath, config);
+  return { added: name, scope: scopeEntry };
+}

package/src/commands/config/remove-scope.mjs

@@ -0,0 +1,11 @@
+import { loadConfig, saveConfig } from '../../config.mjs';
+
+export async function removeScope(name, configPath) {
+  const config = await loadConfig(configPath);
+  if (!config.scopes[name]) {
+    throw new Error(`Scope "${name}" not found`);
+  }
+  delete config.scopes[name];
+  await saveConfig(configPath, config);
+  return { removed: name };
+}

package/src/commands/config/show.mjs

@@ -0,0 +1,5 @@
+import { loadConfig } from '../../config.mjs';
+
+export async function showConfig(configPath) {
+  return await loadConfig(configPath);
+}

package/src/commands/memory/init.mjs

@@ -0,0 +1,57 @@
+import { mkdir, lstat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadConfig, getBasePath } from '../../config.mjs';
+import { gitExec } from '../../git-cmd.mjs';
+import { detectProvider, getProvider, resolveToken } from '../../git/provider.mjs';
+
+async function exists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function cloneOrPull(repo, cloneDir, token, localMode, branch) {
+  if (await exists(cloneDir)) {
+    await gitExec(['-C', cloneDir, 'pull', '--rebase']);
+    return;
+  }
+
+  let cloneUrl;
+  if (localMode) {
+    cloneUrl = repo;
+  } else {
+    const providerName = detectProvider(repo);
+    const provider = getProvider(providerName);
+    cloneUrl = provider.buildCloneUrl(repo, token);
+  }
+
+  const cloneArgs = ['clone', '--depth', '1'];
+  if (branch) cloneArgs.push('--branch', branch);
+  cloneArgs.push(cloneUrl, cloneDir);
+  await gitExec(cloneArgs);
+}
+
+export async function initMemory(options = {}) {
+  const configPath = options.configPath;
+  const dataDir = options.dataDir || join(getBasePath(), 'data');
+  const localMode = options.localMode || false;
+
+  const config = await loadConfig(configPath);
+  const result = { scopes: {} };
+
+  await mkdir(dataDir, { recursive: true });
+
+  for (const [name, scope] of Object.entries(config.scopes)) {
+    const cloneDir = join(dataDir, name);
+    const token = localMode ? undefined : resolveToken(scope);
+
+    await cloneOrPull(scope.repo, cloneDir, token, localMode, scope.branch);
+
+    result.scopes[name] = { local: cloneDir };
+  }
+
+  return result;
+}

package/src/commands/memory/scopes.mjs

@@ -0,0 +1,27 @@
+import { join } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { loadConfig, getBasePath } from '../../config.mjs';
+
+export async function listScopes(options = {}) {
+  const config = await loadConfig(options.configPath);
+  const dataDir = options.dataDir || join(getBasePath(), 'data');
+  const result = { scopes: {} };
+
+  for (const [name, scope] of Object.entries(config.scopes)) {
+    const entry = { repo: scope.repo };
+    if (scope.description) entry.description = scope.description;
+    if (scope.access) entry.access = scope.access;
+
+    const scopeDir = join(dataDir, name);
+    try {
+      await lstat(scopeDir);
+      entry.local = scopeDir;
+    } catch {
+      entry.local = null;
+    }
+
+    result.scopes[name] = entry;
+  }
+
+  return result;
+}

package/src/commands/memory/sync.mjs

@@ -0,0 +1,29 @@
+import { join } from 'node:path';
+import { loadConfig, getBasePath } from '../../config.mjs';
+import { gitExec } from '../../git-cmd.mjs';
+
+export async function syncMemory(options = {}) {
+  const config = await loadConfig(options.configPath);
+  const dataDir = options.dataDir || join(getBasePath(), 'data');
+
+  const result = { synced: [], skipped: [] };
+
+  for (const [name, scope] of Object.entries(config.scopes)) {
+    const cloneDir = join(dataDir, name);
+
+    const status = await gitExec(['-C', cloneDir, 'status', '--porcelain']);
+
+    if (!status) {
+      result.skipped.push(name);
+      continue;
+    }
+
+    await gitExec(['-C', cloneDir, 'add', '-A']);
+    await gitExec(['-C', cloneDir, 'commit', '-m', `bm: update ${name} memories`]);
+    await gitExec(['-C', cloneDir, 'pull', '--rebase']);
+    await gitExec(['-C', cloneDir, 'push']);
+    result.synced.push(name);
+  }
+
+  return result;
+}

package/src/config.mjs

@@ -0,0 +1,30 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+const DEFAULT_BASE_PATH = join(homedir(), '.botrun', 'bm');
+
+export function getBasePath() {
+  return process.env.BM_PATH || DEFAULT_BASE_PATH;
+}
+
+export function getConfigPath() {
+  return process.env.BM_CONFIG || join(getBasePath(), 'config.json');
+}
+
+export async function loadConfig(configPath = getConfigPath()) {
+  try {
+    const content = await readFile(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { scopes: {} };
+    }
+    throw err;
+  }
+}
+
+export async function saveConfig(configPath = getConfigPath(), config) {
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+}

package/src/git/github.mjs

@@ -0,0 +1,3 @@
+export function buildCloneUrl(repo, token) {
+  return `https://x-access-token:${token}@${repo}.git`;
+}

package/src/git/gitlab.mjs

@@ -0,0 +1,3 @@
+export function buildCloneUrl() {
+  throw new Error('GitLab support not yet implemented');
+}

package/src/git/provider.mjs

@@ -0,0 +1,23 @@
+import * as github from './github.mjs';
+import * as gitlab from './gitlab.mjs';
+
+const providers = { github, gitlab };
+
+export function detectProvider(repoUrl) {
+  if (repoUrl.startsWith('github.com')) return 'github';
+  if (repoUrl.startsWith('gitlab.com')) return 'gitlab';
+  throw new Error(`Unknown git provider for URL: ${repoUrl}`);
+}
+
+export function getProvider(name) {
+  const provider = providers[name];
+  if (!provider) throw new Error(`Unknown provider: ${name}`);
+  // trigger "not yet implemented" for gitlab
+  if (name === 'gitlab') provider.buildCloneUrl();
+  return provider;
+}
+
+export function resolveToken(scope) {
+  if (!scope.token_env) return undefined;
+  return process.env[scope.token_env] || undefined;
+}

package/src/git-cmd.mjs

@@ -0,0 +1,12 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export async function gitExec(args, options = {}) {
+  const { stdout } = await execFileAsync('git', args, {
+    maxBuffer: 10 * 1024 * 1024,
+    ...options,
+  });
+  return stdout.trim();
+}