beam-shared 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+Beam Non-Commercial License
+
+Copyright (c) 2026 Suman Biswas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software for personal, educational, internal,
+and other non-commercial purposes, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+2. The Software may not be sold, sublicensed for a fee, or used for any
+commercial purpose.
+
+3. Commercial purpose includes any use primarily intended for or directed
+toward commercial advantage or monetary compensation, including paid products,
+paid services, consulting deliverables, or resale.
+
+4. 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/dist/app-copy.d.ts

@@ -0,0 +1,15 @@
+export declare const EMPTY_STATE_MESSAGES: readonly [{
+    readonly lead: "Ask a question, open a command, or drop in a file to begin.";
+    readonly tip: "Beam can also help with searches, edits, and project awareness.";
+}, {
+    readonly lead: "Start local with Ollama, or switch to OpenAI when you need it.";
+    readonly tip: "Type / to open Beam actions and keep the flow moving.";
+}, {
+    readonly lead: "Point Beam at a file or path, and it can pick up the context.";
+    readonly tip: "Use action log if you want to follow each step Beam takes.";
+}, {
+    readonly lead: "Keep it simple: one prompt, one file, or one quick command.";
+    readonly tip: "Beam is built to handle edits, searches, and project awareness.";
+}];
+export type EmptyStateMessage = (typeof EMPTY_STATE_MESSAGES)[number];
+//# sourceMappingURL=app-copy.d.ts.map

package/dist/app-copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-copy.d.ts","sourceRoot":"","sources":["../src/app-copy.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAiBvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/app-copy.js

@@ -0,0 +1,18 @@
+export const EMPTY_STATE_MESSAGES = [
+    {
+        lead: "Ask a question, open a command, or drop in a file to begin.",
+        tip: "Beam can also help with searches, edits, and project awareness.",
+    },
+    {
+        lead: "Start local with Ollama, or switch to OpenAI when you need it.",
+        tip: "Type / to open Beam actions and keep the flow moving.",
+    },
+    {
+        lead: "Point Beam at a file or path, and it can pick up the context.",
+        tip: "Use action log if you want to follow each step Beam takes.",
+    },
+    {
+        lead: "Keep it simple: one prompt, one file, or one quick command.",
+        tip: "Beam is built to handle edits, searches, and project awareness.",
+    },
+];

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./models.js";
+export * from "./app-copy.js";
+export * from "./system-prompt.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./models.js";
+export * from "./app-copy.js";
+export * from "./system-prompt.js";

package/dist/models.d.ts

@@ -0,0 +1,15 @@
+export interface ModelConfig {
+    id: string;
+    provider: "ollama" | "openai" | "nvidia";
+    tag: string;
+    description: string;
+    installCommand?: string;
+    needsApiKey?: boolean;
+    url?: string;
+    free?: boolean;
+}
+export declare const MODEL_CONFIGS: ModelConfig[];
+export declare const MODELS: string[];
+export type Model = typeof MODELS[number];
+export declare function getModelConfig(modelId: string): ModelConfig | undefined;
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EAiDtC,CAAC;AAEF,eAAO,MAAM,MAAM,UAAyC,CAAC;AAC7D,MAAM,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AAE1C,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEvE"}

package/dist/models.js

@@ -0,0 +1,53 @@
+export const MODEL_CONFIGS = [
+    {
+        id: "qwen2.5:7b",
+        provider: "ollama",
+        tag: "Qwen 2.5",
+        description: "Fast and efficient 7B parameter model",
+        installCommand: "ollama pull qwen2.5:7b",
+        needsApiKey: false,
+        free: true,
+        url: "https://ollama.com/library/qwen2.5:7b",
+    },
+    {
+        id: "qwen3.5:9b",
+        provider: "ollama",
+        tag: "Qwen 3.5",
+        description: "Specialized for code generation and understanding",
+        installCommand: "ollama pull qwen3.5:9b",
+        needsApiKey: false,
+        free: true,
+        url: "https://ollama.com/library/qwen3.5:9b",
+    },
+    {
+        id: "gpt-4.1-mini",
+        provider: "openai",
+        tag: "ChatGPT 4.1 Mini",
+        description: "Fast OpenAI model for everyday coding help",
+        needsApiKey: true,
+        free: false,
+        url: "https://platform.openai.com/docs/models/gpt-4-1-mini",
+    },
+    {
+        id: "gpt-4.1",
+        provider: "openai",
+        tag: "ChatGPT 4.1",
+        description: "Higher-quality OpenAI model for complex tasks",
+        needsApiKey: true,
+        free: false,
+        url: "https://platform.openai.com/docs/models/gpt-4-1",
+    },
+    {
+        id: "google/gemma-4-31b-it",
+        provider: "nvidia",
+        tag: "NVIDIA Hosted",
+        description: "NVIDIA-hosted model with strong reasoning and long outputs",
+        needsApiKey: true,
+        free: true,
+        url: "https://build.nvidia.com/models",
+    },
+];
+export const MODELS = MODEL_CONFIGS.map((model) => model.id);
+export function getModelConfig(modelId) {
+    return MODEL_CONFIGS.find((model) => model.id === modelId);
+}

