@mica-js/sdk 0.0.0-stage → 0.2.0

package/dist/build/prepare.d.ts

@@ -0,0 +1,51 @@
+/** Device definition file expected inside every device directory. */
+export declare const DEVICE_SOURCE_FILE = "model.ddl";
+/** TypeScript declaration generated next to {@link DEVICE_SOURCE_FILE}. */
+export declare const DEVICE_DECLARATION_FILE = "model.d.ddl.ts";
+export interface PrepareOptions {
+    /** Package root containing the source directory; defaults to `process.cwd()`. */
+    readonly root?: string;
+    /** Source directory inside the root that holds `devices/`; defaults to `src`. */
+    readonly sourceDir?: string;
+}
+export interface WatchOptions extends PrepareOptions {
+    /** Coalescing window between a file event and the regeneration; defaults to 50 ms. */
+    readonly debounceMs?: number;
+    /** Receives the declaration paths after every successful regeneration. */
+    readonly onPrepare?: (files: readonly string[]) => void;
+    /** Receives every failed regeneration; watching continues afterwards. */
+    readonly onError?: (error: unknown) => void;
+}
+export interface PrepareWatcher {
+    /** Declaration paths from the initial scan; resolves empty when that scan failed. */
+    readonly ready: Promise<readonly string[]>;
+    /** Stops watching and resolves once the regeneration in flight has finished. */
+    dispose(): Promise<void>;
+}
+/**
+ * Compiles `<root>/<sourceDir>/devices/<name>/model.ddl` into the source-adjacent
+ * `model.d.ddl.ts` declaration module of every device directory.
+ *
+ * Every device compiles before the first write, so a failing definition never leaves the package
+ * with a partly updated set of declarations. A declaration whose content is unchanged keeps its
+ * previous file and timestamp. The previous declaration of a device is removed when its
+ * definition fails to compile or no longer exists; only files carrying the generated marker are
+ * ever removed.
+ *
+ * @returns Absolute paths of the declaration files that the current definitions describe, in
+ * device directory order.
+ * @throws The original `BuildError` of a failed compilation, with the device file path prefixed
+ * to its message.
+ */
+export declare function prepare(options?: PrepareOptions): Promise<readonly string[]>;
+/**
+ * Regenerates declarations whenever a device definition below `<root>/<sourceDir>` appears,
+ * changes or disappears; output writes never feed back into the watch loop.
+ *
+ * Events are coalesced within {@link WatchOptions.debounceMs} and runs are serialized, so a
+ * save burst produces a single regeneration. Failures reach {@link WatchOptions.onError} and
+ * never stop the watcher.
+ *
+ * @throws When the source directory cannot be watched; the message names that directory.
+ */
+export declare function watchDevices(options?: WatchOptions): PrepareWatcher;

package/dist/build/prepare.js

