@miruzero/zero-agent 0.3.4 → 0.3.6

package/src/command/filesystem/delete-directory.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const fs = require('node:fs');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.deleteDirectory',
+  aliases: ['zero.command.deleteDirectory'],
+  description: 'Delete a directory inside allowed roots.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: { type: 'object', properties: { path: { type: 'string' }, recursive: { type: 'boolean', default: false } }, required: ['path'], additionalProperties: false }
+});
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const deleteDirectory = (args = {}, context = {}) => {
+  const dir = pathPolicy.resolveAllowed(args.path, context);
+  if (!fs.statSync(dir).isDirectory()) throw fail('NOT_A_DIRECTORY', 'path is not a directory');
+  fs.rmSync(dir, { recursive: args.recursive === true, force: false });
+  return { ok: true, path: dir, deleted: true };
+};
+
+const deleteDirectoryModule = { descriptor, deleteDirectory };
+Object.assign(exports, deleteDirectoryModule);

package/src/command/filesystem/delete-file.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const fs = require('node:fs');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.deleteFile',
+  aliases: ['zero.command.deleteFile'],
+  description: 'Delete one file inside allowed roots. Directories are rejected.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path'],
+    additionalProperties: false
+  }
+});
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const deleteFile = (args = {}, context = {}) => {
+  const file = pathPolicy.resolveAllowed(args.path, context);
+  if (!fs.existsSync(file)) throw fail('FILE_NOT_FOUND', 'file does not exist');
+  if (!fs.statSync(file).isFile()) throw fail('NOT_A_FILE', 'deleteFile supports files only');
+  fs.unlinkSync(file);
+  return { ok: true, path: file, deleted: true };
+};
+
+const deleteFileModule = { descriptor, deleteFile };
+Object.assign(exports, deleteFileModule);

package/src/command/filesystem/exists.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const fs = require('node:fs');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.exists',
+  aliases: ['zero.command.exists'],
+  description: 'Check whether a path exists inside allowed roots.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path'],
+    additionalProperties: false
+  }
+});
+
+const exists = (args = {}, context = {}) => {
+  const pathValue = pathPolicy.resolveAllowed(args.path, context);
+  return { ok: true, path: pathValue, exists: fs.existsSync(pathValue) };
+};
+
+const existsModule = { descriptor, exists };
+Object.assign(exports, existsModule);

package/src/command/filesystem/get-file-info.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('node:fs');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+const text = require('./text');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.getFileInfo',
+  aliases: ['zero.command.getFileInfo'],
+  description: 'Get metadata for a file or directory inside allowed roots.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path'],
+    additionalProperties: false
+  }
+});
+
+const getFileInfo = (args = {}, context = {}) => {
+  const target = pathPolicy.resolveAllowed(args.path, context);
+  const stat = fs.statSync(target);
+  return {
+    ok: true,
+    path: target,
+    type: stat.isDirectory() ? 'directory' : 'file',
+    size: stat.size,
+    createdAt: stat.birthtime.toISOString(),
+    modifiedAt: stat.mtime.toISOString(),
+    lineCount: stat.isFile() ? text.readUtf8(target).split(/\r?\n/).length : null
+  };
+};
+
+const getFileInfoModule = { descriptor, getFileInfo };
+Object.assign(exports, getFileInfoModule);

package/src/command/filesystem/glob-files.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const path = require('node:path');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+const walk = require('./walk');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.globFiles',
+  aliases: ['zero.command.globFiles'],
+  description: 'Find files by wildcard pattern inside allowed roots.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      pattern: { type: 'string' },
+      maxResults: { type: 'integer', minimum: 1, maximum: 1000, default: 200 }
+    },
+    required: ['path', 'pattern'],
+    additionalProperties: false
+  }
+});
+
+const globFiles = (args = {}, context = {}) => {
+  const root = pathPolicy.resolveAllowed(args.path, context);
+  const rx = walk.wildcard(args.pattern || '*');
+  const max = Math.max(1, Math.min(args.maxResults || 200, 1000));
+  const files = walk.walk(root, { filesOnly: true })
+    .filter((item) => rx.test(path.basename(item.path)) || rx.test(item.relativePath))
+    .slice(0, max);
+  return { ok: true, path: root, pattern: args.pattern, files };
+};
+
+const globFilesModule = { descriptor, globFiles };
+Object.assign(exports, globFilesModule);