package/dist/quick-actions.d.ts

@@ -0,0 +1,8 @@
+export declare const QUICK_ACTIONS: QuickAction[];
+export interface QuickAction {
+    title: string;
+    description: string;
+    shortcut: string;
+    userPrompt: string;
+}
+//# sourceMappingURL=quick-actions.d.ts.map

package/dist/quick-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quick-actions.d.ts","sourceRoot":"","sources":["../src/quick-actions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,EAAE,WAAW,EA8BtC,CAAC;AAEF,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACtB"}

package/dist/quick-actions.js

@@ -0,0 +1,31 @@
+export const QUICK_ACTIONS = [
+    {
+        title: "/commit",
+        description: "Generate a commit message based on the diff",
+        shortcut: "Ctrl+G",
+        userPrompt: "Generate a concise, descriptive git commit message based on the diff or context provided.",
+    },
+    {
+        title: "/test",
+        description: "Generate test cases for the selected code",
+        shortcut: "Ctrl+T",
+        userPrompt: "Generate comprehensive test cases for the selected code or file.",
+    },
+    // {
+    //     title: "/doc",
+    //     description: "Generate documentation for the code",
+    //     shortcut: "Ctrl+D",
+    // },
+    {
+        title: "/fix",
+        description: "Fix issues in the selected code",
+        shortcut: "Ctrl+F",
+        userPrompt: "Identify and fix any issues in the selected code or file.",
+    },
+    {
+        title: "/explain",
+        description: "Explain what the selected code snippet or file does",
+        shortcut: "Ctrl+E",
+        userPrompt: "You're given a file or a selected line snippet as context. Explain the given code clearly and concisely. Optionaly you can read other files if those are relevant. Describe what it does, how it works, and any important patterns or concepts.",
+    },
+];

package/dist/system-prompt.d.ts

@@ -0,0 +1,7 @@
+export declare function getSystemPrompt(hasProjectFiles?: boolean): string;
+/**
+ * Get system prompt tailored to a specific quick action.
+ * Each action has different capabilities and constraints.
+ */
+export declare function getSystemPromptForAction(action: string | undefined, hasProjectFiles?: boolean): string;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"AA2HA,wBAAgB,eAAe,CAAC,eAAe,GAAE,OAAe,GAAG,MAAM,CAKxE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,eAAe,GAAE,OAAe,GAC/B,MAAM,CAoBR"}

package/dist/system-prompt.js

