@dxos/plugin-script 0.8.3 → 0.8.4-main.1c7ec43d41

package/src/blueprints/functions/definitions.ts

@@ -0,0 +1,323 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { ClientService } from '@dxos/client';
+import { Operation } from '@dxos/compute';
+import { Database, Feed, Ref } from '@dxos/echo';
+import { trim } from '@dxos/util';
+
+const FunctionRef = Ref.Ref(Operation.PersistentOperation).annotations({
+  description: 'The ID of the function.',
+});
+
+const FunctionId = Schema.String.annotations({
+  description: 'The ID of the function. Can be passed as the function parameter to other operations.',
+});
+
+const FUNCTION_FORMAT = trim`
+  IMPORTANT: Every function MUST follow this exact pattern — define an Operation, then export default the handler:
+
+  \`\`\`typescript
+  import * as Effect from 'effect/Effect';
+  import * as Schema from 'effect/Schema';
+
+  import { Operation } from '@dxos/compute';
+
+  const MyFunction = Operation.make({
+    meta: {
+      key: 'org.dxos.script.my-function',
+      name: 'My Function',
+    },
+    input: Schema.Struct({
+      city: Schema.String.annotations({ description: 'City name' }),
+    }),
+    output: Schema.Any,
+  });
+
+  export default MyFunction.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ city }) {
+        const res = yield* Effect.promise(() =>
+          fetch(\`https://wttr.in/\${city}?format=j1\`)
+        );
+        const data = yield* Effect.promise(() => res.json());
+        return data;
+      }),
+    ),
+  );
+  \`\`\`
+
+  Key rules:
+  - The file MUST have a single \`export default\` of Operation.pipe(Operation.withHandler(...)).
+  - Use \`Effect.fn(function* (...) { ... })\` for the handler body.
+  - Wrap async calls with \`yield* Effect.promise(() => ...)\`.
+  - Do NOT use top-level await; do NOT export named functions; do NOT use module.exports.
+`;
+
+const AVAILABLE_PACKAGES = trim`
+  Scripts run in an Edge runtime (Cloudflare Workers) with the following pre-bundled packages:
+
+  DXOS SDK:
+  - \`@dxos/echo\` — Reactive local-first database: query, filter, and mutate ECHO objects in spaces.
+  - \`@dxos/functions\` — Edge function framework: triggers, queues, and function definitions.
+  - \`@dxos/ai\` — AI/LLM integration via AiService (access models like Claude, GPT).
+  - \`@dxos/schema\` — Schema utilities and built-in DXOS types.
+  - \`@dxos/types\` — DXOS type definitions.
+  - \`@dxos/operation\` — Define and handle typed operations with input/output schemas.
+  - \`@dxos/util\` — General utility functions.
+  - \`@dxos/log\` — Structured logging.
+
+  Effect-TS (functional programming toolkit):
+  - \`effect\` — Core effect system with sub-modules: Effect, Schema, Stream, Schedule, Array, Record, Option, Either, Match, etc.
+  - \`@effect/platform\` — HTTP client (\`HttpClient\`), platform abstractions for making typed API requests.
+
+  Data format parsing & querying:
+  - \`jsonata\` — Powerful query and transformation expressions for JSON data (filter, sort, group, aggregate, reshape).
+  - \`yaml\` — Parse and stringify YAML documents.
+  - \`fast-xml-parser\` — Fast XML parser and builder; convert between XML and JSON.
+  - \`papaparse\` — CSV parsing and serialization; stream large files, auto-detect delimiters.
+
+  Text & markup processing:
+  - \`turndown\` — HTML to Markdown converter (useful for feeding web content to LLMs).
+
+  HTML/DOM parsing:
+  - \`linkedom\` — Lightweight DOM parser for worker environments; parse and query HTML documents.
+
+  Data processing & utilities:
+  - \`date-fns\` — Comprehensive date utility library: parsing, formatting, comparison, arithmetic, time zones.
+
+  Other:
+  - \`@automerge/automerge\` — CRDT library for conflict-free collaborative data structures.
+  - \`chess.js\` — Chess game logic, move generation, and validation.
+`;
+
+export const Create = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.create',
+    name: 'Create',
+    description: `Creates a new function with TypeScript source code and adds it to the space. ${FUNCTION_FORMAT} ${AVAILABLE_PACKAGES}`,
+  },
+  input: Schema.Struct({
+    name: Schema.String.annotations({
+      description: 'Name of the function.',
+    }),
+    source: Schema.optional(Schema.String).annotations({
+      description: 'TypeScript source code for the function.',
+    }),
+    templateId: Schema.optional(Schema.String).annotations({
+      description: 'ID of a template to use as the initial source.',
+    }),
+  }),
+  output: Schema.Struct({
+    function: FunctionId,
+  }),
+  services: [Database.Service],
+});
+
+export const Read = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.read',
+    name: 'Read',
+    description: 'Reads the source code and metadata of a function.',
+  },
+  input: Schema.Struct({
+    function: FunctionRef,
+  }),
+  output: Schema.Struct({
+    name: Schema.optional(Schema.String),
+    source: Schema.String,
+    description: Schema.optional(Schema.String),
+  }),
+  services: [Database.Service],
+});
+
+const Edit = Schema.Struct({
+  oldString: Schema.String.annotations({
+    description: 'The text to find in the source.',
+  }),
+  newString: Schema.String.annotations({
+    description: 'The text to replace it with.',
+  }),
+  replaceAll: Schema.optional(Schema.Boolean).annotations({
+    description: 'If true, replaces all occurrences. Defaults to false (first occurrence only).',
+  }),
+});
+
+export const Update = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.update',
+    name: 'Update',
+    description: `Updates the source code or metadata of a function. ${FUNCTION_FORMAT}`,
+  },
+  input: Schema.Struct({
+    function: FunctionRef,
+    name: Schema.optional(Schema.String).annotations({
+      description: 'New name for the function.',
+    }),
+    description: Schema.optional(Schema.String).annotations({
+      description: 'New description for the function.',
+    }),
+    edits: Schema.optional(Schema.Array(Edit)).annotations({
+      description: 'Edits to apply to the source. Each edit finds oldString and replaces it with newString.',
+    }),
+  }),
+  output: Schema.Struct({
+    function: FunctionId,
+  }),
+  services: [Database.Service],
+});
+
+export const Delete = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.delete',
+    name: 'Delete',
+    description: 'Deletes a function and its source from the space.',
+  },
+  input: Schema.Struct({
+    function: FunctionRef,
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});
+
+export const Deploy = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.deploy',
+    name: 'Deploy',
+    description: `Deploys a function to the Edge runtime. The function source must follow the required format: a single export default of Operation.pipe(Operation.withHandler(Effect.fn(function* (...) { ... }))). See the Create operation description for a full example.`,
+  },
+  input: Schema.Struct({
+    function: FunctionRef,
+  }),
+  output: Schema.Struct({
+    function: FunctionId,
+    functionUrl: Schema.optional(Schema.String).annotations({
+      description: 'The URL of the deployed function.',
+    }),
+  }),
+  services: [Database.Service, ClientService],
+});
+
+export const Invoke = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.invoke',
+    name: 'Invoke',
+    description: 'Invokes a deployed Edge function with the given payload.',
+  },
+  input: Schema.Struct({
+    function: FunctionRef,
+    payload: Schema.optional(Schema.Unknown).annotations({
+      description: 'The input payload to pass to the function.',
+    }),
+  }),
+  output: Schema.Struct({
+    response: Schema.Unknown.annotations({
+      description: 'The response from the function.',
+    }),
+  }),
+  services: [Database.Service, ClientService],
+});
+
+const InvocationSpanSchema = Schema.Struct({
+  id: Schema.String.annotations({
+    description: 'The invocation ID.',
+  }),
+  timestamp: Schema.Number.annotations({
+    description: 'Start time of the invocation (epoch ms).',
+  }),
+  duration: Schema.Number.annotations({
+    description: 'Duration in milliseconds.',
+  }),
+  outcome: Schema.String.annotations({
+    description: 'Invocation outcome: success, failure, or pending.',
+  }),
+  input: Schema.Object.annotations({
+    description: 'The input payload passed to the function.',
+  }),
+  error: Schema.optional(Schema.Object).annotations({
+    description: 'Error details if the invocation failed.',
+  }),
+});
+
+export const InspectInvocations = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.inspect-invocations',
+    name: 'InspectInvocations',
+    description: 'Queries the invocation trace feed for a function, returning its invocation history.',
+  },
+  input: Schema.Struct({
+    function: FunctionRef,
+    limit: Schema.optional(Schema.Number).annotations({
+      description: 'Maximum number of invocations to return. Defaults to 20.',
+    }),
+  }),
+  output: Schema.Struct({
+    invocations: Schema.Array(InvocationSpanSchema).annotations({
+      description: 'List of invocation spans, most recent first.',
+    }),
+    total: Schema.Number.annotations({
+      description: 'Total number of invocations found.',
+    }),
+  }),
+  services: [Database.Service, Feed.FeedService],
+});
+
+const DeployedFunctionSchema = Schema.Struct({
+  key: Schema.optional(Schema.String).annotations({
+    description: 'Unique key identifying the function. Pass to InstallFunction to install it.',
+  }),
+  name: Schema.String.annotations({
+    description: 'Display name of the function.',
+  }),
+  version: Schema.String.annotations({
+    description: 'Semantic version of the deployed function.',
+  }),
+  description: Schema.optional(Schema.String).annotations({
+    description: 'Description of what the function does.',
+  }),
+  updated: Schema.optional(Schema.String).annotations({
+    description: 'ISO timestamp of the last deployment.',
+  }),
+});
+
+export const QueryDeployedFunctions = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.query-deployed',
+    name: 'QueryDeployedFunctions',
+    description: 'Lists all functions deployed to the EDGE runtime. Use InstallFunction to add one to the space.',
+  },
+  input: Schema.Void,
+  output: Schema.Struct({
+    functions: Schema.Array(DeployedFunctionSchema).annotations({
+      description: 'List of deployed functions.',
+    }),
+  }),
+  services: [ClientService],
+});
+
+export const InstallFunction = Operation.make({
+  meta: {
+    key: 'org.dxos.function.script.install',
+    name: 'InstallFunction',
+    description:
+      'Installs a deployed EDGE function into the current space by key. The returned function ID can be passed directly to Invoke.',
+  },
+  input: Schema.Struct({
+    key: Schema.String.annotations({
+      description: 'The unique key of the deployed function to install (from QueryDeployedFunctions).',
+    }),
+  }),
+  output: Schema.Struct({
+    function: FunctionId,
+    name: Schema.String.annotations({
+      description: 'Name of the installed function.',
+    }),
+    version: Schema.String.annotations({
+      description: 'Version of the installed function.',
+    }),
+  }),
+  services: [ClientService],
+});