package/src/command/filesystem/grep-files.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const path = require('node:path');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+const textModule = require('./text');
+const walk = require('./walk');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.grepFiles',
+  aliases: ['zero.command.grepFiles'],
+  description: 'Search text content in files inside allowed roots.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      pattern: { type: 'string' },
+      literal: { type: 'boolean', default: false },
+      filePattern: { type: 'string' },
+      maxResults: { type: 'integer', minimum: 1, maximum: 1000, default: 200 }
+    },
+    required: ['path', 'pattern'],
+    additionalProperties: false
+  }
+});
+
+const grepFiles = (args = {}, context = {}) => {
+  const root = pathPolicy.resolveAllowed(args.path, context);
+  const max = Math.max(1, Math.min(args.maxResults || 200, 1000));
+  const rx = args.literal ? null : new RegExp(String(args.pattern), 'i');
+  const fileRx = args.filePattern ? walk.wildcard(args.filePattern) : null;
+  const matches = [];
+  for (const file of walk.walk(root, { filesOnly: true })) {
+    if (fileRx && !fileRx.test(path.basename(file.path)) && !fileRx.test(file.relativePath)) continue;
+    let text;
+    try { text = textModule.readUtf8(file.path); } catch { continue; }
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      const hit = args.literal ? line.includes(String(args.pattern)) : rx.test(line);
+      if (!hit) continue;
+      matches.push({ path: file.path, relativePath: file.relativePath, line: index + 1, text: line });
+      if (matches.length >= max) return { ok: true, path: root, pattern: args.pattern, matches };
+    }
+  }
+  return { ok: true, path: root, pattern: args.pattern, matches };
+};
+
+const grepFilesModule = { descriptor, grepFiles };
+Object.assign(exports, grepFilesModule);

package/src/command/filesystem/hash-file.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.hashFile',
+  aliases: ['zero.command.hashFile'],
+  description: 'Calculate SHA-256 hash of a file inside allowed roots.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: { path: { type: 'string' } },
+    required: ['path'],
+    additionalProperties: false
+  }
+});
+
+const hashFile = (args = {}, context = {}) => {
+  const file = pathPolicy.resolveAllowed(args.path, context);
+  return {
+    ok: true,
+    path: file,
+    algorithm: 'sha256',
+    hash: crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+  };
+};
+
+const hashFileModule = { descriptor, hashFile };
+Object.assign(exports, hashFileModule);

package/src/command/filesystem/index.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const modules = {
+  readFile: require('./read-file'),
+  readFiles: require('./read-files'),
+  listDirectory: require('./list-directory'),
+  getFileInfo: require('./get-file-info'),
+  globFiles: require('./glob-files'),
+  grepFiles: require('./grep-files'),
+  writeFile: require('./write-file'),
+  appendFile: require('./append-file'),
+  createFile: require('./create-file'),
+  touchFile: require('./touch-file'),
+  replaceFile: require('./replace-file'),
+  createDirectory: require('./create-directory'),
+  deleteFile: require('./delete-file'),
+  copyDirectory: require('./copy-directory'),
+  moveDirectory: require('./move-directory'),
+  deleteDirectory: require('./delete-directory'),
+  truncateFile: require('./truncate-file'),
+  copyFile: require('./copy-file'),
+  moveFile: require('./move-file'),
+  renameFile: require('./rename-file'),
+  exists: require('./exists'),
+  hashFile: require('./hash-file')
+};
+
+const filesystem = {};
+for (const [name, item] of Object.entries(modules)) {
+  filesystem[name] = item[name];
+  filesystem[`${name}Descriptor`] = item.descriptor;
+}
+
+Object.assign(exports, filesystem);

package/src/command/filesystem/list-directory.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+const walk = require('./walk');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.listDirectory',
+  aliases: ['zero.command.listDirectory'],
+  description: 'List files and directories recursively inside allowed roots.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      depth: { type: 'integer', minimum: 1, maximum: 5, default: 2 }
+    },
+    required: ['path'],
+    additionalProperties: false
+  }
+});
+
+const listDirectory = (args = {}, context = {}) => {
+  const root = pathPolicy.resolveAllowed(args.path, context);
+  const depth = Math.max(1, Math.min(args.depth || 2, 5));
+  return { ok: true, path: root, depth, entries: walk.walk(root, { depth }) };
+};
+
+const listDirectoryModule = { descriptor, listDirectory };
+Object.assign(exports, listDirectoryModule);

package/src/command/filesystem/move-directory.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.moveDirectory',
+  aliases: ['zero.command.moveDirectory'],
+  description: 'Move a directory inside allowed roots.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: { type: 'object', properties: { source: { type: 'string' }, destination: { type: 'string' } }, required: ['source', 'destination'], additionalProperties: false }
+});
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const moveDirectory = (args = {}, context = {}) => {
+  const source = pathPolicy.resolveAllowed(args.source, context);
+  const destination = pathPolicy.resolveAllowed(args.destination, context);
+  if (!fs.statSync(source).isDirectory()) throw fail('NOT_A_DIRECTORY', 'source is not a directory');
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.renameSync(source, destination);
+  return { ok: true, source, destination };
+};
+
+const moveDirectoryModule = { descriptor, moveDirectory };
+Object.assign(exports, moveDirectoryModule);

