aiforcecli-local 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,139 @@
+# aiforcecli-local
+
+A standalone, local-first coding-agent CLI for DeepSeek, GLM, and Qwen models running through Ollama. The npm package is `aiforcecli-local`, and the installed executable is `aiforce-local`. It can run independently or through the `aiforcecli-chat` adapter.
+
+## Capabilities
+
+- Inspect and search a selected repository.
+- Create text files and apply exact, reviewable replacements.
+- Ask before every shell command, including tests and builds.
+- Stream tool activity and command output.
+- Produce deterministic change summaries and compact diffs without requiring Git.
+- Resume local sessions.
+- Emit JSONL events for automation and future adapters.
+- Use native Ollama tool calling with an enforced fallback for models without native tool support.
+- Run entirely locally with no API keys or per-token fees.
+
+## Requirements
+
+- Node.js 20 or newer
+- Ollama
+- Enough RAM or VRAM for the selected model
+- A model pulled into Ollama
+
+## Install for local development
+
+```powershell
+git clone https://github.com/apoorviy/aiforce-local.git
+cd aiforce-local
+npm test
+npm link
+```
+
+Verify the runtime and available presets:
+
+```powershell
+aiforce-local doctor
+aiforce-local models
+```
+
+## Model setup
+
+```powershell
+aiforce-local pull qwen
+aiforce-local pull glm
+aiforce-local pull deepseek
+```
+
+Aliases currently resolve to:
+
+- `deepseek` -> `deepseek-coder-v2:16b`
+- `glm` -> `glm4:9b`
+- `qwen` -> `qwen2.5-coder:7b`
+
+You can supply any exact Ollama tag instead. Upstream availability and model licenses should be checked before redistribution.
+
+## Run the coding agent
+
+From a repository:
+
+```powershell
+cd C:\path\to\project
+aiforce-local agent "Add input validation and tests" --model glm
+```
+
+Or select a repository explicitly:
+
+```powershell
+aiforce-local agent "Fix the failing parser test" --cwd C:\path\to\project --model qwen
+```
+
+When the agent requests a command, the CLI displays the exact command, repository, and timeout:
+
+```text
+Command requested in C:\path\to\project:
+  npm test
+Timeout: 120000ms
+Approve this command? [y/N]
+```
+
+Only `y` or `yes` executes it. Non-interactive sessions deny commands automatically.
+
+Resume a session using the identifier printed at startup:
+
+```powershell
+aiforce-local agent "Continue and address the remaining failure" --resume local-... --cwd C:\path\to\project
+```
+
+Emit machine-readable JSONL events:
+
+```powershell
+aiforce-local agent "Explain the project structure" --json
+```
+
+## Inference-only commands
+
+The original simple prompt and chat commands remain available:
+
+```powershell
+aiforce-local run "Explain dependency injection" --model qwen
+aiforce-local chat --model glm
+```
+
+Type `/exit` to leave interactive chat.
+
+## Safety model
+
+- Model-directed paths are resolved against the repository's real path.
+- Absolute paths, traversal, symlink escapes, `.git`, dependency/build directories, and common credential files are blocked.
+- Reads, searches, output, command duration, file size, and agent turns are bounded.
+- Existing files can only be changed through exact text replacement.
+- File deletion is not available.
+- Every shell command requires a separate approval; there is no approve-all option.
+- An ungrounded model response is rejected until the model inspects the repository.
+- Successful edits are fed back as authoritative state to prevent duplicate or stale actions.
+
+Use the agent in a Git repository so ordinary Git review and rollback remain available.
+
+## Configuration
+
+- `OLLAMA_HOST`: Ollama server URL. Default: `http://127.0.0.1:11434`.
+- `AIFORCE_LOCAL_DATA_DIR`: optional base directory for resumable session data.
+
+By default, sessions are stored under the platform's local application-data directory. Session records include prompts and tool results; do not ask the agent to read secrets.
+
+## Development and evaluation
+
+```powershell
+npm test
+npm run check
+```
+
+The suite includes deterministic behavior evaluations for tool trajectory, command denial, path confinement, editing, grounding enforcement, native-tool fallback, loose GLM tool syntax, and session persistence. Live model quality still depends on the selected model and machine.
+
+## Current boundaries
+
+- Local CLI only; no cloud deployment.
+- Integration with `aiforcecli-chat` is available through its built-in `aiforce-local` adapter.
+- No file deletion, browser automation, MCP, or unattended command execution.
+- Smaller local models can be slower and less reliable than hosted coding agents; the grounding and state gates prevent several common failure modes but cannot make every model equally capable.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "aiforcecli-local",
+  "version": "0.1.0",
+  "description": "Standalone local coding-agent CLI for DeepSeek, GLM, and Qwen models through Ollama.",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "aiforce-local": "src/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apoorviy/aiforce-local.git"
+  },
+  "bugs": {
+    "url": "https://github.com/apoorviy/aiforce-local/issues"
+  },
+  "homepage": "https://github.com/apoorviy/aiforce-local#readme",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-isolation=none",
+    "check": "node --check src/agent-tools.js && node --check src/cli.js && node --check src/coding-agent.js && node --check src/command-runner.js && node --check src/models.js && node --check src/ollama-client.js && node --check src/session-store.js && node --check src/workspace.js",
+    "prepublishOnly": "npm test && npm run check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ollama",
+    "deepseek",
+    "glm",
+    "qwen",
+    "local-ai"
+  ],
+  "author": "Atharv Iyer",
+  "license": "MIT"
+}

