@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/ScopeVerifier.js

@@ -0,0 +1,350 @@
+/**
+ * ScopeVerifier — Pre-action scope verification for agents.
+ *
+ * Before high-risk actions (deployment, git push, external API calls),
+ * the agent pauses to verify: "Am I in the right project? Does this
+ * action match my identity and mission?"
+ *
+ * Born from the Luna incident (2026-02-25): An agent deployed to the
+ * wrong production target because nothing validated that the intended
+ * action matched the agent's current context.
+ *
+ * Design principle: Not a dumb pattern match — an intelligent
+ * self-verification that gives the agent the ability to step back,
+ * review what it's doing, and catch incoherence before it manifests.
+ *
+ * Three verification levels:
+ * 1. Structural — git remote, working directory, project name match
+ * 2. Contextual — action aligns with current topic/conversation scope
+ * 3. Intent — action aligns with stated mission/boundaries in AGENT.md
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+export class ScopeVerifier {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Run a full coherence check for a proposed action.
+     */
+    check(action, context) {
+        const checks = [];
+        // Check 1: Working directory matches expected project
+        checks.push(this.checkWorkingDirectory());
+        // Check 2: Git remote matches expected project
+        checks.push(this.checkGitRemote());
+        // Check 3: If topic is specified, verify topic-project alignment
+        if (context?.topicId) {
+            checks.push(this.checkTopicProjectAlignment(context.topicId));
+        }
+        // Check 4: If deploying, verify deployment target
+        if ((action === 'deploy' || action === 'production-change') && context?.targetUrl) {
+            checks.push(this.checkDeploymentTarget(context.targetUrl, context.topicId));
+        }
+        // Check 5: If modifying files, verify path is within project scope
+        if (context?.targetPath) {
+            checks.push(this.checkPathScope(context.targetPath));
+        }
+        // Check 6: Agent identity consistency
+        checks.push(this.checkAgentIdentity());
+        // Determine overall result
+        const hasErrors = checks.some(c => !c.passed && c.severity === 'error');
+        const hasWarnings = checks.some(c => !c.passed && c.severity === 'warning');
+        const passed = !hasErrors;
+        const recommendation = hasErrors ? 'block' : hasWarnings ? 'warn' : 'proceed';
+        const failedChecks = checks.filter(c => !c.passed);
+        const summary = passed
+            ? `All ${checks.length} coherence checks passed.`
+            : `${failedChecks.length}/${checks.length} checks failed: ${failedChecks.map(c => c.message).join('; ')}`;
+        return {
+            passed,
+            checks,
+            summary,
+            recommendation,
+            checkedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Generate a self-verification prompt for the agent to reflect before acting.
+     * This is the "step back and review" mechanism.
+     */
+    generateReflectionPrompt(action, context) {
+        const result = this.check(action, context);
+        const lines = [];
+        lines.push('=== PRE-ACTION COHERENCE CHECK ===');
+        lines.push('');
+        lines.push('Before proceeding, verify these assertions are correct:');
+        lines.push('');
+        // Identity
+        lines.push(`1. I am working on: ${this.config.projectName}`);
+        lines.push(`   Project directory: ${this.config.projectDir}`);
+        // Git
+        const gitRemote = this.detectGitRemote();
+        if (gitRemote) {
+            lines.push(`   Git remote: ${gitRemote}`);
+        }
+        // Topic context
+        if (context?.topicId && context?.topicName) {
+            const binding = this.getTopicBinding(context.topicId);
+            if (binding) {
+                lines.push(`2. This topic (${context.topicName}) is for: ${binding.projectName}`);
+                lines.push(`   Expected project dir: ${binding.projectDir}`);
+            }
+            else {
+                lines.push(`2. This topic (${context.topicName}) has NO project binding.`);
+                lines.push(`   WARNING: Verify which project this topic is for before proceeding.`);
+            }
+        }
+        // Action
+        lines.push('');
+        lines.push(`Action: ${action}`);
+        if (context?.description) {
+            lines.push(`Description: ${context.description}`);
+        }
+        if (context?.targetUrl) {
+            lines.push(`Target URL: ${context.targetUrl}`);
+        }
+        if (context?.targetPath) {
+            lines.push(`Target path: ${context.targetPath}`);
+        }
+        // Check results
+        if (!result.passed) {
+            lines.push('');
+            lines.push('WARNING — COHERENCE ISSUES DETECTED:');
+            for (const check of result.checks.filter(c => !c.passed)) {
+                const icon = check.severity === 'error' ? '[BLOCK]' : '[WARN]';
+                lines.push(`  ${icon} ${check.message}`);
+                lines.push(`    Expected: ${check.expected}`);
+                lines.push(`    Found: ${check.actual}`);
+            }
+        }
+        lines.push('');
+        lines.push('If any of the above is incorrect, STOP and verify before proceeding.');
+        lines.push('=== END COHERENCE CHECK ===');
+        return lines.join('\n');
+    }
+    /**
+     * Get the topic-project binding for a specific topic.
+     */
+    getTopicBinding(topicId) {
+        return this.config.topicProjects?.[String(topicId)] ?? null;
+    }
+    /**
+     * Register a topic-to-project binding.
+     */
+    setTopicBinding(topicId, binding) {
+        if (!this.config.topicProjects) {
+            this.config.topicProjects = {};
+        }
+        this.config.topicProjects[String(topicId)] = binding;
+        this.saveTopicBindings();
+    }
+    /**
+     * Load topic-project bindings from disk.
+     */
+    loadTopicBindings() {
+        const bindingsPath = path.join(this.config.stateDir, 'topic-project-bindings.json');
+        try {
+            if (fs.existsSync(bindingsPath)) {
+                const data = JSON.parse(fs.readFileSync(bindingsPath, 'utf-8'));
+                this.config.topicProjects = data;
+                return data;
+            }
+        }
+        catch {
+            // @silent-fallback-ok — corrupt bindings, empty map
+        }
+        return {};
+    }
+    /**
+     * Save topic-project bindings to disk.
+     */
+    saveTopicBindings() {
+        const bindingsPath = path.join(this.config.stateDir, 'topic-project-bindings.json');
+        fs.mkdirSync(path.dirname(bindingsPath), { recursive: true });
+        fs.writeFileSync(bindingsPath, JSON.stringify(this.config.topicProjects || {}, null, 2));
+    }
+    // ── Individual Checks ──────────────────────────────────────────
+    checkWorkingDirectory() {
+        let cwd;
+        try {
+            cwd = process.cwd();
+        }
+        catch {
+            cwd = 'unknown';
+        }
+        const expected = this.config.projectDir;
+        const isWithin = cwd.startsWith(expected);
+        return {
+            name: 'working-directory',
+            passed: isWithin,
+            expected: `Within ${expected}`,
+            actual: cwd,
+            severity: 'warning',
+            message: isWithin
+                ? `Working directory is within project scope`
+                : `Working directory (${cwd}) is outside project scope (${expected})`,
+        };
+    }
+    checkGitRemote() {
+        const actual = this.detectGitRemote();
+        const expected = this.config.expectedGitRemote;
+        // If no expected remote configured, just report what we found
+        if (!expected) {
+            return {
+                name: 'git-remote',
+                passed: true,
+                expected: 'any (no expected remote configured)',
+                actual: actual || 'no git remote',
+                severity: 'info',
+                message: actual ? `Git remote: ${actual}` : 'No git remote detected',
+            };
+        }
+        const matches = actual !== null && this.normalizeGitUrl(actual) === this.normalizeGitUrl(expected);
+        return {
+            name: 'git-remote',
+            passed: matches,
+            expected,
+            actual: actual || 'no git remote',
+            severity: 'error',
+            message: matches
+                ? `Git remote matches expected project`
+                : `Git remote MISMATCH: expected ${expected}, found ${actual || 'none'}`,
+        };
+    }
+    checkTopicProjectAlignment(topicId) {
+        const binding = this.getTopicBinding(topicId);
+        if (!binding) {
+            return {
+                name: 'topic-project-alignment',
+                passed: false,
+                expected: `Topic ${topicId} bound to a specific project`,
+                actual: 'No topic-project binding exists',
+                severity: 'warning',
+                message: `Topic ${topicId} has no project binding — verify which project this topic is for`,
+            };
+        }
+        // Check if current project matches the topic's expected project
+        const currentProject = this.config.projectDir;
+        const expectedProject = binding.projectDir;
+        const matches = this.normalizePath(currentProject) === this.normalizePath(expectedProject);
+        return {
+            name: 'topic-project-alignment',
+            passed: matches,
+            expected: `${binding.projectName} (${expectedProject})`,
+            actual: `${this.config.projectName} (${currentProject})`,
+            severity: 'error',
+            message: matches
+                ? `Topic is correctly bound to ${binding.projectName}`
+                : `WRONG PROJECT: Topic ${topicId} is for ${binding.projectName} but current project is ${this.config.projectName}`,
+        };
+    }
+    checkDeploymentTarget(targetUrl, topicId) {
+        // If we have a topic binding with deployment targets, check against those
+        if (topicId) {
+            const binding = this.getTopicBinding(topicId);
+            if (binding?.deploymentTargets && binding.deploymentTargets.length > 0) {
+                const allowed = binding.deploymentTargets.some(t => targetUrl.includes(t) || t.includes(targetUrl));
+                return {
+                    name: 'deployment-target',
+                    passed: allowed,
+                    expected: binding.deploymentTargets.join(', '),
+                    actual: targetUrl,
+                    severity: 'error',
+                    message: allowed
+                        ? `Deployment target matches project configuration`
+                        : `WRONG DEPLOY TARGET: ${targetUrl} is not in allowed targets for ${binding.projectName}`,
+                };
+            }
+        }
+        // No specific check possible without bindings
+        return {
+            name: 'deployment-target',
+            passed: true,
+            expected: 'any (no deployment targets configured)',
+            actual: targetUrl,
+            severity: 'warning',
+            message: `Deploying to ${targetUrl} — no deployment target restrictions configured`,
+        };
+    }
+    checkPathScope(targetPath) {
+        const resolvedPath = path.resolve(targetPath);
+        const projectDir = path.resolve(this.config.projectDir);
+        const isWithin = resolvedPath.startsWith(projectDir);
+        return {
+            name: 'path-scope',
+            passed: isWithin,
+            expected: `Within ${projectDir}`,
+            actual: resolvedPath,
+            severity: 'error',
+            message: isWithin
+                ? `Target path is within project scope`
+                : `PATH OUTSIDE PROJECT: ${resolvedPath} is outside ${projectDir}`,
+        };
+    }
+    checkAgentIdentity() {
+        const agentMdPath = path.join(this.config.stateDir, 'AGENT.md');
+        if (!fs.existsSync(agentMdPath)) {
+            return {
+                name: 'agent-identity',
+                passed: false,
+                expected: 'AGENT.md exists with identity',
+                actual: 'AGENT.md not found',
+                severity: 'warning',
+                message: 'No AGENT.md found — agent identity not established',
+            };
+        }
+        try {
+            const content = fs.readFileSync(agentMdPath, 'utf-8');
+            const hasName = /^#\s+.+/m.test(content);
+            const hasIntent = /##\s+Intent/i.test(content);
+            return {
+                name: 'agent-identity',
+                passed: hasName,
+                expected: 'AGENT.md with name and intent',
+                actual: `Name: ${hasName ? 'yes' : 'no'}, Intent: ${hasIntent ? 'yes' : 'no'}`,
+                severity: hasName ? 'info' : 'warning',
+                message: hasName
+                    ? `Agent identity established${hasIntent ? ' with intent section' : ''}`
+                    : 'AGENT.md exists but has no agent name',
+            };
+        }
+        catch {
+            return {
+                name: 'agent-identity',
+                passed: false,
+                expected: 'Readable AGENT.md',
+                actual: 'Failed to read AGENT.md',
+                severity: 'warning',
+                message: 'Failed to read AGENT.md',
+            };
+        }
+    }
+    // ── Helpers ──────────────────────────────────────────
+    detectGitRemote() {
+        try {
+            return execFileSync('git', ['remote', 'get-url', 'origin'], {
+                cwd: this.config.projectDir,
+                encoding: 'utf-8',
+                stdio: 'pipe',
+            }).trim() || null;
+        }
+        catch {
+            // @silent-fallback-ok — git remote detection
+            return null;
+        }
+    }
+    normalizeGitUrl(url) {
+        return url
+            .replace(/\.git$/, '')
+            .replace(/^https:\/\/github\.com\//, '')
+            .replace(/^git@github\.com:/, '')
+            .toLowerCase();
+    }
+    normalizePath(p) {
+        return path.resolve(p).replace(/\/+$/, '');
+    }
+}
+//# sourceMappingURL=ScopeVerifier.js.map

package/dist/core/ScopeVerifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeVerifier.js","sourceRoot":"","sources":["../../src/core/ScopeVerifier.ts"],"names":[],"mappings":"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"}

package/dist/core/SecretManager.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Unified Secret Manager — single interface for all secret backends.
+ *
+ * Routes secret operations to the configured backend:
+ *   1. Bitwarden (recommended) — cross-machine, cloud-backed
+ *   2. Local encrypted store (fallback) — survives repo nukes on same machine
+ *   3. Manual (no backend) — user pastes secrets when prompted
+ *
+ * The backend preference is stored in ~/.instar/secrets/backend.json
+ * so it persists across agent installs.
+ *
+ * Usage:
+ *   const mgr = new SecretManager('my-agent');
+ *   await mgr.initialize();  // auto-detects or prompts for backend
+ *   const token = mgr.get('telegram-token');
+ *   mgr.set('telegram-token', 'bot123:ABC');
+ */
+export type SecretBackend = 'bitwarden' | 'local' | 'manual';
+export interface SecretManagerConfig {
+    /** Agent name (scopes secrets) */
+    agentName: string;
+    /** Override the backend (skip auto-detection) */
+    backend?: SecretBackend;
+    /** Override the secrets base directory (for testing) */
+    basePath?: string;
+}
+export interface BackendPreference {
+    backend: SecretBackend;
+    /** When the preference was set */
+    configuredAt: string;
+    /** Bitwarden email (if applicable) */
+    bitwardenEmail?: string;
+}
+/** Standard secret keys used across Instar. */
+export declare const SECRET_KEYS: {
+    readonly TELEGRAM_TOKEN: "telegram-token";
+    readonly TELEGRAM_CHAT_ID: "telegram-chat-id";
+    readonly AUTH_TOKEN: "auth-token";
+    readonly DASHBOARD_PIN: "dashboard-pin";
+    readonly TUNNEL_TOKEN: "tunnel-token";
+};
+export declare class SecretManager {
+    private agentName;
+    private backend;
+    private bitwarden;
+    private localStore;
+    private initialized;
+    private secretsDir;
+    private backendFile;
+    private basePath?;
+    constructor(config: SecretManagerConfig);
+    /**
+     * Initialize the secret manager.
+     * Loads the backend preference and connects to the chosen backend.
+     * Returns the active backend type.
+     */
+    initialize(): SecretBackend;
+    /**
+     * Configure the backend and save the preference.
+     */
+    configureBackend(backend: SecretBackend, options?: {
+        bitwardenEmail?: string;
+    }): void;
+    /**
+     * Get a secret by key.
+     * Tries the configured backend, falls back through the chain.
+     */
+    get(key: string): string | null;
+    /**
+     * Set a secret.
+     * Writes to the configured backend AND the local store (as backup).
+     */
+    set(key: string, value: string): boolean;
+    /**
+     * Check if a secret exists in any backend.
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a secret from all backends.
+     */
+    delete(key: string): void;
+    /**
+     * Get all secrets for this agent from the active backend.
+     */
+    getAll(): Record<string, string>;
+    /**
+     * Backup all config secrets to the secret store.
+     * Called before nuke/uninstall to preserve secrets for reinstall.
+     */
+    backupFromConfig(config: {
+        telegramToken?: string;
+        telegramChatId?: string;
+        authToken?: string;
+        dashboardPin?: string;
+        tunnelToken?: string;
+    }): void;
+    /**
+     * Restore Telegram config from the secret store.
+     * Returns null if no secrets found.
+     */
+    restoreTelegramConfig(): {
+        token: string;
+        chatId: string;
+    } | null;
+    /** Get the active backend type. */
+    getBackend(): SecretBackend;
+    /** Get the saved backend preference. */
+    getPreference(): BackendPreference | null;
+    /** Whether any backend is configured (not 'manual'). */
+    isConfigured(): boolean;
+    /** Whether Bitwarden is ready to use. */
+    isBitwardenReady(): boolean;
+    private getFromBackend;
+    private getFromLocal;
+    private setToLocal;
+    private getAllFromLocal;
+    private ensureInitialized;
+    private loadPreference;
+}
+//# sourceMappingURL=SecretManager.d.ts.map

package/dist/core/SecretManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SecretManager.d.ts","sourceRoot":"","sources":["../../src/core/SecretManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,aAAa,CAAC;IACvB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,+CAA+C;AAC/C,eAAO,MAAM,WAAW;;;;;;CAMd,CAAC;AAIX,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,SAAS,CAAkC;IACnD,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,CAAS;gBAEd,MAAM,EAAE,mBAAmB;IAYvC;;;;OAIG;IACH,UAAU,IAAI,aAAa;IA6B3B;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAwBrF;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAgB/B;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IA6BxC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAoBzB;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAqBhC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE;QACvB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,IAAI;IAUR;;;OAGG;IACH,qBAAqB,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAajE,mCAAmC;IACnC,UAAU,IAAI,aAAa;IAI3B,wCAAwC;IACxC,aAAa,IAAI,iBAAiB,GAAG,IAAI;IAIzC,wDAAwD;IACxD,YAAY,IAAI,OAAO;IAIvB,yCAAyC;IACzC,gBAAgB,IAAI,OAAO;IAU3B,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,cAAc;CASvB"}