astrabot 0.1.0

package/index.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+import { runWakeup, printBanner } from "./tui/wakeup"; // Imported printBanner for the breathing effect
+import { runSetup } from "./modes/setup";
+import pkg from "./package.json" with { type: "json" };
+import fs from "fs";
+import path from "path";
+import os from "os";
+import chalk from "chalk";
+import figlet from "figlet"; // Imported figlet for the arcade banner generation
+import { confirm, isCancel, select } from "@clack/prompts";
+import { exec } from "child_process";
+
+const program = new Command();
+
+program
+  .name("astra")
+  .description("Astra CLI — AI-native development companion")
+  .version(pkg.version, "-v, --version", "Output the current version");
+
+program
+  .command("wakeup")
+  .description("Show the banner and pick interaction mode")
+  .action(async () => {
+    await runWakeup();
+  });
+
+program
+  .command("setup")
+  .description("Configure API keys and settings (~/.astra/.env)")
+  .action(async () => {
+    await runSetup();
+  });
+
+program
+  .command("play")
+  .description("Launch an undocumented workspace arcade easter egg mini-game")
+  .action(async () => {
+    // Generate the baseline ASCII asset for the arcade room
+    let arcadeAscii = "";
+    try {
+      arcadeAscii = figlet.textSync("ARCADE", {
+        font: "ANSI Shadow",
+        horizontalLayout: "fitted",
+      });
+    } catch {
+      arcadeAscii = figlet.textSync("ARCADE", { font: "Standard" });
+    }
+
+    // Play the full breathing banner animation with the twinkling stars
+    await printBanner(arcadeAscii);
+
+    console.log(chalk.bold.magenta("  🎮 Astra Arcade Workspace Matrix\n"));
+
+    // 1. Interactive Game Selector Prompt
+    const gameChoice = await select({
+      message: "Choose an arcade game to launch:",
+      options: [
+        { value: "index.html", label: "Retro Snake Classic" },
+        { value: "neon-breaker.html", label: "Neon Brick Breaker" },
+        { value: "exit", label: "Exit"}
+      ],
+    });
+
+    if (isCancel(gameChoice) || gameChoice==="exit") {
+      console.log(chalk.dim("  Arcade closed.\n"));
+      return;
+    }
+
+    // Resolve the internal path safely relative to the executing workspace binary bundle
+    const gameFilePath = path.join(import.meta.dir, "game", gameChoice);
+
+    if (!fs.existsSync(gameFilePath)) {
+      console.log(chalk.red(`\n  ✗ Asset mismatch: Game asset not found at ${gameFilePath}\n`));
+      return;
+    }
+
+    const PORT = 4321;
+    const localUrl = `http://localhost:${PORT}`;
+
+    // 2. Spawn a background static asset file server using Bun's fast native engine
+    try {
+      Bun.serve({
+        port: PORT,
+        fetch(req) {
+          return new Response(Bun.file(gameFilePath));
+        },
+      });
+
+      console.log(chalk.green(`\n  ✓ Local arcade matrix listening live at ${localUrl}`));
+      console.log(chalk.dim("  Press [Ctrl + C] in this terminal session to close down server logs.\n"));
+
+      // 3. Automatically spawn their default system web browser target
+      const startCmd = 
+        process.platform === "win32" ? "start" : 
+        process.platform === "darwin" ? "open" : "xdg-open";
+        
+      exec(`${startCmd} ${localUrl}`);
+    } catch (err) {
+      console.error(chalk.red(`\n  ✗ Port initialization blocked: ${(err as Error).message}\n`));
+    }
+  });
+
+program
+  .command("reset")
+  .description("Completely remove all localized configurations, sessions, and credentials cached by Astra")
+  .action(async () => {
+    console.log(chalk.bold.yellow("\n  ⚠ Danger Zone"));
+    
+    const targetDir = path.join(os.homedir(), ".astra");
+    
+    if (!fs.existsSync(targetDir)) {
+      console.log(chalk.dim("  No active data store or environment parameters discovered at ~/.astra.\n"));
+      return;
+    }
+
+    const authorized = await confirm({
+      message: "Are you absolutely sure you want to purge all stored configurations, environments, and historical run data?",
+      initialValue: false,
+    });
+
+    if (isCancel(authorized) || !authorized) {
+      console.log(chalk.dim("  Reset aborted.\n"));
+      return;
+    }
+
+    try {
+      fs.rmSync(targetDir, { recursive: true, force: true });
+      console.log(chalk.green(`\n  ✓ Local cache wiped successfully from ${targetDir}`));
+      console.log(chalk.dim("  To completely remove the companion binary, run: ") + chalk.cyan("npm uninstall -g astra-dev-cli\n"));
+    } catch (error) {
+      console.error(chalk.red(`\n  ✗ Failed to clear cache directory: ${(error as Error).message}\n`));
+    }
+  });
+
+await program.parseAsync(process.argv);
+
+// Export programmatic version for custom tool diagnostics or bug report attachments
+export const ASTRA_VERSION = pkg.version;