package/src/blueprints/functions/delete.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database } from '@dxos/echo';
+
+import { Delete } from './definitions';
+
+export default Delete.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ function: fn }) {
+      const { db } = yield* Database.Service;
+      const loaded = yield* Database.load(fn);
+      if (loaded.source?.target) {
+        db.remove(loaded.source.target);
+      }
+      db.remove(loaded);
+    }),
+  ),
+);

package/src/blueprints/functions/deploy.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import wasmUrl from 'esbuild-wasm/esbuild.wasm?url';
+
+import { ClientService } from '@dxos/client';
+import { Script, Operation } from '@dxos/compute';
+import { Context } from '@dxos/context';
+import { Database, Obj } from '@dxos/echo';
+import { getUserFunctionIdInMetadata } from '@dxos/functions';
+import { bundleFunction, initializeBundler } from '@dxos/functions-runtime/bundler';
+import { FunctionsServiceClient, incrementSemverPatch } from '@dxos/functions-runtime/edge';
+import { FunctionRuntimeKind } from '@dxos/protocols';
+import { getSpace } from '@dxos/react-client/echo';
+
+import { Deploy } from './definitions';
+
+export default Deploy.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ function: fn }) {
+      const loaded = yield* Database.load(fn);
+      const client = yield* ClientService;
+      if (!loaded.source) {
+        return yield* Effect.fail(new Error('Function has no source script.'));
+      }
+      const script = (yield* Database.load(loaded.source)) as Script.Script;
+
+      const space = getSpace(loaded);
+      if (!space || !script.source?.target?.content) {
+        return yield* Effect.fail(new Error('Script source or space not available'));
+      }
+
+      yield* Effect.promise(() => initializeBundler({ wasmUrl }));
+      const buildResult = yield* Effect.promise(() => bundleFunction({ source: script.source!.target!.content }));
+      if ('error' in buildResult) {
+        return yield* Effect.fail(buildResult.error ?? new Error('Bundle creation failed'));
+      }
+
+      const existingFunctionId = getUserFunctionIdInMetadata(Obj.getMeta(loaded));
+
+      const functionsService = FunctionsServiceClient.fromClient(client);
+      const newFunction = yield* Effect.promise(() =>
+        functionsService.deploy(Context.default(), {
+          ownerPublicKey: space.key,
+          version: loaded.version ? incrementSemverPatch(loaded.version) : '0.0.1',
+          functionId: existingFunctionId,
+          entryPoint: buildResult.entryPoint,
+          assets: buildResult.assets,
+          runtime: FunctionRuntimeKind.enums.WORKER_LOADER,
+        }),
+      );
+
+      Operation.setFrom(loaded, newFunction);
+
+      Obj.update(script, (script) => {
+        script.changed = false;
+      });
+
+      const edgeFunctionId = getUserFunctionIdInMetadata(Obj.getMeta(loaded));
+      return {
+        function: Obj.getDXN(loaded).toString(),
+        functionUrl: edgeFunctionId
+          ? `${client.config.values.runtime?.services?.edge?.url ?? ''}/functions/${edgeFunctionId}`
+          : undefined,
+      };
+    }),
+  ),
+);

