toolcraft-schema 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+# toolcraft-schema
+
+tools for agents and humans
+
+Zero-dependency schema builder for typed command inputs and JSON Schema generation.
+
+## Features
+
+- Zero runtime dependencies
+- Typed schema descriptors
+- `Static<typeof schema>` type inference
+- JSON Schema serialization via `toJsonSchema()`
+
+## Usage
+
+```ts
+import { S, toJsonSchema } from "agent-kit-schema";
+import type { Static } from "agent-kit-schema";
+
+const schema = S.Object({
+  name: S.String({ description: "User name" }),
+  retries: S.Optional(S.Number({ default: 3 })),
+  mode: S.Enum(["fast", "safe"] as const, { default: "safe" }),
+  tags: S.Array(S.String(), { default: [] }),
+});
+
+type Input = Static<typeof schema>;
+// {
+//   name: string;
+//   retries?: number;
+//   mode: "fast" | "safe";
+//   tags: string[];
+// }
+
+const jsonSchema = toJsonSchema(schema);
+```
+
+## API
+
+### Builders
+
+- `S.String({ description?, default? })`
+- `S.Number({ description?, default? })`
+- `S.Boolean({ description?, default? })`
+- `S.Enum(values, { description?, default? })`
+- `S.Array(itemSchema, { description?, default? })`
+- `S.Object({ [key]: schema })`
+- `S.Optional(schema)`
+
+### Type helpers
+
+- `Static<typeof schema>` infers the runtime TypeScript shape for a schema descriptor.
+- Object properties wrapped in `S.Optional(...)` become optional properties in `Static`.
+
+### JSON Schema generation
+
+- `toJsonSchema(schema)` converts any schema descriptor to standard JSON Schema.
+- Object properties not wrapped in `S.Optional(...)` are emitted in `required`.
+- Defaults provided to schema builders are emitted as JSON Schema `default`.
+- Nested `S.Object(...)` schemas produce nested JSON Schema objects.
+- `S.Enum(...)` rejects empty or duplicate values at runtime for JavaScript callers.
+
+## Environment variables
+
+This package exposes no environment variables.
+
+## Configuration
+
+This package currently exposes no package-level configuration options.

package/dist/index.compile-check.d.ts

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

package/dist/index.compile-check.js

