amalgm 0.1.161 → 0.1.162

package/runtime/scripts/amalgm-mcp/workspace/tree/inclusion.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const path = require('path');
+
+const EXCLUDED_DIRECTORIES = new Set([
+  '.amalgm',
+  '.cache',
+  '.git',
+  '.gradle',
+  '.hg',
+  '.mypy_cache',
+  '.next',
+  '.nyc_output',
+  '.parcel-cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.ssh',
+  '.svn',
+  '.svelte-kit',
+  '.turbo',
+  '.venv',
+  '.vite',
+  '__pycache__',
+  'coverage',
+  'node_modules',
+]);
+
+const EXCLUDED_FILES = new Set([
+  '.DS_Store',
+  'Thumbs.db',
+  'desktop.ini',
+  'npm-debug.log',
+  'pnpm-debug.log',
+  'yarn-debug.log',
+  'yarn-error.log',
+]);
+
+function partsFor(relativePath) {
+  return String(relativePath || '').split(/[\\/]/).filter(Boolean);
+}
+
+function isPrivateFile(name) {
+  if (/^\.env(?:\..+)?$/i.test(name) && !/\.example$/i.test(name)) return true;
+  return /^(?:credentials?|secrets?)\.(?:json|ya?ml|toml)$/i.test(name);
+}
+
+// Machine-local metadata, dependencies, generated caches, and secrets never
+// receive workspace identities. The rule applies at every depth. Symlinks are
+// enrolled as leaf nodes and are never followed by the scanner.
+function shouldEnroll(relativePath) {
+  const parts = partsFor(relativePath);
+  if (parts.length === 0 || parts.some((part) => EXCLUDED_DIRECTORIES.has(part))) return false;
+  const name = parts.at(-1);
+  if (EXCLUDED_FILES.has(name) || isPrivateFile(name)) return false;
+  return !name.startsWith('.#') && !name.endsWith('~') && !/\.(?:swp|swo)$/i.test(name);
+}
+
+function shouldSync(relativePath) {
+  return shouldEnroll(relativePath);
+}
+
+function relativeWorkspacePath(workspacePath, absolutePath) {
+  const relative = path.relative(workspacePath, absolutePath);
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) return null;
+  return relative.split(path.sep).join('/');
+}
+
+module.exports = { relativeWorkspacePath, shouldEnroll, shouldSync };

