@mica-js/sdk 0.0.0-stage → 0.2.0

package/dist/metadata/validate.js

@@ -0,0 +1,283 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import { deviceMetadataSchema, widgetMetadataSchema } from './schema.js';
+/** Thrown by {@link validateMetadata} when a metadata document is rejected. */
+export class MetadataValidationError extends Error {
+    kind;
+    issues;
+    metadataId;
+    constructor(kind, issues, metadataId) {
+        super(formatMessage(kind, issues, metadataId));
+        this.name = 'MetadataValidationError';
+        this.kind = kind;
+        this.issues = issues;
+        this.metadataId = metadataId;
+    }
+}
+const ajv = new Ajv2020({
+    allErrors: true,
+    strict: true,
+    allowUnionTypes: true,
+    validateFormats: false,
+});
+const validators = {
+    device: ajv.compile(deviceMetadataSchema),
+    widget: ajv.compile(widgetMetadataSchema),
+};
+/** Keywords whose failure only restates a problem reported by their subschemas. */
+const containerKeywords = new Set(['if', 'allOf', 'anyOf', 'oneOf']);
+/**
+ * Validates one device or widget metadata document.
+ *
+ * @param input Untrusted JSON value of the metadata file.
+ * @param kind Metadata kind that selects the contract.
+ * @param expectedId Id the caller expects; a mismatch is reported at `id`.
+ * @throws {MetadataValidationError} with the path of every rejected value.
+ */
+export function validateMetadata(input, kind, expectedId) {
+    if (kind !== 'device' && kind !== 'widget') {
+        throw new TypeError(`Unknown metadata kind "${String(kind)}"; expected "device" or "widget".`);
+    }
+    const metadataId = isRecord(input) && typeof input.id === 'string' ? input.id : undefined;
+    const fatal = findNonFiniteNumbers(input);
+    if (fatal.length > 0)
+        throw new MetadataValidationError(kind, fatal, metadataId);
+    const validate = validators[kind];
+    const issues = [];
+    if (!validate(input))
+        issues.push(...toIssues(validate.errors ?? [], input));
+    issues.push(...semanticIssues(input));
+    if (expectedId !== undefined && metadataId !== undefined && metadataId !== expectedId) {
+        issues.push({
+            path: 'id',
+            keyword: 'expectedId',
+            message: `must equal the expected metadata id ${quote(expectedId)}`,
+        });
+    }
+    if (issues.length === 0)
+        return;
+    throw new MetadataValidationError(kind, dedupeAndSort(issues), metadataId);
+}
+function toIssues(errors, input) {
+    const issues = [];
+    for (const error of errors) {
+        if (containerKeywords.has(error.keyword))
+            continue;
+        const params = error.params;
+        const basePath = pointerToPath(error.instancePath);
+        let path = basePath;
+        if (error.keyword === 'required')
+            path = joinPath(basePath, String(params.missingProperty));
+        else if (error.keyword === 'additionalProperties') {
+            path = joinPath(basePath, String(params.additionalProperty));
+        }
+        issues.push({ path, message: describeError(error, input), keyword: error.keyword });
+    }
+    if (issues.length > 0 || errors.length === 0)
+        return issues;
+    return errors.map((error) => ({
+        path: pointerToPath(error.instancePath),
+        message: error.message ?? 'is invalid',
+        keyword: error.keyword,
+    }));
+}
+function describeError(error, input) {
+    const params = error.params;
+    switch (error.keyword) {
+        case 'required': {
+            const missing = String(params.missingProperty);
+            const owner = resolvePointer(input, error.instancePath);
+            if (missing === 'nullable' && isRecord(owner) && owner.default === null) {
+                return 'must be true when the default value is null';
+            }
+            return `missing required field ${quote(missing)}`;
+        }
+        case 'additionalProperties':
+            return `unknown field ${quote(String(params.additionalProperty))}`;
+        case 'enum': {
+            const allowed = Array.isArray(params.allowedValues) ? params.allowedValues : [];
+            return `must be one of ${allowed.map((value) => quote(String(value))).join(', ')}`;
+        }
+        case 'const': {
+            const { parent, key } = resolveParent(input, error.instancePath);
+            if (key === 'nullable' && isRecord(parent) && parent.default === null) {
+                return 'must be true when the default value is null';
+            }
+            return `must be ${quote(String(params.allowedValue))}`;
+        }
+        case 'type':
+            return `must be ${describeTypes(params.type)}`;
+        case 'pattern':
+            return `must match the pattern ${String(params.pattern)}`;
+        case 'minLength':
+            return params.limit === 1
+                ? 'must not be empty'
+                : `must have at least ${describeLimit(params)} characters`;
+        case 'maxLength':
+            return `must have at most ${describeLimit(params)} characters`;
+        case 'minimum':
+            return `must be greater than or equal to ${describeLimit(params)}`;
+        case 'maximum':
+            return `must be less than or equal to ${describeLimit(params)}`;
+        case 'exclusiveMinimum':
+            return `must be greater than ${describeLimit(params)}`;
+        case 'exclusiveMaximum':
+            return `must be less than ${describeLimit(params)}`;
+        case 'uniqueItems':
+            return 'must not contain duplicate values';
+        case 'minItems':
+            return `must contain at least ${describeLimit(params)} items`;
+        case 'maxItems':
+            return `must contain at most ${describeLimit(params)} items`;
+        case 'false schema':
+            return describeForbiddenField(input, error.instancePath);
+        case 'not':
+            return `must not be ${formatValue(resolvePointer(input, error.instancePath))}`;
+        default:
+            return error.message ?? 'is invalid';
+    }
+}
+function describeForbiddenField(input, pointer) {
+    const { parent, key } = resolveParent(input, pointer);
+    if (key === 'default' && isRecord(parent)) {
+        if (parent.type === 'bytes') {
+            return 'must not be declared: bytes properties cannot declare defaults';
+        }
+        if (parent.required === true)
+            return 'must not be declared when "required" is true';
+    }
+    if ((key === 'enumName' || key === 'values') && isRecord(parent) && parent.type !== 'enum') {
+        return 'must not be declared unless "type" is "enum"';
+    }
+    return 'must not be declared';
+}
+function describeTypes(type) {
+    const names = (Array.isArray(type) ? type : [type]).map((name) => String(name));
+    if (names.length <= 1)
+        return names[0] ?? 'of the expected type';
+    return `${names.slice(0, -1).join(', ')} or ${names[names.length - 1]}`;
+}
+function formatValue(value) {
+    if (value === undefined)
+        return 'the forbidden value';
+    return JSON.stringify(value) ?? String(value);
+}
+function describeLimit(params) {
+    return JSON.stringify(params.limit);
+}
+/** Checks that JSON Schema cannot express without duplicating every enum. */
+function semanticIssues(input) {
+    if (!isRecord(input))
+        return [];
+    const issues = [];
+    const properties = input.properties;
+    if (!isRecord(properties))
+        return issues;
+    for (const [key, entry] of Object.entries(properties)) {
+        if (!isRecord(entry))
+            continue;
+        const path = `properties.${key}`;
+        if (entry.type === 'enum' && Array.isArray(entry.values) && 'default' in entry) {
+            const value = entry.default;
+            const values = entry.values.filter((item) => typeof item === 'string');
+            if (typeof value === 'string' && !values.includes(value)) {
+                issues.push({
+                    path: `${path}.default`,
+                    keyword: 'default',
+                    message: `must be one of the declared "values" (${values.map(quote).join(', ')})`,
+                });
+            }
+        }
+        const editor = entry.editor;
+        if (isRecord(editor) && editor.kind === 'number') {
+            const { min, max } = editor;
+            if (typeof min === 'number' && typeof max === 'number' && min > max) {
+                issues.push({
+                    path: `${path}.editor`,
+                    keyword: 'editor',
+                    message: '"min" must be less than or equal to "max"',
+                });
+            }
+        }
+    }
+    return issues;
+}
+/** NaN and Infinity are not JSON numbers, so they are rejected before schema validation. */
+function findNonFiniteNumbers(value, path = '', found = []) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            found.push({ path, keyword: 'number', message: 'must be a finite JSON number' });
+        }
+        return found;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => findNonFiniteNumbers(item, joinPath(path, String(index)), found));
+        return found;
+    }
+    if (isRecord(value)) {
+        for (const [key, item] of Object.entries(value)) {
+            findNonFiniteNumbers(item, joinPath(path, key), found);
+        }
+    }
+    return found;
+}
+function dedupeAndSort(issues) {
+    const unique = new Map();
+    for (const issue of issues) {
+        const key = `${issue.path}\u0000${issue.message}`;
+        if (!unique.has(key))
+            unique.set(key, issue);
+    }
+    return [...unique.values()].sort((left, right) => left.path === right.path
+        ? left.message.localeCompare(right.message)
+        : left.path.localeCompare(right.path));
+}
+function formatMessage(kind, issues, metadataId) {
+    const subject = metadataId === undefined ? `${kind} metadata` : `${kind} metadata ${quote(metadataId)}`;
+    const count = `${issues.length} ${issues.length === 1 ? 'problem' : 'problems'}`;
+    const lines = issues.map((issue) => `  - ${issue.path === '' ? '<root>' : issue.path}: ${issue.message}`);
+    return [`Invalid ${subject} (${count}):`, ...lines].join('\n');
+}
+function pointerToPath(pointer) {
+    if (pointer === '')
+        return '';
+    return pointer.slice(1).split('/').map(decodeSegment).join('.');
+}
+function decodeSegment(segment) {
+    return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+function joinPath(base, key) {
+    return base === '' ? key : `${base}.${key}`;
+}
+function resolvePointer(input, pointer) {
+    if (pointer === '')
+        return input;
+    let current = input;
+    for (const segment of pointer.slice(1).split('/').map(decodeSegment)) {
+        if (Array.isArray(current)) {
+            const index = Number(segment);
+            current = Number.isInteger(index) ? current[index] : undefined;
+        }
+        else if (isRecord(current)) {
+            current = current[segment];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+function resolveParent(input, pointer) {
+    const index = pointer.lastIndexOf('/');
+    if (index < 0)
+        return { parent: input, key: '' };
+    return {
+        parent: resolvePointer(input, pointer.slice(0, index)),
+        key: decodeSegment(pointer.slice(index + 1)),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function quote(value) {
+    return JSON.stringify(value);
+}

package/dist/model.d.ts

@@ -0,0 +1 @@
+export * from '@mica-js/device-model';

package/dist/model.js

@@ -0,0 +1 @@
+export * from '@mica-js/device-model';

package/dist/widget.d.ts

@@ -0,0 +1 @@
+export type { WidgetFactory, WidgetImplementation, WidgetInstanceApi, WidgetInputEvent, WidgetDeliveryMeta, WidgetPortListener, WidgetAssetApi, WidgetAssetRef, WidgetAudioApi, WidgetAudioTone, WidgetAudioToneOptions, WidgetAudioStream, WidgetAudioStreamOptions, WidgetAudioVoice, WidgetAudioVoiceSettings, WidgetAudioFormat, WidgetAudioState, WidgetAudioEnded, WidgetAudioEndReason, WidgetAudioRampOptions, WidgetAudioStopOptions, WidgetAudioStreamState, WidgetAudioStreamStatus, WidgetOscillatorType, Disposable, Event, } from '@mica-js/widget/author';

package/dist/widget.js

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

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@mica-js/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Device and widget author APIs with CLI-managed content builds",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "mica": "./dist/build/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./device": {
+      "types": "./dist/device.d.ts",
+      "import": "./dist/device.js"
+    },
+    "./widget": {
+      "types": "./dist/widget.d.ts",
+      "import": "./dist/widget.js"
+    },
+    "./model": {
+      "types": "./dist/model.d.ts",
+      "import": "./dist/model.js"
+    },
+    "./ddl": {
+      "types": "./dist/ddl.d.ts",
+      "import": "./dist/ddl.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata/index.d.ts",
+      "import": "./dist/metadata/index.js"
+    },
+    "./config": {
+      "types": "./dist/build/config.d.ts",
+      "import": "./dist/build/config.js"
+    },
+    "./prepare": {
+      "types": "./dist/build/prepare.d.ts",
+      "import": "./dist/build/prepare.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mica-js/core": "0.6.0",
+    "@mica-js/ddl": "0.2.0",
+    "@mica-js/device-model": "0.5.0",
+    "@mica-js/simulator": "2.1.0",
+    "@mica-js/widget": "0.3.0",
+    "ajv": "^8.17.1",
+    "rolldown": "^1.2.14",
+    "vite": "^8.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/templates/basic/mica.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from '@mica-js/sdk/config';
+
+export default defineConfig({});

package/templates/basic/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "mica-components",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "prepare": "mica prepare",
+    "build": "mica build",
+    "typecheck": "mica prepare && tsc --noEmit"
+  },
+  "devDependencies": {
+    "@mica-js/sdk": "^0.1.0",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/basic/src/devices/resistor/device.json

@@ -0,0 +1,30 @@
+{
+  "kind": "device",
+  "id": "resistor",
+  "version": "1.0.0",
+  "displayName": "Resistor",
+  "designatorPrefix": "R",
+  "properties": {
+    "resistance": {
+      "type": "number",
+      "required": false,
+      "default": 10000,
+      "unit": "ohm",
+      "editor": { "kind": "number", "min": 0.001 }
+    }
+  },
+  "pins": { "a": { "label": "A" }, "b": { "label": "B" } },
+  "symbol": {
+    "bounds": { "x": -40, "y": -20, "width": 80, "height": 40 },
+    "graphics": [
+      { "type": "line", "from": [-40, 0], "to": [-24, 0] },
+      { "type": "rect", "x": -24, "y": -10, "width": 48, "height": 20, "fill": "background" },
+      { "type": "line", "from": [24, 0], "to": [40, 0] }
+    ],
+    "pins": {
+      "a": { "position": [-40, 0], "direction": "left", "label": { "visible": false } },
+      "b": { "position": [40, 0], "direction": "right", "label": { "visible": false } }
+    },
+    "annotations": { "designator": { "position": [0, -16], "align": "center" } }
+  }
+}

package/templates/basic/src/devices/resistor/index.ts

@@ -0,0 +1,8 @@
+import type { Factory } from './model.ddl';
+
+const create: Factory = () => ({
+  sync() {},
+  dispose() {},
+});
+
+export default create;

package/templates/basic/src/devices/resistor/model.ddl

@@ -0,0 +1,6 @@
+device Resistor(resistance: number default 10000) {
+  assert resistance >= 0.001 && resistance <= 1_000_000_000,
+    "resistance must be within the supported range";
+  pin a = [resistor(to: b, resistance: resistance)];
+  pin b;
+}

package/templates/basic/src/widgets/lamp/index.ts

@@ -0,0 +1,22 @@
+import type { WidgetFactory } from '@mica-js/sdk/widget';
+
+const create: WidgetFactory = (api) => {
+  let brightness = 0;
+  const unsubscribe = api.subscribe('brightness', (value) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) return;
+    brightness = Math.max(0, Math.min(1, value));
+    api.invalidate();
+  });
+  return {
+    render(ctx) {
+      ctx.fillStyle = '#22aa55';
+      ctx.globalAlpha = brightness;
+      ctx.fillRect(0, 0, api.width, api.height);
+    },
+    dispose() {
+      unsubscribe();
+    },
+  };
+};
+
+export default create;

package/templates/basic/src/widgets/lamp/widget.json

@@ -0,0 +1,9 @@
+{
+  "kind": "widget",
+  "id": "lamp",
+  "version": "1.0.0",
+  "displayName": "Lamp",
+  "ports": {
+    "brightness": { "direction": "input", "type": "number", "delivery": "level" }
+  }
+}

package/templates/basic/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023", "DOM"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowArbitraryExtensions": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src"]
+}