@@ -0,0 +1,12 @@
+import { S } from "./index.js";
+const ignoredStringSchema = S.String({ description: "Name", default: "guest" });
+const ignoredNumberSchema = S.Number({ description: "Count", default: 1 });
+const ignoredBooleanSchema = S.Boolean({ description: "Enabled", default: false });
+const ignoredEnumSchema = S.Enum(["admin", "user"], { default: "admin" });
+const ignoredIntegerEnumSchema = S.Enum([1, 2], { jsonType: "integer" });
+const ignoredArraySchema = S.Array(S.String(), { default: ["a"] });
+const ignoredObjectSchema = S.Object({
+    name: S.String(),
+    retries: S.Optional(S.Number()),
+});
+const ignoredOptionalSchema = S.Optional(S.Boolean());

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "array" | "object";
+type SchemaKind = "string" | "number" | "boolean" | "enum" | "array" | "object" | "optional";
+type EnumValue = string | number | boolean;
+type JsonSchemaEnumValue = EnumValue | null;
+type NumberJsonType = "number" | "integer";
+type NonEmptyReadonlyArray<T> = readonly [T, ...T[]];
+type ObjectShape = Record<string, AnySchema>;
+type SchemaScope = "cli" | "mcp" | "sdk";
+type StringMetadata = {
+    format?: string;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+};
+type NumberMetadata = {
+    maximum?: number;
+    minimum?: number;
+};
+type ArrayMetadata = {
+    maxItems?: number;
+    minItems?: number;
+};
+type ObjectMetadata = {
+    additionalProperties?: boolean;
+};
+type OptionalKeys<TShape extends ObjectShape> = {
+    [TKey in keyof TShape]: TShape[TKey] extends OptionalSchema<any> ? TKey : never;
+}[keyof TShape];
+type RequiredKeys<TShape extends ObjectShape> = Exclude<keyof TShape, OptionalKeys<TShape>>;
+type PropertyStatic<TSchema extends AnySchema> = TSchema extends OptionalSchema<infer TInner> ? Static<TInner> : Static<TSchema>;
+type InferObject<TShape extends ObjectShape> = {
+    [TKey in RequiredKeys<TShape>]: PropertyStatic<TShape[TKey]>;
+} & {
+    [TKey in OptionalKeys<TShape>]?: PropertyStatic<TShape[TKey]>;
+};
+type SchemaOptions<TDefault> = {
+    description?: string;
+    default?: TDefault;
+    nullable?: boolean;
+    requiredScopes?: readonly SchemaScope[];
+    short?: string;
+    scope?: readonly SchemaScope[];
+};
+interface SchemaBase<TKind extends SchemaKind, TStatic> {
+    readonly kind: TKind;
+    readonly description?: string;
+    readonly default?: TStatic;
+    readonly nullable?: boolean;
+    readonly requiredScopes?: readonly SchemaScope[];
+    readonly short?: string;
+    readonly scope?: readonly SchemaScope[];
+    readonly __static?: TStatic;
+}
+export interface JsonSchema {
+    additionalProperties?: boolean;
+    type?: JsonSchemaType;
+    description?: string;
+    default?: unknown;
+    enum?: ReadonlyArray<JsonSchemaEnumValue>;
+    format?: string;
+    items?: JsonSchema;
+    maxItems?: number;
+    maximum?: number;
+    maxLength?: number;
+    minItems?: number;
+    minimum?: number;
+    minLength?: number;
+    nullable?: boolean;
+    pattern?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+}
+export interface StringSchema extends SchemaBase<"string", string>, StringMetadata {
+}
+export interface NumberSchema extends SchemaBase<"number", number>, NumberMetadata {
+    readonly jsonType?: NumberJsonType;
+}
+export type BooleanSchema = SchemaBase<"boolean", boolean>;
+export interface EnumSchema<TValues extends NonEmptyReadonlyArray<EnumValue>> extends SchemaBase<"enum", TValues[number]> {
+    readonly values: TValues;
+    readonly jsonType?: "integer";
+    readonly labels?: Partial<Record<string, string>>;
+    readonly loadOptions?: (() => Array<{
+        label: string;
+        value: string;
+    }>) | (() => Promise<Array<{
+        label: string;
+        value: string;
+    }>>);
+}
+export interface ArraySchema<TItem extends AnySchema> extends SchemaBase<"array", Array<Static<TItem>>>, ArrayMetadata {
+    readonly item: TItem;
+}
+export interface ObjectSchema<TShape extends ObjectShape> extends SchemaBase<"object", InferObject<TShape>>, ObjectMetadata {
+    readonly shape: TShape;
+}
+export interface OptionalSchema<TInner extends AnySchema> extends SchemaBase<"optional", Static<TInner> | undefined> {
+    readonly inner: TInner;
+}
+export type AnySchema = StringSchema | NumberSchema | BooleanSchema | EnumSchema<NonEmptyReadonlyArray<EnumValue>> | ArraySchema<AnySchema> | ObjectSchema<ObjectShape> | OptionalSchema<AnySchema>;
+export type Static<TSchema extends AnySchema> = TSchema extends SchemaBase<any, infer TStatic> ? TStatic : never;
+export declare const S: {
+    readonly String: (options?: SchemaOptions<string> & StringMetadata) => StringSchema;
+    readonly Number: (options?: SchemaOptions<number> & NumberMetadata & {
+        jsonType?: NumberJsonType;
+    }) => NumberSchema;
+    readonly Boolean: (options?: SchemaOptions<boolean>) => BooleanSchema;
+    readonly Enum: <const TValues extends NonEmptyReadonlyArray<EnumValue>>(values: TValues, options?: SchemaOptions<TValues[number]> & {
+        jsonType?: "integer";
+        labels?: Partial<Record<string, string>>;
+        loadOptions?: (() => Array<{
+            label: string;
+            value: string;
+        }>) | (() => Promise<Array<{
+            label: string;
+            value: string;
+        }>>);
+    }) => EnumSchema<TValues>;
+    readonly Array: <TItem extends AnySchema>(item: TItem, options?: SchemaOptions<Array<Static<TItem>>> & ArrayMetadata) => ArraySchema<TItem>;
+    readonly Object: <const TShape extends ObjectShape>(shape: TShape, options?: SchemaOptions<InferObject<TShape>> & ObjectMetadata) => ObjectSchema<TShape>;
+    readonly Optional: <TInner extends AnySchema>(inner: TInner) => OptionalSchema<TInner>;
+};
+export declare function toJsonSchema(schema: AnySchema): JsonSchema;
+export {};

package/dist/index.js