package/runtime/scripts/amalgm-mcp/workspace/tree/local-state.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { AMALGM_DIR } = require('../../config');
+const { openLocalDb } = require('../../state/db');
+const { descendantsInclude } = require('./reducer');
+
+function invalid(message, statusCode = 400) {
+  return Object.assign(new Error(message), { statusCode });
+}
+
+function rowToNode(row) {
+  if (!row) return null;
+  return {
+    id: row.id,
+    workspaceId: row.workspace_id,
+    parentId: row.parent_id || null,
+    kind: row.kind,
+    name: row.name,
+    relativePath: row.relative_path,
+    symlinkTarget: row.symlink_target || null,
+    deviceId: row.device_id || null,
+    inode: row.inode || null,
+    trashedAt: row.trashed_at || null,
+    purgedAt: row.purged_at || null,
+    missingAt: row.missing_at || null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function workspaceRow(identifier, database = openLocalDb()) {
+  return database.prepare(`
+    SELECT workspaces.*
+    FROM workspaces
+    LEFT JOIN workspace_id_aliases ON workspace_id_aliases.workspace_id = workspaces.id
+    WHERE workspaces.id = ? OR workspaces.path = ? OR workspace_id_aliases.alias_id = ?
+    LIMIT 1
+  `).get(identifier, identifier, identifier) || null;
+}
+
+function relativePathForNode(nodes, nodeId, memo = new Map()) {
+  if (memo.has(nodeId)) return memo.get(nodeId);
+  const node = nodes.get(nodeId);
+  if (!node) throw invalid(`node ${nodeId} does not exist`, 404);
+  if (node.id === node.workspaceId) {
+    memo.set(nodeId, '');
+    return '';
+  }
+  const parentPath = relativePathForNode(nodes, node.parentId, memo);
+  const relativePath = parentPath ? `${parentPath}/${node.name}` : node.name;
+  memo.set(nodeId, relativePath);
+  return relativePath;
+}
+
+function trashPath(workspaceId, nodeId) {
+  return path.join(AMALGM_DIR, 'trash', 'workspaces', workspaceId, nodeId);
+}
+
+function requireMissing(targetPath, message) {
+  try {
+    fs.lstatSync(targetPath);
+    throw invalid(message, 409);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+function materializeOperation(workspace, before, after, operation) {
+  const oldNode = before.get(operation.nodeId) || null;
+  const newNode = after.get(operation.nodeId) || null;
+  const oldRelative = oldNode ? relativePathForNode(before, oldNode.id) : null;
+  const newRelative = newNode ? relativePathForNode(after, newNode.id) : null;
+  const oldPath = oldRelative ? path.join(workspace.path, ...oldRelative.split('/')) : null;
+  const newPath = newRelative ? path.join(workspace.path, ...newRelative.split('/')) : null;
+
+  if (operation.kind === 'tree.create') {
+    requireMissing(newPath, 'create destination already exists');
+    fs.mkdirSync(path.dirname(newPath), { recursive: true });
+    if (operation.nodeKind === 'folder') fs.mkdirSync(newPath);
+    else if (operation.nodeKind === 'symlink') fs.symlinkSync(operation.symlinkTarget, newPath);
+    else fs.writeFileSync(newPath, '');
+  } else if (operation.kind === 'tree.rename' || operation.kind === 'tree.move') {
+    requireMissing(newPath, 'move destination already exists');
+    fs.mkdirSync(path.dirname(newPath), { recursive: true });
+    fs.renameSync(oldPath, newPath);
+  } else if (operation.kind === 'tree.trash') {
+    const destination = trashPath(workspace.id, operation.nodeId);
+    requireMissing(destination, 'trash destination already exists');
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.renameSync(oldPath, destination);
+  } else if (operation.kind === 'tree.restore') {
+    const source = trashPath(workspace.id, operation.nodeId);
+    requireMissing(newPath, 'restore destination already exists');
+    fs.mkdirSync(path.dirname(newPath), { recursive: true });
+    fs.renameSync(source, newPath);
+  } else if (operation.kind === 'tree.purge') {
+    for (const node of before.values()) {
+      if (node.id === operation.nodeId || descendantsInclude(before, operation.nodeId, node.id)) {
+        fs.rmSync(trashPath(workspace.id, node.id), { recursive: true, force: true });
+      }
+    }
+  }
+
+  return { oldPath, newPath };
+}
+
+function absolutePathForWorkspace(workspaceId, relativePath, database) {
+  const workspace = database.prepare('SELECT path FROM workspaces WHERE id = ?').get(workspaceId);
+  if (!workspace) throw invalid('workspace not found', 404);
+  return relativePath ? path.join(workspace.path, ...relativePath.split('/')) : workspace.path;
+}
+
+function persistNodes(database, before, after, workspaceId) {
+  const now = new Date().toISOString();
+  const pathMemo = new Map();
+  const changedPaths = [];
+  for (const node of after.values()) {
+    const relativePath = relativePathForNode(after, node.id, pathMemo);
+    const previous = before.get(node.id);
+    const previousRelative = previous ? relativePathForNode(before, previous.id) : null;
+    if (!previous) {
+      const absolutePath = relativePath ? absolutePathForWorkspace(workspaceId, relativePath, database) : null;
+      const stats = absolutePath ? fs.lstatSync(absolutePath) : null;
+      database.prepare(`
+        INSERT INTO workspace_nodes (
+          id, workspace_id, parent_id, kind, name, relative_path, symlink_target,
+          device_id, inode, trashed_at, purged_at, missing_at, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)
+      `).run(
+        node.id, node.workspaceId, node.parentId, node.kind, node.name,
+        relativePath, node.symlinkTarget, stats ? String(stats.dev) : null,
+        stats ? String(stats.ino) : null, node.trashedAt, node.purgedAt,
+        node.createdAt, now,
+      );
+    } else {
+      database.prepare(`
+        UPDATE workspace_nodes
+        SET parent_id = ?, name = ?, relative_path = ?, trashed_at = ?,
+            purged_at = ?, missing_at = NULL, updated_at = ?
+        WHERE id = ?
+      `).run(node.parentId, node.name, relativePath, node.trashedAt, node.purgedAt, now, node.id);
+      if (previousRelative !== relativePath) {
+        changedPaths.push({
+          nodeId: node.id,
+          oldPath: absolutePathForWorkspace(workspaceId, previousRelative, database),
+          newPath: absolutePathForWorkspace(workspaceId, relativePath, database),
+        });
+      }
+    }
+  }
+  return changedPaths;
+}
+
+function hasAncestorInSet(node, nodesById, ids) {
+  let current = node.parentId;
+  const seen = new Set();
+  while (current && !seen.has(current)) {
+    if (ids.has(current)) return true;
+    seen.add(current);
+    current = nodesById.get(current)?.parentId || null;
+  }
+  return false;
+}
+
+module.exports = {
+  hasAncestorInSet,
+  materializeOperation,
+  persistNodes,
+  relativePathForNode,
+  rowToNode,
+  workspaceRow,
+};

package/runtime/scripts/amalgm-mcp/workspace/tree/operations.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const path = require('path');
+const { isUuid } = require('./identity');
+
+const CONTRACT = 'workspace-tree@1';
+const KINDS = Object.freeze(['folder', 'file', 'symlink']);
+const OPERATION_KINDS = Object.freeze([
+  'tree.create',
+  'tree.rename',
+  'tree.move',
+  'tree.trash',
+  'tree.restore',
+  'tree.purge',
+]);
+
+function invalid(message) {
+  const error = new Error(message);
+  error.statusCode = 400;
+  return error;
+}
+
+function nodeId(value, field) {
+  if (!isUuid(value)) throw invalid(`${field} must be a UUID`);
+  return value.toLowerCase();
+}
+
+function nodeName(value) {
+  const name = typeof value === 'string' ? value.trim() : '';
+  if (!name || name === '.' || name === '..' || name.length > 255) {
+    throw invalid('name must be between 1 and 255 characters');
+  }
+  if (name.includes('/') || name.includes('\\') || name.includes('\0') || path.isAbsolute(name)) {
+    throw invalid('name must be one path segment');
+  }
+  return name;
+}
+
+function optionalTimestamp(value, field) {
+  if (value == null) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) throw invalid(`${field} must be an ISO timestamp`);
+  return date.toISOString();
+}
+
+function normalizeTreeOperation(input) {
+  if (!input || typeof input !== 'object') throw invalid('tree operation is required');
+  if (!OPERATION_KINDS.includes(input.kind)) throw invalid(`unsupported tree operation ${JSON.stringify(input.kind)}`);
+
+  const operation = {
+    kind: input.kind,
+    workspaceId: nodeId(input.workspaceId, 'workspaceId'),
+    nodeId: nodeId(input.nodeId, 'nodeId'),
+    changedAt: optionalTimestamp(input.changedAt, 'changedAt') || new Date().toISOString(),
+  };
+
+  if (input.kind === 'tree.create') {
+    if (!KINDS.includes(input.nodeKind)) throw invalid('nodeKind must be folder, file, or symlink');
+    operation.nodeKind = input.nodeKind;
+    operation.parentId = nodeId(input.parentId, 'parentId');
+    operation.name = nodeName(input.name);
+    operation.createdAt = optionalTimestamp(input.createdAt, 'createdAt') || new Date().toISOString();
+    if (input.nodeKind === 'symlink') {
+      if (typeof input.symlinkTarget !== 'string' || !input.symlinkTarget) {
+        throw invalid('symlinkTarget is required for a symlink');
+      }
+      operation.symlinkTarget = input.symlinkTarget;
+    }
+  } else if (input.kind === 'tree.rename') {
+    operation.name = nodeName(input.name);
+  } else if (input.kind === 'tree.move') {
+    operation.parentId = nodeId(input.parentId, 'parentId');
+    if (input.previousParentId != null) operation.previousParentId = nodeId(input.previousParentId, 'previousParentId');
+    if (input.name != null) operation.name = nodeName(input.name);
+  } else if (input.kind === 'tree.trash') {
+    operation.trashedAt = optionalTimestamp(input.trashedAt, 'trashedAt') || new Date().toISOString();
+  } else if (input.kind === 'tree.restore') {
+    if (input.parentId != null) operation.parentId = nodeId(input.parentId, 'parentId');
+    if (input.name != null) operation.name = nodeName(input.name);
+  } else if (input.kind === 'tree.purge') {
+    operation.purgedAt = optionalTimestamp(input.purgedAt, 'purgedAt') || new Date().toISOString();
+  }
+
+  return operation;
+}
+
+module.exports = {
+  CONTRACT,
+  KINDS,
+  OPERATION_KINDS,
+  normalizeNodeName: nodeName,
+  normalizeTreeOperation,
+};

package/runtime/scripts/amalgm-mcp/workspace/tree/reducer.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const { normalizeTreeOperation } = require('./operations');
+
+function toMap(nodes) {
+  if (nodes instanceof Map) return new Map(nodes);
+  return new Map((nodes || []).map((node) => [node.id, { ...node }]));
+}
+
+function descendantsInclude(nodes, ancestorId, candidateId) {
+  const seen = new Set();
+  let current = candidateId;
+  while (current) {
+    if (current === ancestorId) return true;
+    if (seen.has(current)) return true;
+    seen.add(current);
+    current = nodes.get(current)?.parentId || null;
+  }
+  return false;
+}
+
+function ensureAvailableName(nodes, workspaceId, parentId, name, exceptId = null) {
+  const duplicate = Array.from(nodes.values()).find((node) => (
+    node.workspaceId === workspaceId
+    && node.parentId === parentId
+    && node.name === name
+    && node.id !== exceptId
+    && !node.purgedAt
+    && !node.trashedAt
+  ));
+  if (duplicate) throw Object.assign(new Error(`a node named ${JSON.stringify(name)} already exists there`), { statusCode: 409 });
+}
+
+function applyTreeOperation(inputNodes, inputOperation) {
+  const nodes = toMap(inputNodes);
+  const operation = normalizeTreeOperation(inputOperation);
+  const existing = nodes.get(operation.nodeId);
+
+  if (operation.kind === 'tree.create') {
+    if (existing) throw Object.assign(new Error(`node ${operation.nodeId} already exists`), { statusCode: 409 });
+    const parent = nodes.get(operation.parentId);
+    if (!parent || parent.workspaceId !== operation.workspaceId || parent.kind !== 'folder' || parent.purgedAt || parent.trashedAt) {
+      throw Object.assign(new Error('parent folder does not exist'), { statusCode: 409 });
+    }
+    ensureAvailableName(nodes, operation.workspaceId, operation.parentId, operation.name);
+    nodes.set(operation.nodeId, {
+      id: operation.nodeId,
+      workspaceId: operation.workspaceId,
+      parentId: operation.parentId,
+      kind: operation.nodeKind,
+      name: operation.name,
+      symlinkTarget: operation.symlinkTarget || null,
+      trashedAt: null,
+      purgedAt: null,
+      createdAt: operation.createdAt,
+      updatedAt: operation.createdAt,
+    });
+    return nodes;
+  }
+
+  if (!existing || existing.workspaceId !== operation.workspaceId) {
+    throw Object.assign(new Error(`node ${operation.nodeId} does not exist`), { statusCode: 404 });
+  }
+  if (existing.id === existing.workspaceId) {
+    throw Object.assign(new Error('the workspace root cannot be moved, renamed, trashed, restored, or purged'), { statusCode: 409 });
+  }
+  if (existing.purgedAt) {
+    throw Object.assign(new Error('a permanently removed node cannot be changed'), { statusCode: 409 });
+  }
+  if (existing.trashedAt && operation.kind !== 'tree.restore' && operation.kind !== 'tree.purge') {
+    throw Object.assign(new Error('a trashed node must be restored before it can be changed'), { statusCode: 409 });
+  }
+
+  const next = { ...existing, updatedAt: operation.changedAt };
+  if (operation.kind === 'tree.rename') {
+    ensureAvailableName(nodes, operation.workspaceId, existing.parentId, operation.name, existing.id);
+    next.name = operation.name;
+  } else if (operation.kind === 'tree.move') {
+    const parent = nodes.get(operation.parentId);
+    if (!parent || parent.workspaceId !== operation.workspaceId || parent.kind !== 'folder' || parent.purgedAt || parent.trashedAt) {
+      throw Object.assign(new Error('destination folder does not exist'), { statusCode: 409 });
+    }
+    if (descendantsInclude(nodes, existing.id, operation.parentId)) {
+      throw Object.assign(new Error('a folder cannot move inside itself'), { statusCode: 409 });
+    }
+    const name = operation.name || existing.name;
+    ensureAvailableName(nodes, operation.workspaceId, operation.parentId, name, existing.id);
+    next.parentId = operation.parentId;
+    next.name = name;
+  } else if (operation.kind === 'tree.trash') {
+    if (existing.trashedAt) {
+      throw Object.assign(new Error('a node is already trashed'), { statusCode: 409 });
+    }
+    next.trashedAt = operation.trashedAt;
+  } else if (operation.kind === 'tree.restore') {
+    if (!existing.trashedAt) {
+      throw Object.assign(new Error('a node must be trashed before it can be restored'), { statusCode: 409 });
+    }
+    const parentId = operation.parentId || existing.parentId;
+    const name = operation.name || existing.name;
+    const parent = nodes.get(parentId);
+    if (!parent || parent.workspaceId !== operation.workspaceId || parent.kind !== 'folder' || parent.purgedAt || parent.trashedAt) {
+      throw Object.assign(new Error('restore destination does not exist'), { statusCode: 409 });
+    }
+    if (descendantsInclude(nodes, existing.id, parentId)) {
+      throw Object.assign(new Error('a folder cannot restore inside itself'), { statusCode: 409 });
+    }
+    ensureAvailableName(nodes, operation.workspaceId, parentId, name, existing.id);
+    next.parentId = parentId;
+    next.name = name;
+    next.trashedAt = null;
+  } else if (operation.kind === 'tree.purge') {
+    if (!existing.trashedAt) {
+      throw Object.assign(new Error('a node must be trashed before permanent removal'), { statusCode: 409 });
+    }
+    next.purgedAt = operation.purgedAt;
+  }
+
+  nodes.set(next.id, next);
+  if (operation.kind === 'tree.trash' || operation.kind === 'tree.restore' || operation.kind === 'tree.purge') {
+    for (const child of nodes.values()) {
+      if (child.id === next.id || !descendantsInclude(nodes, next.id, child.id)) continue;
+      if (operation.kind === 'tree.trash' && !child.trashedAt) {
+        nodes.set(child.id, { ...child, trashedAt: operation.trashedAt, updatedAt: operation.changedAt });
+      } else if (operation.kind === 'tree.restore' && child.trashedAt === existing.trashedAt) {
+        nodes.set(child.id, { ...child, trashedAt: null, updatedAt: operation.changedAt });
+      } else if (operation.kind === 'tree.purge') {
+        nodes.set(child.id, { ...child, purgedAt: operation.purgedAt, updatedAt: operation.changedAt });
+      }
+    }
+  }
+  return nodes;
+}
+
+module.exports = {
+  applyTreeOperation,
+  descendantsInclude,
+};

package/runtime/scripts/amalgm-mcp/workspace/tree/snapshot.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const { isUuid } = require('./identity');
+const { KINDS, normalizeNodeName } = require('./operations');
+
+function invalid(message) {
+  throw Object.assign(new Error(message), { statusCode: 400 });
+}
+
+function timestamp(value, fallback) {
+  const date = new Date(value || fallback);
+  if (Number.isNaN(date.getTime())) invalid('workspace tree contains an invalid timestamp');
+  return date.toISOString();
+}
+
+function normalizeTreeSnapshot(input) {
+  if (
+    !input
+    || input.schemaVersion !== 1
+    || !Number.isSafeInteger(input.version)
+    || input.version < 0
+    || !isUuid(input.workspaceId)
+    || !Array.isArray(input.nodes)
+    || input.nodes.length > 200_000
+  ) invalid('workspace-tree@1 snapshot has an invalid shape');
+
+  const workspaceId = input.workspaceId.toLowerCase();
+  const nodes = new Map();
+  for (const value of input.nodes) {
+    if (!isUuid(value?.id) || !isUuid(value?.workspaceId)) invalid('workspace tree node identity is invalid');
+    const id = value.id.toLowerCase();
+    const nodeWorkspaceId = value.workspaceId.toLowerCase();
+    if (nodeWorkspaceId !== workspaceId || nodes.has(id) || !KINDS.includes(value.kind)) {
+      invalid('workspace tree node identity or kind is invalid');
+    }
+    const parentId = value.parentId == null ? null : String(value.parentId).toLowerCase();
+    if (parentId && !isUuid(parentId)) invalid('workspace tree parent identity is invalid');
+    const createdAt = timestamp(value.createdAt, new Date().toISOString());
+    const updatedAt = timestamp(value.updatedAt, createdAt);
+    if (value.kind === 'symlink' && (typeof value.symlinkTarget !== 'string' || !value.symlinkTarget)) {
+      invalid('workspace tree symlink target is invalid');
+    }
+    nodes.set(id, {
+      id,
+      workspaceId,
+      parentId,
+      kind: value.kind,
+      name: normalizeNodeName(value.name),
+      symlinkTarget: value.kind === 'symlink' ? value.symlinkTarget : null,
+      trashedAt: value.trashedAt ? timestamp(value.trashedAt) : null,
+      purgedAt: value.purgedAt ? timestamp(value.purgedAt) : null,
+      createdAt,
+      updatedAt,
+    });
+  }
+
+  const root = nodes.get(workspaceId);
+  if (!root || root.parentId !== null || root.kind !== 'folder') {
+    invalid('workspace tree requires one folder root whose id is the workspace id');
+  }
+  const siblingNames = new Set();
+  for (const node of nodes.values()) {
+    if (node.id === workspaceId) continue;
+    if (!node.parentId || !nodes.has(node.parentId)) invalid('workspace tree node parent is missing');
+    const seen = new Set([node.id]);
+    let current = node;
+    while (current.parentId) {
+      if (seen.has(current.parentId)) invalid('workspace tree contains a cycle');
+      seen.add(current.parentId);
+      current = nodes.get(current.parentId);
+      if (!current) invalid('workspace tree node parent is missing');
+    }
+    if (!node.trashedAt && !node.purgedAt) {
+      const key = `${node.parentId}\0${node.name}`;
+      if (siblingNames.has(key)) invalid('workspace tree contains duplicate live sibling names');
+      siblingNames.add(key);
+    }
+  }
+  return { schemaVersion: 1, workspaceId, version: input.version, nodes };
+}
+
+module.exports = { normalizeTreeSnapshot };