package/src/agent-tools.js

@@ -0,0 +1,115 @@
+import { runApprovedCommand } from './command-runner.js';
+
+export const TOOL_DEFINITIONS = Object.freeze([
+  tool('list_files', 'List files inside the selected repository. Use this before guessing paths.', {
+    path: stringProperty('Relative directory path. Defaults to the repository root.'),
+  }),
+  tool('read_file', 'Read a bounded line range from a UTF-8 text file in the repository.', {
+    path: stringProperty('Relative file path.'),
+    start_line: integerProperty('First line, one-based.'),
+    end_line: integerProperty('Last line, inclusive. At most 1,000 lines per call.'),
+  }, ['path']),
+  tool('search_text', 'Search for literal text across repository text files.', {
+    query: stringProperty('Literal text to find.'),
+    path: stringProperty('Relative directory to search. Defaults to the repository root.'),
+  }, ['query']),
+  tool('create_file', 'Create a new UTF-8 text file. This fails if the path already exists.', {
+    path: stringProperty('Relative file path.'),
+    content: stringProperty('Complete text content for the new file.'),
+  }, ['path', 'content']),
+  tool('replace_text', 'Edit an existing file by replacing exact text. Read the file first and include enough old_text context to make the match unique.', {
+    path: stringProperty('Relative file path.'),
+    old_text: stringProperty('Exact existing text to replace.'),
+    new_text: stringProperty('Replacement text.'),
+    replace_all: { type: 'boolean', description: 'Replace every occurrence. Defaults to false.' },
+  }, ['path', 'old_text', 'new_text']),
+  tool('run_command', 'Request execution of a shell command from the repository root. The user must approve every call before it runs.', {
+    command: stringProperty('Exact shell command to show the user for approval.'),
+    timeout_ms: integerProperty('Timeout between 1,000 and 300,000 milliseconds.'),
+  }, ['command']),
+]);
+
+export async function executeTool(name, rawArguments, context) {
+  const args = normalizeArguments(rawArguments);
+  const { workspace, approveCommand, onCommandOutput, commandRunner = runApprovedCommand } = context;
+  switch (name) {
+    case 'list_files':
+      return workspace.listFiles(optionalString(args.path, '.'));
+    case 'read_file':
+      return workspace.readFile(requiredString(args.path, 'path'), {
+        startLine: optionalInteger(args.start_line, 1),
+        endLine: optionalInteger(args.end_line, 400),
+      });
+    case 'search_text':
+      return workspace.searchText(requiredString(args.query, 'query'), optionalString(args.path, '.'));
+    case 'create_file':
+      return workspace.createFile(requiredString(args.path, 'path'), requiredString(args.content, 'content', { allowEmpty: true }));
+    case 'replace_text':
+      return workspace.replaceText(
+        requiredString(args.path, 'path'),
+        requiredString(args.old_text, 'old_text'),
+        requiredString(args.new_text, 'new_text', { allowEmpty: true }),
+        { replaceAll: args.replace_all === true },
+      );
+    case 'run_command': {
+      const result = await commandRunner({
+        command: requiredString(args.command, 'command'),
+        cwd: workspace.root,
+        approve: approveCommand,
+        timeoutMs: optionalInteger(args.timeout_ms, 120_000),
+        onOutput: onCommandOutput,
+      });
+      return result.approved ? result : { ...result, ok: false, error: 'Command denied by user.' };
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function tool(name, description, properties, required = []) {
+  return {
+    type: 'function',
+    function: {
+      name,
+      description,
+      parameters: { type: 'object', properties, required, additionalProperties: false },
+    },
+  };
+}
+
+function stringProperty(description) {
+  return { type: 'string', description };
+}
+
+function integerProperty(description) {
+  return { type: 'integer', description };
+}
+
+function normalizeArguments(value) {
+  if (value === undefined || value === null) return {};
+  if (typeof value === 'object' && !Array.isArray(value)) return value;
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+    } catch {
+      throw new Error('Tool arguments are not valid JSON.');
+    }
+  }
+  throw new Error('Tool arguments must be an object.');
+}
+
+function requiredString(value, name, { allowEmpty = false } = {}) {
+  if (typeof value !== 'string' || (!allowEmpty && !value.trim())) throw new Error(`${name} must be a${allowEmpty ? '' : ' non-empty'} string.`);
+  return value;
+}
+
+function optionalString(value, fallback) {
+  return value === undefined ? fallback : requiredString(value, 'value');
+}
+
+function optionalInteger(value, fallback) {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value)) throw new Error('Expected an integer value.');
+  return value;
+}

