twinclaw 1.0.0

package/dist/config/workspace.js

@@ -0,0 +1,186 @@
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+const TWINBOT_HOME = '.twinbot';
+const LEGACY_TWINCLAW_HOME = '.twinclaw';
+export function getProfileName() {
+    const profile = process.env.TWINBOT_PROFILE || process.env.TWINCLAW_PROFILE;
+    if (profile && profile.trim().length > 0) {
+        return profile.trim();
+    }
+    return 'default';
+}
+export function getWorkspaceDir() {
+    const profile = getProfileName();
+    const home = os.homedir();
+    if (profile === 'default') {
+        return path.join(home, TWINBOT_HOME, 'workspace');
+    }
+    const sanitizedProfile = profile.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return path.join(home, TWINBOT_HOME, `workspace-${sanitizedProfile}`);
+}
+export function getWorkspaceSubdir(subdir) {
+    return path.join(getWorkspaceDir(), subdir);
+}
+export function getConfigPath() {
+    return path.join(getWorkspaceDir(), 'twinbot.json');
+}
+export function getDatabasePath() {
+    return path.join(getWorkspaceDir(), 'memory', 'twinbot.db');
+}
+export function getIdentityDir() {
+    return path.join(getWorkspaceDir(), 'identity');
+}
+export function getSecretsVaultPath() {
+    return path.join(getWorkspaceDir(), 'secrets.sqlite');
+}
+export function getTranscriptsDir() {
+    return path.join(getWorkspaceDir(), 'transcripts');
+}
+export function ensureWorkspaceDir() {
+    const workspaceDir = getWorkspaceDir();
+    if (!fs.existsSync(workspaceDir)) {
+        fs.mkdirSync(workspaceDir, { recursive: true });
+    }
+}
+export function ensureWorkspaceSubdirs() {
+    ensureWorkspaceDir();
+    const subdirs = ['memory', 'identity', 'transcripts'];
+    for (const subdir of subdirs) {
+        const fullPath = getWorkspaceSubdir(subdir);
+        if (!fs.existsSync(fullPath)) {
+            fs.mkdirSync(fullPath, { recursive: true });
+        }
+    }
+}
+export function getLegacyConfigPath() {
+    // 1. Check for twinbot.json in the new workspace first (partial migration state)
+    const newWorkspaceLegacyFile = path.join(getWorkspaceDir(), 'twinbot.json');
+    if (fs.existsSync(newWorkspaceLegacyFile)) {
+        return newWorkspaceLegacyFile;
+    }
+    // 2. Then check the old .twinbot home (flat structure)
+    const oldTwinBotFile = path.join(os.homedir(), TWINBOT_HOME, 'twinbot.json');
+    if (fs.existsSync(oldTwinBotFile)) {
+        return oldTwinBotFile;
+    }
+    // 3. Finally, check the legacy .twinclaw home
+    const legacyTwinClawFile = path.join(os.homedir(), LEGACY_TWINCLAW_HOME, 'twinclaw.json');
+    return legacyTwinClawFile;
+}
+export function hasLegacyConfig() {
+    const legacyPath = getLegacyConfigPath();
+    const workspacePath = getConfigPath();
+    return fs.existsSync(legacyPath) && !fs.existsSync(workspacePath);
+}
+export function migrateLegacyConfig() {
+    const legacyPath = getLegacyConfigPath();
+    const workspacePath = getConfigPath();
+    if (!fs.existsSync(legacyPath)) {
+        return { migrated: false, sourcePath: null, targetPath: null };
+    }
+    if (fs.existsSync(workspacePath)) {
+        return { migrated: false, sourcePath: legacyPath, targetPath: workspacePath };
+    }
+    const workspaceDir = getWorkspaceDir();
+    if (!fs.existsSync(workspaceDir)) {
+        fs.mkdirSync(workspaceDir, { recursive: true });
+    }
+    try {
+        const content = fs.readFileSync(legacyPath, 'utf-8');
+        fs.writeFileSync(workspacePath, content, { encoding: 'utf-8', mode: 0o600 });
+        const legacyDir = path.dirname(legacyPath);
+        const legacyFiles = ['identity', 'memory', 'transcripts', 'secrets.sqlite', 'twinbot.db', 'twinclaw.db'];
+        for (const file of legacyFiles) {
+            const legacyFile = path.join(legacyDir, file);
+            if (fs.existsSync(legacyFile)) {
+                let targetFileName = file;
+                if (file === 'twinclaw.db')
+                    targetFileName = 'twinbot.db';
+                const targetFile = path.join(workspaceDir, targetFileName);
+                const targetFileDir = path.dirname(targetFile);
+                if (!fs.existsSync(targetFileDir)) {
+                    fs.mkdirSync(targetFileDir, { recursive: true });
+                }
+                if (fs.statSync(legacyFile).isDirectory()) {
+                    fs.cpSync(legacyFile, targetFile, { recursive: true });
+                }
+                else {
+                    fs.copyFileSync(legacyFile, targetFile);
+                }
+            }
+        }
+        return { migrated: true, sourcePath: legacyPath, targetPath: workspacePath };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { migrated: false, sourcePath: legacyPath, targetPath: workspacePath, error: message };
+    }
+}
+export const WORKSPACE_GITIGNORE = `# TwinBot Workspace .gitignore
+# Auto-generated by TwinBot workspace initialization
+
+# Sensitive databases
+*.sqlite
+*.sqlite-journal
+*.sqlite-wal
+*.sqlite-shm
+
+# Secrets vault (never commit)
+secrets.sqlite
+
+# Memory databases
+memory/*.db
+memory/*.db-journal
+
+# Session transcripts (may contain sensitive data)
+transcripts/*.md
+
+# Runtime state files
+runtime-state.json
+*.pid
+
+# Logs
+logs/
+*.log
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+
+# OS files
+.DS_Store
+Thumbs.db
+`;
+export function initializeWorkspaceGitignore() {
+    const workspaceDir = getWorkspaceDir();
+    const gitignorePath = path.join(workspaceDir, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+        return false;
+    }
+    try {
+        fs.writeFileSync(gitignorePath, WORKSPACE_GITIGNORE, { encoding: 'utf-8' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function initializeWorkspace() {
+    ensureWorkspaceSubdirs();
+    initializeWorkspaceGitignore();
+}
+export function getWorkspaceSummary() {
+    const workspaceDir = getWorkspaceDir();
+    return {
+        workspaceDir,
+        configPath: getConfigPath(),
+        databasePath: getDatabasePath(),
+        identityDir: getIdentityDir(),
+        secretsVaultPath: getSecretsVaultPath(),
+        transcriptsDir: getTranscriptsDir(),
+        profileName: getProfileName(),
+        exists: fs.existsSync(workspaceDir),
+    };
+}

package/dist/core/channels-cli.js

@@ -0,0 +1,77 @@
+import WAWebJS from 'whatsapp-web.js';
+import qrcode from 'qrcode-terminal';
+const { Client, LocalAuth } = WAWebJS;
+function printUsage() {
+    console.log(`Channel commands:
+  channels login whatsapp    Start interactive login for WhatsApp (QR Code)`);
+}
+async function runWhatsappLogin() {
+    console.log('[TwinBot Channels] Starting WhatsApp login sequence...');
+    console.log('Initializing secure browser environment...');
+    const client = new Client({
+        authStrategy: new LocalAuth({ dataPath: './memory/whatsapp_auth' }),
+        puppeteer: {
+            args: ['--no-sandbox', '--disable-setuid-sandbox'],
+        },
+    });
+    client.on('qr', (qr) => {
+        console.log('\n[TwinBot Channels] ══════════════════════════════════════════════════');
+        console.log('[TwinBot Channels] ACTION REQUIRED: SCAN TO LINK WHATSAPP');
+        console.log('[TwinBot Channels] 1. Open WhatsApp on your primary phone');
+        console.log('[TwinBot Channels] 2. Tap Menu (⋮) or Settings -> Linked Devices');
+        console.log('[TwinBot Channels] 3. Tap "Link a Device" and scan the code below:');
+        qrcode.generate(qr, { small: true });
+        console.log('[TwinBot Channels] ══════════════════════════════════════════════════\n');
+        console.log('Awaiting scan...');
+    });
+    client.on('ready', () => {
+        console.log('\n[TwinBot Channels] ✓ Login Successful!');
+        console.log('[TwinBot Channels] WhatsApp session is now explicitly linked.');
+        console.log('[TwinBot Channels] You may now close this setup screen.');
+        console.log('\nNext Steps:');
+        console.log('1. Run `node src/index.ts doctor` to verify channel readiness.');
+        console.log('2. Ensure your number is authorized per DM Pairing Policy.');
+        // Clean exit
+        void client.destroy().then(() => {
+            process.exit(0);
+        });
+    });
+    client.on('authenticated', () => {
+        console.log('[TwinBot Channels] Authentication state captured. Finalizing session mapping...');
+    });
+    client.on('auth_failure', (msg) => {
+        console.error(`\n[TwinBot Channels] ✗ Authentication Failed: ${msg}`);
+        console.error('[TwinBot Channels] Remediation: Try deleting the ./memory/whatsapp_auth directory and run `channels login whatsapp` again.');
+        process.exitCode = 1;
+        void client.destroy().then(() => {
+            process.exit(1);
+        });
+    });
+    try {
+        await client.initialize();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\n[TwinBot Channels] ✗ Client initialization failed: ${message}`);
+        process.exitCode = 1;
+    }
+}
+/**
+ * Handle \`channels\` CLI commands.
+ */
+export async function handleChannelsCli(argv) {
+    const topCommand = argv[0];
+    if (topCommand !== 'channels') {
+        return false;
+    }
+    const subcommand = argv[1];
+    const target = argv[2];
+    if (subcommand === 'login' && target === 'whatsapp') {
+        // Fire and forget because runWhatsappLogin manages process.exit internally
+        void runWhatsappLogin();
+        return true;
+    }
+    printUsage();
+    process.exitCode = 1;
+    return true;
+}

package/dist/core/cli.js

@@ -0,0 +1,119 @@
+import { runDoctorChecks, formatDoctorReport } from './doctor.js';
+// ── Help text ────────────────────────────────────────────────────────────────
+const HELP_TEXT = `
+Usage: twinbot [command] [options]
+
+Commands:
+  start               Start the TwinBot gateway runtime
+  doctor              Run diagnostics and validate prerequisites
+  onboard             Run the interactive onboarding wizard (twinbot.json)
+  install             One-command Windows bootstrap + optional onboarding handoff
+  setup               Run the guided configuration wizard
+  pairing             Manage DM pairing approvals (list/approve)
+  secret <subcommand> Manage secrets in the secure vault
+  channels <subcmd>   Manage messaging channels (e.g. login)
+  gateway <subcmd>    Manage the TwinBot background service daemon
+  logs [--follow]     Stream daily structured memory logs from the daemon
+  --onboard           Run the interactive AI persona-building session
+
+Options:
+  --help, -h          Show this help message
+  --json              Output in machine-readable JSON format (doctor only)
+
+Examples:
+  twinbot start
+  twinbot doctor
+  twinbot doctor --json
+  twinbot onboard
+  twinbot setup
+  twinbot pairing list telegram
+  twinbot pairing approve telegram ABCD1234
+  twinbot secret list
+  twinbot secret set API_SECRET mysecret
+  twinbot secret rotate API_SECRET newsecret
+  twinbot secret revoke API_SECRET
+  twinbot secret doctor
+  twinbot gateway install
+  twinbot gateway status
+  twinbot gateway status --deep
+  twinbot gateway restart
+  twinbot gateway tailscale
+  twinbot logs --follow
+`.trim();
+// ── Command handlers ─────────────────────────────────────────────────────────
+/**
+ * Handle the `doctor` command.
+ * Runs all diagnostic checks and emits a report.
+ * Returns `true` when the command was recognized and handled.
+ */
+export function handleDoctorCli(argv) {
+    if (argv[0] !== 'doctor')
+        return false;
+    const asJson = argv.includes('--json');
+    try {
+        const report = runDoctorChecks();
+        const output = formatDoctorReport(report, asJson);
+        console.log(output);
+        if (report.status === 'critical') {
+            process.exitCode = 2;
+        }
+        else if (report.status === 'degraded') {
+            process.exitCode = 1;
+        }
+        else {
+            process.exitCode = 0;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[TwinBot] Doctor check failed: ${message}`);
+        process.exitCode = 1;
+    }
+    return true;
+}
+/**
+ * Handle `--help` or `-h` flags.
+
+ * Returns `true` when the flag was found.
+ */
+export function handleHelpCli(argv) {
+    if (!argv.includes('--help') && !argv.includes('-h'))
+        return false;
+    console.log(HELP_TEXT);
+    process.exitCode = 0;
+    return true;
+}
+/**
+ * Guard against unknown or mistyped top-level commands.
+ * Known commands are allowed to fall through to their own handlers.
+ * Returns `true` and sets a non-zero exit code when an unknown command is detected.
+ */
+export function handleUnknownCommand(argv) {
+    if (argv.length === 0)
+        return false;
+    const command = argv[0];
+    // Flags and known commands pass through
+    const KNOWN_COMMANDS = new Set([
+        'pairing',
+        'secret',
+        'doctor',
+        'start',
+        'onboard',
+        'install',
+        'setup',
+        'channels',
+        'gateway',
+        'logs',
+        '--onboard',
+        '--help',
+        '-h',
+        '--json',
+    ]);
+    if (KNOWN_COMMANDS.has(command) || command.startsWith('--')) {
+        return false;
+    }
+    console.error(`[TwinBot] Unknown command: '${command}'`);
+    console.error(`Run 'twinbot --help' to see available commands.`);
+    process.exitCode = 1;
+    return true;
+}

package/dist/core/context-assembly.js

@@ -0,0 +1,33 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getIdentityDir } from '../config/workspace.js';
+export async function assembleContext(additionalRuntimeContext = '') {
+    let soul = '';
+    let identity = '';
+    let user = '';
+    const identityDir = getIdentityDir();
+    const readOptionalFile = async (fileName) => {
+        try {
+            const filePath = path.join(identityDir, fileName);
+            return await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            return '';
+        }
+    };
+    soul = await readOptionalFile('soul.md');
+    identity = await readOptionalFile('identity.md');
+    user = await readOptionalFile('user.md');
+    const compiled = `
+You are TwinBot. Follow your core directives exactly.
+
+${soul ? `### CORE SOUL & DIRECTIVES\n${soul}` : ''}
+
+${identity ? `### IDENTITY & PERSONA\n${identity}` : ''}
+
+${user ? `### USER PREFERENCES\n${user}` : ''}
+
+${additionalRuntimeContext ? `### ADDITIONAL CONTEXT (RAG MEMORY)\n${additionalRuntimeContext}` : ''}
+  `.trim();
+    return compiled;
+}