@@ -0,0 +1,306 @@
+import { watch } from 'node:fs';
+import { readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { compileDDL, generateDeviceTypeScript } from '@mica-js/ddl';
+/** Device definition file expected inside every device directory. */
+export const DEVICE_SOURCE_FILE = 'model.ddl';
+/** TypeScript declaration generated next to {@link DEVICE_SOURCE_FILE}. */
+export const DEVICE_DECLARATION_FILE = 'model.d.ddl.ts';
+/** Runtime surface every generated declaration imports its boundary types from. */
+const DEVICE_MODULE = '@mica-js/sdk/device';
+/** Text marking a file as a `mica prepare` output, so only generated files are removed. */
+const GENERATED_MARKER = '@mica-js/sdk prepare';
+const DEVICE_DIRECTORY = 'devices';
+const DEFAULT_SOURCE_DIR = 'src';
+const DEFAULT_DEBOUNCE_MS = 50;
+const DEVICE_ALIASES = [
+    'Props',
+    'PropertyInput',
+    'Inputs',
+    'Memory',
+    'Outputs',
+    'Context',
+    'Batch',
+    'Adapter',
+    'Factory',
+];
+/**
+ * Compiles `<root>/<sourceDir>/devices/<name>/model.ddl` into the source-adjacent
+ * `model.d.ddl.ts` declaration module of every device directory.
+ *
+ * Every device compiles before the first write, so a failing definition never leaves the package
+ * with a partly updated set of declarations. A declaration whose content is unchanged keeps its
+ * previous file and timestamp. The previous declaration of a device is removed when its
+ * definition fails to compile or no longer exists; only files carrying the generated marker are
+ * ever removed.
+ *
+ * @returns Absolute paths of the declaration files that the current definitions describe, in
+ * device directory order.
+ * @throws The original `BuildError` of a failed compilation, with the device file path prefixed
+ * to its message.
+ */
+export async function prepare(options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const sourceDir = options.sourceDir ?? DEFAULT_SOURCE_DIR;
+    const devicesDir = resolve(root, sourceDir, DEVICE_DIRECTORY);
+    const directories = await listDeviceDirectories(devicesDir);
+    const devices = [];
+    const orphaned = [];
+    for (const directory of directories) {
+        const deviceDir = join(devicesDir, directory);
+        const sourceFile = join(deviceDir, DEVICE_SOURCE_FILE);
+        const declarationFile = join(deviceDir, DEVICE_DECLARATION_FILE);
+        if (await isFile(sourceFile))
+            devices.push({ sourceFile, declarationFile });
+        else
+            orphaned.push(declarationFile);
+    }
+    const outputs = [];
+    for (const device of devices)
+        outputs.push({
+            file: device.declarationFile,
+            content: await compileDeclaration(device.sourceFile, device.declarationFile),
+        });
+    for (const file of orphaned)
+        await removeGenerated(file);
+    for (const output of outputs)
+        await writeIfChanged(output.file, output.content);
+    return outputs.map((output) => output.file);
+}
+/**
+ * Regenerates declarations whenever a device definition below `<root>/<sourceDir>` appears,
+ * changes or disappears; output writes never feed back into the watch loop.
+ *
+ * Events are coalesced within {@link WatchOptions.debounceMs} and runs are serialized, so a
+ * save burst produces a single regeneration. Failures reach {@link WatchOptions.onError} and
+ * never stop the watcher.
+ *
+ * @throws When the source directory cannot be watched; the message names that directory.
+ */
+export function watchDevices(options = {}) {
+    const root = resolve(options.root ?? process.cwd());
+    const sourceDir = options.sourceDir ?? DEFAULT_SOURCE_DIR;
+    const sourceRoot = resolve(root, sourceDir);
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    let disposed = false;
+    let queued = false;
+    let timer;
+    let current;
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A failing reporter must not end the watch loop.
+        }
+    };
+    const scan = async () => {
+        try {
+            const files = await prepare({ root, sourceDir });
+            options.onPrepare?.(files);
+            return files;
+        }
+        catch (error) {
+            if (!disposed)
+                report(error);
+            return [];
+        }
+    };
+    const drain = async () => {
+        for (;;) {
+            queued = false;
+            const files = await scan();
+            if (!queued || disposed)
+                return files;
+        }
+    };
+    const schedule = () => {
+        if (disposed)
+            return;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            run();
+        }, debounceMs);
+    };
+    const start = () => {
+        const task = drain();
+        current = task;
+        void task.finally(() => {
+            if (current === task)
+                current = undefined;
+            if (queued && !disposed)
+                schedule();
+        });
+        return task;
+    };
+    const run = () => {
+        if (disposed)
+            return;
+        if (current)
+            queued = true;
+        else
+            start();
+    };
+    let watcher;
+    try {
+        watcher = watch(sourceRoot, { recursive: true }, (_event, filename) => {
+            if (disposed)
+                return;
+            void isRelevantEvent(sourceRoot, filename).then((relevant) => {
+                if (relevant && !disposed)
+                    schedule();
+            }, () => {
+                // An unreadable path may still be the device directory that changed.
+                if (!disposed)
+                    schedule();
+            });
+        });
+    }
+    catch (error) {
+        throw new Error(`Cannot watch ${sourceRoot} for ${DEVICE_SOURCE_FILE} changes: ${messageOf(error)}`, { cause: error });
+    }
+    watcher.on('error', (error) => {
+        if (!disposed)
+            report(error);
+    });
+    const ready = start();
+    return {
+        ready,
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            watcher.close();
+            await current;
+        },
+    };
+}
+async function compileDeclaration(sourceFile, declarationFile) {
+    try {
+        const source = await readFile(sourceFile, 'utf8');
+        const model = await compileDDL(source, { uri: pathToFileURL(sourceFile).href });
+        return renderDeclaration(model);
+    }
+    catch (error) {
+        // The editor must never keep declarations that a failed definition contradicts.
+        await removeGenerated(declarationFile).catch(() => undefined);
+        throw annotate(error, sourceFile);
+    }
+}
+function renderDeclaration(model) {
+    const prefix = model.name;
+    const generated = generateDeviceTypeScript(model, {
+        deviceModule: DEVICE_MODULE,
+        name: prefix,
+    });
+    const aliases = DEVICE_ALIASES.map((alias) => `export type ${alias} = ${prefix}${alias};`);
+    return [
+        `// Generated by ${GENERATED_MARKER} from ${DEVICE_SOURCE_FILE}; do not edit.`,
+        '',
+        generated.trimEnd(),
+        '',
+        ...aliases,
+        '',
+    ].join('\n');
+}
+/** A `model.ddl` edit or a device directory appearing, disappearing or being renamed. */
+async function isRelevantEvent(sourceRoot, filename) {
+    if (filename === null)
+        return true;
+    const relativePath = filename.toString();
+    if (basename(relativePath) === DEVICE_SOURCE_FILE)
+        return true;
+    return isDirectory(join(sourceRoot, relativePath));
+}
+async function listDeviceDirectories(devicesDir) {
+    let entries;
+    try {
+        entries = await readdir(devicesDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const directories = [];
+    for (const entry of entries) {
+        if (entry.isDirectory())
+            directories.push(entry.name);
+        else if (entry.isSymbolicLink() && (await isDirectory(join(devicesDir, entry.name))))
+            directories.push(entry.name);
+    }
+    return directories.sort();
+}
+async function removeGenerated(file) {
+    let content;
+    try {
+        content = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!content.includes(GENERATED_MARKER))
+        return;
+    await unlink(file).catch((error) => {
+        if (errorCode(error) !== 'ENOENT')
+            throw error;
+    });
+}
+async function writeIfChanged(file, content) {
+    try {
+        if ((await readFile(file, 'utf8')) === content)
+            return;
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT')
+            throw error;
+    }
+    await writeFile(file, content, 'utf8');
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        throw error;
+    }
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        throw error;
+    }
+}
+function annotate(error, sourceFile) {
+    if (error instanceof Error) {
+        error.message = `${sourceFile}: ${error.message}`;
+        return error;
+    }
+    return new Error(`${sourceFile}: ${String(error)}`);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' ? code : undefined;
+}

