compass-ai 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,207 @@
+# Compass
+
+**Compass** is an AI chief of staff for startups. It listens to your Telegram conversations, extracts tasks, decisions, blockers, and commitments, stores them in structured files, and posts clear summaries to Slack — automatically.
+
+Compass is not a chatbot. It is your execution memory and reporting layer.
+
+Built on [OpenClaw](https://openclaw.ai).
+
+---
+
+## What Compass does
+
+| Capability | Detail |
+|---|---|
+| Listens to Telegram | Reads group and DM conversations passively |
+| Extracts signal | Tasks, decisions, blockers, commitments, metrics |
+| Maintains memory | Writes structured state to local files |
+| Answers questions | Responds when mentioned directly (`@Compass`) |
+| Posts to Slack | Daily standups and weekly reviews on schedule |
+| Stays quiet | Silent unless mentioned or scheduled |
+
+---
+
+## Prerequisites
+
+| Requirement | Detail |
+|---|---|
+| Linux (Ubuntu 20.04+ / Debian 11+) | Cron scheduling requires Linux |
+| Node.js 18 or higher | Runtime |
+| A Telegram bot token | From [@BotFather](https://t.me/BotFather) on Telegram |
+| Your Telegram user ID | From [@userinfobot](https://t.me/userinfobot) on Telegram |
+| A Slack bot token | From your Slack app settings (starts with `xoxb-`) |
+| An LLM API key | Anthropic or OpenAI |
+
+---
+
+## Installation
+
+```bash
+npm install -g compass-ai
+```
+
+This installs the `compass` CLI and automatically installs OpenClaw as a dependency.
+
+---
+
+## Setup (run once)
+
+```bash
+compass init
+```
+
+You will be asked:
+
+```
+LLM provider (anthropic / openai) [anthropic]:
+Anthropic API key:
+Telegram bot token:
+Your Telegram user ID:
+Slack bot token:
+Slack report channel [#standup]:
+Daily standup time (HH:MM, 24h) [09:00]:
+Weekly review day (MON-SUN) [MON]:
+Weekly review time (HH:MM, 24h) [08:00]:
+Your name (for Compass memory):
+```
+
+Press Enter to accept any default shown in brackets.
+
+**What `compass init` creates on your machine:**
+
+```
+~/.openclaw/
+├── agent.json          ← Compass identity
+├── hooks.json          ← boot, logger, session memory
+├── channels.json       ← Telegram + Slack connection
+├── llm.json            ← your LLM provider and key
+└── compass/
+    ├── boot.md         ← Compass system prompt (generated from your answers)
+    ├── user.md         ← your profile and preferences
+    ├── soul.md         ← Compass personality
+    ├── identity.md     ← Compass role definition
+    ├── tools.md        ← allowed tools
+    ├── skills/         ← extract and report skills
+    └── state/
+        ├── tasks.md
+        ├── decisions.md
+        ├── blockers.md
+        ├── commitments.md
+        ├── metrics.md
+        ├── daily-summaries/
+        └── weekly-summaries/
+```
+
+On Linux, cron jobs are configured automatically for daily and weekly reports.
+
+---
+
+## Start
+
+```bash
+compass start
+```
+
+Compass connects to Telegram and Slack and runs in the foreground. To run it as a background service, use a process manager like `pm2` or `systemd`.
+
+---
+
+## Commands
+
+```bash
+compass init                      # First-time setup
+compass start                     # Start the agent
+compass report --type daily       # Trigger a daily standup report now
+compass report --type weekly      # Trigger a weekly review report now
+compass                           # Show help
+```
+
+---
+
+## Using Compass in Telegram
+
+Compass is silent by default. Mention it directly to interact:
+
+```
+@Compass what's blocked?
+@Compass who owns the landing page?
+@Compass what did we decide about the API?
+@Compass show this week's metrics
+@Compass extract from this conversation
+```
+
+---
+
+## Slack reports
+
+Compass posts automatically on your configured schedule:
+
+- **Daily standup** — every day at your configured time
+- **Weekly review** — every Monday (or your configured day) morning
+
+To trigger a report immediately:
+
+```bash
+compass report --type daily
+compass report --type weekly
+```
+
+---
+
+## State files
+
+All extracted information is stored as plain markdown files in `~/.openclaw/compass/state/`. You can read, edit, or back them up like any file.
+
+| File | What it stores |
+|---|---|
+| `tasks.md` | Active tasks with owner, status, deadline, priority |
+| `decisions.md` | Decision log with what, why, alternatives |
+| `blockers.md` | Open blockers with age tracking |
+| `commitments.md` | Commitments and deadlines |
+| `metrics.md` | Key metrics log |
+
+---
+
+## Re-running setup
+
+`compass init` is safe to re-run. It overwrites existing config with your new answers.
+
+```bash
+compass init
+```
+
+---
+
+## Updating
+
+```bash
+npm install -g compass-ai@latest
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `compass: command not found` | Run `npm install -g compass-ai` again |
+| Telegram bot not responding | Send `/start` to your bot first, then `hi` |
+| Slack not posting | Verify your `SLACK_BOT_TOKEN` and that the bot is added to the channel |
+| Cron not firing | Run `crontab -l` to verify entries; check server timezone |
+| OpenClaw not found after install | Run `npm install -g openclaw` manually |
+
+---
+
+## What Compass will not do (Phase 1)
+
+- No sending emails
+- No publishing content externally
+- No spending money
+- No modifying outside systems
+- No autonomous decisions without your approval
+
+---
+
+## License
+
+MIT

package/bin/compass.js

@@ -7,20 +7,27 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const PACKAGE_DIR  = path.join(__dirname, '..');
-const OPENCLAW_DIR = path.join(os.homedir(), '.openclaw');
+const migrations = require('../migrations/index.js');
+const pkg = require('../package.json');
+
+const PACKAGE_DIR   = path.join(__dirname, '..');
+const OPENCLAW_DIR  = path.join(os.homedir(), '.openclaw');
 const WORKSPACE_DIR = path.join(OPENCLAW_DIR, 'compass');
-const STATE_DIR    = path.join(WORKSPACE_DIR, 'state');
-const BOOT_MD      = path.join(WORKSPACE_DIR, 'boot.md');
-const SKILLS_SRC   = path.join(PACKAGE_DIR, 'skills');
+const STATE_DIR     = path.join(WORKSPACE_DIR, 'state');
+const BOOT_MD       = path.join(WORKSPACE_DIR, 'boot.md');
+const SKILLS_SRC    = path.join(PACKAGE_DIR, 'skills');
 
 const cmd = process.argv[2];
 
 switch (cmd) {
-  case 'init':   init().catch(err => { console.error('\n  Error:', err.message); process.exit(1); }); break;
-  case 'start':  start(); break;
-  case 'report': report(); break;
-  default:       help(); break;
+  case 'init':      init().catch(err => { console.error('\n  Error:', err.message); process.exit(1); }); break;
+  case 'start':     start(); break;
+  case 'report':    report(); break;
+  case 'migrate':   runMigrate(); break;
+  case 'rollback':  migrations.rollback(); break;
+  case 'doctor':    migrations.doctor(); break;
+  case 'version':   showVersion(); break;
+  default:          help(); break;
 }
 
 // ── helpers ──────────────────────────────────────────────────────────────────
@@ -75,7 +82,7 @@ async function init() {
   const dailyTime      = await ask(rl, 'Daily standup time (HH:MM, 24h)', '09:00');
   const weeklyDay      = await ask(rl, 'Weekly review day (MON-SUN)', 'MON');
   const weeklyTime     = await ask(rl, 'Weekly review time (HH:MM, 24h)', '08:00');
-  const founderName    = await ask(rl, 'Your name (for Compass memory)', 'Manas');
+  const founderName    = await ask(rl, 'Your name (for Compass memory)');
 
   rl.close();
 
@@ -197,6 +204,10 @@ Phase 1: read Telegram, extract signal, maintain state files, report to Slack.
 
   copyDir(SKILLS_SRC, path.join(WORKSPACE_DIR, 'skills'));
 
+  // ── Write version file ────────────────────────────────────────────────────
+
+  migrations.initVersion(pkg.version);
+
   // ── Cron jobs (Linux only) ────────────────────────────────────────────────
 
   if (process.platform === 'linux') {
@@ -207,17 +218,20 @@ Phase 1: read Telegram, extract signal, maintain state files, report to Slack.
 
   console.log('  ✅  Config written to', OPENCLAW_DIR);
   console.log('  ✅  State files created in', STATE_DIR);
+  console.log('  ✅  Schema version:', migrations.CURRENT_SCHEMA);
   console.log('\n─────────────────────────────────────────');
   console.log('  Compass is ready.\n');
   console.log('  Start:          compass start');
   console.log('  Daily report:   compass report --type daily');
   console.log('  Weekly report:  compass report --type weekly');
+  console.log('  Health check:   compass doctor');
   console.log('\n  Next: open Telegram → find your bot → send /start\n');
 }
 
 // ── start ─────────────────────────────────────────────────────────────────────
 
 function start() {
+  migrations.checkVersion(); // warn if schema is outdated, then continue
   console.log('🧭  Starting Compass...');
   runOpenClaw('start', '--headless');
 }
@@ -234,6 +248,30 @@ function report() {
   runOpenClaw('run', 'compass-report', '--type', type);
 }
 
+// ── migrate ───────────────────────────────────────────────────────────────────
+
+function runMigrate() {
+  const dry = process.argv.includes('--dry');
+  migrations.migrate({ dry }).catch(err => {
+    console.error('\n  Migration error:', err.message, '\n');
+    process.exit(1);
+  });
+}
+
+// ── version ───────────────────────────────────────────────────────────────────
+
+function showVersion() {
+  const versionData = migrations.readVersion();
+  console.log(`\n🧭  compass-ai v${pkg.version}`);
+  console.log(`   Schema:   v${versionData ? versionData.schemaVersion : '?'} / current v${migrations.CURRENT_SCHEMA}`);
+  console.log(`   State:    ${STATE_DIR}`);
+  console.log(`   Config:   ${OPENCLAW_DIR}`);
+  if (versionData?.lastMigratedAt) {
+    console.log(`   Migrated: ${versionData.lastMigratedAt}`);
+  }
+  console.log('');
+}
+
 // ── help ──────────────────────────────────────────────────────────────────────
 
 function help() {
@@ -245,6 +283,13 @@ Usage:
   compass start                      Start the Compass agent
   compass report --type daily        Trigger a daily standup report
   compass report --type weekly       Trigger a weekly review report
+
+Maintenance:
+  compass migrate                    Run pending schema migrations
+  compass migrate --dry              Preview migrations without applying
+  compass rollback                   Restore state from the last backup
+  compass doctor                     Full health check
+  compass version                    Show version and schema info
 `);
 }
 
@@ -318,13 +363,14 @@ Slack:
 `;
 }
 
-function copyDir(src, dest) {
+function copyDir(src, dest, exclude = []) {
   if (!fs.existsSync(src)) return;
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (exclude.includes(entry.name)) continue;
     const srcPath  = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) copyDir(srcPath, destPath);
+    if (entry.isDirectory()) copyDir(srcPath, destPath, exclude);
     else fs.copyFileSync(srcPath, destPath);
   }
 }

package/migrations/001-initial.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Schema v1 — baseline. No transformations needed.
+// This migration exists only to mark the starting point.
+// All installs using compass init will start at schema v1.
+//
+// How to add the next migration:
+//   1. Create 002-your-description.js with the same shape
+//   2. Bump CURRENT_SCHEMA in migrations/index.js to 2
+//   3. Implement up() to transform state files from v1 → v2
+//
+// Example for adding a column to tasks.md:
+//
+//   up: async (stateDir) => {
+//     const file = path.join(stateDir, 'tasks.md');
+//     const content = fs.readFileSync(file, 'utf8');
+//     const updated = addColumn(content, 'Tags', '');
+//     fs.writeFileSync(file, updated, 'utf8');
+//   }
+
+module.exports = {
+  version: 1,
+  description: 'Initial schema baseline',
+  up: async () => {},
+};

package/migrations/index.js

@@ -0,0 +1,316 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+// ── Schema version ────────────────────────────────────────────────────────────
+// Bump ONLY when state file structure changes. NOT on every package release.
+const CURRENT_SCHEMA = 1;
+
+// ── Paths ─────────────────────────────────────────────────────────────────────
+const WORKSPACE_DIR = path.join(os.homedir(), '.openclaw', 'compass');
+const STATE_DIR     = path.join(WORKSPACE_DIR, 'state');
+const VERSION_FILE  = path.join(WORKSPACE_DIR, 'version.json');
+const BACKUPS_DIR   = path.join(WORKSPACE_DIR, 'backups');
+const BOOT_MD       = path.join(WORKSPACE_DIR, 'boot.md');
+
+// ── Discover and load migration files ────────────────────────────────────────
+// Files must match NNN-description.js (e.g. 002-add-priority.js)
+const MIGRATIONS = fs.readdirSync(__dirname)
+  .filter(f => /^\d{3}-.+\.js$/.test(f))
+  .sort()
+  .map(f => require(path.join(__dirname, f)));
+
+// ── Version file ──────────────────────────────────────────────────────────────
+
+function readVersion() {
+  if (!fs.existsSync(VERSION_FILE)) return null;
+  try { return JSON.parse(fs.readFileSync(VERSION_FILE, 'utf8')); } catch { return null; }
+}
+
+function writeVersion(data) {
+  fs.mkdirSync(path.dirname(VERSION_FILE), { recursive: true });
+  fs.writeFileSync(VERSION_FILE, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+// ── Hashing ───────────────────────────────────────────────────────────────────
+
+function hashFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath, 'utf8');
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+// ── Backup ────────────────────────────────────────────────────────────────────
+
+function backup() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupDir = path.join(BACKUPS_DIR, `backup-${ts}`);
+
+  copyDir(WORKSPACE_DIR, backupDir, ['backups']); // never recurse into backups
+
+  // Keep only the last 5 backups — prune oldest
+  if (fs.existsSync(BACKUPS_DIR)) {
+    const all = fs.readdirSync(BACKUPS_DIR).sort();
+    if (all.length > 5) {
+      all.slice(0, all.length - 5).forEach(b => rmDir(path.join(BACKUPS_DIR, b)));
+    }
+  }
+
+  return backupDir;
+}
+
+function latestBackup() {
+  if (!fs.existsSync(BACKUPS_DIR)) return null;
+  const all = fs.readdirSync(BACKUPS_DIR).sort();
+  return all.length ? path.join(BACKUPS_DIR, all[all.length - 1]) : null;
+}
+
+// ── Migrate ───────────────────────────────────────────────────────────────────
+
+async function migrate(options = {}) {
+  const { dry = false } = options;
+
+  const versionData = readVersion();
+
+  // Legacy install: has state files but no version.json — treat as schema v0
+  const fromSchema = versionData ? versionData.schemaVersion : 0;
+
+  if (fromSchema === CURRENT_SCHEMA) {
+    console.log('\n  Already up to date. Schema version:', CURRENT_SCHEMA, '\n');
+    return;
+  }
+
+  const pending = MIGRATIONS.filter(m => m.version > fromSchema && m.version <= CURRENT_SCHEMA);
+
+  if (pending.length === 0) {
+    console.log('\n  No migrations to run.\n');
+    return;
+  }
+
+  console.log(`\n  Pending migrations (schema v${fromSchema} → v${CURRENT_SCHEMA}):\n`);
+  pending.forEach(m => console.log(`    • v${m.version}: ${m.description}`));
+
+  if (dry) {
+    console.log('\n  Dry run complete — no changes made.\n');
+    return;
+  }
+
+  // Backup before touching anything
+  console.log('\n  Creating backup...');
+  const backupDir = backup();
+  console.log('  Backed up to:', backupDir, '\n');
+
+  // Run each migration in sequence — abort and rollback on first failure
+  let lastApplied = fromSchema;
+
+  for (const migration of pending) {
+    process.stdout.write(`  v${migration.version}: ${migration.description}... `);
+    try {
+      await migration.up(STATE_DIR, WORKSPACE_DIR);
+      lastApplied = migration.version;
+      console.log('✅');
+    } catch (err) {
+      console.log('❌');
+      console.error('\n  Migration failed:', err.message);
+      console.error('  Rolling back from backup...');
+      restoreFromDir(backupDir);
+      console.error('  Rollback complete. Schema unchanged.\n');
+      process.exit(1);
+    }
+  }
+
+  // Update version file
+  writeVersion({
+    ...(versionData || {}),
+    schemaVersion: lastApplied,
+    packageVersion: require('../package.json').version,
+    lastMigratedAt: new Date().toISOString(),
+    migrationsApplied: [
+      ...((versionData || {}).migrationsApplied || []),
+      ...pending.map(m => m.version),
+    ],
+    bootMdHash: hashFile(BOOT_MD),
+  });
+
+  console.log(`\n  Migration complete. Schema is now v${lastApplied}.\n`);
+}
+
+// ── Rollback ──────────────────────────────────────────────────────────────────
+
+function rollback() {
+  const backupDir = latestBackup();
+  if (!backupDir) {
+    console.error('\n  No backups found in', BACKUPS_DIR, '\n');
+    process.exit(1);
+  }
+  console.log('\n  Restoring from:', backupDir);
+  restoreFromDir(backupDir);
+  console.log('  Rollback complete.\n');
+}
+
+function restoreFromDir(backupDir) {
+  copyDir(backupDir, WORKSPACE_DIR, []);
+}
+
+// ── Version check (called on compass start) ───────────────────────────────────
+
+function checkVersion() {
+  const versionData = readVersion();
+
+  // Legacy install: state files exist but no version.json
+  if (!versionData) {
+    if (fs.existsSync(path.join(STATE_DIR, 'tasks.md'))) {
+      console.warn('\n  ⚠️  Existing state found but no schema version recorded.');
+      console.warn('  Run: compass migrate\n');
+    }
+    return;
+  }
+
+  if (versionData.schemaVersion < CURRENT_SCHEMA) {
+    console.warn(`\n  ⚠️  State files are schema v${versionData.schemaVersion}, current is v${CURRENT_SCHEMA}.`);
+    console.warn('  Run: compass migrate\n');
+  }
+}
+
+// ── Init version (called after compass init) ──────────────────────────────────
+
+function initVersion(packageVersion) {
+  const existing = readVersion();
+  writeVersion({
+    schemaVersion: CURRENT_SCHEMA,
+    packageVersion,
+    initializedAt: existing?.initializedAt || new Date().toISOString(),
+    lastMigratedAt: null,
+    migrationsApplied: [],
+    bootMdHash: hashFile(BOOT_MD),
+  });
+}
+
+// ── Doctor ────────────────────────────────────────────────────────────────────
+
+function doctor() {
+  const pkg = require('../package.json');
+  const versionData = readVersion();
+
+  const check = (label, ok, detail = '') => {
+    const icon = ok ? '✅' : '❌';
+    const suffix = detail ? `  ${detail}` : '';
+    console.log(`  ${icon}  ${label}${suffix}`);
+    return ok;
+  };
+
+  console.log(`\n🧭  Compass — Doctor\n`);
+  console.log(`  Package:  compass-ai v${pkg.version}`);
+  console.log(`  Schema:   v${versionData ? versionData.schemaVersion : '?'} / current v${CURRENT_SCHEMA}`);
+  console.log('');
+
+  // Runtime
+  console.log('  Runtime');
+  const nodeOk = parseInt(process.version.slice(1)) >= 18;
+  check('Node.js', nodeOk, process.version);
+
+  let oclawOk = false;
+  try {
+    const { execSync } = require('child_process');
+    const oclawPath = execSync('which openclaw 2>/dev/null || command -v openclaw', { encoding: 'utf8' }).trim();
+    oclawOk = !!oclawPath;
+    check('OpenClaw', oclawOk, oclawPath);
+  } catch {
+    check('OpenClaw', false, 'not found — run: npm install -g openclaw');
+  }
+
+  // Config files
+  console.log('\n  Config');
+  const configDir = path.join(os.homedir(), '.openclaw');
+  ['agent.json', 'channels.json', 'llm.json', 'hooks.json'].forEach(f => {
+    check(f, fs.existsSync(path.join(configDir, f)));
+  });
+
+  // Schema
+  console.log('\n  Schema');
+  if (!versionData) {
+    check('version.json', false, 'missing — run: compass migrate');
+  } else {
+    const current = versionData.schemaVersion === CURRENT_SCHEMA;
+    check('version.json', current,
+      current ? `v${versionData.schemaVersion} (current)` : `v${versionData.schemaVersion} — run: compass migrate`);
+  }
+
+  // State files
+  console.log('\n  State files');
+  ['tasks.md', 'decisions.md', 'blockers.md', 'commitments.md', 'metrics.md'].forEach(f => {
+    check(f, fs.existsSync(path.join(STATE_DIR, f)));
+  });
+
+  // Connections
+  console.log('\n  Connections');
+  try {
+    const channels = JSON.parse(fs.readFileSync(path.join(configDir, 'channels.json'), 'utf8'));
+    check('Telegram', !!channels.telegram?.token, channels.telegram?.token ? 'configured' : 'missing token');
+    check('Slack',    !!channels.slack?.token,    channels.slack?.token    ? 'configured' : 'missing token');
+  } catch {
+    check('channels.json', false, 'could not read');
+  }
+
+  // Cron (Linux only)
+  if (process.platform === 'linux') {
+    console.log('\n  Cron');
+    try {
+      const { execSync } = require('child_process');
+      const crontab = execSync('crontab -l 2>/dev/null || true', { encoding: 'utf8' });
+      check('Daily report',  crontab.includes('compass report --type daily'));
+      check('Weekly report', crontab.includes('compass report --type weekly'));
+    } catch {
+      check('Cron', false, 'could not read crontab');
+    }
+  }
+
+  // Backups
+  console.log('\n  Backups');
+  const latest = latestBackup();
+  if (latest) {
+    const name = path.basename(latest);
+    check('Latest backup', true, name);
+  } else {
+    console.log('  —  No backups yet (created automatically before each migration)');
+  }
+
+  console.log('');
+}
+
+// ── Utilities ─────────────────────────────────────────────────────────────────
+
+function copyDir(src, dest, exclude = []) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (exclude.includes(entry.name)) continue;
+    const srcPath  = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(srcPath, destPath, exclude);
+    else fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+function rmDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) rmDir(p);
+    else fs.unlinkSync(p);
+  }
+  fs.rmdirSync(dir);
+}
+
+module.exports = {
+  migrate,
+  rollback,
+  checkVersion,
+  initVersion,
+  doctor,
+  CURRENT_SCHEMA,
+  readVersion,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compass-ai",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI chief of staff for startups — built on OpenClaw",
   "bin": {
     "compass": "./bin/compass.js"
@@ -8,7 +8,7 @@
   "files": [
     "bin/",
     "skills/",
-    "compass-boot.md"
+    "migrations/"
   ],
   "dependencies": {
     "openclaw": "latest"