@xandreed/plugin-workspace 0.0.0-stage → 0.14.0

package/dist/workspace-tools.entity.js

@@ -0,0 +1,133 @@
+import { Result, Schema } from "effect";
+import { AttachmentRejectedReason, BASH_ENV_ALLOWLIST, BashTermination, compileGlob, ImageMediaType, Media } from "@xandreed/core";
+export const WorkspaceToolName = Schema.Literals(["read", "write", "edit", "ls", "find", "grep", "bash"]), WorkspaceSkillName = Schema.Literals(["read", "edit", "shell"]), WORKSPACE_PERMISSIONS = { write: "fs.write", exec: "shell.exec" };
+const atLeast = (minimum) => Schema.Int.check(Schema.isGreaterThanOrEqualTo(minimum)), between = (minimum, maximum) => Schema.Int.check(Schema.isBetween({ minimum, maximum })), InsideWorkspace = Schema.String.check(Schema.makeFilter((path) => path.length > 0 && !path.startsWith("/") && !path.split("/").includes("..") ? !0 : "a path relative to the workspace root, without a .. segment")), Glob = Schema.String.check(Schema.makeFilter((glob) => Result.match(compileGlob(glob, { dot: !0 }), { onSuccess: () => !0, onFailure: (reason) => `not a usable glob: ${reason}` })));
+export const WorkspaceToolsConfig = Schema.Struct({
+  tools: Schema.Array(WorkspaceToolName),
+  always: Schema.Array(WorkspaceSkillName),
+  confine: Schema.Boolean,
+  protect: Schema.Array(Glob),
+  exclude: Schema.Array(Glob),
+  maxLines: between(1, 1e5),
+  maxBytes: between(1024, 10485760),
+  lsEntries: between(1, 1e5),
+  findResults: between(1, 1e5),
+  grepMatches: between(1, 1e4),
+  grepLineChars: between(16, 1e5),
+  maxFileBytes: between(1024, 1073741824),
+  readImages: Schema.Boolean,
+  fuzzyEdit: Schema.Boolean,
+  bashTimeoutMs: atLeast(1),
+  bashMaxTimeoutMs: atLeast(1),
+  bashEnv: Schema.Record(Schema.String, Schema.String),
+  bashInheritEnv: Schema.Boolean,
+  bashEnvAllow: Schema.Array(Schema.String),
+  bashSessionEnv: Schema.Boolean,
+  spillDir: Schema.NullOr(InsideWorkspace),
+  spillKeep: between(1, 1e4),
+  progressMs: between(1, 60000),
+  environmentSection: Schema.Boolean,
+  sectionOrder: Schema.Int
+}).check(Schema.makeFilter((config) => config.bashTimeoutMs <= config.bashMaxTimeoutMs ? !0 : "bashTimeoutMs must not exceed bashMaxTimeoutMs")), workspaceToolsDefaults = {
+  tools: ["read", "write", "edit", "ls", "find", "grep", "bash"],
+  always: ["read"],
+  confine: !0,
+  protect: [".git/**", ".efferent/**"],
+  exclude: ["node_modules", ".git", ".efferent"],
+  maxLines: 2000,
+  maxBytes: 51200,
+  lsEntries: 500,
+  findResults: 1000,
+  grepMatches: 100,
+  grepLineChars: 500,
+  maxFileBytes: 33554432,
+  readImages: !0,
+  fuzzyEdit: !0,
+  bashTimeoutMs: 120000,
+  bashMaxTimeoutMs: 600000,
+  bashEnv: {},
+  bashInheritEnv: !1,
+  bashEnvAllow: BASH_ENV_ALLOWLIST,
+  bashSessionEnv: !1,
+  spillDir: ".efferent/runtime/tool-output",
+  spillKeep: 50,
+  progressMs: 250,
+  environmentSection: !0,
+  sectionOrder: 800
+}, ReadParams = Schema.Struct({
+  path: Schema.String,
+  offset: Schema.optionalKey(atLeast(1)),
+  limit: Schema.optionalKey(atLeast(1))
+}), ReadResult = Schema.Union([
+  Schema.TaggedStruct("Text", {
+    path: Schema.String,
+    text: Schema.String,
+    firstLine: Schema.Int,
+    lastLine: Schema.Int,
+    totalLines: Schema.Int,
+    next: Schema.NullOr(Schema.Int),
+    clipped: Schema.Boolean,
+    lossy: Schema.Boolean
+  }),
+  Schema.TaggedStruct("Binary", {
+    path: Schema.String,
+    bytes: Schema.Int,
+    mediaType: Schema.NullOr(Schema.String)
+  }),
+  Schema.TaggedStruct("Image", {
+    path: Schema.String,
+    image: Media
+  }),
+  Schema.TaggedStruct("ImageRejected", {
+    path: Schema.String,
+    mediaType: ImageMediaType,
+    bytes: Schema.Int,
+    reason: AttachmentRejectedReason,
+    message: Schema.String
+  })
+]), WriteParams = Schema.Struct({ path: Schema.String, content: Schema.String }), WriteResult = Schema.Struct({ path: Schema.String, bytes: Schema.Int, created: Schema.Boolean }), TextEdit = Schema.Struct({ oldText: Schema.String, newText: Schema.String }), EditParams = Schema.Struct({ path: Schema.String, edits: Schema.NonEmptyArray(TextEdit) }), EditResult = Schema.Struct({
+  path: Schema.String,
+  replaced: Schema.Int,
+  normalized: Schema.Boolean,
+  firstChangedLine: Schema.Int,
+  diff: Schema.String
+}), LsParams = Schema.Struct({ path: Schema.optionalKey(Schema.String), limit: Schema.optionalKey(atLeast(1)) }), LsEntry = Schema.Struct({ name: Schema.String, kind: Schema.Literals(["file", "directory", "symlink", "other"]) }), LsResult = Schema.Struct({ path: Schema.String, entries: Schema.Array(LsEntry), total: Schema.Int }), FindParams = Schema.Struct({ pattern: Schema.String, path: Schema.optionalKey(Schema.String), limit: Schema.optionalKey(atLeast(1)) }), FindResult = Schema.Struct({ pattern: Schema.String, path: Schema.String, paths: Schema.Array(Schema.String), truncated: Schema.Boolean }), GrepParams = Schema.Struct({
+  pattern: Schema.String,
+  path: Schema.optionalKey(Schema.String),
+  glob: Schema.optionalKey(Schema.String),
+  ignoreCase: Schema.optionalKey(Schema.Boolean),
+  literal: Schema.optionalKey(Schema.Boolean),
+  context: Schema.optionalKey(between(0, 10)),
+  limit: Schema.optionalKey(atLeast(1))
+}), GrepLine = Schema.Struct({ path: Schema.String, line: Schema.Int, text: Schema.String, match: Schema.Boolean }), GrepResult = Schema.Struct({
+  pattern: Schema.String,
+  path: Schema.String,
+  lines: Schema.Array(GrepLine),
+  matches: Schema.Int,
+  files: Schema.Int,
+  truncated: Schema.Boolean,
+  skipped: Schema.Int
+}), BashParams = Schema.Struct({
+  command: Schema.String,
+  timeout: Schema.optionalKey(atLeast(1)),
+  stdin: Schema.optionalKey(Schema.String)
+}), BashToolResult = Schema.Struct({
+  command: Schema.String,
+  output: Schema.String,
+  exitCode: Schema.NullOr(Schema.Int),
+  signal: Schema.NullOr(Schema.String),
+  termination: BashTermination,
+  truncated: Schema.Boolean,
+  totalLines: Schema.Int,
+  fullOutput: Schema.NullOr(Schema.String),
+  fullOutputCut: Schema.Boolean,
+  durationMs: Schema.Number
+}), workspaceToolSchemas = {
+  read: { name: "read", parametersSchema: ReadParams, successSchema: ReadResult },
+  write: { name: "write", parametersSchema: WriteParams, successSchema: WriteResult },
+  edit: { name: "edit", parametersSchema: EditParams, successSchema: EditResult },
+  ls: { name: "ls", parametersSchema: LsParams, successSchema: LsResult },
+  find: { name: "find", parametersSchema: FindParams, successSchema: FindResult },
+  grep: { name: "grep", parametersSchema: GrepParams, successSchema: GrepResult },
+  bash: { name: "bash", parametersSchema: BashParams, successSchema: BashToolResult }
+};

