@buildifyx/desktop-agent 0.1.0

package/src/cli/commands/update.js

@@ -0,0 +1,31 @@
+import { execFile } from 'node:child_process';
+import process from 'node:process';
+import { checkForUpdate, getPackageMetadata } from '../../version.js';
+
+function npmExecutable() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function runProcess(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, args, { ...options, windowsHide: false }, (error) => {
+      if (error) return reject(error);
+      resolve();
+    });
+    child.stdout?.pipe(process.stdout);
+    child.stderr?.pipe(process.stderr);
+  });
+}
+
+export async function runUpdate() {
+  const metadata = await getPackageMetadata();
+  const status = await checkForUpdate(metadata.name, metadata.version);
+  if (!status.updateAvailable) {
+    console.log(status.latestVersion ? `Already up to date (${metadata.version}).` : `Installed version: ${metadata.version}. Could not verify npm registry.`);
+    return;
+  }
+
+  console.log(`Updating ${metadata.name} to the latest version...`);
+  await runProcess(npmExecutable(), ['install', '--global', `${metadata.name}@latest`]);
+  console.log('Update complete. Run bdxa again to use the latest version.');
+}

package/src/cli/help.js

@@ -0,0 +1,52 @@
+export function printHelp() {
+  console.log(`bdxa — Buildifyx Desktop Agent
+
+Usage:
+  bdxa [options]
+  bdxa <command> [options]
+
+Default:
+  Running bdxa connects this device to Buildifyx Cloud at bdxa.buildifyx.com.
+  Login once with a one-time token before connecting.
+
+Commands:
+  login       Authenticate this device with a login token
+  logout      Revoke this device credential and remove it locally
+  status      Show device authentication status
+  connect     Connect to Buildifyx Cloud (same as default bdxa)
+  local       Start the legacy local MCP HTTP server for development
+  doctor, d   Check environment, root access, and package version
+  update, u   Update Buildifyx Desktop Agent from npm
+  help        Show this help message
+
+Global options:
+  -h, --help        Show help
+  -v, --version     Show installed version
+
+Cloud options:
+  --root <path>     Primary workspace root (default: current directory)
+  --full-access     Permit arbitrary executable names; execution is not sandboxed
+  --no-tui          Disable the interactive TUI; ASK returns confirmation-required
+
+Login options:
+  --token <token>   Login token (prefer interactive input to avoid shell history)
+  --cloud <url>     Cloud origin (default: https://bdxa.buildifyx.com)
+
+Local development options:
+  --root <path>     Primary workspace root
+  --port <number>   Local MCP port (default: 3333)
+  --full-access     Permit arbitrary executable names
+  --no-tui          Disable the interactive TUI
+
+Examples:
+  bdxa login
+  bdxa status
+  bdxa --root ~/projects
+  bdxa connect --root ~/projects
+  bdxa logout
+  bdxa local --root ~/projects --port 3333
+  bdxa doctor
+  bdxa update
+  bdxa -v
+`);
+}

package/src/cli/main.js

@@ -0,0 +1,55 @@
+import { printHelp } from './help.js';
+import { parseInvocation } from './options.js';
+import { runCloud } from './commands/cloud.js';
+import { runDoctor } from './commands/doctor.js';
+import { runLogin } from './commands/login.js';
+import { runLogout } from './commands/logout.js';
+import { runRemote } from './commands/remote.js';
+import { runStatus } from './commands/status.js';
+import { runUpdate } from './commands/update.js';
+import { getPackageMetadata } from '../version.js';
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const { command, args } = parseInvocation(argv);
+
+  if (command === '-h' || command === '--help' || command === 'help') {
+    printHelp();
+    return;
+  }
+  if (command === '-v' || command === '--version') {
+    console.log((await getPackageMetadata()).version);
+    return;
+  }
+  if (command === 'update' || command === 'u') {
+    await runUpdate();
+    return;
+  }
+
+  switch (command) {
+    case 'cloud':
+    case 'connect':
+      await runCloud(args);
+      return;
+    case 'login':
+      await runLogin(args);
+      return;
+    case 'logout':
+      await runLogout();
+      return;
+    case 'status':
+      await runStatus();
+      return;
+    case 'local':
+    case 'remote':
+    case 'r':
+      await runRemote(args);
+      return;
+    case 'doctor':
+    case 'd':
+      await runDoctor(args);
+      return;
+    default:
+      printHelp();
+      throw new Error(`Unknown command: ${command}`);
+  }
+}

