@buildifyx/desktop-agent 0.1.0

package/src/permissions/manager.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { normalizePolicy } from './policy.js';
+import { savePolicy } from './store.js';
+
+export function createPolicyManager(initialPolicy, { filePath } = {}) {
+  let policy = normalizePolicy(initialPolicy);
+  const listeners = new Set();
+
+  function notify() {
+    for (const listener of listeners) listener(policy);
+  }
+
+  async function persist() {
+    policy = await savePolicy(policy, filePath);
+    notify();
+    return policy;
+  }
+
+  return {
+    get: () => policy,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async setCategory(category, action) {
+      policy = normalizePolicy({ ...policy, categories: { ...policy.categories, [category]: action } });
+      return persist();
+    },
+    async addCommandRule(rule) {
+      const normalized = {
+        executable: rule.executable,
+        argsPrefix: Array.isArray(rule.argsPrefix) ? rule.argsPrefix : [],
+        action: rule.action ?? 'ask'
+      };
+      const commandRules = policy.commandRules.filter((item) =>
+        !(item.executable === normalized.executable && JSON.stringify(item.argsPrefix ?? []) === JSON.stringify(normalized.argsPrefix))
+      );
+      commandRules.push(normalized);
+      policy = normalizePolicy({ ...policy, commandRules });
+      return persist();
+    },
+    async removeCommandRule(index) {
+      policy = normalizePolicy({ ...policy, commandRules: policy.commandRules.filter((_, current) => current !== index) });
+      return persist();
+    },
+    async addRoot(root) {
+      const absolute = path.resolve(root);
+      const additionalRoots = [...new Set([...policy.additionalRoots, absolute])];
+      policy = normalizePolicy({ ...policy, additionalRoots });
+      return persist();
+    },
+    async removeRoot(index) {
+      policy = normalizePolicy({ ...policy, additionalRoots: policy.additionalRoots.filter((_, current) => current !== index) });
+      return persist();
+    }
+  };
+}

package/src/permissions/policy.js

@@ -0,0 +1,28 @@
+export const Decision = Object.freeze({
+  ALLOW: 'allow',
+  ASK: 'ask',
+  DENY: 'deny'
+});
+
+export const DEFAULT_POLICY = Object.freeze({
+  categories: {
+    read: Decision.ALLOW,
+    write: Decision.ALLOW,
+    command: Decision.ALLOW,
+    dangerous: Decision.ASK,
+    outsideRoot: Decision.ASK
+  },
+  additionalRoots: [],
+  commandRules: []
+});
+
+export function normalizePolicy(policy = {}) {
+  return {
+    categories: {
+      ...DEFAULT_POLICY.categories,
+      ...(policy.categories ?? {})
+    },
+    additionalRoots: Array.isArray(policy.additionalRoots) ? [...policy.additionalRoots] : [],
+    commandRules: Array.isArray(policy.commandRules) ? policy.commandRules.map((rule) => ({ ...rule })) : []
+  };
+}

package/src/permissions/store.js

@@ -0,0 +1,27 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { normalizePolicy } from './policy.js';
+
+export function defaultPolicyPath() {
+  return path.join(os.homedir(), '.buildifyx', 'policy.json');
+}
+
+export async function loadPolicy(filePath = defaultPolicyPath()) {
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    return normalizePolicy(JSON.parse(raw));
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return normalizePolicy();
+    }
+    throw error;
+  }
+}
+
+export async function savePolicy(policy, filePath = defaultPolicyPath()) {
+  const normalized = normalizePolicy(policy);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
+  return normalized;
+}

package/src/security/path.js