package/src/cli.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output, stderr as errorOutput } from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { runCodingAgent } from './coding-agent.js';
+import { OllamaClient, OllamaError } from './ollama-client.js';
+import { listPresets, resolveModel } from './models.js';
+import { SessionStore } from './session-store.js';
+import { Workspace } from './workspace.js';
+
+const HELP = `aiforce-local - run open models locally through Ollama
+
+Usage:
+  aiforce-local doctor
+  aiforce-local models
+  aiforce-local pull <deepseek|glm|qwen|ollama-tag>
+  aiforce-local run <prompt> [--model <alias|tag>]
+  aiforce-local chat [--model <alias|tag>]
+  aiforce-local agent <task> [--model <alias|tag>] [--cwd <path>]
+  aiforce-local agent <follow-up> --resume <session-id> [--cwd <path>]
+
+Agent options:
+  --model, -m       Model alias or exact Ollama tag (default: qwen)
+  --cwd, -c         Repository directory (default: current directory)
+  --resume          Resume a prior coding-agent session
+  --max-turns       Tool-loop safety limit, 1-100 (default: 24)
+  --json            Emit JSONL events; approvals still use the terminal
+
+Environment:
+  OLLAMA_HOST   Ollama server URL (default: http://127.0.0.1:11434)
+  AIFORCE_LOCAL_DATA_DIR   Override the session-data directory
+`;
+
+export async function main(argv = process.argv.slice(2), dependencies = {}) {
+  const client = dependencies.client ?? new OllamaClient();
+  const [command = 'help', ...args] = argv;
+
+  switch (command) {
+    case 'help':
+    case '--help':
+    case '-h':
+      output.write(HELP);
+      return 0;
+    case 'doctor':
+      return doctor(client);
+    case 'models':
+      return models(client);
+    case 'pull':
+      return pull(client, args);
+    case 'run':
+      return run(client, args);
+    case 'chat':
+      return chat(client, args);
+    case 'agent':
+    case 'exec':
+      return agent(client, args, dependencies);
+    default:
+      throw new Error(`Unknown command "${command}". Run with --help for usage.`);
+  }
+}
+
+async function doctor(client) {
+  const info = await client.version();
+  output.write(`Ollama ${info.version ?? 'unknown'} at ${client.baseUrl}\n`);
+  output.write('Local inference has no per-token API charge.\n');
+  return 0;
+}
+
+async function models(client) {
+  const installed = new Set((await client.models()).map((model) => model.name));
+  for (const preset of listPresets()) {
+    output.write(`${preset.alias.padEnd(10)} ${preset.tag.padEnd(28)} ${installed.has(preset.tag) ? 'installed' : 'not installed'}\n`);
+  }
+  return 0;
+}
+
+async function pull(client, args) {
+  const model = resolveModel(args[0]);
+  output.write(`Pulling ${model}\n`);
+  for await (const event of client.pull(model)) {
+    if (event.total && event.completed) {
+      const percent = Math.floor((event.completed / event.total) * 100);
+      output.write(`\r${event.status ?? 'downloading'} ${percent}%`);
+    } else if (event.status) {
+      output.write(`\r${event.status}`);
+    }
+  }
+  output.write(`\nReady: ${model}\n`);
+  return 0;
+}
+
+async function run(client, args) {
+  const { model, positionals } = parseOptions(args);
+  const prompt = positionals.join(' ').trim();
+  if (!prompt) throw new Error('run requires a prompt.');
+  await streamAnswer(client, resolveModel(model ?? 'qwen'), [{ role: 'user', content: prompt }]);
+  return 0;
+}
+
+async function chat(client, args) {
+  const { model } = parseOptions(args);
+  const selected = resolveModel(model ?? 'qwen');
+  const terminal = readline.createInterface({ input, output });
+  const messages = [];
+  output.write(`Model: ${selected}. Type /exit to quit.\n`);
+  try {
+    while (true) {
+      const prompt = (await terminal.question('> ')).trim();
+      if (!prompt) continue;
+      if (prompt === '/exit') break;
+      messages.push({ role: 'user', content: prompt });
+      const answer = await streamAnswer(client, selected, messages);
+      messages.push({ role: 'assistant', content: answer });
+    }
+  } finally {
+    terminal.close();
+  }
+  return 0;
+}
+
+async function agent(client, args, dependencies) {
+  const options = parseAgentOptions(args);
+  const workspace = dependencies.workspace ?? await Workspace.open(options.cwd);
+  const sessionStore = dependencies.sessionStore ?? new SessionStore();
+  const selectedModel = options.model ? resolveModel(options.model) : options.resume ? undefined : resolveModel('qwen');
+  const emit = dependencies.emit ?? createEventRenderer({ json: options.json });
+  const approveCommand = dependencies.approveCommand ?? createTerminalApprover();
+  const task = options.positionals.join(' ').trim();
+  if (!task && !options.resume) throw new Error('agent requires a task or --resume session id.');
+  await runCodingAgent({
+    client,
+    workspace,
+    task,
+    model: selectedModel,
+    approveCommand,
+    sessionStore,
+    resumeSession: options.resume,
+    maxTurns: options.maxTurns,
+    emit,
+    commandRunner: dependencies.commandRunner,
+  });
+  return 0;
+}
+
+async function streamAnswer(client, model, messages) {
+  let answer = '';
+  for await (const event of client.chat({ model, messages })) {
+    const text = event.message?.content ?? '';
+    answer += text;
+    output.write(text);
+  }
+  output.write('\n');
+  return answer;
+}
+
+export function parseOptions(args) {
+  const positionals = [];
+  let model;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--model' || arg === '-m') {
+      model = args[index + 1];
+      if (!model) throw new Error(`${arg} requires a value.`);
+      index += 1;
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { model, positionals };
+}
+
+export function parseAgentOptions(args) {
+  const options = {
+    model: undefined,
+    cwd: process.cwd(),
+    resume: undefined,
+    maxTurns: 24,
+    json: false,
+    positionals: [],
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      options.json = true;
+      continue;
+    }
+    const optionNames = new Map([
+      ['--model', 'model'], ['-m', 'model'],
+      ['--cwd', 'cwd'], ['-c', 'cwd'],
+      ['--resume', 'resume'],
+      ['--max-turns', 'maxTurns'],
+    ]);
+    const key = optionNames.get(arg);
+    if (!key) {
+      if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
+      options.positionals.push(arg);
+      continue;
+    }
+    const value = args[index + 1];
+    if (!value) throw new Error(`${arg} requires a value.`);
+    index += 1;
+    options[key] = key === 'maxTurns' ? Number.parseInt(value, 10) : value;
+  }
+  if (!Number.isInteger(options.maxTurns) || options.maxTurns < 1 || options.maxTurns > 100) {
+    throw new Error('--max-turns must be an integer between 1 and 100.');
+  }
+  return options;
+}
+
+function createTerminalApprover() {
+  return async ({ command, cwd, timeoutMs }) => {
+    errorOutput.write(`\nCommand requested in ${cwd}:\n  ${command}\nTimeout: ${timeoutMs}ms\n`);
+    if (!input.isTTY) {
+      errorOutput.write('Denied: command approval requires an interactive terminal.\n');
+      return false;
+    }
+    const terminal = readline.createInterface({ input, output: errorOutput });
+    try {
+      const answer = (await terminal.question('Approve this command? [y/N] ')).trim().toLowerCase();
+      return answer === 'y' || answer === 'yes';
+    } finally {
+      terminal.close();
+    }
+  };
+}
+
+function createEventRenderer({ json }) {
+  if (json) return (event) => output.write(`${JSON.stringify(event)}\n`);
+  return (event) => {
+    switch (event.type) {
+      case 'session':
+        errorOutput.write(`session: ${event.sessionId}\nmodel: ${event.model}\nrepository: ${event.root}\n`);
+        break;
+      case 'assistant_delta':
+        output.write(event.text);
+        break;
+      case 'tool_call':
+        errorOutput.write(`\n-> ${event.name} ${formatCompact(event.arguments)}\n`);
+        break;
+      case 'tool_result':
+        errorOutput.write(`<- ${event.name} ${formatCompact(event.result)}\n`);
+        break;
+      case 'command_output':
+        (event.stream === 'stderr' ? errorOutput : output).write(event.text);
+        break;
+      case 'final':
+        output.write('\n');
+        if (event.changes.length) {
+          output.write(`\nChanges (${event.changes.length}):\n`);
+          for (const change of event.changes) output.write(`  ${change.status}: ${change.path}\n`);
+          if (event.diff) output.write(`\n${event.diff}`);
+        } else {
+          output.write('\nNo files changed.\n');
+        }
+        break;
+      default:
+        break;
+    }
+  };
+}
+
+function formatCompact(value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  return text.length > 500 ? `${text.slice(0, 500)}...` : text;
+}
+
+const isEntryPoint = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    const entry = fs.realpathSync(path.resolve(process.argv[1]));
+    const module = fs.realpathSync(fileURLToPath(import.meta.url));
+    return process.platform === 'win32' ? entry.toLowerCase() === module.toLowerCase() : entry === module;
+  } catch {
+    return false;
+  }
+})();
+if (isEntryPoint) {
+  main().then(
+    (code) => { process.exitCode = code; },
+    (error) => {
+      const prefix = error instanceof OllamaError ? 'Ollama' : 'Error';
+      console.error(`${prefix}: ${error.message}`);
+      process.exitCode = 1;
+    },
+  );
+}