package/dist/build/project.d.ts

@@ -0,0 +1,4 @@
+import type { loadProjectConfig } from './config.js';
+type Project = Awaited<ReturnType<typeof loadProjectConfig>>;
+export declare function buildProject(project: Project): Promise<void>;
+export {};

package/dist/build/project.js

@@ -0,0 +1,30 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { build } from 'vite';
+import { micaSdk } from './vite.js';
+function viteConfig(project) {
+    const { root, config } = project;
+    const source = resolve(root, config.sourceDir ?? 'src');
+    const output = resolve(root, config.outDir ?? 'dist');
+    const contains = (parent, child) => {
+        const path = relative(parent, child);
+        return (path === '' ||
+            (!isAbsolute(path) && path !== '..' && !path.startsWith('..\\') && !path.startsWith('../')));
+    };
+    if (contains(output, root) || contains(output, source) || contains(source, output))
+        throw new Error('outDir must be separate from the project root and sourceDir.');
+    return {
+        configFile: false,
+        root,
+        base: config.base ?? '/',
+        publicDir: false,
+        appType: 'custom',
+        resolve: {
+            alias: Object.fromEntries(Object.entries(config.alias ?? {}).map(([key, path]) => [key, resolve(root, path)])),
+        },
+        plugins: [micaSdk({ sourceDir: config.sourceDir ?? 'src' })],
+        build: { outDir: config.outDir ?? 'dist' },
+    };
+}
+export async function buildProject(project) {
+    await build(viteConfig(project));
+}

package/dist/build/vite.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from 'vite';
+export interface MicaSdkOptions {
+    /** Source directory relative to the Vite root; defaults to src. */
+    readonly sourceDir?: string;
+}
+/** Builds independent two-file devices/widgets for the SDK CLI. */
+export declare function micaSdk(options?: MicaSdkOptions): Plugin;

package/dist/build/vite.js