@@ -0,0 +1,61 @@
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+export function isInsideRoot(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+export function isGitInternalPath(root, target) {
+  const relative = path.relative(root, target);
+  return relative.split(path.sep).includes('.git');
+}
+
+export async function resolveSafePath(root, userPath = '.') {
+  const requested = path.resolve(root, userPath);
+
+  if (!isInsideRoot(root, requested)) {
+    throw new Error('Path is outside the allowed root directory.');
+  }
+
+  if (isGitInternalPath(root, requested)) {
+    throw new Error('Access to .git internals is not allowed.');
+  }
+
+  // Resolve symlinks as well, so a symlink inside root cannot escape root.
+  const canonical = await realpath(requested);
+  if (!isInsideRoot(root, canonical)) {
+    throw new Error('Resolved path is outside the allowed root directory.');
+  }
+
+  if (isGitInternalPath(root, canonical)) {
+    throw new Error('Access to .git internals is not allowed.');
+  }
+
+  return canonical;
+}
+
+export async function resolveSafeNewFilePath(root, userPath) {
+  const requested = path.resolve(root, userPath);
+
+  if (!isInsideRoot(root, requested)) {
+    throw new Error('Path is outside the allowed root directory.');
+  }
+
+  if (isGitInternalPath(root, requested)) {
+    throw new Error('Access to .git internals is not allowed.');
+  }
+
+  const requestedParent = path.dirname(requested);
+  const canonicalParent = await realpath(requestedParent);
+
+  if (!isInsideRoot(root, canonicalParent)) {
+    throw new Error('Resolved parent path is outside the allowed root directory.');
+  }
+
+  if (isGitInternalPath(root, canonicalParent)) {
+    throw new Error('Access to .git internals is not allowed.');
+  }
+
+  return path.join(canonicalParent, path.basename(requested));
+}

package/src/security/scope.js

@@ -0,0 +1,45 @@
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { isInsideRoot } from './path.js';
+
+function matchingRoot(roots, target) {
+  return roots.find((root) => isInsideRoot(root, target)) ?? null;
+}
+
+function assertNotGitInternal(target) {
+  if (path.resolve(target).split(path.sep).includes('.git')) {
+    throw new Error('Access to .git internals is not allowed.');
+  }
+}
+
+export async function normalizeRoots(primaryRoot, additionalRoots = []) {
+  const roots = [await realpath(primaryRoot)];
+  for (const candidate of additionalRoots) {
+    try {
+      const canonical = await realpath(candidate);
+      if (!roots.includes(canonical)) roots.push(canonical);
+    } catch {
+      // Invalid persisted roots are ignored until the user fixes them in the TUI.
+    }
+  }
+  return roots;
+}
+
+export async function classifyPath({ root, additionalRoots = [], userPath = '.', newFile = false }) {
+  const roots = await normalizeRoots(root, additionalRoots);
+  const requested = path.isAbsolute(userPath) ? path.resolve(userPath) : path.resolve(root, userPath);
+  assertNotGitInternal(requested);
+
+  if (newFile) {
+    const parent = await realpath(path.dirname(requested));
+    const resolved = path.join(parent, path.basename(requested));
+    assertNotGitInternal(resolved);
+    const matchedRoot = matchingRoot(roots, resolved);
+    return { requested, resolved, matchedRoot, scope: matchedRoot ? (matchedRoot === roots[0] ? 'root' : 'additional') : 'outside' };
+  }
+
+  const resolved = await realpath(requested);
+  assertNotGitInternal(resolved);
+  const matchedRoot = matchingRoot(roots, resolved);
+  return { requested, resolved, matchedRoot, scope: matchedRoot ? (matchedRoot === roots[0] ? 'root' : 'additional') : 'outside' };
+}

package/src/server.js

@@ -0,0 +1 @@
+export { buildMcpServer, isAllowedOrigin, startMcpServer } from './transport/mcp/server.js';

package/src/services/commands.js

@@ -0,0 +1,107 @@
+import { execFile } from 'node:child_process';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { resolveSafePath } from '../security/path.js';
+
+export const MAX_OUTPUT_BYTES = 256 * 1024;
+export const MAX_TIMEOUT_MS = 60_000;
+
+const RESTRICTED_COMMANDS = new Set(['git', 'npm', 'pnpm', 'yarn']);
+
+function validateExecutableName(command) {
+  if (command.includes('/') || command.includes('\\') || path.basename(command) !== command) {
+    throw new Error('Command must be an executable name, not a path.');
+  }
+}
+
+function validateRestrictedArgs(command, args) {
+  if (command === 'npm' && (args[0] === 'exec' || args[0] === 'x')) {
+    throw new Error('npm exec is not allowed in restricted mode.');
+  }
+  if ((command === 'pnpm' || command === 'yarn') && (args[0] === 'dlx' || args[0] === 'exec')) {
+    throw new Error(`${command} ${args[0]} is not allowed in restricted mode.`);
+  }
+}
+
+export function validateCommandPolicy(command, args, { fullAccess = false, allowCustomCommand = false } = {}) {
+  validateExecutableName(command);
+  if (fullAccess || allowCustomCommand) return;
+  if (!RESTRICTED_COMMANDS.has(command)) {
+    throw new Error(`Command is not allowed in restricted mode: ${command}`);
+  }
+  validateRestrictedArgs(command, args);
+}
+
+function resolveExecutable(command) {
+  if (process.platform === 'win32' && ['npm', 'npx', 'pnpm', 'yarn'].includes(command)) {
+    return `${command}.cmd`;
+  }
+  return command;
+}
+
+function executeFile(executable, args, options) {
+  return new Promise((resolve, reject) => {
+    execFile(executable, args, options, (error, stdout, stderr) => {
+      if (error && typeof error.code === 'string') {
+        reject(new Error(`Failed to start ${executable}: ${error.message}`));
+        return;
+      }
+      resolve({
+        exitCode: error && typeof error.code === 'number' ? error.code : 0,
+        signal: error?.signal ?? null,
+        timedOut: Boolean(error?.killed && error?.signal),
+        stdout: stdout ?? '',
+        stderr: stderr ?? ''
+      });
+    });
+  });
+}
+
+export function createCommandService({ root, fullAccess = false }) {
+  return async function runCommand({ command, args = [], cwd = '.', timeoutMs = 15_000 }, context = {}) {
+    validateCommandPolicy(command, args, { fullAccess, allowCustomCommand: context.allowCustomCommand });
+
+    const resolvedCwd = context.pathInfo?.resolved ?? await resolveSafePath(root, cwd);
+    const cwdStat = await stat(resolvedCwd);
+    if (!cwdStat.isDirectory()) throw new Error('cwd must be a directory.');
+
+    context.eventBus?.emit('process.started', {
+      requestId: context.requestId,
+      command,
+      args,
+      cwd: resolvedCwd,
+      sandboxed: false
+    });
+
+    const execution = await executeFile(resolveExecutable(command), args, {
+      cwd: resolvedCwd,
+      timeout: timeoutMs,
+      maxBuffer: MAX_OUTPUT_BYTES,
+      windowsHide: true,
+      encoding: 'utf8',
+      shell: false
+    });
+
+    context.eventBus?.emit('process.completed', {
+      requestId: context.requestId,
+      command,
+      exitCode: execution.exitCode,
+      timedOut: execution.timedOut
+    });
+
+    return {
+      command,
+      args,
+      cwd: path.relative(root, resolvedCwd) || '.',
+      mode: fullAccess ? 'full_access' : context.allowCustomCommand ? 'custom_rule' : 'restricted',
+      ...execution
+    };
+  };
+}
+
+export const commandLimits = {
+  restrictedCommands: [...RESTRICTED_COMMANDS],
+  maxOutputBytes: MAX_OUTPUT_BYTES,
+  maxTimeoutMs: MAX_TIMEOUT_MS
+};

package/src/services/files.js

@@ -0,0 +1,104 @@
+import { readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveSafeNewFilePath, resolveSafePath } from '../security/path.js';
+import {
+  MAX_TEXT_FILE_BYTES,
+  countTextLines,
+  createUtf8File,
+  readUtf8File,
+  replaceCharacters,
+  replaceLines,
+  writeUtf8FileAtomic
+} from '../utils/text.js';
+
+export { MAX_TEXT_FILE_BYTES } from '../utils/text.js';
+
+function displayPath(root, target) {
+  const relative = path.relative(root, target);
+  return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : target;
+}
+
+async function existingTarget(root, input, context) {
+  return context.pathInfo?.resolved ?? resolveSafePath(root, input.path ?? '.');
+}
+
+async function newTarget(root, input, context) {
+  return context.pathInfo?.resolved ?? resolveSafeNewFilePath(root, input.path);
+}
+
+export function createFileServices({ root }) {
+  return {
+    async list_directory(input = {}, context = {}) {
+      const target = await existingTarget(root, input, context);
+      const targetStat = await stat(target);
+      if (!targetStat.isDirectory()) throw new Error('The requested path is not a directory.');
+
+      const dirents = await readdir(target, { withFileTypes: true });
+      const limit = input.limit ?? 200;
+      const entries = dirents.slice(0, limit).map((entry) => ({
+        name: entry.name,
+        type: entry.isDirectory() ? 'directory' : entry.isFile() ? 'file' : entry.isSymbolicLink() ? 'symlink' : 'other',
+        path: displayPath(root, path.join(target, entry.name))
+      }));
+
+      context.eventBus?.emit('resource.accessed', { requestId: context.requestId, resourceType: 'directory', operation: 'list', path: target });
+      return {
+        path: displayPath(root, target),
+        scope: context.pathInfo?.scope ?? 'root',
+        total: dirents.length,
+        returned: entries.length,
+        truncated: dirents.length > entries.length,
+        entries
+      };
+    },
+
+    async read_file(input, context = {}) {
+      const target = await existingTarget(root, input, context);
+      const content = await readUtf8File(target);
+      context.eventBus?.emit('resource.accessed', { requestId: context.requestId, resourceType: 'file', operation: 'read', path: target });
+      return {
+        path: displayPath(root, target),
+        scope: context.pathInfo?.scope ?? 'root',
+        size: Buffer.byteLength(content, 'utf8'),
+        lineCount: countTextLines(content),
+        content
+      };
+    },
+
+    async write_file(input, context = {}) {
+      const target = await newTarget(root, input, context);
+      await createUtf8File(target, input.content);
+      context.eventBus?.emit('resource.accessed', { requestId: context.requestId, resourceType: 'file', operation: 'create', path: target });
+      return {
+        path: displayPath(root, target),
+        scope: context.pathInfo?.scope ?? 'root',
+        created: true,
+        size: Buffer.byteLength(input.content, 'utf8'),
+        lineCount: countTextLines(input.content)
+      };
+    },
+
+    async edit_file(input, context = {}) {
+      const target = await existingTarget(root, input, context);
+      const previousContent = await readUtf8File(target);
+      let nextContent;
+      switch (input.operation) {
+        case 'overwrite': nextContent = input.content; break;
+        case 'replace_lines': nextContent = replaceLines(previousContent, input.startLine, input.endLine, input.lines); break;
+        case 'replace_characters': nextContent = replaceCharacters(previousContent, input.start, input.end, input.content); break;
+        default: throw new Error(`Unsupported edit operation: ${input.operation}`);
+      }
+      const changed = nextContent !== previousContent;
+      if (changed) await writeUtf8FileAtomic(target, nextContent);
+      context.eventBus?.emit('resource.accessed', { requestId: context.requestId, resourceType: 'file', operation: 'write', path: target, changed });
+      return {
+        path: displayPath(root, target),
+        scope: context.pathInfo?.scope ?? 'root',
+        operation: input.operation,
+        changed,
+        size: Buffer.byteLength(nextContent, 'utf8'),
+        lineCount: countTextLines(nextContent)
+      };
+    }
+  };
+}

package/src/services/index.js

@@ -0,0 +1,11 @@
+import { createCommandService } from './commands.js';
+import { createFileServices } from './files.js';
+import { createSystemServices } from './system.js';
+
+export function createServices({ root, fullAccess = false }) {
+  return {
+    ...createSystemServices({ root }),
+    ...createFileServices({ root }),
+    run_command: createCommandService({ root, fullAccess })
+  };
+}

package/src/services/system.js

@@ -0,0 +1,17 @@
+import os from 'node:os';
+import process from 'node:process';
+
+export function createSystemServices({ root }) {
+  return {
+    async get_system_info() {
+      return {
+        platform: process.platform,
+        arch: process.arch,
+        hostname: os.hostname(),
+        osRelease: os.release(),
+        nodeVersion: process.version,
+        allowedRoot: root
+      };
+    }
+  };
+}

package/src/transport/cloud.js

@@ -0,0 +1,206 @@
+import WebSocket from 'ws';
+import { normalizeError } from '../core/errors.js';
+
+export const DEFAULT_CLOUD_ORIGIN = 'https://bdxa.buildifyx.com';
+
+export function normalizeCloudOrigin(value = DEFAULT_CLOUD_ORIGIN) {
+  const url = new URL(value);
+  if (!['https:', 'http:'].includes(url.protocol)) throw new Error('Cloud URL must use http or https.');
+  url.pathname = url.pathname.replace(/\/+$/, '');
+  url.search = '';
+  url.hash = '';
+  return url.toString().replace(/\/$/, '');
+}
+
+export function getCloudEndpoints(origin = DEFAULT_CLOUD_ORIGIN) {
+  const normalized = normalizeCloudOrigin(origin);
+  const http = new URL(normalized);
+  const ws = new URL(normalized);
+  ws.protocol = http.protocol === 'https:' ? 'wss:' : 'ws:';
+  return {
+    origin: normalized,
+    loginUrl: new URL('/api/auth/device-login', http).toString(),
+    meUrl: new URL('/api/device/me', http).toString(),
+    logoutUrl: new URL('/api/device/logout', http).toString(),
+    agentUrl: new URL('/agent', ws).toString()
+  };
+}
+
+async function parseJsonResponse(response) {
+  const text = await response.text();
+  let body = null;
+  if (text) {
+    try { body = JSON.parse(text); } catch { body = { message: text }; }
+  }
+  if (!response.ok) {
+    const message = body?.error?.message ?? body?.message ?? `Cloud request failed (${response.status})`;
+    const error = new Error(message);
+    error.status = response.status;
+    throw error;
+  }
+  return body;
+}
+
+export async function loginDevice({ cloudUrl = DEFAULT_CLOUD_ORIGIN, token, device, signal }) {
+  const { loginUrl } = getCloudEndpoints(cloudUrl);
+  const response = await fetch(loginUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({ token, device }),
+    signal
+  });
+  return parseJsonResponse(response);
+}
+
+export async function getDeviceMe({ cloudUrl = DEFAULT_CLOUD_ORIGIN, deviceToken, signal }) {
+  const { meUrl } = getCloudEndpoints(cloudUrl);
+  const response = await fetch(meUrl, {
+    headers: { authorization: `Bearer ${deviceToken}`, accept: 'application/json' },
+    signal
+  });
+  return parseJsonResponse(response);
+}
+
+export async function logoutDevice({ cloudUrl = DEFAULT_CLOUD_ORIGIN, deviceToken, signal }) {
+  const { logoutUrl } = getCloudEndpoints(cloudUrl);
+  const response = await fetch(logoutUrl, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${deviceToken}`, accept: 'application/json' },
+    signal
+  });
+  if (response.status === 204) return null;
+  return parseJsonResponse(response);
+}
+
+function safeSend(socket, payload) {
+  if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(payload));
+}
+
+export function createCloudAgent({
+  cloudUrl = DEFAULT_CLOUD_ORIGIN,
+  credentials,
+  runtime,
+  manifest,
+  version,
+  deviceInfo,
+  eventBus,
+  heartbeatMs = 30_000,
+  reconnect = true
+}) {
+  const endpoint = getCloudEndpoints(cloudUrl).agentUrl;
+  let socket = null;
+  let stopped = false;
+  let heartbeat = null;
+  let retryTimer = null;
+  let retryAttempt = 0;
+  const listeners = new Set();
+  let state = { status: 'disconnected', endpoint, retryAttempt: 0, lastError: null };
+
+  function setState(patch) {
+    state = { ...state, ...patch };
+    eventBus?.emit('cloud.connection', state);
+    for (const listener of listeners) listener({ ...state });
+  }
+
+  function scheduleReconnect() {
+    if (stopped || !reconnect || retryTimer) return;
+    const delays = [1000, 2000, 5000, 10_000, 30_000];
+    const delay = delays[Math.min(retryAttempt, delays.length - 1)];
+    retryAttempt += 1;
+    setState({ status: 'reconnecting', retryAttempt, retryInMs: delay });
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      connect();
+    }, delay);
+    retryTimer.unref?.();
+  }
+
+  async function handleMessage(raw) {
+    let message;
+    try { message = JSON.parse(raw.toString()); } catch { return; }
+    if (message.type === 'ping') {
+      safeSend(socket, { type: 'pong', timestamp: new Date().toISOString() });
+      return;
+    }
+    if (message.type !== 'tool.call' || !message.requestId || !message.tool) return;
+
+    eventBus?.emit('cloud.tool.received', { requestId: message.requestId, tool: message.tool });
+    try {
+      const result = await runtime.dispatch(message.tool, message.arguments ?? {});
+      safeSend(socket, { type: 'tool.result', requestId: message.requestId, result });
+    } catch (error) {
+      const normalized = normalizeError(error);
+      safeSend(socket, {
+        type: 'tool.error',
+        requestId: message.requestId,
+        error: { code: normalized.code, message: normalized.message, details: normalized.details }
+      });
+    }
+  }
+
+  function connect() {
+    if (stopped) return;
+    if (socket && [WebSocket.OPEN, WebSocket.CONNECTING].includes(socket.readyState)) return;
+    setState({ status: 'connecting', endpoint, lastError: null });
+    socket = new WebSocket(endpoint, {
+      headers: {
+        authorization: `Bearer ${credentials.deviceToken}`,
+        'user-agent': `buildifyx-desktop-agent/${version}`
+      }
+    });
+
+    socket.on('open', () => {
+      retryAttempt = 0;
+      setState({ status: 'connected', retryAttempt: 0, retryInMs: null, connectedAt: new Date().toISOString() });
+      safeSend(socket, {
+        type: 'device.ready',
+        deviceId: credentials.deviceId,
+        agentVersion: version,
+        device: deviceInfo,
+        toolManifest: { count: manifest.count, hash: manifest.hash, manifestVersion: manifest.manifestVersion }
+      });
+      clearInterval(heartbeat);
+      heartbeat = setInterval(() => safeSend(socket, {
+        type: 'device.heartbeat',
+        deviceId: credentials.deviceId,
+        timestamp: new Date().toISOString()
+      }), heartbeatMs);
+      heartbeat.unref?.();
+    });
+
+    socket.on('message', (raw) => { void handleMessage(raw); });
+    socket.on('error', (error) => setState({ lastError: error.message }));
+    socket.on('close', (code, reason) => {
+      clearInterval(heartbeat);
+      heartbeat = null;
+      socket = null;
+      setState({ status: 'disconnected', closeCode: code, closeReason: reason.toString() || null });
+      scheduleReconnect();
+    });
+  }
+
+  async function stop() {
+    stopped = true;
+    clearInterval(heartbeat);
+    clearTimeout(retryTimer);
+    heartbeat = null;
+    retryTimer = null;
+    if (!socket) return;
+    await new Promise((resolve) => {
+      const active = socket;
+      const timeout = setTimeout(resolve, 1000);
+      active.once('close', () => { clearTimeout(timeout); resolve(); });
+      active.close(1000, 'agent shutdown');
+    });
+    socket = null;
+    setState({ status: 'stopped' });
+  }
+
+  return {
+    endpoint,
+    connect,
+    stop,
+    getState: () => ({ ...state }),
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); }
+  };
+}