package/src/command/filesystem/move-file.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.moveFile',
+  aliases: ['zero.command.moveFile'],
+  description: 'Move one file or directory inside allowed roots.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: { source: { type: 'string' }, destination: { type: 'string' } },
+    required: ['source', 'destination'],
+    additionalProperties: false
+  }
+});
+
+const moveFile = (args = {}, context = {}) => {
+  const source = pathPolicy.resolveAllowed(args.source, context);
+  const destination = pathPolicy.resolveAllowed(args.destination, context);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.renameSync(source, destination);
+  return { ok: true, source, destination };
+};
+
+const moveFileModule = { descriptor, moveFile };
+Object.assign(exports, moveFileModule);

package/src/command/filesystem/path-policy.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+
+const err = (code, message) => Object.assign(new Error(message), { code });
+const normalize = (value) => path.resolve(String(value)).toLowerCase();
+const rootsFor = (context = {}, env = context.env || process.env) => {
+  const explicit = Array.isArray(context.commandRoots) && context.commandRoots.length
+    ? context.commandRoots
+    : (Array.isArray(context.roots) ? context.roots : []);
+  const configured = explicit.length ? explicit : String(env.ZERO_AGENT_ROOTS || env.ZERO_COMMAND_ROOTS || '')
+    .split(';').map((item) => item.trim()).filter(Boolean);
+  const roots = configured.length ? configured : [os.homedir(), process.cwd()];
+  return roots.map((item) => path.resolve(String(item)));
+};
+const resolveAllowed = (inputPath, context = {}, env = context.env || process.env) => {
+  if (!inputPath || typeof inputPath !== 'string') throw err('INVALID_PATH', 'path is required');
+  const roots = rootsFor(context, env);
+  const target = path.resolve(inputPath);
+  const targetNorm = normalize(target);
+  const ok = roots.some((root) => {
+    const rootNorm = normalize(root);
+    return targetNorm === rootNorm || targetNorm.startsWith(rootNorm + path.sep.toLowerCase());
+  });
+  if (!ok) throw err('PATH_NOT_ALLOWED', 'path is outside agent allowed roots');
+  return target;
+};
+
+const pathPolicy = { rootsFor, resolveAllowed };
+Object.assign(exports, pathPolicy);

package/src/command/filesystem/read-file.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+const text = require('./text');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.readFile',
+  aliases: ['zero.command.readFile'],
+  description: 'Read a UTF-8 text file inside allowed roots with line pagination.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      offset: { type: 'integer', default: 0 },
+      length: { type: 'integer', minimum: 1, maximum: 1000, default: 200 }
+    },
+    required: ['path'],
+    additionalProperties: false
+  }
+});
+const readFile = (args = {}, context = {}) => {
+  const file = pathPolicy.resolveAllowed(args.path, context);
+  const lines = text.readUtf8(file).split(/\r?\n/);
+  const offset = Number.isInteger(args.offset) ? args.offset : 0;
+  const length = Number.isInteger(args.length) ? args.length : 200;
+  const start = offset < 0 ? Math.max(lines.length + offset, 0) : Math.max(offset, 0);
+  const slice = lines.slice(start, start + length);
+  return { ok: true, path: file, totalLines: lines.length, offset: start, length: slice.length, content: text.numbered(slice, start) };
+};
+
+const readFileModule = { descriptor, readFile };
+Object.assign(exports, readFileModule);

package/src/command/filesystem/read-files.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const zero = require('../../zero-runtime');
+const readFileModule = require('./read-file');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.readFiles',
+  aliases: ['zero.command.readFiles'],
+  description: 'Read multiple UTF-8 text files inside allowed roots.',
+  capability: 'filesystem.read',
+  risk: 'read',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      paths: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 50 },
+      files: {
+        type: 'array', minItems: 1, maxItems: 50,
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            offset: { type: 'integer' },
+            length: { type: 'integer', minimum: 1, maximum: 1000 }
+          },
+          required: ['path'],
+          additionalProperties: false
+        }
+      },
+      offset: { type: 'integer', default: 0 },
+      length: { type: 'integer', minimum: 1, maximum: 1000, default: 200 }
+    },
+    additionalProperties: false
+  }
+});
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const readFiles = (args = {}, context = {}) => {
+  const requests = Array.isArray(args.files) && args.files.length
+    ? args.files.map((item) => ({ path: item.path, offset: item.offset, length: item.length }))
+    : (Array.isArray(args.paths) ? args.paths : []).map((path) => ({ path, offset: args.offset, length: args.length }));
+  if (!requests.length) throw fail('INVALID_PATHS', 'paths or files must contain at least one file');
+  if (requests.length > 50) throw fail('TOO_MANY_PATHS', 'readFiles supports up to 50 files');
+  const files = requests.map((request) => {
+    try { return readFileModule.readFile(request, context); }
+    catch (error) {
+      return { ok: false, path: String(request.path), error: { code: error.code || 'READ_FAILED', message: error.message || String(error) } };
+    }
+  });
+  const succeeded = files.filter((item) => item.ok).length;
+  return { ok: succeeded === files.length, count: files.length, succeeded, failed: files.length - succeeded, files };
+};
+
+const readFilesModule = { descriptor, readFiles };
+Object.assign(exports, readFilesModule);