@@ -0,0 +1,175 @@
+function withMetadata(schema, jsonSchema) {
+    if (schema.description !== undefined) {
+        jsonSchema.description = schema.description;
+    }
+    if (schema.default !== undefined) {
+        jsonSchema.default = schema.default;
+    }
+    if (schema.nullable === true) {
+        jsonSchema.nullable = true;
+    }
+    return jsonSchema;
+}
+function withStringMetadata(schema, jsonSchema) {
+    if (schema.minLength !== undefined) {
+        jsonSchema.minLength = schema.minLength;
+    }
+    if (schema.maxLength !== undefined) {
+        jsonSchema.maxLength = schema.maxLength;
+    }
+    if (schema.pattern !== undefined) {
+        jsonSchema.pattern = schema.pattern;
+    }
+    if (schema.format !== undefined) {
+        jsonSchema.format = schema.format;
+    }
+    return withMetadata(schema, jsonSchema);
+}
+function withNumberMetadata(schema, jsonSchema) {
+    if (schema.minimum !== undefined) {
+        jsonSchema.minimum = schema.minimum;
+    }
+    if (schema.maximum !== undefined) {
+        jsonSchema.maximum = schema.maximum;
+    }
+    return withMetadata(schema, jsonSchema);
+}
+function withArrayMetadata(schema, jsonSchema) {
+    if (schema.minItems !== undefined) {
+        jsonSchema.minItems = schema.minItems;
+    }
+    if (schema.maxItems !== undefined) {
+        jsonSchema.maxItems = schema.maxItems;
+    }
+    return withMetadata(schema, jsonSchema);
+}
+function withObjectMetadata(schema, jsonSchema) {
+    if (schema.additionalProperties !== undefined) {
+        jsonSchema.additionalProperties = schema.additionalProperties;
+    }
+    return withMetadata(schema, jsonSchema);
+}
+function getEnumJsonType(values) {
+    const [firstValue] = values;
+    if (firstValue === undefined) {
+        return undefined;
+    }
+    const firstType = typeof firstValue;
+    const isSinglePrimitiveType = values.every((value) => typeof value === firstType);
+    if (!isSinglePrimitiveType) {
+        return undefined;
+    }
+    if (firstType === "string" || firstType === "number" || firstType === "boolean") {
+        return firstType;
+    }
+    return undefined;
+}
+function isOptionalSchema(schema) {
+    return schema.kind === "optional";
+}
+function assertValidEnumValues(values) {
+    if (values.length === 0) {
+        throw new Error("Enum schema requires at least one value");
+    }
+    const uniqueValues = new Set(values);
+    if (uniqueValues.size !== values.length) {
+        throw new Error("Enum schema values must be unique");
+    }
+}
+function unwrapOptional(schema) {
+    if (isOptionalSchema(schema)) {
+        return unwrapOptional(schema.inner);
+    }
+    return schema;
+}
+export const S = {
+    String(options = {}) {
+        return {
+            kind: "string",
+            ...options,
+        };
+    },
+    Number(options = {}) {
+        return {
+            kind: "number",
+            ...options,
+        };
+    },
+    Boolean(options = {}) {
+        return {
+            kind: "boolean",
+            ...options,
+        };
+    },
+    Enum(values, options = {}) {
+        assertValidEnumValues(values);
+        return {
+            kind: "enum",
+            values,
+            ...options,
+        };
+    },
+    Array(item, options = {}) {
+        return {
+            kind: "array",
+            item,
+            ...options,
+        };
+    },
+    Object(shape, options = {}) {
+        return {
+            kind: "object",
+            shape,
+            ...options,
+        };
+    },
+    Optional(inner) {
+        return {
+            kind: "optional",
+            inner,
+        };
+    },
+};
+export function toJsonSchema(schema) {
+    const unwrappedSchema = unwrapOptional(schema);
+    switch (unwrappedSchema.kind) {
+        case "string":
+            return withStringMetadata(unwrappedSchema, { type: "string" });
+        case "number":
+            return withNumberMetadata(unwrappedSchema, { type: unwrappedSchema.jsonType ?? "number" });
+        case "boolean":
+            return withMetadata(unwrappedSchema, { type: "boolean" });
+        case "enum": {
+            const jsonSchema = {
+                enum: unwrappedSchema.nullable === true
+                    ? [...unwrappedSchema.values, null]
+                    : [...unwrappedSchema.values],
+            };
+            const enumType = unwrappedSchema.jsonType ?? getEnumJsonType(unwrappedSchema.values);
+            if (enumType !== undefined) {
+                jsonSchema.type = enumType;
+            }
+            return withMetadata(unwrappedSchema, jsonSchema);
+        }
+        case "array":
+            return withArrayMetadata(unwrappedSchema, {
+                type: "array",
+                items: toJsonSchema(unwrappedSchema.item),
+            });
+        case "object": {
+            const properties = {};
+            const required = [];
+            for (const [key, propertySchema] of Object.entries(unwrappedSchema.shape)) {
+                properties[key] = toJsonSchema(propertySchema);
+                if (!isOptionalSchema(propertySchema)) {
+                    required.push(key);
+                }
+            }
+            return withObjectMetadata(unwrappedSchema, {
+                type: "object",
+                properties,
+                required,
+            });
+        }
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "toolcraft-schema",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "cd ../.. && vitest run packages/agent-kit-schema/src/index.test.ts",
+    "test:unit": "cd ../.. && vitest run packages/agent-kit-schema/src/index.test.ts",
+    "lint": "cd ../.. && eslint packages/agent-kit-schema/src --ext ts && tsc -p packages/agent-kit-schema/tsconfig.json --noEmit"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poe-platform/poe-code.git",
+    "directory": "packages/agent-kit-schema"
+  }
+}