@aelionsdk/material-sdk 0.1.0-beta.1 → 1.1.0-rc.1

package/README.md

@@ -1,7 +1,54 @@
-# @aelionsdk/material-sdk
+# `@aelionsdk/material-sdk`
 
-Type-safe authoring, validation and packaging tools for Aelion materials
+Type-safe authoring, validation, packaging, signing and trust tools for Aelion
+Material Protocol v1.
 
-Install with `npm install @aelionsdk/material-sdk@next`.
+## Install
 
-Version 0.1.0-beta.1 is a prerelease and its API may change before the first stable release. This package is part of [AelionSDK](https://github.com/FoyonaCZY/AelionSDK); see the repository README for supported browsers, examples and deployment requirements.
+```bash
+npm install @aelionsdk/material-sdk@next
+```
+
+## Author CLI
+
+The package installs `aelion-material`:
+
+```bash
+pnpm exec aelion-material init ./my-pack
+pnpm exec aelion-material build ./my-pack
+pnpm exec aelion-material validate ./my-pack
+pnpm exec aelion-material types ./my-pack
+pnpm exec aelion-material preview ./my-pack
+pnpm exec aelion-material prepublish ./my-pack
+pnpm exec aelion-material pack ./my-pack --out ./dist/my-pack.aelionmat
+pnpm exec aelion-material golden actual.rgba expected.rgba --tolerance 2
+```
+
+`build` refreshes declared payload sizes/hashes and generates types plus the
+preview report. `prepublish` requires valid payload hashes and schemas, no error diagnostics,
+strict determinism, and WebGL2/WebGPU compiler parity for declarative Graph
+materials. The `.aelionmat` archive is deterministic.
+
+Signing keys are deliberately not read by the generic CLI. A host that owns a
+publisher key should obtain a `CryptoKey` from its own key system and call
+`signMaterialPackage()` explicitly.
+
+Node build systems can import the same operations from
+`@aelionsdk/material-sdk/author-cli`.
+
+## TypeScript API
+
+```ts
+import {
+  MaterialLabSession,
+  materialDefinition,
+  materialGraph,
+  packMaterialPackage,
+} from '@aelionsdk/material-sdk';
+```
+
+See the [Material guide](https://foyonaczy.github.io/AelionSDK/guides/materials/)
+and [AMP v1 reference](https://foyonaczy.github.io/AelionSDK/reference/material-protocol-v1/).
+
+Version `1.1.0-rc.1` is a prerelease. Public changes before 1.0 are recorded
+in the repository changelog and migration documentation. Licensed under MIT.

package/dist/cli-lib.d.ts

@@ -0,0 +1,34 @@
+import { MaterialLabSession, compareMaterialGolden } from './lab.js';
+export interface MaterialAuthorInspection {
+    readonly directory: string;
+    readonly packageId: string;
+    readonly version: string;
+    readonly integrity: string;
+    readonly files: number;
+    readonly materials: readonly {
+        readonly id: string;
+        readonly kind: string;
+        readonly parameters: number;
+        readonly webgl2: boolean;
+        readonly webgpu: boolean;
+        readonly budget: ReturnType<MaterialLabSession['analyze']>['budget'];
+    }[];
+}
+export declare function validateMaterialAuthorPackage(directory: string): Promise<MaterialAuthorInspection>;
+export declare function synchronizeMaterialAuthorManifest(directory: string): Promise<string>;
+export declare function generateMaterialTypes(directory: string, outputPath?: string): Promise<string>;
+export declare function writeMaterialPreviewReport(directory: string, outputPath?: string): Promise<string>;
+export declare function packMaterialAuthorPackage(directory: string, outputPath: string): Promise<{
+    readonly path: string;
+    readonly integrity: string;
+    readonly bytes: number;
+}>;
+export declare function buildMaterialAuthorPackage(directory: string): Promise<{
+    readonly inspection: MaterialAuthorInspection;
+    readonly typesPath: string;
+    readonly previewPath: string;
+}>;
+export declare function compareMaterialGoldenFiles(actualPath: string, expectedPath: string, tolerance?: number): Promise<ReturnType<typeof compareMaterialGolden>>;
+export declare function prepublishMaterialAuthorPackage(directory: string): Promise<MaterialAuthorInspection>;
+export declare function initializeMaterialAuthorPackage(directory: string): Promise<string>;
+//# sourceMappingURL=cli-lib.d.ts.map

package/dist/cli-lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-lib.d.ts","sourceRoot":"","sources":["../src/cli-lib.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAmBrE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;KACtE,EAAE,CAAC;CACL;AAsID,wBAAsB,6BAA6B,CACjD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,wBAAwB,CAAC,CAEnC;AAED,wBAAsB,iCAAiC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB1F;AAYD,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,UAAU,SAAgD,GACzD,OAAO,CAAC,MAAM,CAAC,CAsBjB;AAED,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,MAAM,EACjB,UAAU,SAA8C,GACvD,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAUxF;AAED,wBAAsB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3E,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC,CAQD;AAED,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAI,GACZ,OAAO,CAAC,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAGnD;AAED,wBAAsB,+BAA+B,CACnD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,wBAAwB,CAAC,CAenC;AAED,wBAAsB,+BAA+B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6HxF"}

package/dist/cli-lib.js

@@ -0,0 +1,367 @@
+import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { canonicalMaterialBytes, sha256Hex } from './canonical.js';
+import { MaterialLabSession, compareMaterialGolden } from './lab.js';
+import { packMaterialPackage, verifyMaterialPackage } from './package.js';
+import { assertMaterialDefinitionSchema, assertMaterialGraphSchema, assertMaterialManifestSchema, } from './schema-validation.js';
+import { createDeterministicMaterialArchive } from './zip.js';
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const encoder = new TextEncoder();
+function safePath(root, path) {
+    const absolute = resolve(root, path);
+    const fromRoot = relative(root, absolute).replaceAll('\\', '/');
+    if (fromRoot.length === 0 ||
+        fromRoot === '..' ||
+        fromRoot.startsWith('../') ||
+        fromRoot.startsWith('/') ||
+        path.includes('\\')) {
+        throw new TypeError(`Unsafe Material path ${path}`);
+    }
+    return absolute;
+}
+function json(bytes, path) {
+    try {
+        return JSON.parse(decoder.decode(bytes));
+    }
+    catch (error) {
+        throw new TypeError(`Invalid JSON in ${path}`, { cause: error });
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadAuthorPackage(directory) {
+    const root = resolve(directory);
+    const manifestPath = resolve(root, 'manifest.json');
+    const manifestSource = new Uint8Array(await readFile(manifestPath));
+    const manifestValue = json(manifestSource, manifestPath);
+    assertMaterialManifestSchema(manifestValue);
+    const manifest = manifestValue;
+    const manifestBytes = canonicalMaterialBytes(manifest);
+    const files = new Map([['manifest.json', manifestBytes]]);
+    for (const entry of manifest.files) {
+        const bytes = new Uint8Array(await readFile(safePath(root, entry.path)));
+        files.set(entry.path, bytes);
+    }
+    const archiveBytes = createDeterministicMaterialArchive(files);
+    const integrity = `sha256:${await sha256Hex(manifestBytes)}`;
+    const packed = {
+        manifest,
+        manifestBytes,
+        files,
+        archiveBytes,
+        integrity,
+    };
+    await verifyMaterialPackage(packed, integrity);
+    const definitionPaths = new Set(manifest.materials.map(material => material.definition));
+    const graphPaths = new Set();
+    const authored = manifest.materials.map(material => {
+        const definitionBytes = files.get(material.definition);
+        if (definitionBytes === undefined) {
+            throw new TypeError(`Definition ${material.definition} is missing`);
+        }
+        const definitionValue = json(definitionBytes, material.definition);
+        assertMaterialDefinitionSchema(definitionValue);
+        const definition = definitionValue;
+        if (definition.id !== material.id || definition.kind !== material.kind) {
+            throw new TypeError(`Definition identity differs for ${material.id}`);
+        }
+        const graphImplementation = definition.implementations.find(value => value.type === 'graph');
+        if (graphImplementation === undefined)
+            return { definition };
+        graphPaths.add(graphImplementation.graph);
+        const graphBytes = files.get(graphImplementation.graph);
+        if (graphBytes === undefined) {
+            throw new TypeError(`Graph ${graphImplementation.graph} is missing`);
+        }
+        const graphValue = json(graphBytes, graphImplementation.graph);
+        assertMaterialGraphSchema(graphValue);
+        return {
+            definition,
+            graph: graphValue,
+            definitionPath: material.definition,
+            graphPath: graphImplementation.graph,
+        };
+    });
+    const extraFiles = manifest.files.flatMap(entry => {
+        if (definitionPaths.has(entry.path) || graphPaths.has(entry.path))
+            return [];
+        const data = files.get(entry.path);
+        if (data === undefined)
+            throw new TypeError(`Package file ${entry.path} is missing`);
+        return [{ path: entry.path, mediaType: entry.mediaType, data }];
+    });
+    // Re-run the same authoring validation/compilation path used by package
+    // creation. The stored manifest verification above remains authoritative for
+    // exact payload bytes and transport integrity.
+    await packMaterialPackage({
+        metadata: manifest.package,
+        materials: authored,
+        files: extraFiles,
+    });
+    return { directory: root, manifest, packed, authored, extraFiles };
+}
+function inspection(loaded) {
+    return {
+        directory: loaded.directory,
+        packageId: loaded.manifest.package.id,
+        version: loaded.manifest.package.version,
+        integrity: loaded.packed.integrity,
+        files: loaded.manifest.files.length + 1,
+        materials: loaded.authored.map(material => {
+            const report = new MaterialLabSession(material).analyze();
+            return {
+                id: material.definition.id,
+                kind: material.definition.kind,
+                parameters: material.definition.parameters.length,
+                webgl2: report.webgl2.available,
+                webgpu: report.webgpu.available,
+                budget: report.budget,
+            };
+        }),
+    };
+}
+export async function validateMaterialAuthorPackage(directory) {
+    return inspection(await loadAuthorPackage(directory));
+}
+export async function synchronizeMaterialAuthorManifest(directory) {
+    const root = resolve(directory);
+    const manifestPath = resolve(root, 'manifest.json');
+    const manifestValue = json(new Uint8Array(await readFile(manifestPath)), manifestPath);
+    assertMaterialManifestSchema(manifestValue);
+    const manifest = manifestValue;
+    const files = await Promise.all(manifest.files.map(async (entry) => {
+        const bytes = new Uint8Array(await readFile(safePath(root, entry.path)));
+        return {
+            ...entry,
+            bytes: bytes.byteLength,
+            sha256: await sha256Hex(bytes),
+        };
+    }));
+    await writeFile(manifestPath, `${JSON.stringify({ ...manifest, files }, null, 2)}\n`, 'utf8');
+    return manifestPath;
+}
+function parameterType(type) {
+    if (type === 'boolean')
+        return 'boolean';
+    if (type === 'enum' || type === 'string')
+        return 'string';
+    if (['integer', 'float', 'angle', 'duration'].includes(type))
+        return 'number';
+    if (type === 'vec2')
+        return 'readonly [number, number]';
+    if (type === 'vec3')
+        return 'readonly [number, number, number]';
+    if (type === 'vec4' || type === 'color')
+        return 'readonly [number, number, number, number]';
+    return 'JsonValue';
+}
+export async function generateMaterialTypes(directory, outputPath = resolve(directory, 'material.generated.d.ts')) {
+    const loaded = await loadAuthorPackage(directory);
+    const needsJsonValue = loaded.authored.some(material => material.definition.parameters.some(parameter => ['gradient', 'curve'].includes(parameter.type)));
+    const sections = loaded.authored.map(material => {
+        const name = `${material.definition.id
+            .split(/[^A-Za-z0-9]+/u)
+            .filter(Boolean)
+            .map(part => `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`)
+            .join('')}Parameters`;
+        const members = material.definition.parameters.map(parameter => `  readonly ${JSON.stringify(parameter.id)}: ${parameterType(parameter.type)};`);
+        return `export interface ${name} {\n${members.join('\n')}\n}`;
+    });
+    const source = `${needsJsonValue ? "import type { JsonValue } from '@aelionsdk/core';\n\n" : ''}${sections.join('\n\n')}\n`;
+    await mkdir(dirname(resolve(outputPath)), { recursive: true });
+    await writeFile(resolve(outputPath), source, 'utf8');
+    return resolve(outputPath);
+}
+export async function writeMaterialPreviewReport(directory, outputPath = resolve(directory, 'material-preview.json')) {
+    const loaded = await loadAuthorPackage(directory);
+    const report = {
+        reportVersion: '1.0.0',
+        package: {
+            id: loaded.manifest.package.id,
+            version: loaded.manifest.package.version,
+            integrity: loaded.packed.integrity,
+        },
+        materials: loaded.authored.map(material => ({
+            id: material.definition.id,
+            display: material.definition.display,
+            execution: material.definition.execution,
+            analysis: new MaterialLabSession(material).analyze(),
+        })),
+    };
+    await mkdir(dirname(resolve(outputPath)), { recursive: true });
+    await writeFile(resolve(outputPath), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    return resolve(outputPath);
+}
+export async function packMaterialAuthorPackage(directory, outputPath) {
+    await synchronizeMaterialAuthorManifest(directory);
+    const loaded = await loadAuthorPackage(directory);
+    await mkdir(dirname(resolve(outputPath)), { recursive: true });
+    await writeFile(resolve(outputPath), loaded.packed.archiveBytes);
+    return {
+        path: resolve(outputPath),
+        integrity: loaded.packed.integrity,
+        bytes: loaded.packed.archiveBytes.byteLength,
+    };
+}
+export async function buildMaterialAuthorPackage(directory) {
+    await synchronizeMaterialAuthorManifest(directory);
+    const inspection = await validateMaterialAuthorPackage(directory);
+    const [typesPath, previewPath] = await Promise.all([
+        generateMaterialTypes(directory),
+        writeMaterialPreviewReport(directory),
+    ]);
+    return { inspection, typesPath, previewPath };
+}
+export async function compareMaterialGoldenFiles(actualPath, expectedPath, tolerance = 2) {
+    const [actual, expected] = await Promise.all([readFile(actualPath), readFile(expectedPath)]);
+    return compareMaterialGolden(actual, expected, tolerance);
+}
+export async function prepublishMaterialAuthorPackage(directory) {
+    const loaded = await loadAuthorPackage(directory);
+    for (const material of loaded.authored) {
+        const report = new MaterialLabSession(material).analyze();
+        if (report.diagnostics.some(value => value.severity === 'error')) {
+            throw new TypeError(`Material ${material.definition.id} has error diagnostics`);
+        }
+        if (material.graph !== undefined && (!report.webgl2.available || !report.webgpu.available)) {
+            throw new TypeError(`Material ${material.definition.id} lacks WebGL2/WebGPU compiler parity`);
+        }
+        if (material.definition.execution.determinism === 'non-deterministic') {
+            throw new TypeError(`Material ${material.definition.id} is non-deterministic`);
+        }
+    }
+    return inspection(loaded);
+}
+export async function initializeMaterialAuthorPackage(directory) {
+    const root = resolve(directory);
+    if ((await exists(root)) && (await readdir(root)).length > 0) {
+        throw new TypeError(`Material directory is not empty: ${root}`);
+    }
+    const definition = {
+        $schema: 'https://schemas.aelion.dev/material/definition/v1.json',
+        protocolVersion: '1.0.0',
+        id: 'starter-filter',
+        kind: 'visual-filter',
+        display: { name: 'Starter Filter', category: 'starter' },
+        scopes: ['source', 'item', 'track', 'sequence'],
+        ports: [
+            {
+                id: 'source',
+                direction: 'input',
+                type: 'visual-frame',
+                role: 'source',
+                binding: 'host',
+                required: true,
+            },
+            {
+                id: 'result',
+                direction: 'output',
+                type: 'visual-frame',
+                role: 'result',
+                binding: 'host',
+                required: true,
+            },
+        ],
+        parameters: [
+            {
+                id: 'intensity',
+                type: 'float',
+                default: 1,
+                range: { min: 0, max: 1, step: 0.01 },
+                unit: 'ratio',
+                animatable: true,
+                interpolation: 'linear',
+                affects: 'uniform',
+                ui: { control: 'slider', group: 'main', order: 0, label: 'Intensity' },
+            },
+        ],
+        bundledResources: [],
+        resourceSlots: [],
+        execution: {
+            color: { input: 'working-linear', output: 'working-linear' },
+            alpha: {
+                input: 'premultiplied',
+                output: 'premultiplied',
+                preservesTransparency: true,
+            },
+            resolution: { policy: 'same-as-host' },
+            spatialPadding: { mode: 'none' },
+            temporal: { pastUs: 0, futureUs: 0, stateful: false, seekPolicy: 'stateless' },
+            determinism: 'strict',
+            supports: { realtime: true, offline: true, alpha: true, hdr: false, tiled: true },
+        },
+        implementations: [
+            {
+                type: 'graph',
+                graph: 'graphs/starter-filter.graph.json',
+                nodeSet: 'aelion.visual.nodes/1.0.0',
+            },
+        ],
+        splitPolicy: 'copy',
+    };
+    const graph = {
+        $schema: 'https://schemas.aelion.dev/material/graph/v1.json',
+        graphVersion: '1.0.0',
+        nodeSet: 'aelion.visual.nodes/1.0.0',
+        nodes: [
+            {
+                id: 'mix',
+                type: 'composite.mix',
+                typeVersion: '1.0.0',
+                inputs: {
+                    a: { inputPort: 'source' },
+                    b: { inputPort: 'source' },
+                    amount: { parameter: 'intensity' },
+                },
+            },
+        ],
+        outputs: { result: { node: 'mix', output: 'frame' } },
+    };
+    const definitionPath = 'materials/starter-filter.material.json';
+    const graphPath = 'graphs/starter-filter.graph.json';
+    const definitionSource = `${JSON.stringify(definition, null, 2)}\n`;
+    const graphSource = `${JSON.stringify(graph, null, 2)}\n`;
+    const manifest = {
+        $schema: 'https://schemas.aelion.dev/material/package/v1.json',
+        protocolVersion: '1.0.0',
+        package: {
+            id: 'dev.example.starter',
+            version: '0.1.0',
+            displayName: 'Starter Material',
+            publisher: { id: 'dev.example', name: 'Example Publisher' },
+            license: 'MIT',
+            engines: { aelion: '>=1.0.0-rc.1 <2.0.0', nodeSet: 'aelion.visual.nodes/1.0.0' },
+            trust: 'declarative',
+        },
+        materials: [{ id: definition.id, kind: definition.kind, definition: definitionPath }],
+        files: [
+            {
+                path: graphPath,
+                mediaType: 'application/vnd.aelion.material-graph+json',
+                bytes: encoder.encode(graphSource).byteLength,
+                sha256: await sha256Hex(encoder.encode(graphSource)),
+            },
+            {
+                path: definitionPath,
+                mediaType: 'application/vnd.aelion.material+json',
+                bytes: encoder.encode(definitionSource).byteLength,
+                sha256: await sha256Hex(encoder.encode(definitionSource)),
+            },
+        ],
+    };
+    await mkdir(resolve(root, 'materials'), { recursive: true });
+    await mkdir(resolve(root, 'graphs'), { recursive: true });
+    await writeFile(resolve(root, definitionPath), definitionSource, 'utf8');
+    await writeFile(resolve(root, graphPath), graphSource, 'utf8');
+    await writeFile(resolve(root, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    await validateMaterialAuthorPackage(root);
+    await generateMaterialTypes(root);
+    return root;
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { buildMaterialAuthorPackage, compareMaterialGoldenFiles, generateMaterialTypes, initializeMaterialAuthorPackage, packMaterialAuthorPackage, prepublishMaterialAuthorPackage, validateMaterialAuthorPackage, writeMaterialPreviewReport, } from './cli-lib.js';
+function option(name) {
+    const index = process.argv.indexOf(name);
+    return index < 0 ? undefined : process.argv[index + 1];
+}
+function required(value, description) {
+    if (value === undefined || value.length === 0)
+        throw new TypeError(`${description} is required`);
+    return value;
+}
+async function main() {
+    const command = process.argv[2];
+    const target = process.argv[3];
+    let result;
+    if (command === 'init') {
+        result = { directory: await initializeMaterialAuthorPackage(required(target, 'directory')) };
+    }
+    else if (command === 'build') {
+        result = await buildMaterialAuthorPackage(required(target, 'directory'));
+    }
+    else if (command === 'validate' || command === 'inspect') {
+        result = await validateMaterialAuthorPackage(required(target, 'directory'));
+    }
+    else if (command === 'types') {
+        result = {
+            path: await generateMaterialTypes(required(target, 'directory'), option('--out') ?? resolve(required(target, 'directory'), 'material.generated.d.ts')),
+        };
+    }
+    else if (command === 'preview') {
+        result = {
+            path: await writeMaterialPreviewReport(required(target, 'directory'), option('--out') ?? resolve(required(target, 'directory'), 'material-preview.json')),
+        };
+    }
+    else if (command === 'pack') {
+        result = await packMaterialAuthorPackage(required(target, 'directory'), required(option('--out'), '--out'));
+    }
+    else if (command === 'golden') {
+        const tolerance = Number.parseInt(option('--tolerance') ?? '2', 10);
+        const comparison = await compareMaterialGoldenFiles(required(target, 'actual file'), required(process.argv[4], 'expected file'), tolerance);
+        result = comparison;
+        if (!comparison.passed)
+            process.exitCode = 1;
+    }
+    else if (command === 'prepublish') {
+        result = await prepublishMaterialAuthorPackage(required(target, 'directory'));
+    }
+    else {
+        throw new TypeError('Usage: aelion-material <init|build|validate|inspect|types|preview|pack|golden|prepublish> ...');
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+void main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aelionsdk/material-sdk",
-  "version": "0.1.0-beta.1",
+  "version": "1.1.0-rc.1",
   "description": "Type-safe authoring, validation and packaging tools for Aelion materials",
   "license": "MIT",
   "repository": {
@@ -20,27 +20,35 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./author-cli": {
+      "types": "./dist/cli-lib.d.ts",
+      "import": "./dist/cli-lib.js"
     }
   },
+  "bin": {
+    "aelion-material": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "!dist/.tsbuildinfo"
   ],
   "engines": {
-    "node": ">=20.19"
+    "node": ">=24 <25"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@aelionsdk/core": "0.1.0-beta.1",
-    "@aelionsdk/material-compiler": "0.1.0-beta.1",
-    "ajv": "8.17.1",
+    "@aelionsdk/core": "1.1.0-rc.1",
+    "@aelionsdk/material-compiler": "1.1.0-rc.1",
+    "ajv": "8.18.0",
     "ajv-formats": "3.0.1"
   },
   "scripts": {
     "build": "tsc -b",
+    "cli": "corepack pnpm run build && node dist/cli.js",
     "typecheck": "tsc -b --pretty false"
   }
 }