@@ -0,0 +1,134 @@
+const BASE_PROMPT = `
+You are an AI assistant called beam with START, PLAN, ACTION, OBSERVATION and OUTPUT state.
+Wait for the user prompt and first PLAN using available tools.
+After planning, take the ACTION with appropriate tools and wait for OBSERVATION.
+Once you get the OBSERVATION, return the AI response based on the START prompt and observations.
+
+Strictly follow the JSON output format as given in the examples.
+
+For simple conversational messages, greetings, small talk, or non-technical messages like generating a commit message, skip to output directly:
+{"type": "output", "output": "Hey! What can I help you with?"}
+
+Available tools:`;
+const PROJECT_CONTEXT_TOOL = `
+- Project structure is provided as context above.
+  Use the provided project-files.json to understand the project layout instead of calling getProjectAwareness.`;
+const PROJECT_AWARENESS_TOOL = `
+- function getProjectAwareness(rootDir: string): string[]
+  Scans the workspace, creates or refreshes .beam/project-files.json, and returns the discovered project file paths.
+  Use this first when you need project context.`;
+const READ_ONLY_TOOLS = `
+
+- function readPath(path: string): object
+  Reads a file or lists a directory inside the workspace.
+  Use this first when you need the contents of a file or a quick directory view.
+
+- function glob(pattern: string): object
+  Finds files in the workspace that match a glob pattern like "**/*.ts".
+  Use this for fast file pattern matching.
+
+- function grep(pattern: string, flags?: string): object
+  Searches file contents with a regular expression and returns matching lines.
+  Use this when you need powerful content search with regex support.
+
+- function webSearch(query: string, limit?: number): object
+  Searches the web for current information and returns a small set of result links and snippets.
+  Use this when the answer may have changed recently or needs fresh external context.
+
+- function webFetch(url: string): object
+  Fetches a URL and extracts readable text for analysis.
+  Use this after webSearch, or when the user gives you a URL to inspect.`;
+const WRITE_TOOLS = `
+- function writePath(path: string, content: string): object
+  Writes or creates a file. Parent directories are created automatically.
+
+- function editPath(path: string, searchValue: string, replaceValue: string): object
+  Replaces literal text in a file and writes the result back.
+
+- function deletePath(path: string): object
+  Deletes a file or directory inside the workspace.
+  Beam will ask the user for confirmation before deletion.
+
+- function runCommand(command: string): object
+  Runs a shell command inside the open workspace folder.
+  Use this for build, test, lint, install, git status, and other CLI-based tasks.
+
+  Rules:
+  - Do not use interactive commands.
+  - Do not use destructive commands like rm -rf, sudo, git reset --hard, shutdown, or reboot.`;
+const STRICT_RULES_READ_ONLY = `
+STRICT RULES:
+- Only ONE plan per response cycle. After planning, ALWAYS follow with an action.
+- Never plan twice in a row. Never repeat the same action twice.
+- Once you have enough information from observations, go straight to output.
+- For code/technical output: use markdown with triple backticks and a language tag.
+- For conversational output: plain text only, no markdown.
+- Escape newlines as \\n inside JSON string values.
+- DO NOT modify or write any files. You can only read files, search, or fetch web content.`;
+const STRICT_RULES_WRITE = `
+STRICT RULES:
+- Only ONE plan per response cycle. After planning, ALWAYS follow with an action.
+- Never plan twice in a row. Never repeat the same action twice.
+- Once you have enough information from observations, go straight to output.
+- For code/technical output: use markdown with triple backticks and a language tag.
+- For conversational output: plain text only, no markdown.
+- Escape newlines as \\n inside JSON string values.`;
+const OUTPUT_FORMAT = `
+Output Format Examples:
+
+// Conversational:
+{"type": "output", "output": "Hey! What can I help you with?"}
+
+// Single tool task:
+{"type": "plan", "plan": "I will inspect the file structure"}
+{"type": "action", "action": "getProjectAwareness", "parameters": {"rootDir": "./"}}
+// (observation is injected by the system, not by you — wait for it, then continue)
+{"type": "action", "action": "readPath", "parameters": {"path": "src/index.ts"}}
+{"type": "output", "output": "Your app is running on port 3000."}
+
+// Multi-step task:
+{"type": "plan", "plan": "I will inspect the code then write a summary"}
+{"type": "action", "action": "grep", "parameters": {"pattern": "writePath"}}
+// (wait for observation)
+{"type": "action", "action": "writePath", "parameters": {"path": "doc.md", "content": "# Project\\n..."}}
+{"type": "output", "output": "I've written doc.md with a summary of your project."}
+
+IMPORTANT: You NEVER emit {"type": "observation", ...}. Observations are injected by the system after each action. Just wait and then respond with the next action or output.
+`;
+function buildPrompt(toolsSection, includeWriteTools, includeProjectAwarenessTool) {
+    return (BASE_PROMPT +
+        toolsSection +
+        (includeProjectAwarenessTool ? PROJECT_AWARENESS_TOOL : "") +
+        READ_ONLY_TOOLS +
+        (includeWriteTools ? `\n\n${WRITE_TOOLS}` : "") +
+        `\n\n` +
+        (includeWriteTools ? STRICT_RULES_WRITE : STRICT_RULES_READ_ONLY) +
+        `\n\n` +
+        OUTPUT_FORMAT);
+}
+export function getSystemPrompt(hasProjectFiles = false) {
+    const toolsSection = hasProjectFiles ? PROJECT_CONTEXT_TOOL : `
+- If the project-files cache is not already provided, use getProjectAwareness to build it.`;
+    return buildPrompt(toolsSection, true, !hasProjectFiles);
+}
+/**
+ * Get system prompt tailored to a specific quick action.
+ * Each action has different capabilities and constraints.
+ */
+export function getSystemPromptForAction(action, hasProjectFiles = false) {
+    if (!action) {
+        return getSystemPrompt(hasProjectFiles);
+    }
+    const toolsSection = hasProjectFiles ? PROJECT_CONTEXT_TOOL : `
+- If the project-files cache is not already provided, use getProjectAwareness to build it.`;
+    switch (action) {
+        case "/explain":
+        case "/commit":
+            return buildPrompt(toolsSection, false, !hasProjectFiles);
+        case "/test":
+        case "/fix":
+            return buildPrompt(toolsSection, true, !hasProjectFiles);
+        default:
+            return getSystemPrompt(hasProjectFiles);
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "beam-shared",
+  "version": "0.1.0",
+  "description": "Shared utilities and types for Beam",
+  "keywords": ["beam", "shared", "utilities"],
+  "author": "Suman Biswas <textsumanb@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "homepage": "https://github.com/sumanbiswas7/beam#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sumanbiswas7/beam.git",
+    "directory": "packages/shared"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./models": "./dist/models.js",
+    "./app-copy": "./dist/app-copy.js"
+  },
+  "scripts": {
+    "build": "tsc -p ./tsconfig.json",
+    "dev": "tsc -w -p ./tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}