@@ -0,0 +1,60 @@
+import { buildContent } from './content.js';
+import { prepare } from './prepare.js';
+const entryId = 'virtual:mica-sdk-empty';
+/** Builds independent two-file devices/widgets for the SDK CLI. */
+export function micaSdk(options = {}) {
+    let config;
+    const compile = async () => {
+        await prepare({ root: config.root, ...options });
+        return buildContent({
+            root: config.root,
+            ...options,
+            aliases: config.resolve.alias,
+            minify: config.build.minify !== false,
+        });
+    };
+    return {
+        name: 'mica:sdk',
+        config(_config, environment) {
+            if (environment.command !== 'build')
+                return;
+            return {
+                publicDir: false,
+                build: {
+                    sourcemap: false,
+                    copyPublicDir: false,
+                    lib: { entry: entryId, formats: ['es'], fileName: () => '__mica_sdk__.js' },
+                    rolldownOptions: { input: entryId },
+                },
+            };
+        },
+        configResolved(resolved) {
+            config = resolved;
+        },
+        resolveId(id) {
+            if (id === entryId)
+                return '\0' + entryId;
+        },
+        load(id) {
+            if (id === '\0' + entryId)
+                return 'export {};';
+        },
+        async buildStart() {
+            if (config.command !== 'build')
+                return;
+            for (const file of await compile())
+                this.emitFile({ type: 'asset', ...file });
+        },
+        generateBundle(_options, bundle) {
+            if (config.command !== 'build')
+                return;
+            for (const [name, output] of Object.entries(bundle)) {
+                if (output.type === 'chunk' && output.facadeModuleId === '\0' + entryId)
+                    delete bundle[name];
+                else if (output.type === 'chunk' ||
+                    !/^(devices\/[A-Za-z0-9-]+\/device|widgets\/[A-Za-z0-9-]+\/widget)\.(js|json)$/.test(name))
+                    this.error(`Unexpected content artifact: ${name}`);
+            }
+        },
+    };
+}

package/dist/ddl.d.ts

@@ -0,0 +1,2 @@
+export { compileDDL, generateDeviceTypes, generateDeviceTypeScript } from '@mica-js/ddl';
+export type { CompileDDLOptions, DeviceTypeScriptOptions, DeviceIR } from '@mica-js/ddl';

package/dist/ddl.js

@@ -0,0 +1 @@
+export { compileDDL, generateDeviceTypes, generateDeviceTypeScript } from '@mica-js/ddl';

package/dist/device.d.ts

@@ -0,0 +1 @@
+export type { BorrowedBytes, ReadonlyBytes, ChannelMessage, Notification, DeviceAdapter, DeviceBatch, DeviceContext, DeviceFactory, InputChannel, InputNotification, TopicBridge, TopicMessage, JitHost, JitOptions, JitTranslate, JitTranslateInput, InstructionHook, Disposable, Event, } from '@mica-js/simulator';

package/dist/device.js

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createDeviceLibrary, createBoard, SimulationError } from '@mica-js/simulator';
+export type { Board, BoardDescription, BoardOptions, DeviceLibrary, DeviceLibraryEntry, } from '@mica-js/simulator';

package/dist/index.js

@@ -0,0 +1 @@
+export { createDeviceLibrary, createBoard, SimulationError } from '@mica-js/simulator';

package/dist/metadata/index.d.ts

@@ -0,0 +1,5 @@
+export { deviceMetadataSchema, widgetMetadataSchema } from './schema.js';
+export type { MetadataJsonSchema } from './schema.js';
+export { MetadataValidationError, validateMetadata } from './validate.js';
+export type { MetadataIssue } from './validate.js';
+export type { ArcGraphic, BooleanProperty, BytesProperty, CheckboxEditor, CircleGraphic, DesignatorAnnotationMetadata, DeviceMetadata, EnumProperty, FileEditor, Graphic, GraphicFill, LineGraphic, Metadata, MetadataKind, NumberEditor, NumberProperty, PinDirection, PinLabelMetadata, PinMetadata, Point, PolylineGraphic, PortDelivery, PortDirection, PortMetadata, PortPayloadType, PropertyEditor, PropertyMetadata, PropertyType, RectGraphic, SelectEditor, StringProperty, SymbolAnnotationsMetadata, SymbolBounds, SymbolMetadata, SymbolPinMetadata, TextAlign, TextareaEditor, TextEditor, TextGraphic, WidgetMetadata, } from './types.js';

package/dist/metadata/index.js

@@ -0,0 +1,2 @@
+export { deviceMetadataSchema, widgetMetadataSchema } from './schema.js';
+export { MetadataValidationError, validateMetadata } from './validate.js';

package/dist/metadata/schema.d.ts

@@ -0,0 +1,10 @@
+import type { MetadataKind } from './types.js';
+export type { MetadataKind };
+/** A JSON Schema node. The exported schemas are plain data and can be serialized as-is. */
+export type MetadataJsonSchema = {
+    readonly [keyword: string]: unknown;
+};
+/** Metadata of a single device, independent of any package manifest or DDL source. */
+export declare const deviceMetadataSchema: MetadataJsonSchema;
+/** Metadata of a single widget, independent of any package manifest or DDL source. */
+export declare const widgetMetadataSchema: MetadataJsonSchema;