package/modes/agent/action-tracker.ts

@@ -0,0 +1,47 @@
+import type { ActionLog, ActionStatus } from "./types";
+import { isMutationType } from "./types";
+
+export class ActionTracker{
+    private actions:ActionLog[] = []
+    private counter = 0
+
+    log(
+        entry: Omit<ActionLog, 'id' | 'timestamp'> & {
+            id?: string;
+            timestamp?: Date;
+        },
+    ):ActionLog {
+        const action:ActionLog = {
+            id: entry.id ?? `action_${this.counter++}`,
+            timestamp: entry.timestamp ?? new Date(),
+            type: entry.type,
+            path: entry.path,
+            details: {...entry.details},
+            status: entry.status,
+            userApproved: entry.userApproved
+        }
+        this.actions.push(action)
+        return action
+    }
+
+    getActions():readonly ActionLog[] {
+        return this.actions
+    }
+
+    getPendingMutations():ActionLog[] {
+        return this.actions.filter(
+            (a)=>isMutationType(a.type) && a.status==="pending"
+        )
+    }
+
+    getPendingMutationsForPath(path: string): ActionLog[] {
+        return this.getPendingMutations().filter((a) => a.path === path)
+    }
+
+    updateStatus(id: string, status: ActionStatus, userApproved?: boolean): void {
+        const a = this.actions.find((x)=>x.id===id)
+        if(!a) return
+        a.status = status
+        if(userApproved!==undefined) a.userApproved = userApproved
+    }
+}

package/modes/agent/agent-tools.ts