package/src/blueprints/functions/index.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export * from './definitions';
+
+export const ScriptHandlers = OperationHandlerSet.lazy(
+  () => import('./create'),
+  () => import('./read'),
+  () => import('./update'),
+  () => import('./delete'),
+  () => import('./deploy'),
+  () => import('./invoke'),
+  () => import('./inspect-invocations'),
+  () => import('./query-deployed-functions'),
+  () => import('./install-function'),
+);

package/src/blueprints/functions/inspect-invocations.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { SpaceProperties } from '@dxos/client-protocol';
+import { Operation } from '@dxos/compute';
+import { Database, Feed, Filter, Obj, Query } from '@dxos/echo';
+import { getUserFunctionIdInMetadata } from '@dxos/functions';
+import { InvocationTraceEndEvent, InvocationTraceStartEvent, createInvocationSpans } from '@dxos/functions-runtime';
+
+import { InspectInvocations } from './definitions';
+
+export default InspectInvocations.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ function: fn, limit }) {
+      const loaded = yield* Database.load(fn);
+      const maxResults = limit ?? 20;
+
+      const [properties] = yield* Database.runQuery(Query.type(SpaceProperties));
+      if (!properties?.invocationTraceFeed) {
+        return { invocations: [], total: 0 };
+      }
+
+      const feed = yield* Database.load(properties.invocationTraceFeed);
+      const startEvents = yield* Feed.runQuery(feed, Filter.type(InvocationTraceStartEvent));
+      const endEvents = yield* Feed.runQuery(feed, Filter.type(InvocationTraceEndEvent));
+      const allSpans = createInvocationSpans([...startEvents, ...endEvents]);
+
+      const functionId = getUserFunctionIdInMetadata(Obj.getMeta(loaded));
+
+      const filtered = allSpans.filter((span) => {
+        if (!span.invocationTarget || !functionId) {
+          return false;
+        }
+        const targetDxn = span.invocationTarget.dxn.toString();
+        const uuidPart = targetDxn.split(':').pop();
+        return uuidPart === functionId;
+      });
+
+      filtered.sort((a, b) => b.timestamp - a.timestamp);
+      const total = filtered.length;
+      const invocations = filtered.slice(0, maxResults).map((span) => ({
+        id: span.id,
+        timestamp: span.timestamp,
+        duration: span.duration,
+        outcome: `${span.outcome}`,
+        input: span.input !== null && typeof span.input === 'object' ? span.input : { value: span.input },
+        error: span.error ? (span.error as object) : undefined,
+      }));
+
+      return { invocations, total };
+    }),
+  ),
+);