package/dist/workspace-tools.journey.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/write-tools.adapter.d.ts

@@ -0,0 +1,12 @@
+import type { RegisteredTool } from "@xandreed/core";
+import type { WorkspaceToolContext } from "./read-tools.adapter.js";
+/** `write`: create a file, or replace all of one, through a temporary file and a rename (see `save`). */
+export declare const writeTool: (context: WorkspaceToolContext) => RegisteredTool;
+/**
+ * `edit`: exact replacements in a UTF-8 text file, all matched against the
+ * file as it was, with the BOM and line endings kept. A file that is not
+ * valid UTF-8 is refused (`NotUtf8`): writing its decoded text back would
+ * turn every byte that is not into U+FFFD, lines the edits never touched
+ * included.
+ */
+export declare const editTool: (context: WorkspaceToolContext) => RegisteredTool;

package/dist/write-tools.adapter.js

@@ -0,0 +1,77 @@
+import { Tool } from "effect/ai";
+import { Effect, Option, Random, RcMap } from "effect";
+import { defineTool, Failure } from "@xandreed/core";
+import { applyTextEdits, unifiedDiff } from "./text-edit.entity.functions.js";
+import { decodeText, encodeText, formatBytes, looksBinary, utf8Length } from "./text-window.entity.functions.js";
+import { checkWritable, fsFailure, openWorkspace, resolveTarget } from "./workspace-path.entity.functions.js";
+import { EditParams, EditResult, WORKSPACE_PERMISSIONS, WriteParams, WriteResult } from "./workspace-tools.entity.js";
+import { compactEdit, compactWrite, renderEdit, renderWrite, toolDescriptions } from "./workspace-tools.entity.functions.js";
+import { failure, fileSubjects, notAFile } from "./read-tools.adapter.js";
+const WriteTool = (description) => Tool.make("write", { description, parameters: WriteParams, success: WriteResult, failure: Failure, failureMode: "return" }), EditTool = (description) => Tool.make("edit", { description, parameters: EditParams, success: EditResult, failure: Failure, failureMode: "return" }), holding = (context, path) => (change) => Effect.scoped(RcMap.get(context.locks, path).pipe(Effect.flatMap((lock) => lock.withPermits(1)(change)))), existing = (access, target) => access.fs.stat(target.path).pipe(Effect.map(Option.some), Effect.catchIf((error) => error.reason === "NotFound", () => Effect.succeed(Option.none())), Effect.mapError(fsFailure(target.display))), notForNewFiles = 3657, save = (access, target, content, before) => {
+  const mode = Option.flatMap(before, (info) => info.mode), inPlace = access.fs.write(target.path, content), replaced = Effect.gen(function* () {
+    const suffix = (yield* Random.nextIntBetween(0, 2147483647)).toString(36), temporary = access.path.join(access.path.dirname(target.path), `.${access.path.basename(target.path)}.${suffix}.efferent-tmp`), discard = access.fs.remove(temporary).pipe(Effect.ignore);
+    yield* access.fs.write(temporary, content, { createParents: !0 });
+    if (!(yield* Option.match(mode, {
+      onNone: () => Effect.succeed(!0),
+      onSome: (kept) => access.fs.stat(temporary).pipe(Effect.map((fresh) => Option.contains(fresh.mode, kept)), Effect.tapError(() => discard))
+    })))
+      return yield* discard.pipe(Effect.andThen(inPlace));
+    yield* access.fs.rename(temporary, target.path).pipe(Effect.tapError(() => discard));
+  });
+  return (Option.exists(mode, (bits) => (bits & notForNewFiles) !== 0) ? inPlace : replaced).pipe(Effect.mapError(fsFailure(target.display)));
+};
+export const writeTool = (context) => defineTool({
+  tool: WriteTool(toolDescriptions(context.config).write),
+  handler: (params) => Effect.gen(function* () {
+    const access = yield* openWorkspace(context.path), target = yield* resolveTarget(access, params.path, { confine: context.config.confine });
+    yield* checkWritable(access, target, context.protect);
+    return yield* holding(context, target.path)(Effect.gen(function* () {
+      const before = yield* existing(access, target);
+      if (Option.exists(before, (info) => info.kind === "directory"))
+        return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory`));
+      if (Option.exists(before, (info) => info.kind !== "file"))
+        return yield* Effect.fail(notAFile(target.display, "write"));
+      if (params.content.length === 0 && Option.exists(before, (info) => info.size > 0))
+        return yield* Effect.fail(failure("WouldEmpty", `${target.display} has content; write refuses to empty it. Use edit to remove parts of it, or bash to delete it`));
+      yield* save(access, target, params.content, before);
+      return { path: target.display, bytes: utf8Length(params.content), created: Option.isNone(before) };
+    }));
+  }),
+  view: { version: "1", render: renderWrite, compact: compactWrite, subjects: (result) => fileSubjects(result.path) },
+  annotations: { permissions: [WORKSPACE_PERMISSIONS.write] }
+}), editTool = (context) => defineTool({
+  tool: EditTool(toolDescriptions(context.config).edit),
+  handler: (params) => Effect.gen(function* () {
+    const { config } = context, access = yield* openWorkspace(context.path), target = yield* resolveTarget(access, params.path, { confine: config.confine });
+    yield* checkWritable(access, target, context.protect);
+    return yield* holding(context, target.path)(Effect.gen(function* () {
+      const before = yield* existing(access, target), info = yield* Option.match(before, {
+        onNone: () => Effect.fail(failure("NotFound", `${target.display} does not exist; use write to create it`)),
+        onSome: Effect.succeed
+      });
+      if (info.kind === "directory")
+        return yield* Effect.fail(failure("IsDirectory", `${target.display} is a directory`));
+      if (info.kind !== "file")
+        return yield* Effect.fail(notAFile(target.display, "edit"));
+      if (info.size > config.maxFileBytes)
+        return yield* Effect.fail(failure("FileTooLarge", `${target.display} is ${formatBytes(info.size)}, more than the ${formatBytes(config.maxFileBytes)} edit loads`));
+      const bytes = yield* access.fs.readBytes(target.path).pipe(Effect.mapError(fsFailure(target.display)));
+      if (looksBinary(bytes))
+        return yield* Effect.fail(failure("Binary", `${target.display} is a binary file; edit changes text files only`));
+      const decoded = decodeText(bytes);
+      if (decoded.lossy)
+        return yield* Effect.fail(failure("NotUtf8", `${target.display} is not valid UTF-8 (Latin-1 or another encoding, say); edit changes UTF-8 text files only, since it would replace the bytes it cannot decode. Use bash (sed, iconv) to change it`));
+      const plan = yield* Effect.fromResult(applyTextEdits(decoded.text, params.edits, { fuzzy: config.fuzzyEdit }));
+      yield* save(access, target, encodeText({ text: plan.text, bom: decoded.bom }), before);
+      return {
+        path: target.display,
+        replaced: plan.replaced,
+        normalized: plan.normalized,
+        firstChangedLine: plan.firstChangedLine,
+        diff: unifiedDiff(target.display, plan.before, plan.after, config.maxBytes)
+      };
+    }));
+  }),
+  view: { version: "1", render: renderEdit, compact: compactEdit, subjects: (result) => fileSubjects(result.path) },
+  annotations: { permissions: [WORKSPACE_PERMISSIONS.write] }
+});

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@xandreed/plugin-workspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.14.0",
+  "engines": {
+    "node": ">=24",
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "description": "The local machine as the FileSystem and Bash ports (node:fs and node:child_process adapters and the plugin that provides them), the workspace tools an agent works with (read, write, edit, ls, find, grep and bash) and skills from directories of SKILL.md files (Node 24 and Bun, on Linux and macOS).",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@xandreed/core": "0.14.0",
+    "effect": "4.0.7"
+  },
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT"
+}