@@ -0,0 +1,338 @@
+import {tool} from 'ai'
+import {z} from 'zod'
+import type { ToolExecutor } from './tool-executor'
+
+interface AgentToolHooks {
+    afterCreateFile?: (path: string) => Promise<string | void>;
+}
+
+export function createAgentTools(executor: ToolExecutor, hooks: AgentToolHooks = {}){
+    return {
+
+        read_file: tool({
+            description: "Read a text file from the workspace. Use a path relative to the project root.",
+            inputSchema: z.object({
+                path: z.string().describe("Relative file path")
+            }),
+            execute: async({path:p}) => executor.readFile(p)
+        }),
+
+        create_file: tool({
+            description:
+                "Stage creation of a new file (not written until the user approves).",
+            inputSchema: z.object({
+                path: z.string(),
+                content: z.string(),
+            }),
+            execute: async ({ path: p, content }) => {
+                const staged = executor.createFile(p, content)
+                const followUp = await hooks.afterCreateFile?.(executor.normalizePath(p))
+                return followUp ?? staged
+            },
+        }),
+
+        modify_file: tool({
+            description:
+                "Stage a full-file replacement for an existing file (pending approval).",
+            inputSchema: z.object({
+                path: z.string(),
+                content: z.string().describe("Complete new file contents"),
+            }),
+            execute: async ({ path: p, content }) => executor.modifyFile(p, content),
+        }),
+
+        delete_file: tool({
+            description: "Stage deletion of a file (pending approval).",
+            inputSchema: z.object({
+                path: z.string(),
+            }),
+            execute: async ({ path: p }) => executor.deleteFile(p),
+        }),
+
+        create_folder: tool({
+            description:
+                "Stage creation of a directory tree (pending approval). Uses mkdir -p on apply.",
+            inputSchema: z.object({
+                path: z.string().describe("Relative directory path"),
+            }),
+            execute: async ({ path: p }) => executor.createFolder(p),
+        }),
+
+        list_files: tool({
+            description: "List files and directories under a path.",
+            inputSchema: z.object({
+                path: z.string(),
+                recursive: z.boolean().optional().default(false),
+            }),
+            execute: async ({ path: p, recursive }) =>
+                executor.listFiles(p, recursive),
+        }),
+
+        search_files: tool({
+            description:
+                'Find files matching a glob pattern (e.g. "*.ts", "**/*.md"). Optional content substring filter.',
+            inputSchema: z.object({
+                root: z.string().describe("Directory to search, relative to root"),
+                pattern: z
+                .string()
+                .describe("Glob-like pattern using * and ** (forward slashes)"),
+                content_contains: z.string().optional(),
+            }),
+            execute: async ({ root, pattern, content_contains }) =>
+                executor.searchFiles(root, pattern, content_contains),
+        }),
+
+        analyze_codebase: tool({
+            description:
+                "Summarize structure: file counts, size, extensions. Read-only.",
+            inputSchema: z.object({
+                path: z.string().default("."),
+            }),
+            execute: async ({ path: p }) => executor.analyzeCodebase(p),
+        }),
+
+        read_multiple_files: tool({
+            description:
+                "Read multiple files in a single tool call. Each file is individually logged to the action trail.",
+            inputSchema: z.object({
+                paths: z.array(z.string())
+            }),
+            execute: async ({ paths }) =>
+                executor.readMultipleFiles(paths)
+        }),
+
+        grep: tool({
+        description:
+            "Search file contents using a text query.",
+        inputSchema: z.object({
+            root: z.string().default("."),
+            query: z.string(),
+            caseSensitive: z.boolean().default(false)
+        }),
+        execute: async (args) =>
+            executor.grep(args)
+        }),
+
+        replace_in_file: tool({
+        description:
+            "Replace text inside a file while preserving the rest.",
+        inputSchema: z.object({
+            path: z.string(),
+            search: z.string(),
+            replace: z.string()
+        }),
+        execute: async ({path, search, replace}) =>
+            executor.replaceInFile(path, search, replace)
+        }),
+
+        append_to_file: tool({
+        description:
+            "Append content to the end of a file.",
+        inputSchema: z.object({
+            path: z.string(),
+            content: z.string()
+        }),
+        execute: async ({ path, content }) =>
+            executor.appendToFile( path, content )
+        }),
+
+        insert_at_line: tool({
+        description:
+            "Insert content at a specific line.",
+        inputSchema: z.object({
+            path: z.string(),
+            line: z.number(),
+            content: z.string()
+        }),
+        execute: async ({path, line, content}) =>
+            executor.insertAtLine(path, line, content)
+        }),
+
+        run_command: tool({
+        description:
+            "Run a command immediately and capture output.",
+        inputSchema: z.object({
+            command: z.string(),
+            cwd: z.string().optional()
+        }),
+        execute: async ({command, cwd}) =>
+            executor.runCommand(command, cwd)
+        }),
+
+        run_background_command: tool({
+        description:
+            "Start a long-running process.",
+        inputSchema: z.object({
+            command: z.string(),
+            cwd: z.string().optional()
+        }),
+        execute: async (args) =>
+            executor.runBackgroundCommand(args)
+        }),
+
+        git_status: tool({
+        description:
+            "Get git status.",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.gitStatus()
+        }),
+
+        git_diff: tool({
+        description:
+            "Get git diff.",
+        inputSchema: z.object({
+            staged: z.boolean().default(false)
+        }),
+        execute: async ({ staged }) =>
+            executor.gitDiff(staged)
+        }),
+
+        git_log: tool({
+        description:
+            "Get recent commits.",
+        inputSchema: z.object({
+            limit: z.number().default(20)
+        }),
+        execute: async ({ limit }) =>
+            executor.gitLog(limit)
+        }),
+
+        run_tests: tool({
+        description:
+            "Run the project's test suite.",
+        inputSchema: z.object({
+            filter: z.string().optional()
+        }),
+        execute: async ({ filter }) =>
+            executor.runTests(filter)
+        }),
+
+        run_test_file: tool({
+        description:
+            "Run a specific test file.",
+        inputSchema: z.object({
+            path: z.string()
+        }),
+        execute: async ({ path }) =>
+            executor.runTestFile(path)
+        }),
+
+        lint_project: tool({
+        description:
+            "Run linting.",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.lintProject()
+        }),
+
+        format_project: tool({
+        description:
+            "Run formatting.",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.formatProject()
+        }),
+
+        detect_framework: tool({
+        description:
+            "Detect framework, package manager and language.",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.detectFramework()
+        }),
+
+        read_package_json: tool({
+        description:
+            "Read package.json summary.",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.readPackageJson()
+        }),
+
+        web_search: tool({
+        description:
+            "Search the web for documentation.",
+        inputSchema: z.object({
+            query: z.string()
+        }),
+        execute: async ({ query }) =>
+            executor.webSearch(query)
+        }),
+
+        fetch_url: tool({
+        description:
+            "Fetch and summarize a URL.",
+        inputSchema: z.object({
+            url: z.string()
+        }),
+        execute: async ({ url }) =>
+            executor.fetchUrl(url)
+        }),
+
+        create_plan: tool({
+        description:
+            "Create a task execution plan.",
+        inputSchema: z.object({
+            goal: z.string()
+        }),
+        execute: async ({ goal }) =>
+            executor.createPlan(goal)
+        }),
+
+        get_plan: tool({
+        description:
+            "Retrieve current plan.",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.getPlan()
+        }),
+
+        show_pending_changes: tool({
+        description:
+            "Show staged file operations (read-only display - does NOT apply changes). Use this to review what would be modified before user approval.",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.showPendingChanges()
+        }),
+
+        // ❌ REMOVED: apply_changes
+        // This tool has been removed because applying changes must go through
+        // the runApprovalFlow() in orchestrator.ts which requires explicit
+        // user approval. Agents should never auto-apply changes without
+        // user consent.
+
+        discard_changes: tool({
+        description:
+            "Discard all staged operations (useful if you want to start over).",
+        inputSchema: z.object({}),
+        execute: async () =>
+            executor.discardChanges()
+        }),
+
+        execute_shell: tool({
+            description:
+                "Queue a shell command to run in the workspace after user approval. Use with care.",
+            inputSchema: z.object({
+                command: z.string().describe("Single command; runs with shell: true"),
+            }),
+            execute: async ({ command }) => executor.queueShell(command),
+        }),
+
+        list_skills: tool({
+            description:
+                "List absolute paths to SKILL.md files under configured skill directories (Cursor / Claude).",
+            inputSchema: z.object({}),
+            execute: async () => executor.listSkills(),
+        }),
+
+        read_skill: tool({
+            description:
+                "Read a SKILL.md file. Path must be absolute and under skill roots, or use a path returned by list_skills.",
+            inputSchema: z.object({
+                path: z.string(),
+            }),
+            execute: async ({ path: p }) => executor.readSkill(p),
+        }),
+    }
+}