package/src/command/filesystem/rename-file.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const zero = require('../../zero-runtime');
+const moveFileModule = require('./move-file');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.renameFile',
+  aliases: ['zero.command.renameFile'],
+  description: 'Rename one file or directory inside allowed roots.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: moveFileModule.descriptor.inputSchema
+});
+
+const renameFile = (args = {}, context = {}) => moveFileModule.moveFile(args, context);
+
+const renameFileModule = { descriptor, renameFile };
+Object.assign(exports, renameFileModule);

package/src/command/filesystem/replace-file.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const fs = require('node:fs');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+const textModule = require('./text');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.replaceFile',
+  aliases: ['zero.command.replaceFile'],
+  description: 'Replace exact text inside a UTF-8 file in allowed roots.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      oldString: { type: 'string' },
+      newString: { type: 'string' },
+      expectedReplacements: { type: 'integer', minimum: 0 }
+    },
+    required: ['path', 'oldString', 'newString'],
+    additionalProperties: false
+  }
+});
+
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const replaceFile = (args = {}, context = {}) => {
+  const file = pathPolicy.resolveAllowed(args.path, context);
+  const oldString = String(args.oldString ?? '');
+  if (!oldString) throw fail('INVALID_REPLACE', 'oldString must not be empty');
+  const newString = String(args.newString ?? '');
+  const text = textModule.readUtf8(file);
+  const replacements = text.split(oldString).length - 1;
+  if (Number.isInteger(args.expectedReplacements) && replacements !== args.expectedReplacements) {
+    throw fail('REPLACE_COUNT_MISMATCH', `expected ${args.expectedReplacements} replacements, got ${replacements}`);
+  }
+  fs.writeFileSync(file, text.split(oldString).join(newString), 'utf8');
+  return { ok: true, path: file, replacements };
+};
+
+const replaceFileModule = { descriptor, replaceFile };
+Object.assign(exports, replaceFileModule);

package/src/command/filesystem/text.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const textDecoder = new TextDecoder('utf-8', { fatal: false });
+const err = (code, message) => Object.assign(new Error(message), { code });
+const readUtf8 = (file) => {
+  const data = fs.readFileSync(file);
+  if (data.includes(0)) throw err('BINARY_FILE', 'binary file is not supported');
+  return textDecoder.decode(data);
+};
+const numbered = (lines, startIndex) => lines
+  .map((line, index) => String(startIndex + index + 1).padStart(4, ' ') + '\t' + line)
+  .join('\n');
+
+const text = { readUtf8, numbered };
+Object.assign(exports, text);

package/src/command/filesystem/touch-file.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.touchFile',
+  aliases: ['zero.command.touchFile'],
+  description: 'Create or update a file timestamp inside allowed roots.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false }
+});
+
+const touchFile = (args = {}, context = {}) => {
+  const file = pathPolicy.resolveAllowed(args.path, context);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (!fs.existsSync(file)) fs.closeSync(fs.openSync(file, 'w'));
+  const now = new Date();
+  fs.utimesSync(file, now, now);
+  return { ok: true, path: file, touched: true };
+};
+
+const touchFileModule = { descriptor, touchFile };
+Object.assign(exports, touchFileModule);

package/src/command/filesystem/truncate-file.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const fs = require('node:fs');
+const zero = require('../../zero-runtime');
+const pathPolicy = require('./path-policy');
+
+const descriptor = zero.descriptor.validate({
+  name: 'zero.command.filesystem.truncateFile',
+  aliases: ['zero.command.truncateFile'],
+  description: 'Truncate a file to a specific byte size inside allowed roots.',
+  capability: 'filesystem.write',
+  risk: 'write',
+  execution: 'target',
+  adapters: ['native'],
+  inputSchema: { type: 'object', properties: { path: { type: 'string' }, size: { type: 'integer', minimum: 0, default: 0 } }, required: ['path'], additionalProperties: false }
+});
+
+const truncateFile = (args = {}, context = {}) => {
+  const file = pathPolicy.resolveAllowed(args.path, context);
+  const size = Number.isInteger(args.size) && args.size >= 0 ? args.size : 0;
+  fs.truncateSync(file, size);
+  return { ok: true, path: file, size };
+};
+
+const truncateFileModule = { descriptor, truncateFile };
+Object.assign(exports, truncateFileModule);