package/src/cli/options.js

@@ -0,0 +1,34 @@
+import { access, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+export function getOption(args, name, fallback) {
+  const index = args.indexOf(name);
+  if (index === -1) return fallback;
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) throw new Error(`Missing value for ${name}`);
+  return value;
+}
+
+export function hasFlag(args, name) {
+  return args.includes(name);
+}
+
+export async function resolveRoot(input = process.cwd()) {
+  const candidate = path.resolve(input);
+  await access(candidate);
+  return realpath(candidate);
+}
+
+export function parsePort(value = '3333') {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid port: ${value}`);
+  return port;
+}
+
+export function parseInvocation(argv) {
+  const first = argv[0];
+  const cloudFlags = new Set(['--root', '--full-access', '--no-tui']);
+  if (!first || cloudFlags.has(first)) return { command: 'cloud', args: argv };
+  return { command: first, args: argv.slice(1) };
+}

package/src/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import { runCli } from './cli/main.js';
+
+runCli().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`\nError: ${message}`);
+
+  if (error instanceof Error && error.cause) {
+    const cause = error.cause;
+    if (cause instanceof Error) {
+      const details = [cause.code, cause.message].filter(Boolean).join(': ');
+      if (details) console.error(`Cause: ${details}`);
+    } else {
+      console.error(`Cause: ${String(cause)}`);
+    }
+  }
+
+  process.exitCode = 1;
+});

package/src/core/dispatcher.js

@@ -0,0 +1,49 @@
+import { randomUUID } from 'node:crypto';
+import { AgentError, ErrorCode, normalizeError } from './errors.js';
+
+function summarizeInput(toolName, input = {}) {
+  const summary = { ...input };
+  if (typeof summary.content === 'string') summary.content = `<${summary.content.length} chars>`;
+  if (Array.isArray(summary.lines)) summary.lines = `<${summary.lines.length} lines>`;
+  return summary;
+}
+
+export function createDispatcher({ services, authorize, eventBus }) {
+  if (!services || typeof services !== 'object') {
+    throw new AgentError(ErrorCode.INTERNAL_ERROR, 'services are required');
+  }
+
+  return async function dispatch(toolName, input = {}) {
+    const requestId = randomUUID();
+    const startedAt = Date.now();
+    const handler = services[toolName];
+
+    eventBus?.emit('tool.started', {
+      requestId,
+      tool: toolName,
+      input: summarizeInput(toolName, input)
+    });
+
+    if (typeof handler !== 'function') {
+      const error = new AgentError(ErrorCode.TOOL_NOT_FOUND, `Unknown tool: ${toolName}`, { toolName });
+      eventBus?.emit('tool.failed', { requestId, tool: toolName, durationMs: Date.now() - startedAt, error: { code: error.code, message: error.message } });
+      throw error;
+    }
+
+    try {
+      const context = authorize ? await authorize(toolName, input, requestId) : {};
+      const result = await handler(input, { ...context, requestId, eventBus });
+      eventBus?.emit('tool.completed', { requestId, tool: toolName, durationMs: Date.now() - startedAt });
+      return result;
+    } catch (error) {
+      const normalized = normalizeError(error);
+      eventBus?.emit('tool.failed', {
+        requestId,
+        tool: toolName,
+        durationMs: Date.now() - startedAt,
+        error: { code: normalized.code, message: normalized.message }
+      });
+      throw normalized;
+    }
+  };
+}

package/src/core/errors.js

@@ -0,0 +1,37 @@
+export const ErrorCode = Object.freeze({
+  TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  CONFIRMATION_REQUIRED: 'CONFIRMATION_REQUIRED',
+  PATH_OUTSIDE_ROOT: 'PATH_OUTSIDE_ROOT',
+  GIT_INTERNAL_PATH: 'GIT_INTERNAL_PATH',
+  FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+  FILE_NOT_REGULAR: 'FILE_NOT_REGULAR',
+  FILE_TOO_LARGE: 'FILE_TOO_LARGE',
+  INVALID_TEXT_FILE: 'INVALID_TEXT_FILE',
+  FILE_EXISTS: 'FILE_EXISTS',
+  COMMAND_NOT_ALLOWED: 'COMMAND_NOT_ALLOWED',
+  COMMAND_TIMEOUT: 'COMMAND_TIMEOUT',
+  INVALID_INPUT: 'INVALID_INPUT',
+  INTERNAL_ERROR: 'INTERNAL_ERROR'
+});
+
+export class AgentError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'AgentError';
+    this.code = code;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export function isAgentError(error) {
+  return error instanceof AgentError;
+}
+
+export function normalizeError(error, fallbackCode = ErrorCode.INTERNAL_ERROR) {
+  if (isAgentError(error)) return error;
+  return new AgentError(
+    fallbackCode,
+    error instanceof Error ? error.message : String(error)
+  );
+}

package/src/core/permissions.js

@@ -0,0 +1,53 @@
+import { AgentError, ErrorCode } from './errors.js';
+
+export const PermissionAction = Object.freeze({
+  ALLOW: 'allow',
+  DENY: 'deny',
+  CONFIRM: 'confirm'
+});
+
+export const ToolPermission = Object.freeze({
+  get_system_info: 'read',
+  list_directory: 'read',
+  read_file: 'read',
+  write_file: 'write',
+  edit_file: 'write',
+  run_command: 'command'
+});
+
+export const DEFAULT_PERMISSION_POLICY = Object.freeze({
+  read: PermissionAction.ALLOW,
+  write: PermissionAction.ALLOW,
+  command: PermissionAction.ALLOW
+});
+
+export function createPermissionPolicy(overrides = {}) {
+  return {
+    ...DEFAULT_PERMISSION_POLICY,
+    ...overrides
+  };
+}
+
+export function assertToolPermission(toolName, policy = DEFAULT_PERMISSION_POLICY) {
+  const permission = ToolPermission[toolName];
+  if (!permission) {
+    throw new AgentError(ErrorCode.TOOL_NOT_FOUND, `Unknown tool: ${toolName}`);
+  }
+
+  const action = policy[permission] ?? PermissionAction.DENY;
+  if (action === PermissionAction.DENY) {
+    throw new AgentError(ErrorCode.PERMISSION_DENIED, `Permission denied for ${toolName} (${permission}).`, {
+      toolName,
+      permission
+    });
+  }
+
+  if (action === PermissionAction.CONFIRM) {
+    throw new AgentError(ErrorCode.CONFIRMATION_REQUIRED, `Confirmation required for ${toolName} (${permission}).`, {
+      toolName,
+      permission
+    });
+  }
+
+  return permission;
+}

package/src/core/runtime.js

@@ -0,0 +1,45 @@
+import { createDispatcher } from './dispatcher.js';
+import { createServices } from '../services/index.js';
+import { createEventBus } from '../events/bus.js';
+import { createApprovalQueue } from '../permissions/approvals.js';
+import { createPermissionController } from '../permissions/controller.js';
+import { createPolicyManager } from '../permissions/manager.js';
+import { normalizePolicy } from '../permissions/policy.js';
+
+function legacyPermissionsToPolicy(permissions) {
+  if (!permissions) return undefined;
+  const map = (value) => value === 'confirm' ? 'ask' : value;
+  return {
+    categories: {
+      read: map(permissions.read),
+      write: map(permissions.write),
+      command: map(permissions.command)
+    }
+  };
+}
+
+export function createRuntime({
+  root,
+  fullAccess = false,
+  permissions,
+  policy = legacyPermissionsToPolicy(permissions),
+  policyManager = createPolicyManager(normalizePolicy(policy)),
+  eventBus = createEventBus(),
+  approvalQueue,
+  interactive = !permissions
+}) {
+  const activeApprovalQueue = interactive ? (approvalQueue ?? createApprovalQueue({ eventBus })) : null;
+  const services = createServices({ root, fullAccess });
+  const authorize = createPermissionController({ root, policyManager, approvalQueue: activeApprovalQueue, eventBus });
+  const dispatch = createDispatcher({ services, authorize, eventBus });
+
+  return {
+    root,
+    fullAccess,
+    policyManager,
+    eventBus,
+    approvalQueue: activeApprovalQueue,
+    services,
+    dispatch
+  };
+}

package/src/events/bus.js

@@ -0,0 +1,39 @@
+import { randomUUID } from 'node:crypto';
+
+export function createEventBus({ maxHistory = 500 } = {}) {
+  const listeners = new Set();
+  const history = [];
+
+  function emit(type, data = {}) {
+    const event = {
+      id: randomUUID(),
+      type,
+      timestamp: new Date().toISOString(),
+      ...data
+    };
+
+    history.push(event);
+    if (history.length > maxHistory) history.splice(0, history.length - maxHistory);
+
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Observers must never break agent execution.
+      }
+    }
+
+    return event;
+  }
+
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  return {
+    emit,
+    subscribe,
+    getHistory: () => [...history]
+  };
+}

package/src/permissions/approvals.js

@@ -0,0 +1,47 @@
+import { randomUUID } from 'node:crypto';
+
+function auditSafeDetails(details) {
+  const input = { ...(details.input ?? {}) };
+  if (typeof input.content === 'string') input.content = `<${input.content.length} chars>`;
+  if (Array.isArray(input.lines)) input.lines = `<${input.lines.length} lines>`;
+  return { ...details, input };
+}
+
+export function createApprovalQueue({ eventBus } = {}) {
+  const pending = new Map();
+  const listeners = new Set();
+
+  function notify() {
+    const requests = [...pending.values()].map(({ resolve, ...request }) => request);
+    for (const listener of listeners) listener(requests);
+  }
+
+  function request(details) {
+    const id = randomUUID();
+    return new Promise((resolve) => {
+      pending.set(id, { id, createdAt: new Date().toISOString(), ...details, resolve });
+      eventBus?.emit('permission.requested', { requestId: id, ...auditSafeDetails(details) });
+      notify();
+    });
+  }
+
+  function resolveRequest(id, decision) {
+    const item = pending.get(id);
+    if (!item) return false;
+    pending.delete(id);
+    item.resolve(decision);
+    eventBus?.emit('permission.resolved', { requestId: id, ...decision });
+    notify();
+    return true;
+  }
+
+  return {
+    request,
+    resolve: resolveRequest,
+    getPending: () => [...pending.values()].map(({ resolve, ...request }) => request),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}

package/src/permissions/controller.js

@@ -0,0 +1,92 @@
+import { AgentError, ErrorCode } from '../core/errors.js';
+import { classifyPath } from '../security/scope.js';
+import { describeRequest, evaluateRequest, getRequestedPath, isFullAccessPolicy, matchCommandRule } from './evaluator.js';
+import { Decision } from './policy.js';
+
+function resourceOperation(toolName) {
+  if (toolName === 'list_directory') return 'list';
+  if (toolName === 'read_file') return 'read';
+  if (toolName === 'write_file') return 'create';
+  if (toolName === 'edit_file') return 'write';
+  if (toolName === 'run_command') return 'cwd';
+  return null;
+}
+
+export function createPermissionController({ root, policyManager, approvalQueue, eventBus }) {
+  return async function authorize(toolName, input, requestId) {
+    const policy = policyManager.get();
+    let pathInfo = null;
+    let approvedByPrompt = false;
+    const requestedPath = getRequestedPath(toolName, input);
+
+    if (requestedPath) {
+      pathInfo = await classifyPath({
+        root,
+        additionalRoots: policy.additionalRoots,
+        userPath: requestedPath,
+        newFile: toolName === 'write_file'
+      });
+      eventBus?.emit('resource.access.requested', {
+        requestId,
+        tool: toolName,
+        resourceType: toolName === 'run_command' ? 'directory' : 'file',
+        operation: resourceOperation(toolName),
+        path: pathInfo.resolved,
+        scope: pathInfo.scope
+      });
+    }
+
+    const evaluation = evaluateRequest({
+      toolName,
+      input,
+      policy,
+      pathScope: pathInfo?.scope === 'outside' ? 'outside' : 'root'
+    });
+
+    eventBus?.emit('permission.evaluated', {
+      requestId,
+      tool: toolName,
+      decision: evaluation.decision,
+      category: evaluation.category,
+      reason: evaluation.reason
+    });
+
+    let approved = evaluation.decision === Decision.ALLOW;
+    if (evaluation.decision === Decision.ASK) {
+      if (!approvalQueue) {
+        throw new AgentError(ErrorCode.CONFIRMATION_REQUIRED, `Confirmation required: ${describeRequest(toolName, input)}`);
+      }
+      const decision = await approvalQueue.request({
+        toolName,
+        input,
+        description: describeRequest(toolName, input),
+        category: evaluation.category,
+        pathInfo,
+        evaluation
+      });
+      approved = decision.action === 'allow';
+      approvedByPrompt = approved;
+      if (approved && decision.remember === 'command' && toolName === 'run_command') {
+        await policyManager.addCommandRule({ executable: input.command, argsPrefix: input.args ?? [], action: 'allow' });
+      }
+      if (approved && decision.remember === 'root' && pathInfo?.scope === 'outside') {
+        await policyManager.addRoot(pathInfo.resolved);
+      }
+    }
+
+    if (!approved || evaluation.decision === Decision.DENY) {
+      throw new AgentError(ErrorCode.PERMISSION_DENIED, `Permission denied: ${describeRequest(toolName, input)}`, {
+        toolName,
+        category: evaluation.category
+      });
+    }
+
+    const currentPolicy = policyManager.get();
+    return {
+      pathInfo,
+      allowCustomCommand: toolName === 'run_command' && (
+        isFullAccessPolicy(currentPolicy) || approvedByPrompt || Boolean(matchCommandRule(currentPolicy, input.command, input.args ?? []))
+      )
+    };
+  };
+}

package/src/permissions/evaluator.js

@@ -0,0 +1,93 @@
+import { Decision } from './policy.js';
+
+const TOOL_CATEGORY = Object.freeze({
+  get_system_info: 'read',
+  list_directory: 'read',
+  read_file: 'read',
+  write_file: 'write',
+  edit_file: 'write',
+  run_command: 'command'
+});
+
+const FILE_TOOLS = new Set(['list_directory', 'read_file', 'write_file', 'edit_file']);
+const DANGEROUS_COMMANDS = new Set(['rm', 'rmdir', 'del', 'erase', 'format', 'shutdown', 'reboot', 'kill', 'taskkill']);
+
+function startsWithArgs(args, prefix = []) {
+  return prefix.every((value, index) => args[index] === value);
+}
+
+export function matchCommandRule(policy, command, args = []) {
+  const matches = policy.commandRules
+    .map((rule, index) => ({ rule, index }))
+    .filter(({ rule }) => rule.executable === command && startsWithArgs(args, rule.argsPrefix ?? []));
+
+  if (!matches.length) return undefined;
+
+  // Prefer the most specific argument-prefix rule. If two rules are equally
+  // specific, prefer the latest one so a newer user choice wins predictably.
+  matches.sort((left, right) => {
+    const specificity = (right.rule.argsPrefix?.length ?? 0) - (left.rule.argsPrefix?.length ?? 0);
+    return specificity !== 0 ? specificity : right.index - left.index;
+  });
+
+  return matches[0].rule;
+}
+
+export function isDangerousCommand(command, args = []) {
+  if (DANGEROUS_COMMANDS.has(command)) return true;
+  if (command === 'git' && ['clean', 'reset'].includes(args[0])) return true;
+  if (['npm', 'pnpm', 'yarn'].includes(command) && ['uninstall', 'remove'].includes(args[0])) return true;
+  return false;
+}
+
+export function getRequestedPath(toolName, input = {}) {
+  if (FILE_TOOLS.has(toolName) && typeof input.path === 'string') return input.path;
+  if (toolName === 'run_command' && typeof input.cwd === 'string') return input.cwd;
+  return null;
+}
+
+export function isFullAccessPolicy(policy) {
+  return ['read', 'write', 'command', 'dangerous', 'outsideRoot']
+    .every((category) => policy.categories[category] === Decision.ALLOW);
+}
+
+export function evaluateRequest({ toolName, input = {}, policy, pathScope = 'root' }) {
+  const category = TOOL_CATEGORY[toolName];
+  if (!category) return { decision: Decision.DENY, category: 'unknown', reason: 'Unknown tool' };
+
+  if (pathScope === 'outside') {
+    return {
+      decision: policy.categories.outsideRoot ?? Decision.DENY,
+      category: 'outsideRoot',
+      reason: 'Path is outside configured roots'
+    };
+  }
+
+  if (toolName === 'run_command') {
+    const args = input.args ?? [];
+    const rule = matchCommandRule(policy, input.command, args);
+    if (rule) {
+      const pattern = [rule.executable, ...(rule.argsPrefix ?? [])].join(' ');
+      return { decision: rule.action, category: 'commandRule', rule, reason: `Matched command rule: ${pattern}` };
+    }
+    if (isDangerousCommand(input.command, args)) {
+      return {
+        decision: policy.categories.dangerous ?? Decision.ASK,
+        category: 'dangerous',
+        reason: 'Command is potentially destructive'
+      };
+    }
+  }
+
+  return {
+    decision: policy.categories[category] ?? Decision.DENY,
+    category,
+    reason: `Policy category: ${category}`
+  };
+}
+
+export function describeRequest(toolName, input = {}) {
+  if (toolName === 'run_command') return `${input.command ?? ''} ${(input.args ?? []).join(' ')}`.trim();
+  if (typeof input.path === 'string') return `${toolName}: ${input.path}`;
+  return toolName;
+}