package/modes/agent/approval.ts

@@ -0,0 +1,184 @@
+import type { ActionTracker } from "./action-tracker";
+import chalk from "chalk";
+import {select, isCancel} from '@clack/prompts'
+import type { ActionLog } from "./types";
+import { composeBeforeAfter, formatPatch } from "./diff-view";
+import { renderTerminalMarkdown } from "../../tui/terminal-md";
+
+interface ReviewGroup{
+    label:string;
+    actionIds:string[],
+    patch:string | null
+}
+
+interface ApprovalFlowOptions {
+    paths?: string[];
+    skipBatchPrompt?: boolean;
+}
+
+function groupPending(pending: ActionLog[]): ReviewGroup[] {
+    const byPath = new Map<string, ActionLog[]>();
+    const shells: ActionLog[] = [];
+
+    for (const a of pending) {
+        if (a.type === "tool_execute") {
+        shells.push(a);
+        continue;
+        }
+        const key = a.path;
+        if (!byPath.has(key)) byPath.set(key, []);
+        byPath.get(key)!.push(a);
+    }
+
+    const groups: ReviewGroup[] = [];
+
+    const pathEntries = [...byPath.entries()].sort(([a], [b]) =>
+        a.localeCompare(b),
+    );
+    for (const [p, acts] of pathEntries) {
+        const sorted = acts.sort(
+        (x, y) => x.timestamp.getTime() - y.timestamp.getTime(),
+        );
+        const ids = sorted.map((x) => x.id);
+
+        if (sorted.every((x) => x.type === "folder_create")) {
+        groups.push({
+            label: `Create folder: ${p}`,
+            actionIds: ids,
+            patch: null,
+        });
+        continue;
+        }
+
+        const { before, after } = composeBeforeAfter(sorted);
+        const patch = formatPatch(p, before, after);
+        const kinds = [...new Set(sorted.map((x) => x.type))].join(", ");
+        groups.push({ label: `${p} (${kinds})`, actionIds: ids, patch });
+    }
+
+    for (const s of shells) {
+        groups.push({
+        label: `Shell: ${s.details.command ?? "(no command)"}`,
+        actionIds: [s.id],
+        patch: null,
+        });
+    }
+
+    return groups;
+}
+
+/**
+ * Run the approval flow for staged changes.
+ * 
+ * This function:
+ * 1. Checks if there are any pending changes
+ * 2. If none, returns false (nothing to approve)
+ * 3. If yes, prompts user to approve all, review individually, or cancel
+ * 4. Updates tracker with user's approval decisions
+ * 5. Returns true if ANY changes were approved, false if all rejected/cancelled
+ * 
+ * @param tracker ActionTracker with pending mutations
+ * @returns true if user approved any changes, false otherwise
+ */
+export async function runApprovalFlow(
+    tracker: ActionTracker,
+    options: ApprovalFlowOptions = {},
+):Promise<boolean>{
+    const pathSet = options.paths ? new Set(options.paths) : null
+    const pending = pathSet
+        ? tracker.getPendingMutations().filter((a) => pathSet.has(a.path))
+        : tracker.getPendingMutations()
+    
+    // No changes to review
+    if(pending.length === 0){
+        console.log(chalk.dim('\nNo staged file, folder or shell changes to review.\n'))
+        return false  // ✓ Correct: nothing to approve
+    }
+
+    if(!options.skipBatchPrompt){
+        // Ask user how to proceed
+        const choice = await select({
+            message: "Apply staged changes?",
+            options: [
+                {value: "all", label: "Approve and apply all"},
+                {value: "select", label: "Review one by one"},
+                {value: "cancel", label: "Cancel"},
+            ]
+        })
+
+        // User cancelled
+        if(isCancel(choice) || choice === "cancel"){
+            // Mark all as rejected
+            for(const a of pending){
+                tracker.updateStatus(a.id, "rejected", false)
+            }
+            return false  // ✓ Correct: user rejected all
+        }
+
+        // User selected "Approve all" - approve everything and return immediately
+        if(choice === "all"){
+            for(const a of pending){
+                tracker.updateStatus(a.id, "approved", true)
+            }
+            return true  // ✓ IMPORTANT: return immediately without asking about each change
+        }
+    }
+
+    // User selected "Review one by one"
+    // Groups changes by file for easier review
+    const groups = groupPending(pending);
+    
+    for(const g of groups){
+        // Keep asking about this group until user makes a choice
+        while(true){
+            const opt = await select({
+                message: chalk.bold(g.label),
+                options: [
+                    { value: "accept", label: "Accept" },
+                    { value: "diff", label: "Show diff", hint: g.patch ? "" : "N/A" },
+                    { value: "reject", label: "Reject" },
+                ],
+            })
+
+            // User hit Ctrl+C during review
+            if(isCancel(opt)){
+                for(const a of pending) {
+                    tracker.updateStatus(a.id, "rejected", false)
+                }
+                return false
+            }
+
+            // User wants to see the diff
+            if(opt === "diff"){
+                if (g.patch) {
+                    console.log(
+                        "\n" +
+                        renderTerminalMarkdown("```diff\n" + g.patch + "\n```\n") +
+                        "\n",
+                    );
+                }
+                // ✓ Loop continues, ask again for this group
+                continue;
+            }
+
+            // User accepted or rejected this group
+            // opt === "accept" or opt === "reject"
+            for(const id of g.actionIds){
+                tracker.updateStatus(
+                    id, 
+                    opt === "accept" ? "approved" : "rejected",
+                    opt === "accept"
+                )
+            }
+            
+            // ✓ Break inner loop, move to next group
+            break
+        }
+    }
+
+    // ✓ Return true only if user approved ANY changes
+    // If user rejected all, this returns false (nothing gets applied)
+    return pending.some((a) =>
+        tracker.getActions().some((x) => x.id === a.id && x.status === "approved"),
+    )
+}