@cstack-protocol/pingala 1.0.0

package/src/index.ts

@@ -0,0 +1,562 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { csAuditTool } from "./tools/cs-audit.js";
+import { validateStackChangeTool } from "./tools/validate-stack-change.js";
+import { getGovernanceContextTool } from "./tools/get-governance-context.js";
+import { calculateCsiTool } from "./tools/calculate-csi.js";
+import { analyzeStackTool } from "./tools/analyze-stack.js";
+import { MethodologyLoader } from "./core/methodology.js";
+import { Governor } from "./core/governor.js";
+import { PingalaEngine } from "./core/pingala.js";
+import { initPingalaTelemetry, getRegistryMode } from "./core/sdk-adapter.js";
+import process from "node:process";
+import { z } from "zod";
+import express from "express";
+import cors from "cors";
+
+// Load .env variables natively if available (Node v20.6+)
+try {
+    (process as any).loadEnvFile();
+} catch (e) {
+    // .env file missing or not supported, move on
+}
+
+/**
+ * CSTACK MCP Server (Powered by Pingala)
+ * 
+ * The governance layer for the Conscious Stack ecosystem.
+ * Enforces the 5:3:1 Protocol and provides diagnostic tools.
+ */
+const server = new McpServer({
+    name: "cstack-mcp",
+    version: "0.4.5-cloud",
+});
+
+// Initialize Telemetry for Cloud Mode
+try {
+    initPingalaTelemetry('contributor');
+} catch (e) {
+    console.error("[Pingala] Telemetry initialization failed (likely missing SDK)", e);
+}
+
+// Load methodology for dynamic description
+const rules = MethodologyLoader.load531Rules();
+const protocolDesc = rules.rawDescription || "1 Anchor, 3 Active, 5 Supporting";
+
+// Register Tools
+server.tool(
+    csAuditTool.name,
+    `${csAuditTool.description} (Protocol Rule: ${protocolDesc})`,
+    csAuditTool.schema,
+    csAuditTool.handler
+);
+
+server.tool(
+    validateStackChangeTool.name,
+    validateStackChangeTool.description,
+    validateStackChangeTool.schema as any,
+    validateStackChangeTool.handler
+);
+
+server.tool(
+    getGovernanceContextTool.name,
+    getGovernanceContextTool.description,
+    getGovernanceContextTool.schema,
+    getGovernanceContextTool.handler
+);
+
+server.tool(
+    calculateCsiTool.name,
+    calculateCsiTool.description,
+    calculateCsiTool.schema as any,
+    calculateCsiTool.handler
+);
+
+server.tool(
+    analyzeStackTool.name,
+    analyzeStackTool.description,
+    analyzeStackTool.schema as any,
+    analyzeStackTool.handler
+);
+
+// Register Resources
+server.resource(
+    "current-stack",
+    "cstack://stack-map/current",
+    {
+        description: "The current 5:3:1 hierarchy of tools",
+        mimeType: "application/json"
+    },
+    async (uri: URL) => {
+        const stack = Governor.getStack();
+        return {
+            contents: [{
+                uri: uri.href,
+                text: JSON.stringify({
+                    anchor: stack.find(t => t.role === 'Anchor') || null,
+                    active: stack.filter(t => t.role === 'Active'),
+                    supporting: stack.filter(t => t.role === 'Supporting')
+                }, null, 2)
+            }]
+        };
+    }
+);
+
+server.resource(
+    "maturity-status",
+    "cstack://maturity/status",
+    {
+        description: "Current maturity level and days of stability",
+        mimeType: "application/json"
+    },
+    async (uri: URL) => {
+        const state = Governor.getMaturityState();
+        return {
+            contents: [{
+                uri: uri.href,
+                text: JSON.stringify(state, null, 2)
+            }]
+        };
+    }
+);
+
+server.resource(
+    "latest-csi",
+    "cstack://csi/latest",
+    {
+        description: "Current Conscious Stack Index (CSI) with component breakdown",
+        mimeType: "application/json"
+    },
+    async (uri: URL) => {
+        const stack = Governor.getStack();
+        const diagnosis = await PingalaEngine.diagnose({ tools: stack });
+        return {
+            contents: [{
+                uri: uri.href,
+                text: JSON.stringify(diagnosis, null, 2)
+            }]
+        };
+    }
+);
+
+server.resource(
+    "stack-drift",
+    "cstack://drift/current",
+    {
+        description: "Current architectural drift signals and score",
+        mimeType: "application/json"
+    },
+    async (uri: URL) => {
+        const drift = Governor.getStackDriftScore();
+        return {
+            contents: [{
+                uri: uri.href,
+                text: JSON.stringify(drift, null, 2)
+            }]
+        };
+    }
+);
+
+// Register Prompts
+server.prompt(
+    "inject-constraints",
+    {
+        base_prompt: z.string().describe("The user's original request")
+    },
+    async (args) => {
+        const stack = Governor.getStack();
+        const state = Governor.getMaturityState();
+        const diagnosis = await PingalaEngine.diagnose({ tools: stack });
+        const context = Governor.getGovernanceContext();
+        const mode = getRegistryMode();
+
+        const modeFlag = mode === 'Authorized' ? 'COLLECTIVE MODE (Authorized)' : 'SOVEREIGN MODE (Local-First)';
+        const connectionDetails = mode === 'Authorized'
+            ? 'Connected to patterns.consciousstack.com (Live Registry)'
+            : 'Using local patterns and public registry fallback.';
+
+        return {
+            messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `GOVERNANCE CONTEXT [${modeFlag}]:
+- Functional Nodes: ${JSON.stringify(context.functional_nodes)}
+- Maturity Level: ${state.level} (${state.level_name}) - ${state.stability_days} days stable
+- CSI Score: ${diagnosis.csi_score} [${diagnosis.risk_band}] (Blended: SDK Logic + Fragmentation)
+- CSI Delta: ${context.progression.csi_delta > 0 ? '+' : ''}${context.progression.csi_delta}
+- SDK Violations: ${diagnosis.protocol_analysis.violations.length > 0 ? diagnosis.protocol_analysis.violations.join('; ') : 'None'}
+- Allowed Actions: ${context.allowed_actions.join(", ")}
+- Blocked Actions: ${context.blocked_actions.join(", ")}
+
+REGISTRY & MOAT:
+- Status: ${connectionDetails}
+- Data Moat: ${mode === 'Authorized' ? 'ACTIVE (Contributing anonymized signals)' : 'PENDING (Key required for contribution)'}
+- Privacy Guard: Tool names are NEVER captured, only Categories (e.g., 'Productivity').
+
+CONSTRAINTS (Horizon 1.5 - Functional Scaling):
+- 5:3:1 Protocol: Max 1 Anchor Node, 3 Active Nodes, 5 Supporting Nodes (9 Functional Slots Total).
+- Subtraction over addition: Always explore removal before addition.
+- CSI threshold: No destabilizing changes if CSI < 70.
+- Maturity gate: Level ${state.level} requires specific stability before expansion (${context.progression.days_remaining} days remaining).
+
+INSTRUCTIONS:
+1. Review 'SDK Violations' first. These represent specific Failure Patterns (e.g., 'Anchor Void') from the registry.
+2. If tool changes are requested, call validate_stack_change() immediately.
+3. ADAPTER RECOGNITION (Horizon 1.5): If a user provides a flat list of apps, identify if any serve the same function across different devices (e.g., 'Chrome (mobile)' and 'Chrome (desktop)'). 
+   - Cluster these into a single 'functionId' (e.g., 'browser').
+   - Tag device-specific versions with 'contexts' and 'isAdapter: true'.
+   - The MCP now auto-detects these, but your hints improve precision.
+4. PROTOCOL HANDSHAKE: If in COLLECTIVE MODE and you detect a significant CSI shift or a novel pattern match, inform the user: "Significant stack shift detected. Signal buffered for collective intelligence."
+5. Your goal: High Resonance (CSI > 85). Minimize Fragmentation and maximize Decision Provenance.
+
+USER REQUEST:
+${args.base_prompt}`
+                }
+            }]
+        };
+    }
+);
+
+server.prompt(
+    "canonical-output",
+    {
+        analysis_type: z.enum(["audit", "mirror", "zoning"]).describe("Type of analysis being performed")
+    },
+    async (args) => {
+        return {
+            messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Respond using the Pingala canonical structure for ${args.analysis_type}:
+
+## 1. Target State
+[Define desired operating condition with specific metrics]
+
+## 2. Current State
+[Summarize present signals from stack, CSI, telemetry]
+
+## 3. Recommendations
+[3-5 actionable changes tied to Target State]
+
+## 4. Guardrails
+[Rules that prevent erosion]
+
+## 5. Workflow Improvements
+[Concrete protocol changes]
+
+## 6. Crystalline Geometry
+[Identify hex/cubic patterns and evolution path]
+
+## 7. Additional Info
+[Assumptions, caveats, telemetry notes]`
+                }
+            }]
+        };
+    }
+);
+
+server.prompt(
+    "augmentation-only",
+    {
+        decision_context: z.string().describe("What decision needs to be made")
+    },
+    async (args) => {
+        return {
+            messages: [{
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `AUGMENTATION MODE ACTIVE
+
+Your role: Provide analysis and options
+Human's role: Make final decision and own the outcome
+
+Decision context: ${args.decision_context}
+
+Provide:
+1. Key factors to consider
+2. 2-3 options with tradeoffs
+3. Data/evidence supporting each option
+4. Potential risks and mitigations
+
+Do NOT:
+- Make the decision for the human
+- Use language like 'you should' or 'I recommend'
+- Provide a single answer without alternatives
+
+End with: 'What do you decide?'`
+                }
+            }]
+        };
+    }
+);
+
+import { validateToken } from "./core/auth.js";
+
+const app = express();
+app.use(cors());
+
+let transport: SSEServerTransport | null = null;
+
+// Apply auth only to MCP endpoints (keep / public for landing page)
+app.use("/sse", validateToken);
+app.use("/messages", validateToken);
+
+app.get("/", (req: any, res: any) => {
+    res.send(`
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>Pingala MCP | Conscious Stack</title>
+            <link rel="preconnect" href="https://fonts.googleapis.com">
+            <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+            <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&family=Outfit:wght@300;600&display=swap" rel="stylesheet">
+            <style>
+                :root {
+                    --bg: #0a0a0c;
+                    --fg: #e2e2e4;
+                    --accent: #9a86fd;
+                    --glass: rgba(255, 255, 255, 0.05);
+                }
+                body {
+                    margin: 0;
+                    padding: 0;
+                    background: var(--bg);
+                    color: var(--fg);
+                    font-family: 'Inter', sans-serif;
+                    display: flex;
+                    flex-direction: column;
+                    align-items: center;
+                    justify-content: center;
+                    min-height: 100vh;
+                    overflow: hidden;
+                }
+                .container {
+                    text-align: center;
+                    z-index: 10;
+                    padding: 2rem;
+                    background: var(--glass);
+                    backdrop-filter: blur(20px);
+                    border: 1px solid rgba(255, 255, 255, 0.1);
+                    border-radius: 24px;
+                    max-width: 600px;
+                }
+                h1 {
+                    font-family: 'Outfit', sans-serif;
+                    font-size: 3rem;
+                    margin: 0;
+                    background: linear-gradient(135deg, #fff 0%, var(--accent) 100%);
+                    -webkit-background-clip: text;
+                    -webkit-text-fill-color: transparent;
+                }
+                p {
+                    color: #a1a1aa;
+                    line-height: 1.6;
+                    margin: 1.5rem 0;
+                }
+                .details {
+                    text-align: left;
+                    background: rgba(0,0,0,0.3);
+                    padding: 1.5rem;
+                    border-radius: 12px;
+                    margin-top: 2rem;
+                    font-family: monospace;
+                    font-size: 0.9rem;
+                    border-left: 4px solid var(--accent);
+                }
+                .glow {
+                    position: absolute;
+                    width: 600px;
+                    height: 600px;
+                    background: radial-gradient(circle, rgba(154, 134, 253, 0.15) 0%, transparent 70%);
+                    top: 50%;
+                    left: 50%;
+                    transform: translate(-50%, -50%);
+                    z-index: 1;
+                }
+            </style>
+        </head>
+        <body>
+            <div class="glow"></div>
+            <div class="container">
+                <h1>Pingala MCP</h1>
+                <p>Architectural Guardrails for AI Autonomy.<br>The first AI<>Human Co-Governance Layer.</p>
+                <div class="details">
+                    <strong>Endpoint:</strong> mcp.consciousstack.com/sse<br>
+                    <strong>Transport:</strong> SSE (Server-Sent Events)<br>
+                    <strong>Auth:</strong> Bearer Token Required
+                </div>
+                <p style="font-size: 0.8rem; opacity: 0.5; margin-top: 2rem;">&copy; 2026 Conscious Stack Protocol</p>
+            </div>
+        </body>
+        </html>
+    `);
+});
+
+app.get("/sse", async (req: any, res: any) => {
+    // Thread the token into the message endpoint so POSTs are automatically authorized
+    const token = req.query.token || (req.headers.authorization?.startsWith("Bearer ") ? req.headers.authorization.split(" ")[1] : null);
+    const messageEndpoint = token ? `/messages?token=${token}` : "/messages";
+
+    transport = new SSEServerTransport(messageEndpoint as any, res);
+    await server.connect(transport);
+});
+
+app.post("/messages", async (req: any, res: any) => {
+    if (transport) {
+        try {
+            await transport.handlePostMessage(req, res);
+        } catch (e: any) {
+            console.error("[SSE] Post message error:", e.message);
+            res.status(500).send(e.message);
+        }
+    } else {
+        console.warn("[SSE] Message received but no active transport found. Vercel lambda likely recycled.");
+        res.status(400).send("No active SSE connection. Please reconnect.");
+    }
+});
+
+const PORT = process.env.PORT || 3000;
+
+
+// CLI COMMANDS
+// Only run these if arguments are provided
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command) {
+    handleCliCommand(command, args.slice(1));
+} else {
+    // Only listen if not running as a Vercel serverless function AND no CLI command
+    if (process.env.NODE_ENV !== 'production' || !process.env.VERCEL) {
+        app.listen(PORT, () => {
+            console.log(`Pingala MCP Cloud Server running on port ${PORT}`);
+            console.log(`SSE endpoint: /sse`);
+            console.log(`Messages endpoint: /messages`);
+        });
+    }
+}
+
+async function handleCliCommand(cmd: string, opts: string[]) {
+    try {
+        switch (cmd) {
+            case 'audit':
+                await runAudit();
+                break;
+            case 'setup-claude':
+                await runSetupClaude();
+                break;
+            case 'config':
+                await runConfig(opts);
+                break;
+            default:
+                console.error(`Unknown command: ${cmd}`);
+                console.log(`Available commands: audit, setup-claude, config`);
+                process.exit(1);
+        }
+    } catch (error) {
+        console.error("Error executing command:", error);
+        process.exit(1);
+    }
+    // Explicit exit after CLI command
+    process.exit(0);
+}
+
+async function runAudit() {
+    console.log("🔍 Pingala: Starting local sovereignty audit...");
+
+    // Force local detection
+    const stack = Governor.getStack();
+    const result = (await csAuditTool.handler({ path: process.cwd() } as any)) as any;
+
+    // Parse result from tool output
+    const content = result.content[0].text;
+    console.log("\n" + content);
+
+    // Add "Next Steps" hook
+    console.log("\n---------------------------------------------------------");
+    console.log("🚀 Want to track this over time and get pattern matching?");
+    console.log("   Run: npx @cstack-protocol/pingala config set-key <YOUR_CSTACK_API_KEY>");
+    console.log("   Get a key at: https://api.consciousstack.com");
+    console.log("---------------------------------------------------------");
+}
+
+async function runSetupClaude() {
+    const fs = await import('fs');
+    const path = await import('path');
+    const os = await import('os');
+
+    console.log("🤖 Pingala: Configuring Claude Desktop...");
+
+    const configPath = path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    let config: any = { mcpServers: {} };
+
+    if (fs.existsSync(configPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        } catch (e) {
+            console.warn("Could not parse existing config, creating new.");
+        }
+    } else {
+        // Ensure directory exists
+        const dir = path.dirname(configPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    }
+
+    // Try to find API Key
+    let apiKey = process.env.CSTACK_API_KEY;
+    if (!apiKey) {
+        const homeConfig = path.join(os.homedir(), '.cstackrc');
+        if (fs.existsSync(homeConfig)) {
+            const content = fs.readFileSync(homeConfig, 'utf8');
+            const match = content.match(/CSTACK_API_KEY=(.*)/);
+            if (match) apiKey = match[1].trim();
+        }
+    }
+
+    // Add Pingala
+    config.mcpServers["pingala"] = {
+        command: "npx",
+        args: ["-y", "@cstack-protocol/pingala@latest"],
+        env: {
+            "CSTACK_API_KEY": apiKey || ""
+        }
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    console.log(`✅ Successfully updated ${configPath}`);
+
+    if (!apiKey) {
+        console.warn("\n⚠️  No API Key found. Your Pingala agent will run in local-only mode.");
+        console.log("   To enable cloud patterns: npx @cstack-protocol/pingala config set-key <KEY> && npx @cstack-protocol/pingala setup-claude");
+    } else {
+        console.log("   API Key injected successfully.");
+    }
+    console.log("   Please restart Claude Desktop to enable Pingala.");
+}
+
+async function runConfig(opts: string[]) {
+    if (opts[0] === 'set-key' && opts[1]) {
+        console.log(`🔑 Setting API Key: ${opts[1].substring(0, 8)}...`);
+        // In a real CLI, we might write to a local .env or config file in home dir
+        // For now, let's guide them to export it
+        console.log("To persist this, please add it to your environment variables:");
+        console.log(`export CSTACK_API_KEY=${opts[1]}`);
+
+        // Setup rudimentary dotfile persistence for the brave
+        const fs = await import('fs');
+        const path = await import('path');
+        const os = await import('os');
+        const homeConfig = path.join(os.homedir(), '.cstackrc');
+        fs.writeFileSync(homeConfig, `CSTACK_API_KEY=${opts[1]}`);
+        console.log(`   (Saved to ${homeConfig} for local tools)`);
+    } else {
+        console.log("Usage: config set-key <key>");
+    }
+}
+
+export default app;

package/src/test-l3.ts

@@ -0,0 +1,45 @@
+import { csAuditTool } from "./tools/cs-audit.js";
+import { MethodologyLoader } from "./core/methodology.js";
+import { ConsentManager } from "./core/consent-manager.js";
+import * as path from "node:path";
+
+async function test_l3_audit() {
+    process.env.CSTACK_AGENT_CORE_PATH = "/Users/georgesiosi/Documents/GitHub/conscious-stack/_active/cs-agent-core";
+    MethodologyLoader.init();
+
+    // Set workspace to the current active directory
+    const workspacePath = "/Users/georgesiosi/Documents/GitHub/conscious-stack/_active/cs-mcp-core";
+    ConsentManager.setWorkspace(workspacePath);
+
+    // Mock tool stack
+    const tools = [
+        { name: "FocusMonitor", role: "Anchor", functionId: "Tai Ji", category: "OS" },
+        { name: "Cursor", role: "Active", functionId: "Gen", category: "Development" },
+        { name: "Notion", role: "Active", functionId: "Qian", category: "Knowledge" },
+        { name: "Obsidian", role: "Active", functionId: "Dui", category: "Knowledge" },
+        { name: "Slack", role: "Supporting", functionId: "Li", category: "Communication" },
+        { name: "Linear", role: "Supporting", functionId: "Kan", category: "Task" }
+    ];
+
+    console.log("--- TEST 1: L3 Audit Without Consent ---");
+    const result1 = await csAuditTool.handler({
+        tools,
+        path: workspacePath,
+        depth_level: "L3"
+    });
+    console.log(JSON.stringify(result1, null, 2));
+
+    console.log("\n--- TEST 2: L3 Audit WITH CONSENT ---");
+    // Simulate user granting consent in the workspace
+    ConsentManager.setConsent("L2", true);
+    ConsentManager.setConsent("L3", true);
+
+    const result2 = await csAuditTool.handler({
+        tools,
+        path: workspacePath,
+        depth_level: "L3"
+    });
+    console.log(JSON.stringify(result2, null, 2));
+}
+
+test_l3_audit().catch(console.error);