@collegium/sdk 0.0.1-beta.8 → 0.0.1-beta.9

package/README.md

@@ -38,10 +38,10 @@ export default defineTool({
   approval: (args) => ({ body: `save contact "${args.id}": ${args.name}`, presentation: 'verbatim' }),
   description: 'Save or update a contact.',
   execute: async (args, { err, settings, storage }) => {
-    if ((await storage.contacts.list()).length >= settings.maxContacts) {
+    if ((await storage.contacts.findMany()).length >= settings.maxContacts) {
       err.invalidArguments('contact limit reached; delete one first');
     }
-    await storage.contacts.put(args.id, { email: args.email, name: args.name });
+    await storage.contacts.create({ email: args.email, id: args.id, name: args.name });
     return `contact ${args.id} saved`;
   },
   parameters: z.object({ email: z.email(), id: z.string().min(1), name: z.string().min(1) })
@@ -50,6 +50,8 @@ export default defineTool({
 
 A tool with `approval` always stops for a human, who sees the full payload before it runs; one without never gates. The channel and the trace disclose both, line by line. `execute` returns the text the model reads, and raises the two failures a tool controls through `err`: `invalidArguments` continues the turn, `unresolved` ends it as an unconfirmed side effect.
 
+**Storage.** Each declared collection is a set of records: the schema's output plus `id`, `createdAt`, and `updatedAt`, which the store stamps. The handle has `create`, `findMany`, `findById`, `updateById`, and `deleteById`. `create` takes the schema's input with an optional `id`, minting a cuid2 when none is given. `findMany` with no argument lists everything; with a `where` over the schema's top-level scalar fields and `id` — a value for equality, `{ in: [...] }` for membership, `{ contains: text }` for a case-insensitive substring on a string — and an optional `limit`, it filters. Field names and value types come from the schema, so a bad query does not compile.
+
 **Testing.** `@collegium/sdk/testing` builds the context `execute` receives, over in-memory storage that validates and parses as the deployment's store does. Pass your config; settings go through your schema, so defaults apply.
 
 ```ts

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { c as ToolTurnScope, d as defineConfig, i as defineTool, n as ToolContext, o as ToolApprovalPayload, s as ToolDisclosure, t as PluginTool, u as Register } from "./tool-CN2DS668.js";
+import { c as ToolTurnScope, d as defineConfig, i as defineTool, n as ToolContext, o as ToolApprovalPayload, s as ToolDisclosure, t as PluginTool, u as Register } from "./tool-Vqe6D48m.js";
 export { type PluginTool, type Register, type ToolApprovalPayload, type ToolContext, type ToolDisclosure, type ToolTurnScope, defineConfig, defineTool };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { a as PluginToolFailureError, c as ToolTurnScope, l as PluginConfig, r as ToolContextFor } from "./tool-CN2DS668.js";
+import { a as PluginToolFailureError, c as ToolTurnScope, l as PluginConfig, r as ToolContextFor } from "./tool-Vqe6D48m.js";
 import { z } from "zod";
 //#region src/testing.d.ts
 /** `settings` as the declared schema accepts them, so defaults apply as they do at boot; `turn` overrides the four facts */

package/dist/testing.js

@@ -8,6 +8,82 @@ var PluginToolFailureError = class extends Error {
 	}
 };
 //#endregion
+//#region ../../node_modules/.pnpm/es-toolkit@1.50.0/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
+/**
+* Checks if a given value is a plain object.
+*
+* @param value - The value to check.
+* @returns True if the value is a plain object, otherwise false.
+*
+* @example
+* ```typescript
+* // ✅👇 True
+*
+* isPlainObject({ });                       // ✅
+* isPlainObject({ key: 'value' });          // ✅
+* isPlainObject({ key: new Date() });       // ✅
+* isPlainObject(new Object());              // ✅
+* isPlainObject(Object.create(null));       // ✅
+* isPlainObject({ nested: { key: true} });  // ✅
+* isPlainObject(new Proxy({}, {}));         // ✅
+* isPlainObject({ [Symbol('tag')]: 'A' });  // ✅
+*
+* // ✅👇 (cross-realms, node context, workers, ...)
+* const runInNewContext = await import('node:vm').then(
+*     (mod) => mod.runInNewContext
+* );
+* isPlainObject(runInNewContext('({})'));   // ✅
+*
+* // ❌👇 False
+*
+* class Test { };
+* isPlainObject(new Test())           // ❌
+* isPlainObject(10);                  // ❌
+* isPlainObject(null);                // ❌
+* isPlainObject('hello');             // ❌
+* isPlainObject([]);                  // ❌
+* isPlainObject(new Date());          // ❌
+* isPlainObject(new Uint8Array([1])); // ❌
+* isPlainObject(Buffer.from('ABC'));  // ❌
+* isPlainObject(Promise.resolve({})); // ❌
+* isPlainObject(Object.create({}));   // ❌
+* isPlainObject(new (class Cls {}));  // ❌
+* isPlainObject(globalThis);          // ❌,
+* ```
+*/
+function isPlainObject(value) {
+	if (!value || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	if (!(proto === null || proto === Object.prototype || Object.getPrototypeOf(proto) === null)) return false;
+	return Object.prototype.toString.call(value) === "[object Object]";
+}
+//#endregion
+//#region ../core/dist/toolsets/storage/collection-query.utils.js
+/** folds ASCII letters only, matching SQLite's `lower()` without ICU, so the store and this evaluator agree on every string */
+const foldAsciiCase = (text) => text.replace(/[A-Z]+/g, (upper) => upper.toLowerCase());
+const readField = (record, field) => isPlainObject(record) ? record[field] : void 0;
+const matchesScalar = (actual, expected) => expected === null ? actual === null || actual === void 0 : actual === expected;
+const matchesCondition = (actual, condition) => {
+	if (condition === null || typeof condition !== "object") return matchesScalar(actual, condition);
+	if ("in" in condition) return condition.in.some((candidate) => matchesScalar(actual, candidate));
+	return typeof actual === "string" && foldAsciiCase(actual).includes(foldAsciiCase(condition.contains));
+};
+const readConditions = (where) => {
+	const conditions = [];
+	for (const [field, condition] of Object.entries(where ?? {})) if (condition !== void 0) conditions.push([field, condition]);
+	return conditions;
+};
+/** the stated conditions of a query, by field, an undefined one dropped as unstated */
+function collectionQueryConditions(query) {
+	return readConditions(query.where);
+}
+/** the query over records already in memory, in their own order — the semantics the store's compiled form must reproduce */
+function applyCollectionQuery(records, query) {
+	const conditions = collectionQueryConditions(query);
+	const matching = records.filter((record) => conditions.every(([field, condition]) => matchesCondition(readField(record, field), condition)));
+	return query.limit === void 0 ? matching : matching.slice(0, query.limit);
+}
+//#endregion
 //#region ../core/dist/plugins/plugins.utils.js
 /** what a plugin tool receives as `err`; shared with the SDK's testing entry, so a test raises the failure a deployment would */
 const PLUGIN_TOOL_ERR = {
@@ -32,17 +108,44 @@ const DEFAULT_TURN = {
 	triggeringPostId: null,
 	turnId: "test-turn"
 };
+/** the deployment's store mints a cuid2; here any unique string serves, and a test that needs a known id passes one */
 function createCollection(schema) {
 	const rows = /* @__PURE__ */ new Map();
+	const toRecord = ({ createdAt, id, updatedAt, ...value }) => ({
+		...schema.parse(value),
+		createdAt,
+		id,
+		updatedAt
+	});
 	return {
-		delete: (key) => Promise.try(() => rows.delete(key)),
-		get: (key) => Promise.try(() => rows.has(key) ? schema.parse(rows.get(key)) : null),
-		list: () => Promise.try(() => [...rows].map(([key, value]) => ({
-			key,
-			value: schema.parse(value)
-		}))),
-		put: (key, value) => Promise.try(() => {
-			rows.set(key, schema.parse(value));
+		create: ({ id = crypto.randomUUID(), ...data }) => Promise.try(() => {
+			if (rows.has(id)) throw new Error(`storage collection already holds a record with id "${id}"`);
+			const now = /* @__PURE__ */ new Date();
+			rows.set(id, {
+				...schema.parse(data),
+				createdAt: now,
+				id,
+				updatedAt: now
+			});
+			return toRecord(rows.get(id));
+		}),
+		deleteById: (id) => Promise.try(() => rows.delete(id)),
+		findById: (id) => Promise.try(() => rows.has(id) ? toRecord(rows.get(id)) : null),
+		findMany: (query = {}) => Promise.try(() => applyCollectionQuery([...rows.values()].map(toRecord), query)),
+		updateById: (id, patch) => Promise.try(() => {
+			const row = rows.get(id);
+			if (row === void 0) return null;
+			const { createdAt, id: _id, updatedAt: _updatedAt, ...value } = row;
+			rows.set(id, {
+				...schema.parse({
+					...schema.parse(value),
+					...patch
+				}),
+				createdAt,
+				id,
+				updatedAt: /* @__PURE__ */ new Date()
+			});
+			return toRecord(rows.get(id));
 		})
 	};
 }

package/dist/{tool-CN2DS668.d.ts → tool-Vqe6D48m.d.ts}

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { Promisable } from "type-fest";
 //#region src/config.d.ts
 type CollectionsDeclaration$1 = {
-  readonly [key: string]: z.ZodType;
+  readonly [key: string]: z.ZodObject;
 };
 /**
  * The config file's default export: the settings schema agents are configured by, and the storage
@@ -143,6 +143,54 @@ type PluginToolDeclaration<TContext, TParams extends z.ZodType> = {
   traceDetail?(args: z.infer<TParams>): string;
 };
 //#endregion
+//#region ../core/src/toolsets/storage/collection-query.types.d.ts
+/** the JSON scalars a query may compare; an object, array, or date field is not queryable */
+type Scalar = boolean | null | number | string;
+/**
+ * The top-level scalar fields of a record, each stripped of the undefined an optional field
+ * carries. The intersection with the scalar union changes nothing for a concrete record and is what
+ * lets the compiler see, over a generic one, that every condition is a scalar condition.
+ */
+type QueryableFields<TRecord> = { readonly [K in keyof TRecord as Exclude<TRecord[K], undefined> extends Scalar ? K : never]-?: Exclude<TRecord[K], undefined> & Scalar; };
+/** one field's condition: equality, membership, or — on a string field — a case-insensitive substring */
+type CollectionFieldCondition<TField> = ([Extract<TField, string>] extends [never] ? never : {
+  readonly contains: string;
+}) | TField | {
+  readonly in: readonly TField[];
+};
+/** an AND over field conditions, keyed by the record's own scalar fields */
+type CollectionWhere<TRecord> = { readonly [K in keyof QueryableFields<TRecord>]?: CollectionFieldCondition<QueryableFields<TRecord>[K]>; };
+type CollectionQuery<TRecord> = {
+  readonly limit?: number;
+  readonly where?: CollectionWhere<TRecord>;
+};
+//#endregion
+//#region ../core/src/toolsets/storage/collection.types.d.ts
+/** what the store stamps on every record beside the declared fields; a schema may not declare any of these */
+type CollectionRecordStamp = {
+  readonly createdAt: Date;
+  readonly id: string;
+  readonly updatedAt: Date;
+};
+type CollectionRecord<TValue> = CollectionRecordStamp & TValue;
+/**
+ * A toolset-scoped handle over one declared storage collection. Every record is the schema's
+ * output plus the stamp; `create` parses through the schema, so defaults apply, and mints a
+ * cuid2 unless an id is given. Reads parse each stored value, so a row an older schema wrote
+ * fails loudly rather than leaking a stale shape into the tool.
+ */
+type ToolsetCollection<TSchema extends z.ZodObject> = {
+  create(data: z.input<TSchema> & {
+    readonly id?: string;
+  }): Promise<CollectionRecord<z.output<TSchema>>>;
+  deleteById(id: string): Promise<boolean>;
+  findById(id: string): Promise<CollectionRecord<z.output<TSchema>> | null>;
+  /** without a query, every record in insertion order */
+  findMany(query?: CollectionQuery<CollectionRecord<z.output<TSchema>>>): Promise<CollectionRecord<z.output<TSchema>>[]>;
+  /** the patch merged over the stored fields and the whole parsed again, so a patch cannot leave an invalid record */
+  updateById(id: string, patch: Partial<z.input<TSchema>>): Promise<CollectionRecord<z.output<TSchema>> | null>;
+};
+//#endregion
 //#region ../core/src/toolsets/toolsets.types.d.ts
 /** `settings`, `storage`, and `turn` are the context's own keys, so a service may not claim them */
 type ServicesDeclaration = {
@@ -153,19 +201,9 @@ type ServicesDeclaration = {
   readonly turn?: never;
 };
 type CollectionsDeclaration = {
-  readonly [key: string]: z.ZodType;
+  readonly [key: string]: z.ZodObject;
 };
 type EmptyDeclaration = {};
-/** a toolset-scoped handle over one declared storage collection; rows are validated on write and parsed on read */
-type ToolsetCollection<TValue> = {
-  delete(key: string): Promise<boolean>;
-  get(key: string): Promise<null | TValue>;
-  list(): Promise<{
-    key: string;
-    value: TValue;
-  }[]>;
-  put(key: string, value: TValue): Promise<void>;
-};
 /**
  * What `execute` receives, assembled from exactly what the toolset declared (§4): each service
  * under its own name, `settings` and `storage` only when declared, and always the turn. Reaching
@@ -174,7 +212,7 @@ type ToolsetCollection<TValue> = {
 type ToolsetContext<TServices extends ServicesDeclaration = EmptyDeclaration, TSettings extends undefined | z.ZodType = undefined, TCollections extends CollectionsDeclaration = EmptyDeclaration> = { readonly [K in keyof TServices]: TServices[K] extends ServiceToken<infer TInstance> ? TInstance : never; } & {
   readonly turn: ToolTurnScope;
 } & (keyof TCollections extends never ? unknown : {
-  readonly storage: { readonly [K in keyof TCollections]: ToolsetCollection<z.infer<TCollections[K]>>; };
+  readonly storage: { readonly [K in keyof TCollections]: ToolsetCollection<TCollections[K]>; };
 }) & (TSettings extends z.ZodType ? {
   readonly settings: z.infer<TSettings>;
 } : unknown);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@collegium/sdk",
   "type": "module",
-  "version": "0.0.1-beta.8",
+  "version": "0.0.1-beta.9",
   "description": "Write a Collegium plugin: declare a toolset with its tools, settings, storage, and skills.",
   "license": "AGPL-3.0-only",
   "homepage": "https://collegium.sh",