package/src/blueprints/functions/install-function.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { ClientService } from '@dxos/client';
+import { Operation } from '@dxos/compute';
+import { Context } from '@dxos/context';
+import { Obj, Query } from '@dxos/echo';
+import { FunctionsServiceClient } from '@dxos/functions-runtime/edge';
+
+import { InstallFunction } from './definitions';
+
+export default InstallFunction.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ key }) {
+      const client = yield* ClientService;
+      const functionsService = FunctionsServiceClient.fromClient(client);
+      const deployed = yield* Effect.promise(() => functionsService.query(Context.default()));
+
+      const fn = deployed.findLast((entry) => entry.key === key);
+      if (!fn) {
+        return yield* Effect.fail(new Error(`No deployed function found with key: ${key}`));
+      }
+
+      const space = client.spaces.get()[0];
+      if (!space) {
+        return yield* Effect.fail(new Error('No space available'));
+      }
+
+      yield* Effect.promise(() => client.addTypes([Operation.PersistentOperation]));
+
+      const existingFunctions = yield* Effect.promise(() =>
+        space.db.query(Query.type(Operation.PersistentOperation, { key })).run(),
+      );
+
+      let installed: Operation.PersistentOperation;
+      if (existingFunctions.length > 0) {
+        installed = existingFunctions[0];
+        for (const existing of existingFunctions) {
+          Operation.setFrom(existing, fn);
+        }
+      } else {
+        installed = Obj.clone(fn);
+        space.db.add(installed);
+      }
+
+      return {
+        function: Obj.getDXN(installed).toString(),
+        name: fn.name ?? 'Unnamed function',
+        version: fn.version ?? '0.0.0',
+      };
+    }),
+  ),
+);

