@askance/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Advancer Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @askance/cli
+
+Tool call interception & approval management for AI coding agents.
+
+Askance hooks into your coding agent (Claude Code, Cursor, GitHub Copilot) and routes tool calls through policy rules and a cloud dashboard for approval — so agents can work while you review from any device.
+
+## Quick Start
+
+```bash
+npm install --save-dev @askance/cli
+npx askance init
+npx askance login
+# Restart your agent session
+```
+
+## What it does
+
+- **Hook handler** — intercepts tool calls before execution and evaluates them against your `.askance.yml` policy rules
+- **MCP server** — provides tools for the agent to wait for approvals and check for instructions
+- **CLI** — sets up config files and authenticates with the Askance cloud
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx askance init` | Set up hooks, MCP server, policy rules, and CLAUDE.md |
+| `npx askance login` | Authenticate via browser (GitHub, Google, or Microsoft) |
+| `npx askance template <name>` | Apply a policy template (`conservative`, `moderate`, `permissive`, `ci-safe`) |
+| `npx askance help` | Show usage information |
+
+### Init options
+
+```bash
+npx askance init            # Claude Code (default)
+npx askance init --cursor   # Cursor IDE
+npx askance init --copilot  # GitHub Copilot
+npx askance init --all      # All agents
+```
+
+## Policy rules
+
+Policy rules in `.askance.yml` control what happens when the agent uses a tool:
+
+- **allow** — tool call proceeds immediately
+- **gate** — queued for approval in the dashboard
+- **deny** — blocked automatically
+
+```yaml
+rules:
+  - name: "Allow read-only tools"
+    match:
+      tool: "^(Read|Glob|Grep|WebSearch)$"
+    action: allow
+
+  - name: "Gate file writes"
+    match:
+      tool: "^(Edit|Write)$"
+    action: gate
+    risk: medium
+
+  - name: "Deny destructive commands"
+    match:
+      tool: "^Bash$"
+      command: "(rm -rf|chmod 777)"
+    action: deny
+    risk: high
+```
+
+## Dashboard
+
+Manage approvals at [app.askance.app](https://app.askance.app) — approve, deny, or send instructions to your agent from any device.
+
+## Documentation
+
+Full docs at [askance.app/docs](https://askance.app/docs)
+
+## License
+
+MIT

package/dist/cli/index.js

@@ -0,0 +1,515 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const api_client_1 = require("../common/api-client");
+const COMMANDS = ["init", "login", "template", "help"];
+const command = (process.argv[2] ?? "help");
+const projectDir = process.cwd();
+// Parse flags from argv (everything after the command)
+const flags = new Set(process.argv.slice(3).filter((a) => a.startsWith("--")));
+const flagCursor = flags.has("--cursor");
+const flagCopilot = flags.has("--copilot");
+const flagAll = flags.has("--all");
+// Resolve the package root (where dist/ lives)
+const pkgRoot = path_1.default.resolve(__dirname, "..", "..");
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function ensurePolicy() {
+    const policyPath = path_1.default.join(projectDir, ".askance.yml");
+    if (!fs_1.default.existsSync(policyPath)) {
+        const defaultPolicy = `version: 1
+
+api_url: https://api.askance.app
+project_id: ""
+
+keep_alive:
+  enabled: true
+  duration: 3600        # total seconds to stay alive polling (default: 1 hour)
+  poll_interval: 30     # seconds per poll cycle (default: 30s)
+
+rules:
+  - name: "Allow read-only tools"
+    match:
+      tool: "^(Read|Glob|Grep|WebSearch|WebFetch)$"
+    action: allow
+
+  - name: "Allow safe bash commands"
+    match:
+      tool: "^Bash$"
+      command: "^(npm test|npm run lint|npm run build|git status|git diff|git log|ls)"
+    action: allow
+
+  - name: "Gate file writes"
+    match:
+      tool: "^(Edit|Write|NotebookEdit)$"
+    action: gate
+    risk: medium
+
+  - name: "Gate package installs"
+    match:
+      tool: "^Bash$"
+      command: "(npm install|pip install|dotnet add)"
+    action: gate
+    risk: medium
+
+  - name: "Deny destructive commands"
+    match:
+      tool: "^Bash$"
+      command: "(rm -rf|chmod 777|curl.*\\\\|.*bash)"
+    action: deny
+    risk: high
+
+  - name: "Default - gate everything else"
+    match:
+      tool: ".*"
+    action: gate
+    risk: low
+`;
+        fs_1.default.writeFileSync(policyPath, defaultPolicy);
+        console.log("[askance] Created .askance.yml");
+    }
+    else {
+        console.log("[askance] .askance.yml already exists, skipping");
+    }
+}
+function ensureGitignore() {
+    const gitignorePath = path_1.default.join(projectDir, ".gitignore");
+    if (fs_1.default.existsSync(gitignorePath)) {
+        const content = fs_1.default.readFileSync(gitignorePath, "utf-8");
+        if (!content.includes(".askance/")) {
+            fs_1.default.appendFileSync(gitignorePath, "\n# Askance session data\n.askance/\n");
+            console.log("[askance] Added .askance/ to .gitignore");
+        }
+    }
+    else {
+        fs_1.default.writeFileSync(gitignorePath, "# Askance session data\n.askance/\n");
+        console.log("[askance] Created .gitignore with .askance/");
+    }
+}
+// ---------------------------------------------------------------------------
+// Claude Code init (default)
+// ---------------------------------------------------------------------------
+function initClaude() {
+    const claudeDir = path_1.default.join(projectDir, ".claude");
+    if (!fs_1.default.existsSync(claudeDir)) {
+        fs_1.default.mkdirSync(claudeDir, { recursive: true });
+    }
+    const settingsPath = path_1.default.join(claudeDir, "settings.json");
+    const hookHandlerPath = path_1.default.join(pkgRoot, "dist", "hook-handler", "index.js").replace(/\\/g, "/");
+    const stopHookPath = path_1.default.join(pkgRoot, "dist", "hook-handler", "stop-hook.js").replace(/\\/g, "/");
+    const mcpServerPath = path_1.default.join(pkgRoot, "dist", "mcp-server", "index.js").replace(/\\/g, "/");
+    const settings = fs_1.default.existsSync(settingsPath)
+        ? JSON.parse(fs_1.default.readFileSync(settingsPath, "utf-8"))
+        : {};
+    // Set hooks
+    const hooks = (settings.hooks ?? {});
+    hooks.PreToolUse = [
+        {
+            matcher: "^(?!mcp__askance__).*",
+            hooks: [
+                {
+                    type: "command",
+                    command: `node "${hookHandlerPath}"`,
+                    timeout: 120,
+                },
+            ],
+        },
+    ];
+    hooks.Stop = [
+        {
+            matcher: "",
+            hooks: [
+                {
+                    type: "command",
+                    command: `node "${stopHookPath}"`,
+                    timeout: 10,
+                },
+            ],
+        },
+    ];
+    settings.hooks = hooks;
+    // Set MCP server
+    const mcpServers = (settings.mcpServers ?? {});
+    mcpServers.askance = {
+        command: "node",
+        args: [mcpServerPath],
+    };
+    settings.mcpServers = mcpServers;
+    fs_1.default.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("[askance] Updated .claude/settings.json");
+}
+// ---------------------------------------------------------------------------
+// Cursor IDE init
+// ---------------------------------------------------------------------------
+function initCursor() {
+    const cursorDir = path_1.default.join(projectDir, ".cursor");
+    if (!fs_1.default.existsSync(cursorDir)) {
+        fs_1.default.mkdirSync(cursorDir, { recursive: true });
+    }
+    const settingsPath = path_1.default.join(cursorDir, "settings.json");
+    const hookHandlerPath = path_1.default.join(pkgRoot, "dist", "hook-handler", "index.js").replace(/\\/g, "/");
+    const mcpServerPath = path_1.default.join(pkgRoot, "dist", "mcp-server", "index.js").replace(/\\/g, "/");
+    const settings = fs_1.default.existsSync(settingsPath)
+        ? JSON.parse(fs_1.default.readFileSync(settingsPath, "utf-8"))
+        : {};
+    // Set Cursor hooks
+    const cursorHooks = (settings["cursor.hooks"] ?? {});
+    cursorHooks.preToolUse = {
+        command: "node",
+        args: [hookHandlerPath],
+        matchTools: [".*"],
+        excludeTools: ["mcp__askance__.*"],
+    };
+    settings["cursor.hooks"] = cursorHooks;
+    // Set Cursor MCP servers
+    const cursorMcp = (settings["cursor.mcp"] ?? {});
+    const servers = (cursorMcp.servers ?? {});
+    servers.askance = {
+        command: "node",
+        args: [mcpServerPath],
+    };
+    cursorMcp.servers = servers;
+    settings["cursor.mcp"] = cursorMcp;
+    fs_1.default.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("[askance] Updated .cursor/settings.json");
+}
+// ---------------------------------------------------------------------------
+// GitHub Copilot init
+// ---------------------------------------------------------------------------
+function initCopilot() {
+    const githubDir = path_1.default.join(projectDir, ".github");
+    if (!fs_1.default.existsSync(githubDir)) {
+        fs_1.default.mkdirSync(githubDir, { recursive: true });
+    }
+    const configPath = path_1.default.join(githubDir, "copilot-config.json");
+    const hookHandlerPath = path_1.default.join(pkgRoot, "dist", "hook-handler", "index.js").replace(/\\/g, "/");
+    const config = fs_1.default.existsSync(configPath)
+        ? JSON.parse(fs_1.default.readFileSync(configPath, "utf-8"))
+        : {};
+    // Set Copilot agent hooks
+    const copilotAgent = (config["copilot.agent"] ?? {});
+    const hooks = (copilotAgent.hooks ?? {});
+    hooks.preToolUse = {
+        command: "node",
+        args: [hookHandlerPath],
+        matchTools: [".*"],
+    };
+    copilotAgent.hooks = hooks;
+    config["copilot.agent"] = copilotAgent;
+    fs_1.default.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+    console.log("[askance] Updated .github/copilot-config.json");
+}
+// ---------------------------------------------------------------------------
+// Main init orchestrator
+// ---------------------------------------------------------------------------
+const CLAUDE_MD_SECTION = `
+## Askance — Tool Call Oversight
+
+This project uses [Askance](https://askance.app) for AI tool call interception and approval management.
+
+**How it works:**
+- All tool calls are intercepted by Askance hooks and evaluated against policy rules in \`.askance.yml\`
+- Safe operations (reads, searches) are auto-approved; risky operations require human approval
+- When a tool call is gated for approval, use \`mcp__askance__wait\` to wait for the decision
+- Use \`mcp__askance__check_instructions\` periodically to check for operator instructions
+
+**Important:**
+- If a tool call returns \`pending\` status with an \`approval_id\`, call \`mcp__askance__wait\` with that ID before retrying
+- Do NOT bypass or work around gated tool calls — they require human approval
+- The operator may send instructions via the dashboard; check for them using the MCP tools
+`;
+function ensureClaudeMd() {
+    const claudeMdPath = path_1.default.join(projectDir, "CLAUDE.md");
+    if (fs_1.default.existsSync(claudeMdPath)) {
+        const content = fs_1.default.readFileSync(claudeMdPath, "utf-8");
+        if (content.includes("Askance")) {
+            console.log("[askance] CLAUDE.md already contains Askance section, skipping");
+            return;
+        }
+        fs_1.default.appendFileSync(claudeMdPath, "\n" + CLAUDE_MD_SECTION);
+        console.log("[askance] Added Askance section to existing CLAUDE.md");
+    }
+    else {
+        fs_1.default.writeFileSync(claudeMdPath, CLAUDE_MD_SECTION.trimStart());
+        console.log("[askance] Created CLAUDE.md with Askance instructions");
+    }
+}
+function init() {
+    console.log("[askance] Initializing Askance in", projectDir);
+    // 1. Always write .askance.yml + .gitignore
+    ensurePolicy();
+    ensureGitignore();
+    // 2. Determine which IDE configs to set up
+    const setupClaude = flagAll || (!flagCursor && !flagCopilot);
+    const setupCursor = flagAll || flagCursor;
+    const setupCopilot = flagAll || flagCopilot;
+    if (setupClaude) {
+        initClaude();
+        ensureClaudeMd();
+    }
+    if (setupCursor) {
+        initCursor();
+    }
+    if (setupCopilot) {
+        initCopilot();
+    }
+    // 3. Print next steps
+    console.log("\n[askance] Setup complete! Next steps:");
+    console.log("  1. Log in:            npx askance login");
+    if (setupClaude) {
+        console.log("  2. Restart your Claude Code session (hooks load at startup)");
+    }
+    if (setupCursor) {
+        console.log("  2. Restart Cursor to load the hooks and MCP server");
+    }
+    if (setupCopilot) {
+        console.log("  2. Copilot agent hooks are configured in .github/copilot-config.json");
+    }
+    console.log("  3. Open the dashboard: https://app.askance.app");
+    console.log("  4. Edit .askance.yml to customize your policy rules");
+}
+// ---------------------------------------------------------------------------
+// Login — opens browser for auth, saves JWT to .askance/credentials
+// ---------------------------------------------------------------------------
+async function login() {
+    const config = (0, api_client_1.readConfig)();
+    const apiUrl = config.apiUrl;
+    // Check if already logged in
+    if (config.token) {
+        console.log("[askance] Already logged in.");
+        console.log(`  API:  ${apiUrl}`);
+        // Try to read email from credentials
+        const credPath = path_1.default.join(projectDir, ".askance", "credentials");
+        if (fs_1.default.existsSync(credPath)) {
+            try {
+                const creds = JSON.parse(fs_1.default.readFileSync(credPath, "utf-8"));
+                if (creds.user_email) {
+                    console.log(`  User: ${creds.user_email}`);
+                }
+            }
+            catch { }
+        }
+        console.log("\n  To log in as a different user, delete .askance/credentials and run login again.");
+        return;
+    }
+    // Generate a device code / CLI login token
+    console.log("[askance] Logging in to Askance...");
+    console.log(`  API: ${apiUrl}`);
+    // Request a CLI login session from the backend
+    const { apiPost, apiGet } = await Promise.resolve().then(() => __importStar(require("../common/api-client")));
+    const startResult = await apiPost("/api/auth/cli/start");
+    if (!startResult.ok || !startResult.data) {
+        console.error("[askance] Failed to start login. Is the API running?");
+        console.error(`  URL: ${apiUrl}`);
+        if (startResult.error)
+            console.error(`  Error: ${startResult.error}`);
+        console.log("\n  You can also set ASKANCE_TOKEN environment variable directly.");
+        process.exit(1);
+    }
+    const { loginId, loginUrl } = startResult.data;
+    // Open browser
+    console.log("\n  Opening browser for authentication...");
+    console.log(`  If the browser doesn't open, visit: ${loginUrl}`);
+    try {
+        const { exec } = await Promise.resolve().then(() => __importStar(require("child_process")));
+        const openCmd = process.platform === "win32" ? `start "" "${loginUrl}"` :
+            process.platform === "darwin" ? `open "${loginUrl}"` :
+                `xdg-open "${loginUrl}"`;
+        exec(openCmd);
+    }
+    catch {
+        // Browser didn't open — user can manually visit the URL
+    }
+    // Poll for completion
+    console.log("\n  Waiting for authentication...");
+    const maxWait = 300_000; // 5 minutes
+    const pollInterval = 3_000;
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWait) {
+        await new Promise((r) => setTimeout(r, pollInterval));
+        const pollResult = await apiGet(`/api/auth/cli/poll/${loginId}`);
+        if (pollResult.ok && pollResult.data) {
+            if (pollResult.data.status === "completed" && pollResult.data.token) {
+                // Save credentials
+                const askanceDir = path_1.default.join(projectDir, ".askance");
+                if (!fs_1.default.existsSync(askanceDir)) {
+                    fs_1.default.mkdirSync(askanceDir, { recursive: true });
+                }
+                const credentials = {
+                    token: pollResult.data.token,
+                    refresh_token: pollResult.data.refreshToken ?? "",
+                    api_url: apiUrl,
+                    user_email: pollResult.data.email ?? "",
+                    project_id: pollResult.data.projectId ?? "",
+                };
+                fs_1.default.writeFileSync(path_1.default.join(askanceDir, "credentials"), JSON.stringify(credentials, null, 2) + "\n", { mode: 0o600 });
+                // Update .askance.yml project_id if we got one
+                if (pollResult.data.projectId) {
+                    const policyPath = path_1.default.join(projectDir, ".askance.yml");
+                    if (fs_1.default.existsSync(policyPath)) {
+                        let content = fs_1.default.readFileSync(policyPath, "utf-8");
+                        content = content.replace(/^project_id:\s*"?"?.*"?"?\s*$/m, `project_id: "${pollResult.data.projectId}"`);
+                        fs_1.default.writeFileSync(policyPath, content);
+                    }
+                }
+                (0, api_client_1.clearConfigCache)();
+                console.log("\n[askance] Login successful!");
+                if (pollResult.data.email) {
+                    console.log(`  Logged in as: ${pollResult.data.email}`);
+                }
+                console.log("  Credentials saved to .askance/credentials");
+                return;
+            }
+            if (pollResult.data.status === "expired") {
+                console.error("\n[askance] Login session expired. Please try again.");
+                process.exit(1);
+            }
+        }
+    }
+    console.error("\n[askance] Login timed out. Please try again.");
+    process.exit(1);
+}
+function template() {
+    const TEMPLATES = ["conservative", "moderate", "permissive", "ci-safe"];
+    const templateName = process.argv[3];
+    if (!templateName) {
+        console.log(`
+[askance] Policy Template Packs
+
+Available templates:
+  conservative   Gate writes and bash, deny destructive commands
+  moderate       Allow safe writes and bash, gate the rest
+  permissive     Allow everything, deny only destructive commands
+  ci-safe        Minimal permissions for CI/CD environments
+
+Usage:
+  npx askance template <name>
+
+Example:
+  npx askance template moderate
+`);
+        return;
+    }
+    if (!TEMPLATES.includes(templateName)) {
+        console.error(`[askance] Unknown template: "${templateName}"`);
+        console.error(`[askance] Available templates: ${TEMPLATES.join(", ")}`);
+        process.exit(1);
+    }
+    // Templates are bundled alongside the compiled output
+    // In source: src/templates/<name>.yml
+    // In dist:   dist/templates/<name>.yml (copied by build)
+    // Also try source path for development
+    const distTemplatePath = path_1.default.join(pkgRoot, "dist", "templates", `${templateName}.yml`);
+    const srcTemplatePath = path_1.default.join(pkgRoot, "src", "templates", `${templateName}.yml`);
+    const templatePath = fs_1.default.existsSync(distTemplatePath) ? distTemplatePath : srcTemplatePath;
+    if (!fs_1.default.existsSync(templatePath)) {
+        console.error(`[askance] Template file not found at ${templatePath}`);
+        console.error("[askance] Try rebuilding: npm run build");
+        process.exit(1);
+    }
+    const destPath = path_1.default.join(projectDir, ".askance.yml");
+    const templateContent = fs_1.default.readFileSync(templatePath, "utf-8");
+    if (fs_1.default.existsSync(destPath)) {
+        console.log(`[askance] Overwriting existing .askance.yml with "${templateName}" template`);
+    }
+    fs_1.default.writeFileSync(destPath, templateContent);
+    console.log(`[askance] Applied "${templateName}" template to .askance.yml`);
+    console.log("[askance] Restart your agent session to apply the new policy");
+}
+function help() {
+    console.log(`
+Askance — Tool Call Interception & Exception Management for AI Coding Agents
+
+Usage:
+  npx askance <command> [options]
+
+Commands:
+  init     Set up Askance in the current project
+           - Creates .askance.yml (policy rules)
+           - Configures agent hooks and MCP servers
+
+           Options:
+             (no flag)   Configure for Claude Code (default)
+             --cursor    Configure for Cursor IDE (.cursor/settings.json)
+             --copilot   Configure for GitHub Copilot (.github/copilot-config.json)
+             --all       Configure for all supported agents
+
+  login    Authenticate with Askance
+           - Opens browser for OAuth sign-in
+           - Saves access token to .askance/credentials
+
+  template Apply a pre-built policy template
+           - Available: conservative, moderate, permissive, ci-safe
+           - Usage: npx askance template <name>
+
+  help     Show this help message
+
+Quick Start:
+  cd /path/to/your-project
+  npx askance init            # Claude Code (default)
+  npx askance init --cursor   # Cursor IDE
+  npx askance init --copilot  # GitHub Copilot
+  npx askance init --all      # All agents
+  npx askance login           # Authenticate
+  # Restart your agent session
+  # Open https://app.askance.app
+
+Dashboard: https://app.askance.app
+Docs:      https://askance.app
+`);
+}
+switch (command) {
+    case "init":
+        init();
+        break;
+    case "login":
+        login();
+        break;
+    case "template":
+        template();
+        break;
+    case "help":
+    default:
+        help();
+        break;
+}
+//# sourceMappingURL=index.js.map