package/src/blueprints/functions/invoke.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { ClientService } from '@dxos/client';
+import { Operation } from '@dxos/compute';
+import { Context } from '@dxos/context';
+import { Database } from '@dxos/echo';
+import { FunctionsServiceClient } from '@dxos/functions-runtime/edge';
+import { getSpace } from '@dxos/react-client/echo';
+
+import { Invoke } from './definitions';
+
+export default Invoke.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ function: fn, payload }) {
+      const loaded = yield* Database.load(fn);
+      const client = yield* ClientService;
+
+      const space = getSpace(loaded);
+      if (!space) {
+        return yield* Effect.fail(new Error('Function is not in a space.'));
+      }
+
+      const functionsService = FunctionsServiceClient.fromClient(client);
+      const result = yield* Effect.promise(() =>
+        functionsService.invoke(Context.default(), loaded, payload ?? {}, { spaceId: space.id }),
+      );
+
+      return { response: result };
+    }),
+  ),
+);

package/src/blueprints/functions/query-deployed-functions.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { ClientService } from '@dxos/client';
+import { Operation } from '@dxos/compute';
+import { Context } from '@dxos/context';
+import { FunctionsServiceClient } from '@dxos/functions-runtime/edge';
+
+import { QueryDeployedFunctions } from './definitions';
+
+export default QueryDeployedFunctions.pipe(
+  Operation.withHandler(
+    Effect.fn(function* () {
+      const client = yield* ClientService;
+      const functionsService = FunctionsServiceClient.fromClient(client);
+      const deployed = yield* Effect.promise(() => functionsService.query(Context.default()));
+      return {
+        functions: deployed.map((fn) => ({
+          key: fn.key,
+          name: fn.name ?? 'Unnamed function',
+          version: fn.version ?? '0.0.0',
+          description: fn.description,
+          updated: fn.updated,
+        })),
+      };
+    }),
+  ),
+);

package/src/blueprints/functions/read.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { type Script, Operation } from '@dxos/compute';
+import { Database } from '@dxos/echo';
+
+import { Read } from './definitions';
+
+export default Read.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ function: fn }) {
+      const loaded = yield* Database.load(fn);
+      if (!loaded.source) {
+        return yield* Effect.fail(new Error('Function has no source script.'));
+      }
+      const script = (yield* Database.load(loaded.source)) as Script.Script;
+      const text = yield* Database.load(script.source);
+
+      return {
+        name: script.name,
+        source: text.content,
+        description: script.description,
+      };
+    }),
+  ),
+);